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