Update libnet to CPAN version 3.01
[perl.git] / cpan / libnet / lib / Net / libnetFAQ.pod
1 =head1 NAME
2
3 libnetFAQ - libnet Frequently Asked Questions
4
5 =head1 DESCRIPTION
6
7 =head2 Where to get this document
8
9 This document is distributed with the libnet distribution, and is also
10 available on the libnet web page at
11
12     http://search.cpan.org/dist/libnet/
13
14 =head2 How to contribute to this document
15
16 You may report corrections, additions, and suggestions on the
17 CPAN request tracker at
18
19     http://rt.cpan.org/Dist/Display.html?Name=libnet
20
21 =head1 Author and Copyright Information
22
23 Copyright (c) 1997-1998 Graham Barr. All rights reserved.
24 This document is free; you can redistribute it and/or modify it
25 under the terms of the Artistic License.
26
27 Currently maintained by Steve Hay <shay@cpan.org>.
28
29 =head2 Disclaimer
30
31 This information is offered in good faith and in the hope that it may
32 be of use, but is not guaranteed to be correct, up to date, or suitable
33 for any particular purpose whatsoever.  The authors accept no liability
34 in respect of this information or its use.
35
36
37 =head1 Obtaining and installing libnet
38
39 =head2 What is libnet ?
40
41 libnet is a collection of perl5 modules which all related to network
42 programming. The majority of the modules available provided the
43 client side of popular server-client protocols that are used in
44 the internet community.
45
46 =head2 Which version of perl do I need ?
47
48 This version of libnet requires Perl 5.8.1 or higher.
49
50 =head2 What other modules do I need ?
51
52 No non-core modules are required for normal use, except on os390,
53 which requires Convert::EBCDIC.
54
55 Authen::SASL is required for AUTH support.
56
57 IO::Socket::SSL version 1.999 or higher is required for SSL support.
58
59 IO::Socket::IP version 0.20 or IO::Socket::INET6 version 2.62 is
60 required for IPv6 support.
61
62 =head2 What machines support libnet ?
63
64 libnet itself is an entirely perl-code distribution so it should work
65 on any machine that perl runs on.
66
67 =head2 Where can I get the latest libnet release
68
69 The latest libnet release is always on CPAN, you will find it
70 in 
71
72  http://search.cpan.org/dist/libnet/
73
74 =head1 Using Net::FTP
75
76 =head2 How do I download files from an FTP server ?
77
78 An example taken from an article posted to comp.lang.perl.misc
79
80     #!/your/path/to/perl
81
82     # a module making life easier
83
84     use Net::FTP;
85
86     # for debugging: $ftp = Net::FTP->new('site','Debug',10);
87     # open a connection and log in!
88
89     $ftp = Net::FTP->new('target_site.somewhere.xxx');
90     $ftp->login('username','password');
91
92     # set transfer mode to binary
93
94     $ftp->binary();
95
96     # change the directory on the ftp site
97
98     $ftp->cwd('/some/path/to/somewhere/');
99
100     foreach $name ('file1', 'file2', 'file3') {
101
102     # get's arguments are in the following order:
103     # ftp server's filename
104     # filename to save the transfer to on the local machine
105     # can be simply used as get($name) if you want the same name
106
107       $ftp->get($name,$name);
108     }
109
110     # ftp done!
111
112     $ftp->quit;
113
114 =head2 How do I transfer files in binary mode ?
115
116 To transfer files without <LF><CR> translation Net::FTP provides
117 the C<binary> method
118
119     $ftp->binary;
120
121 =head2 How can I get the size of a file on a remote FTP server ?
122
123 =head2 How can I get the modification time of a file on a remote FTP server ?
124
125 =head2 How can I change the permissions of a file on a remote server ?
126
127 The FTP protocol does not have a command for changing the permissions
128 of a file on the remote server. But some ftp servers may allow a chmod
129 command to be issued via a SITE command, eg
130
131     $ftp->quot('site chmod 0777',$filename);
132
133 But this is not guaranteed to work.
134
135 =head2 Can I do a reget operation like the ftp command ?
136
137 =head2 How do I get a directory listing from an FTP server ?
138
139 =head2 Changing directory to "" does not fail ?
140
141 Passing an argument of "" to ->cwd() has the same affect of calling ->cwd()
142 without any arguments. Turn on Debug (I<See below>) and you will see what is
143 happening
144
145     $ftp = Net::FTP->new($host, Debug => 1);
146     $ftp->login;
147     $ftp->cwd("");
148
149 gives
150
151     Net::FTP=GLOB(0x82196d8)>>> CWD /
152     Net::FTP=GLOB(0x82196d8)<<< 250 CWD command successful.
153
154 =head2 I am behind a SOCKS firewall, but the Firewall option does not work ?
155
156 The Firewall option is only for support of one type of firewall. The type
157 supported is an ftp proxy.
158
159 To use Net::FTP, or any other module in the libnet distribution,
160 through a SOCKS firewall you must create a socks-ified perl executable
161 by compiling perl with the socks library.
162
163 =head2 I am behind an FTP proxy firewall, but cannot access machines outside ?
164
165 Net::FTP implements the most popular ftp proxy firewall approach. The scheme
166 implemented is that where you log in to the firewall with C<user@hostname>
167
168 I have heard of one other type of firewall which requires a login to the
169 firewall with an account, then a second login with C<user@hostname>. You can
170 still use Net::FTP to traverse these firewalls, but a more manual approach
171 must be taken, eg
172
173     $ftp = Net::FTP->new($firewall) or die $@;
174     $ftp->login($firewall_user, $firewall_passwd) or die $ftp->message;
175     $ftp->login($ext_user . '@' . $ext_host, $ext_passwd) or die $ftp->message.
176
177 =head2 My ftp proxy firewall does not listen on port 21
178
179 FTP servers usually listen on the same port number, port 21, as any other
180 FTP server. But there is no reason why this has to be the case.
181
182 If you pass a port number to Net::FTP then it assumes this is the port
183 number of the final destination. By default Net::FTP will always try
184 to connect to the firewall on port 21.
185
186 Net::FTP uses IO::Socket to open the connection and IO::Socket allows
187 the port number to be specified as part of the hostname. So this problem
188 can be resolved by either passing a Firewall option like C<"hostname:1234">
189 or by setting the C<ftp_firewall> option in Net::Config to be a string
190 in the same form.
191
192 =head2 Is it possible to change the file permissions of a file on an FTP server ?
193
194 The answer to this is "maybe". The FTP protocol does not specify a command to change
195 file permissions on a remote host. However many servers do allow you to run the
196 chmod command via the C<SITE> command. This can be done with
197
198   $ftp->site('chmod','0775',$file);
199
200 =head2 I have seen scripts call a method message, but cannot find it documented ?
201
202 Net::FTP, like several other packages in libnet, inherits from Net::Cmd, so
203 all the methods described in Net::Cmd are also available on Net::FTP
204 objects.
205
206 =head2 Why does Net::FTP not implement mput and mget methods
207
208 The quick answer is because they are easy to implement yourself. The long
209 answer is that to write these in such a way that multiple platforms are
210 supported correctly would just require too much code. Below are
211 some examples how you can implement these yourself.
212
213 sub mput {
214   my($ftp,$pattern) = @_;
215   foreach my $file (glob($pattern)) {
216     $ftp->put($file) or warn $ftp->message;
217   }
218 }
219
220 sub mget {
221   my($ftp,$pattern) = @_;
222   foreach my $file ($ftp->ls($pattern)) {
223     $ftp->get($file) or warn $ftp->message;
224   }
225 }
226
227
228 =head1 Using Net::SMTP
229
230 =head2 Why can't the part of an Email address after the @ be used as the hostname ?
231
232 The part of an Email address which follows the @ is not necessarily a hostname,
233 it is a mail domain. To find the name of a host to connect for a mail domain
234 you need to do a DNS MX lookup
235
236 =head2 Why does Net::SMTP not do DNS MX lookups ?
237
238 Net::SMTP implements the SMTP protocol. The DNS MX lookup is not part
239 of this protocol.
240
241 =head2 The verify method always returns true ?
242
243 Well it may seem that way, but it does not. The verify method returns true
244 if the command succeeded. If you pass verify an address which the
245 server would normally have to forward to another machine, the command
246 will succeed with something like
247
248     252 Couldn't verify <someone@there> but will attempt delivery anyway
249
250 This command will fail only if you pass it an address in a domain
251 the server directly delivers for, and that address does not exist.
252
253 =head1 Debugging scripts
254
255 =head2 How can I debug my scripts that use Net::* modules ?
256
257 Most of the libnet client classes allow options to be passed to the
258 constructor, in most cases one option is called C<Debug>. Passing
259 this option with a non-zero value will turn on a protocol trace, which
260 will be sent to STDERR. This trace can be useful to see what commands
261 are being sent to the remote server and what responses are being
262 received back.
263
264     #!/your/path/to/perl
265
266     use Net::FTP;
267
268     my $ftp = new Net::FTP($host, Debug => 1);
269     $ftp->login('gbarr','password');
270     $ftp->quit;
271
272 this script would output something like
273
274  Net::FTP: Net::FTP(2.22)
275  Net::FTP:   Exporter
276  Net::FTP:   Net::Cmd(2.0801)
277  Net::FTP:   IO::Socket::INET
278  Net::FTP:     IO::Socket(1.1603)
279  Net::FTP:       IO::Handle(1.1504)
280
281  Net::FTP=GLOB(0x8152974)<<< 220 imagine FTP server (Version wu-2.4(5) Tue Jul 29 11:17:18 CDT 1997) ready.
282  Net::FTP=GLOB(0x8152974)>>> user gbarr
283  Net::FTP=GLOB(0x8152974)<<< 331 Password required for gbarr.
284  Net::FTP=GLOB(0x8152974)>>> PASS ....
285  Net::FTP=GLOB(0x8152974)<<< 230 User gbarr logged in.  Access restrictions apply.
286  Net::FTP=GLOB(0x8152974)>>> QUIT
287  Net::FTP=GLOB(0x8152974)<<< 221 Goodbye.
288
289 The first few lines tell you the modules that Net::FTP uses and their versions,
290 this is useful data to me when a user reports a bug. The last seven lines
291 show the communication with the server. Each line has three parts. The first
292 part is the object itself, this is useful for separating the output
293 if you are using multiple objects. The second part is either C<<<<<> to
294 show data coming from the server or C<&gt&gt&gt&gt> to show data
295 going to the server. The remainder of the line is the command
296 being sent or response being received.
297
298 =head1 AUTHOR AND COPYRIGHT
299
300 Copyright (c) 1997 Graham Barr.
301 All rights reserved.
302