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