Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Net::libnetFAQ.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Net::libnetFAQ 3pm"
61 .TH Net::libnetFAQ 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 libnetFAQ \- libnet Frequently Asked Questions
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 .SS "Where to get this document"
71 .IX Subsection "Where to get this document"
72 This document is distributed with the libnet distribution, and is also
73 available on the libnet web page at
74 .PP
75 <https://metacpan.org/release/libnet>
76 .SS "How to contribute to this document"
77 .IX Subsection "How to contribute to this document"
78 You may report corrections, additions, and suggestions on the
79 CPAN Request Tracker at
80 .PP
81 <https://rt.cpan.org/Public/Bug/Report.html?Queue=libnet>
82 .SH "Author and Copyright Information"
83 .IX Header "Author and Copyright Information"
84 Copyright (C) 1997\-1998 Graham Barr. All rights reserved.
85 This document is free; you can redistribute it and/or modify it under
86 the same terms as Perl itself, i.e. under the terms of either the GNU
87 General Public License or the Artistic License, as specified in the
88 \&\fILICENCE\fR file.
89 .PP
90 Steve Hay <[email protected] <mailto:[email protected]>> is now maintaining
91 libnet as of version 1.22_02.
92 .SS Disclaimer
93 .IX Subsection "Disclaimer"
94 This information is offered in good faith and in the hope that it may
95 be of use, but is not guaranteed to be correct, up to date, or suitable
96 for any particular purpose whatsoever. The authors accept no liability
97 in respect of this information or its use.
98 .SH "Obtaining and installing libnet"
99 .IX Header "Obtaining and installing libnet"
100 .SS "What is libnet ?"
101 .IX Subsection "What is libnet ?"
102 libnet is a collection of perl5 modules which all related to network
103 programming. The majority of the modules available provided the
104 client side of popular server\-client protocols that are used in
105 the internet community.
106 .SS "Which version of perl do I need ?"
107 .IX Subsection "Which version of perl do I need ?"
108 This version of libnet requires Perl 5.8.1 or higher.
109 .SS "What other modules do I need ?"
110 .IX Subsection "What other modules do I need ?"
111 No non\-core modules are required for normal use, except on os390,
112 which requires Convert::EBCDIC.
113 .PP
114 Authen::SASL is required for AUTH support.
115 .PP
116 IO::Socket::SSL version 2.007 or higher is required for SSL support.
117 .PP
118 IO::Socket::IP version 0.25 or IO::Socket::INET6 version 2.62 is
119 required for IPv6 support.
120 .SS "What machines support libnet ?"
121 .IX Subsection "What machines support libnet ?"
122 libnet itself is an entirely perl\-code distribution so it should work
123 on any machine that perl runs on.
124 .SS "Where can I get the latest libnet release"
125 .IX Subsection "Where can I get the latest libnet release"
126 The latest libnet release is always on CPAN, you will find it
127 in
128 .PP
129 <https://metacpan.org/release/libnet>
130 .SH "Using Net::FTP"
131 .IX Header "Using Net::FTP"
132 .SS "How do I download files from an FTP server ?"
133 .IX Subsection "How do I download files from an FTP server ?"
134 An example taken from an article posted to comp.lang.perl.misc
135 .PP
136 .Vb 1
137 \& #!/your/path/to/perl
138 \&
139 \& # a module making life easier
140 \&
141 \& use Net::FTP;
142 \&
143 \& # for debugging: $ftp = Net::FTP\->new(\*(Aqsite\*(Aq,\*(AqDebug\*(Aq,10);
144 \& # open a connection and log in!
145 \&
146 \& $ftp = Net::FTP\->new(\*(Aqtarget_site.somewhere.xxx\*(Aq);
147 \& $ftp\->login(\*(Aqusername\*(Aq,\*(Aqpassword\*(Aq);
148 \&
149 \& # set transfer mode to binary
150 \&
151 \& $ftp\->binary();
152 \&
153 \& # change the directory on the ftp site
154 \&
155 \& $ftp\->cwd(\*(Aq/some/path/to/somewhere/\*(Aq);
156 \&
157 \& foreach $name (\*(Aqfile1\*(Aq, \*(Aqfile2\*(Aq, \*(Aqfile3\*(Aq) {
158 \&
159 \& # get\*(Aqs arguments are in the following order:
160 \& # ftp server\*(Aqs filename
161 \& # filename to save the transfer to on the local machine
162 \& # can be simply used as get($name) if you want the same name
163 \&
164 \& $ftp\->get($name,$name);
165 \& }
166 \&
167 \& # ftp done!
168 \&
169 \& $ftp\->quit;
170 .Ve
171 .SS "How do I transfer files in binary mode ?"
172 .IX Subsection "How do I transfer files in binary mode ?"
173 To transfer files without <LF><CR> translation Net::FTP provides
174 the \f(CW\*(C`binary\*(C'\fR method
175 .PP
176 .Vb 1
177 \& $ftp\->binary;
178 .Ve
179 .SS "How can I get the size of a file on a remote FTP server ?"
180 .IX Subsection "How can I get the size of a file on a remote FTP server ?"
181 .SS "How can I get the modification time of a file on a remote FTP server ?"
182 .IX Subsection "How can I get the modification time of a file on a remote FTP server ?"
183 .SS "How can I change the permissions of a file on a remote server ?"
184 .IX Subsection "How can I change the permissions of a file on a remote server ?"
185 The FTP protocol does not have a command for changing the permissions
186 of a file on the remote server. But some ftp servers may allow a chmod
187 command to be issued via a SITE command, eg
188 .PP
189 .Vb 1
190 \& $ftp\->quot(\*(Aqsite chmod 0777\*(Aq,$filename);
191 .Ve
192 .PP
193 But this is not guaranteed to work.
194 .SS "Can I do a reget operation like the ftp command ?"
195 .IX Subsection "Can I do a reget operation like the ftp command ?"
196 .SS "How do I get a directory listing from an FTP server ?"
197 .IX Subsection "How do I get a directory listing from an FTP server ?"
198 .SS "Changing directory to """" does not fail ?"
199 .IX Subsection "Changing directory to """" does not fail ?"
200 Passing an argument of "" to \->\fBcwd()\fR has the same affect of calling \->\fBcwd()\fR
201 without any arguments. Turn on Debug (\fISee below\fR) and you will see what is
202 happening
203 .PP
204 .Vb 3
205 \& $ftp = Net::FTP\->new($host, Debug => 1);
206 \& $ftp\->login;
207 \& $ftp\->cwd("");
208 .Ve
209 .PP
210 gives
211 .PP
212 .Vb 2
213 \& Net::FTP=GLOB(0x82196d8)>>> CWD /
214 \& Net::FTP=GLOB(0x82196d8)<<< 250 CWD command successful.
215 .Ve
216 .SS "I am behind a SOCKS firewall, but the Firewall option does not work ?"
217 .IX Subsection "I am behind a SOCKS firewall, but the Firewall option does not work ?"
218 The Firewall option is only for support of one type of firewall. The type
219 supported is an ftp proxy.
220 .PP
221 To use Net::FTP, or any other module in the libnet distribution,
222 through a SOCKS firewall you must create a socks\-ified perl executable
223 by compiling perl with the socks library.
224 .SS "I am behind an FTP proxy firewall, but cannot access machines outside ?"
225 .IX Subsection "I am behind an FTP proxy firewall, but cannot access machines outside ?"
226 Net::FTP implements the most popular ftp proxy firewall approach. The scheme
227 implemented is that where you log in to the firewall with \f(CW\*(C`user@hostname\*(C'\fR
228 .PP
229 I have heard of one other type of firewall which requires a login to the
230 firewall with an account, then a second login with \f(CW\*(C`user@hostname\*(C'\fR. You can
231 still use Net::FTP to traverse these firewalls, but a more manual approach
232 must be taken, eg
233 .PP
234 .Vb 3
235 \& $ftp = Net::FTP\->new($firewall) or die $@;
236 \& $ftp\->login($firewall_user, $firewall_passwd) or die $ftp\->message;
237 \& $ftp\->login($ext_user . \*(Aq@\*(Aq . $ext_host, $ext_passwd) or die $ftp\->message.
238 .Ve
239 .SS "My ftp proxy firewall does not listen on port 21"
240 .IX Subsection "My ftp proxy firewall does not listen on port 21"
241 FTP servers usually listen on the same port number, port 21, as any other
242 FTP server. But there is no reason why this has to be the case.
243 .PP
244 If you pass a port number to Net::FTP then it assumes this is the port
245 number of the final destination. By default Net::FTP will always try
246 to connect to the firewall on port 21.
247 .PP
248 Net::FTP uses IO::Socket to open the connection and IO::Socket allows
249 the port number to be specified as part of the hostname. So this problem
250 can be resolved by either passing a Firewall option like \f(CW"hostname:1234"\fR
251 or by setting the \f(CW\*(C`ftp_firewall\*(C'\fR option in Net::Config to be a string
252 in the same form.
253 .SS "Is it possible to change the file permissions of a file on an FTP server ?"
254 .IX Subsection "Is it possible to change the file permissions of a file on an FTP server ?"
255 The answer to this is "maybe". The FTP protocol does not specify a command to change
256 file permissions on a remote host. However many servers do allow you to run the
257 chmod command via the \f(CW\*(C`SITE\*(C'\fR command. This can be done with
258 .PP
259 .Vb 1
260 \& $ftp\->site(\*(Aqchmod\*(Aq,\*(Aq0775\*(Aq,$file);
261 .Ve
262 .SS "I have seen scripts call a method message, but cannot find it documented ?"
263 .IX Subsection "I have seen scripts call a method message, but cannot find it documented ?"
264 Net::FTP, like several other packages in libnet, inherits from Net::Cmd, so
265 all the methods described in Net::Cmd are also available on Net::FTP
266 objects.
267 .SS "Why does Net::FTP not implement mput and mget methods"
268 .IX Subsection "Why does Net::FTP not implement mput and mget methods"
269 The quick answer is because they are easy to implement yourself. The long
270 answer is that to write these in such a way that multiple platforms are
271 supported correctly would just require too much code. Below are
272 some examples how you can implement these yourself.
273 .PP
274 sub mput {
275 my($ftp,$pattern) = \f(CW@_\fR;
276 foreach my \f(CW$file\fR (glob($pattern)) {
277 \f(CW$ftp\fR\->put($file) or warn \f(CW$ftp\fR\->message;
278 }
279 }
280 .PP
281 sub mget {
282 my($ftp,$pattern) = \f(CW@_\fR;
283 foreach my \f(CW$file\fR ($ftp\->ls($pattern)) {
284 \f(CW$ftp\fR\->get($file) or warn \f(CW$ftp\fR\->message;
285 }
286 }
287 .SH "Using Net::SMTP"
288 .IX Header "Using Net::SMTP"
289 .SS "Why can\*(Aqt the part of an Email address after the @ be used as the hostname ?"
290 .IX Subsection "Why can't the part of an Email address after the @ be used as the hostname ?"
291 The part of an Email address which follows the @ is not necessarily a hostname,
292 it is a mail domain. To find the name of a host to connect for a mail domain
293 you need to do a DNS MX lookup
294 .SS "Why does Net::SMTP not do DNS MX lookups ?"
295 .IX Subsection "Why does Net::SMTP not do DNS MX lookups ?"
296 Net::SMTP implements the SMTP protocol. The DNS MX lookup is not part
297 of this protocol.
298 .SS "The verify method always returns true ?"
299 .IX Subsection "The verify method always returns true ?"
300 Well it may seem that way, but it does not. The verify method returns true
301 if the command succeeded. If you pass verify an address which the
302 server would normally have to forward to another machine, the command
303 will succeed with something like
304 .PP
305 .Vb 1
306 \& 252 Couldn\*(Aqt verify <someone@there> but will attempt delivery anyway
307 .Ve
308 .PP
309 This command will fail only if you pass it an address in a domain
310 the server directly delivers for, and that address does not exist.
311 .SH "Debugging scripts"
312 .IX Header "Debugging scripts"
313 .SS "How can I debug my scripts that use Net::* modules ?"
314 .IX Subsection "How can I debug my scripts that use Net::* modules ?"
315 Most of the libnet client classes allow options to be passed to the
316 constructor, in most cases one option is called \f(CW\*(C`Debug\*(C'\fR. Passing
317 this option with a non\-zero value will turn on a protocol trace, which
318 will be sent to STDERR. This trace can be useful to see what commands
319 are being sent to the remote server and what responses are being
320 received back.
321 .PP
322 .Vb 1
323 \& #!/your/path/to/perl
324 \&
325 \& use Net::FTP;
326 \&
327 \& my $ftp = new Net::FTP($host, Debug => 1);
328 \& $ftp\->login(\*(Aqgbarr\*(Aq,\*(Aqpassword\*(Aq);
329 \& $ftp\->quit;
330 .Ve
331 .PP
332 this script would output something like
333 .PP
334 .Vb 6
335 \& Net::FTP: Net::FTP(2.22)
336 \& Net::FTP: Exporter
337 \& Net::FTP: Net::Cmd(2.0801)
338 \& Net::FTP: IO::Socket::INET
339 \& Net::FTP: IO::Socket(1.1603)
340 \& Net::FTP: IO::Handle(1.1504)
341 \&
342 \& Net::FTP=GLOB(0x8152974)<<< 220 imagine FTP server (Version wu\-2.4(5) Tue Jul 29 11:17:18 CDT 1997) ready.
343 \& Net::FTP=GLOB(0x8152974)>>> user gbarr
344 \& Net::FTP=GLOB(0x8152974)<<< 331 Password required for gbarr.
345 \& Net::FTP=GLOB(0x8152974)>>> PASS ....
346 \& Net::FTP=GLOB(0x8152974)<<< 230 User gbarr logged in. Access restrictions apply.
347 \& Net::FTP=GLOB(0x8152974)>>> QUIT
348 \& Net::FTP=GLOB(0x8152974)<<< 221 Goodbye.
349 .Ve
350 .PP
351 The first few lines tell you the modules that Net::FTP uses and their versions,
352 this is useful data to me when a user reports a bug. The last seven lines
353 show the communication with the server. Each line has three parts. The first
354 part is the object itself, this is useful for separating the output
355 if you are using multiple objects. The second part is either \f(CW\*(C`<<<<\*(C'\fR to
356 show data coming from the server or \f(CW\*(C`&gt&gt&gt&gt\*(C'\fR to show data
357 going to the server. The remainder of the line is the command
358 being sent or response being received.
359 .SH "AUTHOR AND COPYRIGHT"
360 .IX Header "AUTHOR AND COPYRIGHT"
361 Copyright (C) 1997\-1998 Graham Barr. All rights reserved.