1FTPSSL(3) User Contributed Perl Documentation FTPSSL(3)
2
6 Net::FTPSSL - A FTP over SSL/TLS class
7
10 use Net::FTPSSL;
11 my $ftps = Net::FTPSSL->new('ftp.yoursecureserver.com',
13 Port => 21,
14 Encryption => EXP_CRYPT,
15 Debug => 1)
16 or die "Can't open ftp.yoursecureserver.com";
17 $ftps->login('anonymous', 'user@localhost')
19 or die "Can't login: ", $ftps->last_message();
20 $ftps->cwd("/pub") or die "Can't change directory: " . $ftps->last_message();
22 $ftps->get("file") or die "Can't get file: " . $ftps->last_message();
24 $ftps->quit();
26 Had you included Croak => 1 as an option to new, you could have left
28 off the or die checks and your die messages would be more specific to
29 the actual problem encountered!
30
32 "Net::FTPSSL" is a class implementing a simple FTP client over a Secure
33 Sockets Layer (SSL) or Transport Layer Security (TLS) connection
34 written in Perl as described in RFC959 and RFC2228. It will use TLS by
35 default.
36
38 new( HOST [, OPTIONS ] )
39 Creates a new Net::FTPSSL object and opens a connection with the
40 "HOST". "HOST" is the address of the FTP server and it's a required
41 argument. OPTIONS are passed in a hash like fashion, using key and
42 value pairs.
43 If it can't create a new Net::FTPSSL object, it will return undef
45 unless you set the Croak option. In either case you will find the
46 cause of the failure in $Net::FTPSSL::ERRSTR.
47 "OPTIONS" are:
49 Encryption - The connection can be implicitly (IMP_CRYPT)
51 encrypted, explicitly (EXP_CRYPT) encrypted, or regular FTP
52 (CLR_CRYPT). In explicit cases the connection begins clear and
53 became encrypted after an "AUTH" command is sent, while implicit
54 starts off encrypted. For CLR_CRYPT, the connection never becomes
55 encrypted. Default value is EXP_CRYPT.
56 Port - The port number to connect to on the remote FTPS server.
58 The default port is 21 for EXP_CRYPT and CLR_CRYPT. But for
59 IMP_CRYPT the default port is 990. You only need to provide a port
60 if you need to override the default value.
61 DataProtLevel - The level of security on the data channel. The
63 default is DATA_PROT_PRIVATE, where the data is also encrypted.
64 DATA_PROT_CLEAR is for data sent as clear text. DATA_PROT_SAFE and
65 DATA_PROT_CONFIDENTIAL are not currently supported. If CLR_CRYPT
66 was selected, the data channel is always DATA_PROT_CLEAR and can't
67 be overridden.
68 useSSL - Use this option to connect to the server using SSL instead
70 of TLS. TLS is the default encryption type and the more secure of
71 the two protocols. Set useSSL => 1 to use SSL.
72 Timeout - Set a connection timeout value. Default value is 120.
74 PreserveTimestamp - During all puts and gets, attempt to preserve
76 the file's timestamp. By default it will not preserve the
77 timestamps.
78 Buffer - This is the block size that Net::FTPSSL will use when a
80 transfer is made. Default value is 10240.
81 Trace - Turns on/off put/get download tracing to STDERR. Default
83 is off.
84 Debug - This turns the debug tracing option on/off. Default is off.
86 (0,1,2)
87 DebugLogFile - Redirects the output of Debug from STDERR to the
89 requested error log file name. This option is ignored unless Debug
90 is also turned on. Enforced this way for backwards compatability.
91 If Debug is set to 2, the log file will be opened in append mode
92 instead of creating a new log file. This file is closed when quit
93 is called and Debug messages go back to STDERR again afterwards.
94 Croak - Force most methods to call croak() on failure instead of
96 returning FALSE. The default is to return FALSE or undef on
97 failure. When it croaks, it will attempt to close the FTPS
98 connection as well, preserving the last message before it attempts
99 to close the connection. Allowing the server to know the client is
100 going away. This will cause $Net::FTPSSL::ERRSTR to be set as
101 well.
102 SSL_Advanced - Expects a reference to a hash. This feature is
104 totally unsupported. It is only provided so you can attempt to use
105 the more obscure options when start_SSL() is called. If an option
106 here conflicts with other options we would normally use, entries in
107 this hash take precedence. See IO::Socket::SSL for these options.
108
110 Most of the methods return true or false, true when the operation was a
111 success and false when failed. Methods like list or nlst return an
112 empty array when they fail. This behavior can be modified by the Croak
113 option.
114 login( USER, PASSWORD )
116 Use the given information to log into the FTPS server.
117 quit()
119 This method breaks the connection to the FTPS server. It will also
120 close the file pointed to by option DebugLogFile.
121 list( [DIRECTORY [, PATTERN]] )
123 This method returns a list of files in a format simalar to this:
124 (Server Specific)
125 drwxrwx--- 1 owner group 512 May 31 11:16 .
127 drwxrwx--- 1 owner group 512 May 31 11:16 ..
128 drwxrwx--- 1 owner group 512 Oct 27 2004 foo
129 drwxrwx--- 1 owner group 512 Oct 27 2004 pub
130 drwxrwx--- 1 owner group 512 Mar 29 12:09 bar
131 If DIRECTORY is omitted, the method will return the list of the
133 current directory.
134 If PATTERN is provided, it would limit the result similar to the
136 unix ls command or the Windows dir command. The only wild cards
137 supported are * and ?. (Match 0 or more chars. Or any one char.)
138 So a pattern of f*, ?Oo or FOO would find just foo from the list
139 above. Files with spaces in their name can cause strange results
140 when searching for a pattern.
141 nlst( [DIRECTORY [, PATTERN]] )
143 Same as "list" but returns the list in this format:
144 foo
146 pub
147 bar
148 Spaces in the filename do not cause problems with the PATTERN with
150 "nlst". Personally, I suggest using nlst instead of list.
151 ascii()
153 Sets the file transfer mode to ASCII. CR LF transformations will
154 be done.
155 binary()
157 Sets the file transfer mode to binary. No transformation will be
158 done.
159 get( REMOTE_FILE, [LOCAL_FILE] )
161 Retrieves the REMOTE_FILE from the ftp server. LOCAL_FILE may be a
162 filename or a filehandle. Return undef if it fails.
163 If the option PreserveTimestamp was used, and the FTPS server
165 supports it, it will attempt to reset the timestamp on LOCAL_FILE
166 to the timestamp on REMOTE_FILE.
167 put( LOCAL_FILE, [REMOTE_FILE] )
169 Stores the LOCAL_FILE onto the remote ftp server. LOCAL_FILE may be
170 a filehandle, but in this case REMOTE_FILE is required. Return
171 undef if it fails.
172 If the option PreserveTimestamp was used, and the FTPS server
174 supports it, it will attempt to reset the timestamp on REMOTE_FILE
175 to the timestamp on LOCAL_FILE.
176 uput( LOCAL_FILE, [REMOTE_FILE] )
178 Stores the LOCAL_FILE onto the remote ftp server. LOCAL_FILE may be
179 a filehandle, but in this case REMOTE_FILE is required. If
180 REMOTE_FILE already exists on the ftps server, a unique name is
181 calculated for use instead.
182 If the file transfer succeeds, this function will return the actual
184 name used on the remote ftps server. If it can't figure that out,
185 it will return what was used for REMOTE_FILE. On failure this
186 method will return undef.
187 If the option PreserveTimestamp was used, and the FTPS server
189 supports it, it will attempt to reset the timestamp on the remote
190 file using the file name being returned by this function to the
191 timestamp on LOCAL_FILE. So if the wrong name is being returned,
192 the wrong file will get it's timestamp updated.
193 xput( LOCAL_FILE, [REMOTE_FILE, [PREFIX, [POSTFIX, [BODY]]]] )
195 Use when the directory you are dropping REMOTE_FILE into is
196 monitored by a file recognizer that might pick the file up before
197 the file transfer has completed. So the file is transferred using
198 a temporary name using a naming convention that the file recognizer
199 will ignore and is guaranteed to be unique. Once the file transfer
200 successfully completes, it will be renamed to REMOTE_FILE for
201 immediate pickup by the file recognizer. If you requested to
202 preserve the file's timestamp, this step is done after the file is
203 renamed and so can't be 100% guaranteed if the file recognizer
204 picks it up first. Since if it was done before the rename, other
205 more serious problems could crop up if the resulting timestamp was
206 old enough.
207 On failure this function will attempt to delete the scratch file
209 for you if its at all possible. You will have to talk to your FTP
210 server administrator on good values for PREFIX and POSTFIX if the
211 defaults are no good for you.
212 PREFIX defaults to _tmp. unless you override it. Set to "" if you
214 need to suppress the PREFIX. This PREFIX can be a path to another
215 directory if needed, but that directory must already exist! Set to
216 undef to keep this default and you need to change the default for
217 POSTFIX or BODY.
218 POSTFIX defaults to .tmp unless you override it. Set to "" if you
220 need to suppress the POSTFIX. Set to undef to keep this default
221 and you need to change the default for BODY.
222 BODY defaults to client-name.PID so that you are guaranteed the
224 temp file will have an unique name on the remote server. It is
225 strongly recommended that you don't override this value.
226 So the temp scratch file would be called something like this by
228 default: _tmp.testclient.51243.tmp.
229 As a final note, if REMOTE_FILE has path information in it's name,
231 the temp scratch file will have the same directory added to it
232 unless you override the PREFIX with a different directory to drop
233 the scratch file into. This avoids forcing you to change into the
234 requested directory first when you have multiple files to send out
235 into multiple directories.
236 xget( REMOTE_FILE, [LOCAL_FILE, [PREFIX, [POSTFIX, [BODY]]]] )
238 The inverse of xput, where the file recognizer is on the client
239 side. The only other difference being what BODY defaults to. It
240 defaults to reverse(testclient).PID. So your default scratch file
241 would be something like: _tmp.tneilctset.51243.tmp.
242 Just be aware that in this case LOCAL_FILE can no longer be a file
244 handle.
245 delete( REMOTE_FILE )
247 Deletes the indicated REMOTE_FILE.
248 cwd( DIR )
250 Attempts to change directory to the directory given in DIR on the
251 remote server.
252 pwd()
254 Returns the full pathname of the current directory on the remote
255 server.
256 cdup()
258 Changes directory to the parent of the current directory on the
259 remote server.
260 mkdir( DIR )
262 Creates the indicated directory DIR on the remote server. No
263 recursion at the moment.
264 rmdir( DIR )
266 Removes the empty indicated directory DIR on the remote server. No
267 recursion at the moment.
268 noop()
270 It specifies no action other than the server send an OK reply.
271 rename( OLD, NEW )
273 Allows you to rename the file on the remote server.
274 ccc( [ DataProtLevel ] )
276 Sends the clear command channel request to the FTPS server. If you
277 provide the DataProtLevel, it will change it from the current data
278 protection level to this one before it sends the CCC command.
279 After the CCC command, the data channel protection level can not be
280 changed again and will always remain at this setting. Once you
281 execute the CCC request, you will have to create a new Net::FTPSSL
282 object to secure the command channel again. Due to security
283 concerns it is recommended that you do not use this method.
284 If the version of IO::Socket::SSL you have installed is too old,
286 this function will not work since stop_SSL won't be defined (like
287 in v1.08). So it is recommended that you be on at least version
288 1.18 or later if you plan on using this function.
289 site( ARGS )
291 Send a SITE command to the remote server and wait for a response.
292 mfmt( time_str, remote_file ) or _mfmt( timestamp, remote_file )
294 Both are boolean functions that attempt to reset the remote file's
295 timestamp on the FTPS server and returns true on success. The 1st
296 version can call croak on failure if Croak is turned on, while the
297 2nd version will not do this. The other difference between these
298 two functions is the format of the file's timestamp to use.
299 time_str expects the timestamp to be GMT time in format
301 YYYYMMDDHHMMSS. While timestamp expects to be in the same format
302 as returned by localtime().
303 mdtm( remote_file ) or _mdtm( remote_file )
305 The 1st version returns the file's timestamp as a string in
306 YYYYMMDDHHMMSS format using GMT time, it will return undef or call
307 croak on failure.
308 The 2nd version returns the file's timestamp in the same format as
310 returned by localtime() and will never call croak.
311 size( remote_file )
313 This function will return undef or croak on failure. Otherwise it
314 will return the file's size in bytes, which may also be zero bytes!
315 Just be aware for text files that the size returned may not match
316 the file's actual size when the file is downloaded to your system
317 in ASCII mode. This is an OS specific issue. It will always match
318 if you are using BINARY mode.
319 supported( CMD [,SITE_OPT] )
321 Returns TRUE if the remote server supports the given command. CMD
322 must match exactly. If the CMD is SITE and SITE_OPT is supplied,
323 it will also check if the specified SITE_OPT sub-command is
324 supported. Not all servers will support the use of SITE_OPT. This
325 function ignores the Croak request.
326 quot( CMD [,ARGS] )
328 Send a command, that Net::FTPSSL does not directly support, to the
329 remote server and wait for a response. You are responsible for
330 parsing anything you need from message() yourself.
331 Returns the most significant digit of the response code. So it
333 will ignore the Croak request.
334 WARNING This call should only be used on commands that do not
336 require data connections. Misuse of this method can hang the
337 connection if the internal list of FTP commands using a data
338 channel is incomplete.
339 last_message() or message()
341 Use either one to collect the last response from the FTPS server.
342 This is the same response printed to STDERR when Debug is turned
343 on. It may also contain any fatal error message encountered.
344 If you couldn't create a Net::FTPSSL object, you should get your
346 error message from $Net::FTPSSL::ERRSTR instead. Be careful since
347 $Net::FTPSSL::ERRSTR is shared between instances of Net::FTPSSL,
348 while message & last_message are not shared between instances!
349 last_status_code()
351 Returns the one digit status code associated with the last response
352 from the FTPS server.
353 set_croak( [1/0] )
355 Used to turn the Croak option on/off after the Net::FTPSSL object
356 has been created. It returns the previous Croak settings before
357 the change is made. If you don't provide an argument, all it does
358 is return the current setting. Provided in case the Croak option
359 proves to be too restrictive in some cases.
360 set_callback( [cb_func_ref, end_cb_func_ref [, cb_data_ref]] )
362 This function allows the user to define a callback function to use
363 whenever a data channel to the server is open. If either
364 cb_func_ref or end_cb_func_ref is undefined, it disables the
365 callback functionality, since both are required for call backs to
366 function properly.
367 The cb_func_ref is a reference to a function to handle processing
369 the data channel data. This is a void function that can be called
370 multiple times. It is called each time a chunk of data is read
371 from or written to the data channel.
372 The end_cb_func_ref is a reference to a function to handle closing
374 the callback for this data channel connection. This function is
375 allowed to return a string of additional data to process before the
376 data channel is closed. It is called only once per command after
377 processing all the data channel data.
378 The cb_data_ref is an optional reference to an array or hash that
380 the caller can use to store values between calls to the callback
381 function and the end callback function. If you don't need such a
382 work area, it's safe to not provide one. The Net::FTPSSL class
383 doesn't look at this reference.
384 The callback function must take the following 5 arguments:
386 B<callback> (ftps_func_name, data_ref, data_len_ref, total_len, cb_data_ref);
388 The ftps_func_name will tell what Net::FTPSSL function requested
390 the callback so that your callback function can determine what the
391 data is for and do conditional logic accordingly. We don't provide
392 a reference to the Net::FTPSSL object itself since the class is not
393 recursive. Each Net::FTPSSL object should have it's own cb_dat_ref
394 to work with. But methods within the class can share one.
395 Since we pass the data going through the data channel as a
397 reference, you are allowed to modify the data. But if you do, be
398 sure to update data_len_ref to the new data length as well.
399 Otherwise you will get buggy responses.
400 Finally, the total_len is how many bytes have already been
402 processed. It does not include the data passed for the current
403 callback call. So it will always be zero the first time it's
404 called.
405 Once we finish processing data for the data channel, a different
407 callback function will be called to tell you that the data channel
408 is closing. This is your last chance to affect what is going over
409 the data channel and to do any needed post processing. The end
410 callback function must take the following arguments:
411 $end = B<end_callback> (ftps_func_name, total_len, cb_data_ref);
413 These arguments have the same meaning as for the callback function,
415 except that this function allows you to optionally provide
416 additional data to/from the data channel. If reading from the data
417 channel, it will treat the return value as the last data returned
418 before it was closed. Otherwise it will be written to the data
419 channel before it is closed. Please return undef if there is
420 nothing extra for the Net::FTPSSL command to process.
421 You should also take care to clean up the contents of cb_data_ref
423 in the end_callback function. Otherwise the next callback sequence
424 that uses this work area may behave strangely.
425 As a final note, should the data channel be empty, it is likely
427 that just the end_callback function is called without any calls to
428 the callback function.
429
431 Marco Dalla Stella - <kral at paranoici dot org>
432 Curtis Leach - <cleach at cpan dot org> - As of v0.05
434
436 Net::Cmd
437 Net::FTP
439 Net::SSLeay::Handle
441 IO::Socket::SSL
443 RFC 959 - ftp://ftp.rfc-editor.org/in-notes/rfc959.txt <ftp://ftp.rfc-
445 editor.org/in-notes/rfc959.txt>
446 RFC 2228 - ftp://ftp.rfc-editor.org/in-notes/rfc2228.txt
448 <ftp://ftp.rfc-editor.org/in-notes/rfc2228.txt>
449 RFC 4217 - ftp://ftp.rfc-editor.org/in-notes/rfc4217.txt
451 <ftp://ftp.rfc-editor.org/in-notes/rfc4217.txt>
452
454 Graham Barr <gbarr at pobox dot com> - for have written such a great
455 collection of modules (libnet).
456
458 Please report any bugs with a FTPS log file created via options
459 Debug=>1 and DebugLogFile=>"file.txt" along with your sample code at
460 http://search.cpan.org/~cleach/Net-FTPSSL-0.15/FTPSSL.pm
461 <http://search.cpan.org/~cleach/Net-FTPSSL-0.15/FTPSSL.pm>.
462 Patches are appreciated when a log file and sample code are also
464 provided.
465
467 Copyright (c) 2005 Marco Dalla Stella. All rights reserved.
468 Copyright (c) 2009, 2010 Curtis Leach. All rights reserved.
470 This program is free software; you can redistribute it and/or modify it
472 under the same terms as Perl itself.
473perl v5.12.1 2010-04-27 FTPSSL(3)