1FTPSSL(3) User Contributed Perl Documentation FTPSSL(3)
2
6 Net::FTPSSL - A FTP over TLS/SSL class
7
10 use Net::FTPSSL;
11 my $ftps = Net::FTPSSL->new('ftp.your-secure-server.com',
13 Encryption => EXP_CRYPT,
14 Debug => 1, DebugLogFile => "myLog.txt",
15 Croak => 1);
16 $ftps->trapWarn (); # Only call if opening a CPAN bug report.
18 $ftps->login('anonymous', 'user@localhost');
20 $ftps->cwd("/pub");
22 $ftps->get("file");
24 $ftps->quit();
26 Since I included Croak => 1 as an option to new, it automatically
28 called die for me if any Net::FTPSSL command failed. So there was no
29 need for any messy error checking in my code example!
30
32 "Net::FTPSSL" is a class implementing a simple FTP client over a
33 Transport Layer Security (TLS) or Secure Sockets Layer (SSL) connection
34 written in Perl as described in RFC959 and RFC2228. It will use TLS
35 v1.2 by default, since TLS is more secure than SSL. But if you wish to
36 downgrade you may use SSL_version to do so.
37
39 new( HOST [, OPTIONS ] )
40 Creates a new Net::FTPSSL object and opens a connection with the
41 "HOST". "HOST" is the address of the FTPS server and it's a
42 required argument. OPTIONS are passed in a hash like fashion, using
43 key and value pairs. If you wish you can also pass OPTIONS as a
44 hash reference.
45 If it can't create a new Net::FTPSSL object, it will return undef
47 unless you set the Croak option. In either case you will find the
48 cause of the failure in $Net::FTPSSL::ERRSTR.
49 "OPTIONS" are:
51 Encryption - The connection can be implicitly (IMP_CRYPT)
53 encrypted, explicitly (EXP_CRYPT) encrypted, or regular FTP
54 (CLR_CRYPT). In explicit cases the connection begins clear and
55 became encrypted after an "AUTH" command is sent, while implicit
56 starts off encrypted. For CLR_CRYPT, the connection never becomes
57 encrypted. Default value is EXP_CRYPT.
58 Port - The port number to connect to on the remote FTPS server.
60 The default port is 21 for EXP_CRYPT and CLR_CRYPT. But for
61 IMP_CRYPT the default port is 990. You only need to provide a port
62 if you need to override the default value.
63 DataProtLevel - The level of security on the data channel. The
65 default is DATA_PROT_PRIVATE, where the data is also encrypted.
66 DATA_PROT_CLEAR is for data sent as clear text. DATA_PROT_SAFE and
67 DATA_PROT_CONFIDENTIAL are not currently supported. If CLR_CRYPT
68 was selected, the data channel is always DATA_PROT_CLEAR and can't
69 be overridden.
70 ProxyArgs - A hash reference to pass to the proxy server. When a
72 proxy server is encountered, this class uses Net::HTTPTunnel to get
73 through to the server you need to talk to. See Net::HTTPTunnel for
74 what values are supported. Options remote-host and remote-port are
75 hard coded to the same values as provided by HOST and PORT above
76 and cannot be overridden.
77 PreserveTimestamp - During all puts and gets, attempt to preserve
79 the file's timestamp. By default it will not preserve the
80 timestamps.
81 Set to a value > zero if the MDTM & MFMT commands properly use GMT.
83 Set to a value < zero if the server incorrectly uses it's local
84 time zone instead. Using the wrong value can result in really
85 wacky modify times on your files if you choose the wrong one for
86 your server. t/10-complex.t does include a test to try to guess
87 which one the server uses.
88 Pret - Set if you are talking to a distributed FTPS server like
90 DrFtpd that needs a PRET command issued before all calls to PASV.
91 You only need to use this option if the server barfs at the PRET
92 auto-detect logic.
93 Trace - Turns on/off (1/0) put/get download tracing to STDERR. The
95 default is off.
96 Debug - This turns the debug tracing option on/off. Default is off.
98 (0,1,2)
99 DebugLogFile - Redirects the output of Debug from STDERR to the
101 requested error log file name. This option is ignored unless Debug
102 is also turned on. Enforced this way for backwards compatibility.
103 If Debug is set to 2, the log file will be opened in append mode
104 instead of creating a new log file. This log file is closed when
105 this class instance goes out of scope.
106 Instead of a file name, you may instead specify an open file handle
108 or GLOB and it will write the logs there insead. (Not really
109 recommended.)
110 Croak - Force most methods to call croak() on failure instead of
112 returning FALSE. The default is to return FALSE or undef on
113 failure. When it croaks, it will attempt to close the FTPS
114 connection as well, preserving the last message before it attempts
115 to close the connection. Allowing the server to know the client is
116 going away. This will cause $Net::FTPSSL::ERRSTR to be set as
117 well.
118 ReuseSession - Tells the FTP/S server that we wish to reuse the
120 command channel session for all data channel connections.
121 (0/1/2/etc.) It defaults to 0, no reuse.
122 When requested, it will use a default session cache size of 5, but
124 you can increase the cache's size by setting the ReuseSession to a
125 larger value. Where the session cache size is (4 + the
126 ReuseSession value).
127 DisableContext - Tells the FTP/S server that we don't wish to reuse
129 the command channel context for all data channel connections.
130 (0/1) If option ReuseSession or SSL_Client_Certificate are also
131 used, this option is ignored! By default the context is always
132 reused on encrypted data channels via SSL_reuse_ctx.
133 SSL_* - SSL arguments which can be applied when start_SSL() is
135 finally called to encrypt the command channel. See IO::Socket::SSL
136 for a list of valid arguments.
137 This is an alternative to using the SSL_Client_Certificate option.
139 But any SSL_* options provided here overrides what's provided in
140 that hash.
141 SSL_Client_Certificate - Expects a reference to a hash. It's main
143 purpose is to allow you to use client certificates when talking to
144 your FTP/S server. Options here apply to the creation of the
145 command channel. And when a data channel is needed later, it uses
146 the SSL_reuse_ctx option to reuse the command channel's context.
147 See start_SSL() in IO::Socket::SSL for more details on this and
149 other options available besides those for certificates. If an
150 option provided via this hash conflicts with other options we would
151 normally use, the entries in this hash take precedence, except for
152 any direct SSL_* options provided in both places.
153 Domain - Specify the domain to use, i.e. AF_INET or AF_INET6. This
155 argument will be passed to the IO::Socket::* class when creating
156 the socket connection. It's a way to enforce using IPv4 vs IPv6
157 even when it would default to the other. Family is an accepted
158 alias for the Domain tag if you prefer it.
159 Buffer - This is the block size that Net::FTPSSL will use when a
161 transfer is made over the Data Channel. Default value is 10240. It
162 does not affect the Command Channel.
163 Timeout - Set a connection timeout value. Default value is 120.
165 xWait - Used with xput & xtransfer. Tells how long to wait after
167 the upload has completed before renaming the file. The default is
168 no wait, but if you specify a number here, it will wait that number
169 of seconds before issuing the rename command. Some servers force
170 you to wait a bit before it will honor the RNTO part of the rename
171 command.
172 LocalAddr - Local address to use for all socket connections, this
174 argument will be passed to all IO::Socket::INET calls.
175 OverridePASV - Some FTPS servers sitting behind a firewall
177 incorrectly return their local IP Address instead of their external
178 IP Address used outside the firewall where the client is. To use
179 this option to correct this problem, you must specify the correct
180 host to use for the data channel connection. This should usually
181 match what you provided as the host! But if this server also does
182 load balancing, you are out of luck. This option may not be able
183 to help you if multiple IP Addresses can be returned.
184 OverrideHELP - Some FTPS servers on encrypted connections
186 incorrectly send back part of the response to the HELP command in
187 clear text instead of it all being encrypted, breaking the command
188 channel connection. This module calls HELP internally via
189 supported() for some conditional logic, making a work around
190 necessary to be able to talk to such servers.
191 This option supports four distinct modes to support your needs.
193 You can pass a reference to an array that lists all the FTP
194 commands your sever supports, you can set it to 1 to say all
195 commands are supported, set it to 0 to say none of the commands are
196 supported, or finally set it to -1 to call FEAT instead of HELP for
197 the list of supported commands. See supported() or fix_supported()
198 for more details.
199 This option can also be usefull when your server doesn't support
201 the HELP command itself and you need to trigger some of the
202 conditional logic.
203 useSSL - This option is being depreciated in favor of
205 IO::Socket::SSL's SSL_version option. It's just a quick and dirty
206 way to downgrade your connection from TLS to SSL which is no longer
207 recommended.
208
210 Most of the methods return true or false, true when the operation was a
211 success and false when failed. Methods like list or nlst return an
212 empty array when they fail. This behavior can be modified by the Croak
213 option.
214 login( USER, PASSWORD )
216 Use the given information to log into the FTPS server.
217 quit()
219 This method breaks the connection to the FTPS server.
220 force_epsv( [1/2] )
222 Used to force EPSV instead of PASV when establishing a data
223 channel. Once this method is called, it is imposible to swap back
224 to PASV. This method should be called as soon as possible after
225 you log in if EPSV is required.
226 It does this by sending "EPSV ALL" to the server. Afterwards the
228 server will reject all EPTR, PORT and PASV commands.
229 After "EPSV ALL" is sent, it will attempt to verify your choice of
231 IP Protocol to use: 1 or 2 (v4 or v6). The default is 1. It will
232 use the selected protocol for all future EPSV calls. If you need
233 to change which protocol to use, you may call this function a
234 second time to swap to the other EPSV Protocol.
235 This method returns true if it succeeds, or false if it fails.
237 set_croak( [1/0] )
239 Used to turn the Croak option on/off after the Net::FTPSSL object
240 has been created. It returns the previous Croak settings before
241 the change is made. If you don't provide an argument, all it does
242 is return the current setting. Provided in case the Croak option
243 proves to be too restrictive in some cases.
244 list( [DIRECTORY [, PATTERN]] )
246 This method returns a list of files in a format similar to this:
247 (Server Specific)
248 drwxrwx--- 1 owner group 512 May 31 11:16 .
250 drwxrwx--- 1 owner group 512 May 31 11:16 ..
251 -rwxrwx--- 1 owner group 512 Oct 27 2004 foo
252 -rwxrwx--- 1 owner group 512 Oct 27 2004 pub
253 drwxrwx--- 1 owner group 512 Mar 29 12:09 bar
254 If DIRECTORY is omitted, the method will return the list of the
256 current directory.
257 If PATTERN is provided, it would limit the result similar to the
259 unix ls command or the Windows dir command. The only wild cards
260 supported are * and ?. (Match 0 or more chars. Or any one char.)
261 So a pattern of f*, ?Oo or FOO would find just foo from the list
262 above. Files with spaces in their name can cause strange results
263 when searching with a pattern.
264 nlst( [DIRECTORY [, PATTERN]] )
266 Same as "list" but returns the list in this format:
267 foo
269 pub
270 bar
271 Spaces in the filename do not cause problems with the PATTERN with
273 "nlst". Personally, I suggest using nlst instead of list.
274 mlsd( [DIRECTORY [, PATTERN [, FTYPE]]] )
276 Returns a list of files/directories in a standardized machine
277 readable format designed for easy parsing. Where the list of
278 features about each file/directory is defined by your FTPS server
279 and may be modifiable by you.
280 modify=20041027194930;type=file;size=28194; foo
282 modify=20041027194932;type=file;size=3201931; pub
283 modify=20180329120944;type=dir;size=256; bar
284 Spaces in the filename do not cause problems with the PATTERN with
286 "mlsd".
287 If FTYPE is provided, it does additional filtering based on type of
289 file. If the type attribute isn't returned, and FTYPE is non-zero,
290 it will filter out everything!
291 0 - All file types. (default)
292 1 - Regular Directories only.
293 2 - Regular Files only.
294 3 - Special Files only.
295 4 - Special Directories only.
296 mlst( FILE )
298 Requests the FTPS server return the feature set for the requested
299 FILE. Where FILE may be any type of file or directory exactly
300 matching the given name.
301 If the requested file/directory doesn't exist it will return undef
303 or croak. If it exists it will return the features about the file
304 the same way mlsd does, but the returned filename may contain path
305 info. Where dir is the current directory name.
306 For example if we were looking for file pub again:
308 modify=20041027194932;type=file;size=3201931; /dir/pub
309 parse_mlsx( VALUE [, LOWER_CASE_FLAG] )
311 Takes the VALUE returned by mlst or one of the array values from
312 mlsd and converts it into a hash. Where key ";file;" is the
313 filename and anything else was a feature describing the file.
314 It returns a hash reference containing the data. If the LINE isn't
316 in the proper format, it returns undef. The only key that's
317 guarenteed to exist in the hash after a successsful parse is
318 ";file;". All other keys/features returned are based on how your
319 FTPS server has been configured.
320 For example:
322 Type=File;Size=3201931; Pub
323 would return (Type=>File, Size=>3201931, ;file;=>Pub)
324 But if LOWER_CASE_FLAG was set to a non-zero value, it would then
326 convert everything except the file's name into lower case.
327 Type=File;Size=3201931; Pub
328 would return (type=>file, size=>3201931, ;file;=>Pub)
329 ascii()
331 Sets the file transfer mode to ASCII. CR LF transformations will
332 be done. ASCII is the default transfer mode.
333 binary()
335 Sets the file transfer mode to binary. No CR LF transformation will
336 be done.
337 mixedModeAI()
339 Mixture of ASCII & binary mode. The server does CR LF
340 transformations while the client side does not. (For a really
341 weird server)
342 mixedModeIA()
344 Mixture of binary & ASCII mode. The client does CR LF
345 transformations while the server side does not. (For a really
346 weird server)
347 put( LOCAL_FILE [, REMOTE_FILE [, OFFSET]] )
349 Stores the LOCAL_FILE onto the remote ftps server. LOCAL_FILE may
350 be a open IO::Handle or GLOB, but in this case REMOTE_FILE is
351 required. It returns undef if put() fails.
352 If you provide an OFFSET, this method assumes you are attempting to
354 continue with an upload that was aborted earlier. And it's your
355 responsibility to verify that it's the same file on the server you
356 tried to upload earlier. By providing the OFFSET, this function
357 will send a REST command to the FTPS Server to skip over that many
358 bytes before it starts writing to the file. This method will also
359 skip over the requested OFFSET after opening the LOCAL_FILE for
360 reading, but if passed a file handle it will assume you've already
361 positioned it correctly. If you provide an OFFSET of -1, this
362 method will calculate the offset for you by issuing a SIZE command
363 against the file on the FTPS server. So REMOTE_FILE must already
364 exist to use -1, or it's an error. It is also an error to make
365 OFFSET larger than the REMOTE_FILE.
366 If the OFFSET you provide turns out to be smaller than the current
368 size of REMOVE_FILE, the server will truncate the REMOTE_FILE to
369 that size before appending to the end of REMOTE_FILE. (This may
370 not be consistent across all FTPS Servers, so don't depend on this
371 feature without testing it first.)
372 If the option PreserveTimestamp was used, and the FTPS server
374 supports it, it will attempt to reset the timestamp on REMOTE_FILE
375 to the timestamp on LOCAL_FILE.
376 append( LOCAL_FILE [, REMOTE_FILE [, OFFSET]] )
378 Appends the LOCAL_FILE onto the REMOTE_FILE on the ftps server. If
379 REMOTE_FILE doesn't exist, the file will be created. LOCAL_FILE
380 may be a open IO::Handle or GLOB, but in this case REMOTE_FILE is
381 required and OFFSET is ignored. It returns undef if append()
382 fails.
383 If you provide an OFFSET, it will skip over that number of bytes in
385 the LOCAL_FILE except when it was a file handle, but will not send
386 a REST command to the server. It will just append to the end of
387 REMOTE_FILE on the server. You can also provide an OFFSET of -1
388 with the same limitations as with put(). If you need the REST
389 command sent to the FTPS server, use put() instead.
390 If the option PreserveTimestamp was used, and the FTPS server
392 supports it, it will attempt to reset the timestamp on REMOTE_FILE
393 to the timestamp on LOCAL_FILE.
394 uput( LOCAL_FILE, [REMOTE_FILE] )
396 Stores the LOCAL_FILE onto the remote FTPS server. LOCAL_FILE may
397 be an open IO::Handle or GLOB, but in this case REMOTE_FILE is
398 required. Do not put any path info in REMOTE_FILE! Its default is
399 LOCAL_FILE.
400 This command can be implemented differently on different FTPS
402 servers. On some servers it ignores REMOTE_FILE and just assigns
403 it a unique name. On other servers it uses REMOTE_FILE as a
404 starting point. In either case sometimes it returns the final file
405 name used and on other servers it keeps it a secret.
406 So if your FTPS server honors the REMOTE_FILE it may use that name
408 on the upload if it doesn't already exist. But if it already
409 exists, then it will generate a unique name instead.
410 If the file transfer succeeds, this function will try to return the
412 actual name used on the remote FTPS server. If the server accepts
413 the REMOTE_FILE hint and doesn't return the filename, it will
414 assume REMOTE_FILE. If it doesn't accept REMOTE_FILE and doesn't
415 return the name used, we'll return a single '?' instead. In this
416 case the request worked, but this command has no way to figure out
417 what name was generated on the remote FTPS server and we know
418 REMOTE_FILE is wrong! So we want to return a printable value that
419 will evaluate to true for success but still tell you the actual
420 name used is unknown!
421 Just be aware that spaces in the filename used on the FTPS server
423 could mean an incomplete filename is returned by this method.
424 If the option PreserveTimestamp was used, and the FTPS server
426 supports it, it will attempt to reset the timestamp on the remote
427 file using the file name being returned by this function to the
428 timestamp on LOCAL_FILE. So if the wrong name is being returned,
429 the wrong file could get its timestamp updated.
430 uput2( LOCAL_FILE, [REMOTE_FILE] )
432 A much, much slower version of uput. Only useful when regular uput
433 can't determine the actual filename used for the upload to your
434 FTPS server or it returns the wrong answer for that server. And
435 you really, really need the right filename!
436 It gets the right answer by calling nlst, uput, and then nlst
438 again. And as long as there is only one new file returned in the
439 2nd nlst call, we have the actual filename used on the FTPS server.
440 So having spaces in this filename causes no issues.
441 This function assumes you are uploading to the FTPS server's
443 current directory. Since the uput command doesn't always honor
444 REMOTE_FILE on all servers.
445 It returns undef if the upload fails. It retuns '?' if it still
447 can't figure out what the FTPS server called the file after the
448 upload (very rare and unusual). Otherwise it's the name of the
449 file on the FTPS server.
450 xput( LOCAL_FILE, [REMOTE_FILE, [PREFIX, [POSTFIX, [BODY]]]] )
452 Use when the directory you are dropping REMOTE_FILE into is
453 monitored by a file recognizer that might pick the file up before
454 the file transfer has completed. So the file is transferred using
455 a temporary name using a naming convention that the file recognizer
456 will ignore and is guaranteed to be unique. Once the file transfer
457 successfully completes, it will be renamed to REMOTE_FILE for
458 immediate pickup by the file recognizer. If you requested to
459 preserve the file's timestamp, this step is done after the file is
460 renamed and so can't be 100% guaranteed if the file recognizer
461 picks it up first. Since if it was done before the rename, other
462 more serious problems could crop up if the resulting timestamp was
463 old enough.
464 On failure this function will attempt to delete the scratch file
466 for you if its at all possible. You will have to talk to your FTPS
467 server administrator on good values for PREFIX and POSTFIX if the
468 defaults are no good for you.
469 PREFIX defaults to _tmp. unless you override it. Set to "" if you
471 need to suppress the PREFIX. This PREFIX can be a path to another
472 directory if needed, but that directory must already exist! Set to
473 undef to keep this default and you need to change the default for
474 POSTFIX or BODY.
475 POSTFIX defaults to .tmp unless you override it. Set to "" if you
477 need to suppress the POSTFIX. Set to undef to keep this default
478 and you need to change the default for BODY.
479 BODY defaults to client-name.PID so that you are guaranteed the
481 temp file will have an unique name on the remote server. It is
482 strongly recommended that you don't override this value.
483 So the temp scratch file would be called something like this by
485 default: _tmp.testclient.51243.tmp.
486 As a final note, if REMOTE_FILE has path information in it's name,
488 the temp scratch file will have the same directory added to it
489 unless you override the PREFIX with a different directory to drop
490 the scratch file into. This avoids forcing you to change into the
491 requested directory first when you have multiple files to send out
492 into multiple directories.
493 get( REMOTE_FILE [, LOCAL_FILE [, OFFSET]] )
495 Retrieves the REMOTE_FILE from the ftps server. LOCAL_FILE may be a
496 filename or a open IO::Handle or GLOB. It returns undef if get()
497 fails. You don't usually need to use OFFSET.
498 If you provide an OFFSET, this method assumes your are attempting
500 to continue with a download that was aborted earlier. And it's
501 your responsibility to verify that it's the same file you tried to
502 download earlier. By providing the OFFSET, it will send a REST
503 command to the FTPS Server to skip over that many bytes before it
504 starts downloading the file again. If you provide an OFFSET of -1,
505 this method will calculate the offset for you based on the size of
506 LOCAL_FILE using the current transfer mode. (ASCII or BINARY). It
507 is an error to set it to -1 if the LOCAL_FILE is a file handle.
508 On the client side of the download, the OFFSET will do the
510 following: Open the file and truncate everything after the given
511 OFFSET. So if you give an OFFSET that is too big, it's an error.
512 If it's too small, the file will be truncated to that OFFSET before
513 appending what's being downloaded. If the LOCAL_FILE is a file
514 handle, it will assume the file handle has already been positioned
515 to the proper OFFEST and it will not perform a truncate. Instead
516 it will just append to that file handle's current location. Just
517 beware that using huge OFFSETs in ASCII mode can be a bit slow if
518 the LOCAL_FILE needs to be truncated.
519 If the option PreserveTimestamp was used, and the FTPS Server
521 supports it, it will attempt to reset the timestamp on LOCAL_FILE
522 to the timestamp on REMOTE_FILE after the download completes.
523 xget( REMOTE_FILE, [LOCAL_FILE, [PREFIX, [POSTFIX, [BODY]]]] )
525 The inverse of xput, where the file recognizer is on the client
526 side. The only other difference being what BODY defaults to. It
527 defaults to reverse(testclient).PID. So your default scratch file
528 would be something like: _tmp.tneilctset.51243.tmp.
529 Just be aware that in this case LOCAL_FILE can no longer be a open
531 IO::Handle or glob.
532 transfer( dest_server, REMOTE_FILE [, DEST_FILE [, OFFSET]] )
534 Retrieves the REMOTE_FILE from the current ftps server and uploads
535 it to the dest_server as DEST_FILE without making any copy of the
536 file on your local file system. If DEST_FILE isn't provided, it
537 uses REMOTE_FILE on the dest_server.
538 It assumes that dest_server is an Net::FTPSSL object and you have
540 already successfully logged onto dest_server and set both ends to
541 either binary or ascii mode! So this function skips over the CR/LF
542 logic and lets the other servers handle it. You must also set the
543 Croak option to the same value on both ends.
544 Finally, if logging is turned on, the logs to this function will be
546 split between the logs on each system. So the logs may be a bit of
547 a pain to follow since you'd need to look in two places for each
548 half.
549 xtransfer( dest_server, REMOTE_FILE, [DEST_FILE, [PREFIX,
551 [POSTFIX, [BODY]]]] )
552 Same as transfer, but it uses a temporary filename on the
554 dest_server during the transfer. And then renames it to DEST_FILE
555 afterwards.
556 See xput for the meaning of the remaining parameters.
558 delete( REMOTE_FILE )
560 Deletes the indicated REMOTE_FILE.
561 cwd( DIR )
563 Attempts to change directory to the directory given in DIR on the
564 remote server.
565 pwd( )
567 Returns the full pathname of the current directory on the remote
568 server.
569 cdup( )
571 Changes directory to the parent of the current directory on the
572 remote server.
573 mkdir( DIR )
575 Creates the indicated directory DIR on the remote server. No
576 recursion at the moment.
577 rmdir( DIR )
579 Removes the empty indicated directory DIR on the remote server. No
580 recursion at the moment.
581 noop( )
583 It requires no action other than the server send an OK reply.
584 rename( OLD, NEW )
586 Allows you to rename the file on the remote server.
587 site( ARGS )
589 Send a SITE command to the remote server and wait for a response.
590 mfmt( time_str, remote_file ) or _mfmt( timestamp, remote_file [,
592 local_flag] )
593 Both are boolean functions that attempt to reset the remote file's
594 timestamp on the FTPS server and returns true on success. The 1st
595 version can call croak on failure if Croak is turned on, while the
596 2nd version will not do this. The other difference between these
597 two functions is the format of the file's timestamp to use.
598 time_str expects the timestamp to be GMT time in format
600 YYYYMMDDHHMMSS. While timestamp expects to be in the same format
601 as returned by localtime() and converts it to the YYYYMMDDHHMMSS
602 format for you in GMT time.
603 But some servers incorectly use local time instead of GMT. So the
605 local_flag option was added to tell it to use local time instead of
606 GMT time when converting the timestamp into a string. When used
607 internally by this module, this functionality is controlled by
608 PreserveTimestamp instead.
609 mdtm( remote_file ) or _mdtm( remote_file [, local_flag] )
611 The 1st version returns the file's timestamp as a string in
612 YYYYMMDDHHMMSS format using GMT time, it will return undef or call
613 croak on failure. (Some servers incorrectly use local time
614 instead.)
615 The 2nd version returns the file's timestamp in the same format as
617 returned by gmtime() and will never call croak. But some servers
618 incorectly use local time instead of GMT. So the local_flag option
619 was added to tell it to use local time instead of GMT time for this
620 conversion. When used internally by this module, this
621 functionality is controlled by PreserveTimestamp instead.
622 size( remote_file )
624 This function will return undef or croak on failure. Otherwise it
625 will return the file's size in bytes, which may also be zero bytes!
626 Just be aware for text files that the size returned may not match
627 the file's actual size after the file has been downloaded to your
628 system in ASCII mode. This is an OS specific issue. It will
629 always match if you are using BINARY mode.
630 Also SIZE may return a different size for ASCII & BINARY modes.
632 This issue depends on what OS the FTPS server is running under.
633 Should they be different, the ASCII size will be the BINARY size
634 plus the number of lines in the file.
635 Finally if the file isn't a regular file, it may in some cases
637 return undef. Depending on which FTP command was available to
638 calculate the file's size with.
639 dir( [DIRECTORY [, PATTERN]] )
641 This is an alias to list. Returns an array of filenames in the
642 long detailed format.
643 ls( [DIRECTORY [, PATTERN]] )
645 This is an alias to nlst. Returns an array of filenames in name
646 only format.
647 last_message() or message()
649 Use either one to collect the last response from the FTPS server.
650 This is the same response printed to STDERR when Debug is turned
651 on. It may also contain any fatal error message encountered.
652 If you couldn't create a Net::FTPSSL object, you should get your
654 error message from $Net::FTPSSL::ERRSTR instead. Be careful since
655 $Net::FTPSSL::ERRSTR is shared between instances of Net::FTPSSL,
656 while message & last_message are not shared between instances!
657 last_status_code( )
659 Returns the one digit status code associated with the last response
660 from the FTPS server. The status is the first digit from the full
661 3 digit response code.
662 The possible values are exposed via the following 7 constants:
664 CMD_INFO, CMD_OK, CMD_MORE, CMD_REJECT, CMD_ERROR, CMD_PROTECT and
665 CMD_PENDING.
666 quot( CMD [,ARGS] )
668 Send a command, that Net::FTPSSL does not directly support, to the
669 remote server and wait for a response. You are responsible for
670 parsing anything you need from message() yourself.
671 Returns the most significant digit of the response code. So it
673 will ignore the Croak request.
674 WARNING This call should only be used on commands that do not
676 require data connections. Misuse of this method can hang the
677 connection if the internal list of FTP commands using a data
678 channel is incomplete.
679 ccc( [ DataProtLevel ] )
681 Sends the clear command channel request to the FTPS server. If you
682 provide the DataProtLevel, it will change it from the current data
683 protection level to this one before it sends the CCC command.
684 After the CCC command, the data channel protection level cannot be
685 changed again and will always remain at this setting. Once you
686 execute the CCC request, you will have to create a new Net::FTPSSL
687 object to secure the command channel again. Due to security
688 concerns it is recommended that you do not use this method.
689 supported( CMD [, SUB_CMD] )
691 Returns TRUE if the remote server supports the given command. CMD
692 must match exactly. This function will ignore the Croak request.
693 If the CMD is SITE, FEAT or OPTS and SUB_CMD is supplied, it will
695 also check if the specified SUB_CMD sub-command is supported by
696 that command. Not all servers will support the use of SUB_CMD.
697 It determines if a command is supported by calling HELP and parses
699 the results for a match. And if FEAT is supported it calls FEAT
700 and adds these commands to the HELP list. The results are cached
701 so HELP and FEAT are only called once.
702 Some rare servers send the HELP results partially encrypted and
704 partially in clear text, causing the encrypted channel to break.
705 In that case you will need to override this method for things to
706 work correctly with these non-conforming servers. See the
707 OverrideHELP option in the constructor for how to do this.
708 Some servers don't support the HELP command itself! When this
710 happens, this method will always return FALSE unless you set the
711 OverrideHELP option in the constructor.
712 This command assumes that the FTP/S server is configured correctly.
714 But I've run into some servers where HELP says a command is present
715 when it's really unknown. So I'm assuming the reverse may be true
716 sometimes as well. So when you hit this issue, use OverrideHELP or
717 fix_supported to work arround this problem.
718 This method is used internally for conditional logic such as when
720 checking if ALLO is supported during any file upload requests. In
721 all there are about a dozen different commands checked internally
722 in various situations.
723 all_supported( CMD1 [, CMD2 [, CMD3 [, CMD4 [, ...]]]] )
725 Similar to supported, except that it tests everything in this list
726 of one or more FTP commands passed to it to see if they are
727 supported. If the list is empty, or if even one command in the
728 list isn't supported, it returns FALSE. Otherwise it returns TRUE.
729 It will also ignore the Croak request.
730 fix_supported( MODE, CMD1 [, CMD2 [, CMD3 [, CMD4 [, ...]]]] )
732 Sometimes the FTPS server lies to us about what commands are
733 supported. This function provides a way to give the supported
734 command updates. This method is a NOOP if OverrideHELP => 1 was
735 used. Any other OverrideHELP option will cause HELP to be ignored
736 if it's one of the commands.
737 If MODE is true, it adds these commands to the list of supported
739 commands.
740 If MODE is false, it removes these commands as being supported.
742 Returns the number of FTP commands added/removed from support!
744 feat()
746 Asks the server for a list of features supported by this server.
747 It returns the list of commands as keys to a hash reference whose
748 value (behavior) is usually the empty string. But if a command
749 returns more details about the command, the command's value in the
750 hash will be those details (aka behavior).
751 Ex: MLST size*;create;modify*;perm;media-type, where MLST would be
752 the hash key & the rest of the line describes that command's
753 behavior.
754 While the OPTS command is never returned by a FEAT call to the
756 server, it will be automtically added to this hash if any command
757 listed has a behavior string after it. Since OPTS only has meaning
758 if at least one command has a behavior string defined. And many
759 servers only implement the OPTS command if there is a behavior that
760 can be modified. So in this case OPTS will point to a hash of
761 commands the OPTS command can modify!
762 So if the OPTS command appears in the hash, then each call to feat
764 will result in a server hit. Otherwise the result is cached. This
765 is because calls to OPTS could modify the behaviour of FEAT.
766 If OverrideHELP was used, HELP will be removed from the FEAT hash
768 returned since you stated this server doesn't support the HELP
769 command.
770 Should the FEAT command fail for any reason, the returned hash
772 reference will be empty or Croak will be called.
773 restart( OFFSET )
775 Set the byte offset at which to begin the next data transfer.
776 Net::FTPSSL simply records this value and uses it during the next
777 data transfer. For this reason this method will never return an
778 error, but setting it may cause subsequent data transfers to fail.
779 I recommend using the OFFSET directly in get(), put(), append() and
781 transfer() instead of using this method. It was only added to make
782 Net::FTPSSL compatible with Net::FTP. A non-zero offset in those
783 methods will override what you provide here. If you call any of
784 the other get()/put() variants after calling this function, you
785 will get an error.
786 It is OK to use an OFFSET of -1 here to have Net::FTPSSL calculate
788 the correct OFFSET for you before it get's used. Just like if you
789 had provided it directly to the get(), put(), append() and
790 transfer() calls.
791 This OFFSET will be automatically zeroed out after the 1st time it
793 is used.
794 is_file( FILE )
796 Returns true if the passed FILE name is recognized as a regular
797 file on the remote FTPS server. Otherwise it returns false.
798 If the MLST command is supported with the TYPE feature turned on we
800 can get a definitive answer. Otherwise it's assumed a regular file
801 if the size function works! (IE. returns a size >= 0 Bytes.)
802 is_dir( DIRECTORY )
804 Returns true if the passed DIRECTORY name is recognized as a
805 directory on the remote FTPS server. It returns false if it can't
806 prove it or it's not a directory.
807 If the MLST command is supported with the TYPE feature turned on we
809 can get a definitive answer. Otherwise it's assumed a directory if
810 you can cwd into it.
811 But if it's using this backup method and your login doesn't have
813 permission to cwd into that directory, this function will not
814 recognize it as a directory, even if it really is one!
815 set_callback( [cb_func_ref, end_cb_func_ref [, cb_data_ref]] )
817 This function allows the user to define a callback function to use
818 whenever a data channel to the server is open. If either
819 cb_func_ref or end_cb_func_ref is undefined, it disables the
820 callback functionality, since both are required for call backs to
821 function properly.
822 The cb_func_ref is a reference to a function to handle processing
824 the data channel data. This is a void function that can be called
825 multiple times. It is called each time a chunk of data is read
826 from or written to the data channel.
827 The end_cb_func_ref is a reference to a function to handle closing
829 the callback for this data channel connection. This function is
830 allowed to return a string of additional data to process before the
831 data channel is closed. It is called only once per command after
832 processing all the data channel data.
833 The cb_data_ref is an optional reference to an array or hash that
835 the caller can use to store values between calls to the callback
836 function and the end callback function. If you don't need such a
837 work area, it's safe to not provide one. The Net::FTPSSL class
838 doesn't look at this reference.
839 The callback function must take the following 5 arguments:
841 B<callback> (ftps_func_name, data_ref, data_len_ref, total_len, cb_data_ref);
843 The ftps_func_name will tell what Net::FTPSSL function requested
845 the callback so that your callback function can determine what the
846 data is for and do conditional logic accordingly. We don't provide
847 a reference to the Net::FTPSSL object itself since the class is not
848 recursive. Each Net::FTPSSL object should have it's own cb_dat_ref
849 to work with. But methods within the class can share one.
850 Since we pass the data going through the data channel as a
852 reference, you are allowed to modify the data. But if you do, be
853 sure to update data_len_ref to the new data length as well if it
854 changes. Otherwise you will get buggy responses. Just be aware
855 that if you change the length, more than likely you'll be unable to
856 reliably restart an upload or download via restart() or using
857 OFFSET in the put & get commands.
858 Finally, the total_len is how many bytes have already been
860 processed. It does not include the data passed for the current
861 callback call. So it will always be zero the first time it's
862 called.
863 Once we finish processing data for the data channel, a different
865 callback function will be called to tell you that the data channel
866 is closing. That will be your last chance to affect what is going
867 over the data channel and to do any needed post processing. The
868 end callback function must take the following arguments:
869 $end = B<end_callback> (ftps_func_name, total_len, cb_data_ref);
871 These arguments have the same meaning as for the callback function,
873 except that this function allows you to optionally provide
874 additional data to/from the data channel. If reading from the data
875 channel, it will treat the return value as the last data returned
876 before it was closed. Otherwise it will be written to the data
877 channel before it is closed. Please return undef if there is
878 nothing extra for the Net::FTPSSL command to process.
879 You should also take care to clean up the contents of cb_data_ref
881 in the end_callback function. Otherwise the next callback sequence
882 that uses this work area may behave strangely.
883 As a final note, should the data channel be empty, it is very
885 likely that just the end_callback function will be called without
886 any calls to the callback function.
887 get_log_filehandle()
889 Returns the open file handle for the file specified by the
890 DebugLogFile option specified by "new()". If you did not use this
891 option, it will return undef.
892 Just be aware that once this object goes out of scope, the returned
894 file handle becomes invalid.
895 set_dc_from_hash( HASH )
897 This function provides you a way to micro manage the SSL
898 characteristics of the FTPS Data Channel without having to hack the
899 Net::FTPSSL code base. It should be called as soon as possible
900 after the call to new().
901 It takes a HASH as it's argument. Either by value or by address.
903 This hash of key/value pairs will be used to control the Data
904 Channel SSL options.
905 If the key's value is set to undef, it is an instruction to delete
907 an existing Data Channel option. If the key has a value it is an
908 instruction to add this key/value pair to the Data Channel options.
909 If the option already exists, it will override that value.
910 It returns the number of entries updated for the Data Channel.
912 copy_cc_to_dc( FORCE, ARRAY )
914 This function provides you a way to copy some of the SSL options
915 used to manage the Command Channel over to the Data Channel as well
916 without having to hack the Net::FTPSSL code base. It should be
917 called as soon as possible after the call to new().
918 It takes an ARRAY as it's arguments. Either by value or by
920 address. It looks up each array value in the Command Channel's SSL
921 characteristics and copies them over to use as a Data Channel
922 option.
923 If the option doen't exist for the Command Channel, that array
925 entry is ignored.
926 If the option is already set in the Data Channel, the array entry
928 overrides the current value in the Data Channel.
929 It returns the number of entries updated for the Data Channel.
931 trapWarn()
933 This method is only active if Debug is turned on with DebugLogFile
934 provided as well. Otherwise calling it does nothing. This trap
935 for warnings is automatically turned off when the the instance of
936 this class goes out of scope. It returns 1 if the trap was turned
937 on, else 0 if it wasn't.
938 Calling this method causes all Perl warnings to be written to the
940 log file you specified when you called new(). The warnings will
941 appear in the log file when they occur to assist in debugging this
942 module. It automatically puts the word WARNING: in front of the
943 message being logged.
944 So this method is only really useful if you wish to open a CPAN
946 ticket to report a problem with Net::FTPSSL and you think having
947 the generated warning showing up in the logs will help in getting
948 your issue resolved.
949 You may call this method for multiple Net::FTPSSL instances and it
951 will cause the warning to be written to multiple log files.
952 If your program already traps warnings before you call this method,
954 this code will forward the warning to your trap logic as well.
955
957 The logs generated by Net::FTPSSL are very easy to interpret. After
958 you get past the initial configuration information needed to support
959 opening a CPAN ticket, it's basically the FTPS traffic going back and
960 forth between your perl Client and the FTPS Server you are talking to.
961 Each line begins with a prefix that tells what is happening.
963 ">>>" - Represents outbound traffic sent to the FTPS Server.
965 "<<<" - Represents inbound traffic received from the FTPS Server.
967 "<<+" - Represents messages from Net::FTPSSL itself in response to a
969 request that doesn't hit the FTPS Server.
970 "WARNING:" - Represents a trapped perl warning written to the logs.
972 "SKT >>>" & "SKT <<<" represent socket traffic before the Net::FTPSSL
974 object gets created.
975 There are a couple of other rare variants to the above theme. But they
977 are purely information only. So this is basically it.
978
980 Marco Dalla Stella - <kral at paranoici dot org>
981 Curtis Leach - <cleach at cpan dot org> - As of v0.05
983
985 Net::Cmd
986 Net::FTP
988 Net::SSLeay::Handle
990 IO::Socket::SSL
992 RFC 959 - <http://www.rfc-editor.org/info/rfc959>
994 RFC 2228 - <http://www.rfc-editor.org/info/rfc2228>
996 RFC 2246 - <http://www.rfc-editor.org/info/rfc2246>
998 RFC 4217 - <http://www.rfc-editor.org/info/rfc4217>
1000
1002 Graham Barr <gbarr at pobox dot com> - for have written such a great
1003 collection of modules (libnet).
1004
1006 Please report any bugs with a FTPS log file created via options
1007 Debug=>1 and DebugLogFile=>"file.txt" along with your sample code at
1008 <https://metacpan.org/pod/Net::FTPSSL>.
1009 Patches are appreciated when a log file and sample code are also
1011 provided.
1012
1014 Copyright (c) 2009 - 2019 Curtis Leach. All rights reserved.
1015 Copyright (c) 2005 Marco Dalla Stella. All rights reserved.
1017 This program is free software; you can redistribute it and/or modify it
1019 under the same terms as Perl itself.
1020perl v5.32.0 2020-07-28 FTPSSL(3)