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 recomended.
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 drwxrwx--- 1 owner group 512 Oct 27 2004 foo
252 drwxrwx--- 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 for 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 ascii()
276 Sets the file transfer mode to ASCII. CR LF transformations will
277 be done. ASCII is the default transfer mode.
278 binary()
280 Sets the file transfer mode to binary. No CR LF transformation will
281 be done.
282 mixedModeAI()
284 Mixture of ASCII & binary mode. The server does CR LF
285 transfernations while the client side does not. (For a really
286 weird server)
287 mixedModeIA()
289 Mixture of binary & ASCII mode. The client does CR LF
290 transfernations while the server side does not. (For a really
291 weird server)
292 put( LOCAL_FILE [, REMOTE_FILE [, OFFSET]] )
294 Stores the LOCAL_FILE onto the remote ftps server. LOCAL_FILE may
295 be a open IO::Handle or GLOB, but in this case REMOTE_FILE is
296 required. It returns undef if put() fails.
297 If you provide an OFFSET, this method assumes you are attempting to
299 continue with an upload that was aborted earlier. And it's your
300 responsibility to verify that it's the same file on the server you
301 tried to upload earlier. By providing the OFFSET, this function
302 will send a REST command to the FTPS Server to skip over that many
303 bytes before it starts writing to the file. This method will also
304 skip over the requested OFFSET after opening the LOCAL_FILE for
305 reading, but if passed a file handle it will assume you've already
306 positioned it correctly. If you provide an OFFSET of -1, this
307 method will calculate the offset for you by issuing a SIZE command
308 against the file on the FTPS server. So REMOTE_FILE must already
309 exist to use -1, or it's an error. It is also an error to make
310 OFFSET larger than the REMOTE_FILE.
311 If the OFFSET you provide turns out to be smaller than the current
313 size of REMOVE_FILE, the server will truncate the REMOTE_FILE to
314 that size before appending to the end of REMOTE_FILE. (This may
315 not be consistent across all FTPS Servers, so don't depend on this
316 feature without testing it first.)
317 If the option PreserveTimestamp was used, and the FTPS server
319 supports it, it will attempt to reset the timestamp on REMOTE_FILE
320 to the timestamp on LOCAL_FILE.
321 append( LOCAL_FILE [, REMOTE_FILE [, OFFSET]] )
323 Appends the LOCAL_FILE onto the REMOTE_FILE on the ftps server. If
324 REMOTE_FILE doesn't exist, the file will be created. LOCAL_FILE
325 may be a open IO::Handle or GLOB, but in this case REMOTE_FILE is
326 required and OFFSET is ignored. It returns undef if append()
327 fails.
328 If you provide an OFFSET, it will skip over that number of bytes in
330 the LOCAL_FILE except when it was a file handle, but will not send
331 a REST command to the server. It will just append to the end of
332 REMOTE_FILE on the server. You can also provide an OFFSET of -1
333 with the same limitations as with put(). If you need the REST
334 command sent to the FTPS server, use put() instead.
335 If the option PreserveTimestamp was used, and the FTPS server
337 supports it, it will attempt to reset the timestamp on REMOTE_FILE
338 to the timestamp on LOCAL_FILE.
339 uput( LOCAL_FILE, [REMOTE_FILE] )
341 Stores the LOCAL_FILE onto the remote ftps server. LOCAL_FILE may
342 be a open IO::Handle or GLOB, but in this case REMOTE_FILE is
343 required. If REMOTE_FILE already exists on the ftps server, a
344 unique name is calculated by the server for use instead. But on
345 some servers, the remote server won't take the hint and will always
346 generate a unique name instead.
347 If the file transfer succeeds, this function will try to return the
349 actual name used on the remote ftps server. If it can't figure
350 that out, it will return what was used for REMOTE_FILE. On failure
351 this method will return undef. If the remote server won't take the
352 hint and we can't figure out the name it used, we'll return a
353 string containing a single ? instead. In this case the request
354 worked, but this command has no way to figure out what name was
355 generated on the remote ftps server. And we want to return a
356 printable value that will evaluate to true!
357 If the option PreserveTimestamp was used, and the FTPS server
359 supports it, it will attempt to reset the timestamp on the remote
360 file using the file name being returned by this function to the
361 timestamp on LOCAL_FILE. So if the wrong name is being returned,
362 the wrong file could get it's timestamp updated.
363 xput( LOCAL_FILE, [REMOTE_FILE, [PREFIX, [POSTFIX, [BODY]]]] )
365 Use when the directory you are dropping REMOTE_FILE into is
366 monitored by a file recognizer that might pick the file up before
367 the file transfer has completed. So the file is transferred using
368 a temporary name using a naming convention that the file recognizer
369 will ignore and is guaranteed to be unique. Once the file transfer
370 successfully completes, it will be renamed to REMOTE_FILE for
371 immediate pickup by the file recognizer. If you requested to
372 preserve the file's timestamp, this step is done after the file is
373 renamed and so can't be 100% guaranteed if the file recognizer
374 picks it up first. Since if it was done before the rename, other
375 more serious problems could crop up if the resulting timestamp was
376 old enough.
377 On failure this function will attempt to delete the scratch file
379 for you if its at all possible. You will have to talk to your FTPS
380 server administrator on good values for PREFIX and POSTFIX if the
381 defaults are no good for you.
382 PREFIX defaults to _tmp. unless you override it. Set to "" if you
384 need to suppress the PREFIX. This PREFIX can be a path to another
385 directory if needed, but that directory must already exist! Set to
386 undef to keep this default and you need to change the default for
387 POSTFIX or BODY.
388 POSTFIX defaults to .tmp unless you override it. Set to "" if you
390 need to suppress the POSTFIX. Set to undef to keep this default
391 and you need to change the default for BODY.
392 BODY defaults to client-name.PID so that you are guaranteed the
394 temp file will have an unique name on the remote server. It is
395 strongly recommended that you don't override this value.
396 So the temp scratch file would be called something like this by
398 default: _tmp.testclient.51243.tmp.
399 As a final note, if REMOTE_FILE has path information in it's name,
401 the temp scratch file will have the same directory added to it
402 unless you override the PREFIX with a different directory to drop
403 the scratch file into. This avoids forcing you to change into the
404 requested directory first when you have multiple files to send out
405 into multiple directories.
406 get( REMOTE_FILE [, LOCAL_FILE [, OFFSET]] )
408 Retrieves the REMOTE_FILE from the ftps server. LOCAL_FILE may be a
409 filename or a open IO::Handle or GLOB. It returns undef if get()
410 fails. You don't usually need to use OFFSET.
411 If you provide an OFFSET, this method assumes your are attempting
413 to continue with a download that was aborted earlier. And it's
414 your responsibility to verify that it's the same file you tried to
415 download earlier. By providing the OFFSET, it will send a REST
416 command to the FTPS Server to skip over that many bytes before it
417 starts downloading the file again. If you provide an OFFSET of -1,
418 this method will calculate the offset for you based on the size of
419 LOCAL_FILE using the current transfer mode. (ASCII or BINARY). It
420 is an error to set it to -1 if the LOCAL_FILE is a file handle.
421 On the client side of the download, the OFFSET will do the
423 following: Open the file and truncate everything after the given
424 OFFSET. So if you give an OFFSET that is too big, it's an error.
425 If it's too small, the file will be truncated to that OFFSET before
426 appending what's being downloaded. If the LOCAL_FILE is a file
427 handle, it will assume the file handle has already been positioned
428 to the proper OFFEST and it will not perform a truncate. Instead
429 it will just append to that file handle's current location. Just
430 beware that using huge OFFSETs in ASCII mode can be a bit slow if
431 the LOCAL_FILE needs to be truncated.
432 If the option PreserveTimestamp was used, and the FTPS Server
434 supports it, it will attempt to reset the timestamp on LOCAL_FILE
435 to the timestamp on REMOTE_FILE after the download completes.
436 xget( REMOTE_FILE, [LOCAL_FILE, [PREFIX, [POSTFIX, [BODY]]]] )
438 The inverse of xput, where the file recognizer is on the client
439 side. The only other difference being what BODY defaults to. It
440 defaults to reverse(testclient).PID. So your default scratch file
441 would be something like: _tmp.tneilctset.51243.tmp.
442 Just be aware that in this case LOCAL_FILE can no longer be a open
444 IO::Handle or glob.
445 transfer( dest_server, REMOTE_FILE [, DEST_FILE [, OFFSET]] )
447 Retrieves the REMOTE_FILE from the current ftps server and uploads
448 it to the dest_server as DEST_FILE without making any copy of the
449 file on your local file system. If DEST_FILE isn't provided, it
450 uses REMOTE_FILE on the dest_server.
451 It assumes that dest_server is an Net::FTPSSL object and you have
453 already successfully logged onto dest_server and set both ends to
454 either binary or ascii mode! So this function skips over the CR/LF
455 logic and lets the other servers handle it. You must also set the
456 Croak option to the same value on both ends.
457 Finally, if logging is turned on, the logs to this function will be
459 split between the logs on each system. So the logs may be a bit of
460 a pain to follow since you'd need to look in two places for each
461 half.
462 xtransfer( dest_server, REMOTE_FILE, [DEST_FILE, [PREFIX,
464 [POSTFIX, [BODY]]]] )
465 Same as transfer, but it uses a temporary filename on the
467 dest_server during the transfer. And then renames it to DEST_FILE
468 afterwards.
469 See xput for the meaning of the remaining parameters.
471 delete( REMOTE_FILE )
473 Deletes the indicated REMOTE_FILE.
474 cwd( DIR )
476 Attempts to change directory to the directory given in DIR on the
477 remote server.
478 pwd( )
480 Returns the full pathname of the current directory on the remote
481 server.
482 cdup( )
484 Changes directory to the parent of the current directory on the
485 remote server.
486 mkdir( DIR )
488 Creates the indicated directory DIR on the remote server. No
489 recursion at the moment.
490 rmdir( DIR )
492 Removes the empty indicated directory DIR on the remote server. No
493 recursion at the moment.
494 noop( )
496 It requires no action other than the server send an OK reply.
497 rename( OLD, NEW )
499 Allows you to rename the file on the remote server.
500 site( ARGS )
502 Send a SITE command to the remote server and wait for a response.
503 mfmt( time_str, remote_file ) or _mfmt( timestamp, remote_file [,
505 local_flag] )
506 Both are boolean functions that attempt to reset the remote file's
507 timestamp on the FTPS server and returns true on success. The 1st
508 version can call croak on failure if Croak is turned on, while the
509 2nd version will not do this. The other difference between these
510 two functions is the format of the file's timestamp to use.
511 time_str expects the timestamp to be GMT time in format
513 YYYYMMDDHHMMSS. While timestamp expects to be in the same format
514 as returned by localtime() and converts it to the YYYYMMDDHHMMSS
515 format for you in GMT time.
516 But some servers incorectly use local time instead of GMT. So the
518 local_flag option was added to tell it to use local time instead of
519 GMT time when converting the timestamp into a string. When used
520 internally by this module, this functionality is controlled by
521 PreserveTimestamp instead.
522 mdtm( remote_file ) or _mdtm( remote_file [, local_flag] )
524 The 1st version returns the file's timestamp as a string in
525 YYYYMMDDHHMMSS format using GMT time, it will return undef or call
526 croak on failure. (Some servers incorrectly use local time
527 instead.)
528 The 2nd version returns the file's timestamp in the same format as
530 returned by gmtime() and will never call croak. But some servers
531 incorectly use local time instead of GMT. So the local_flag option
532 was added to tell it to use local time instead of GMT time for this
533 conversion. When used internally by this module, this
534 functionality is controlled by PreserveTimestamp instead.
535 size( remote_file )
537 This function will return undef or croak on failure. Otherwise it
538 will return the file's size in bytes, which may also be zero bytes!
539 Just be aware for text files that the size returned may not match
540 the file's actual size after the file has been downloaded to your
541 system in ASCII mode. This is an OS specific issue. It will
542 always match if you are using BINARY mode.
543 Also SIZE may return a different size for ASCII & BINARY modes.
545 This issue depends on what OS the FTPS server is running under.
546 Should they be different, the ASCII size will be the BINARY size
547 plus the number of lines in the file.
548 Finally if the file isn't a regular file, it will return undef.
550 last_message() or message()
552 Use either one to collect the last response from the FTPS server.
553 This is the same response printed to STDERR when Debug is turned
554 on. It may also contain any fatal error message encountered.
555 If you couldn't create a Net::FTPSSL object, you should get your
557 error message from $Net::FTPSSL::ERRSTR instead. Be careful since
558 $Net::FTPSSL::ERRSTR is shared between instances of Net::FTPSSL,
559 while message & last_message are not shared between instances!
560 last_status_code( )
562 Returns the one digit status code associated with the last response
563 from the FTPS server. The status is the first digit from the full
564 3 digit response code.
565 The possible values are exposed via the following 7 constants:
567 CMD_INFO, CMD_OK, CMD_MORE, CMD_REJECT, CMD_ERROR, CMD_PROTECT and
568 CMD_PENDING.
569 quot( CMD [,ARGS] )
571 Send a command, that Net::FTPSSL does not directly support, to the
572 remote server and wait for a response. You are responsible for
573 parsing anything you need from message() yourself.
574 Returns the most significant digit of the response code. So it
576 will ignore the Croak request.
577 WARNING This call should only be used on commands that do not
579 require data connections. Misuse of this method can hang the
580 connection if the internal list of FTP commands using a data
581 channel is incomplete.
582 ccc( [ DataProtLevel ] )
584 Sends the clear command channel request to the FTPS server. If you
585 provide the DataProtLevel, it will change it from the current data
586 protection level to this one before it sends the CCC command.
587 After the CCC command, the data channel protection level cannot be
588 changed again and will always remain at this setting. Once you
589 execute the CCC request, you will have to create a new Net::FTPSSL
590 object to secure the command channel again. Due to security
591 concerns it is recommended that you do not use this method.
592 supported( CMD [, SUB_CMD] )
594 Returns TRUE if the remote server supports the given command. CMD
595 must match exactly. This function will ignore the Croak request.
596 If the CMD is SITE, FEAT or OPTS and SUB_CMD is supplied, it will
598 also check if the specified SUB_CMD sub-command is supported by
599 that command. Not all servers will support the use of SUB_CMD.
600 It determines if a command is supported by calling HELP and parses
602 the results for a match. And if FEAT is supported it calls FEAT
603 and adds these commands to the HELP list. The results are cached
604 so HELP and FEAT are only called once.
605 Some rare servers send the HELP results partially encrypted and
607 partially in clear text, causing the encrypted channel to break.
608 In that case you will need to override this method for things to
609 work correctly with these non-conforming servers. See the
610 OverrideHELP option in the constructor for how to do this.
611 Some servers don't support the HELP command itself! When this
613 happens, this method will always return FALSE unless you set the
614 OverrideHELP option in the constructor.
615 This command assumes that the FTP/S server is configured correctly.
617 But I've run into some servers where HELP says a command is present
618 when it's really unknown. So I'm assuming the reverse may be true
619 sometimes as well. So when you hit this issue, use OverrideHELP or
620 fix_supported to work arround this problem.
621 This method is used internally for conditional logic such as when
623 checking if ALLO is supported during any file upload requests. In
624 all there are about a dozen different commands checked internally
625 in various situations.
626 all_supported( CMD1 [, CMD2 [, CMD3 [, CMD4 [, ...]]]] )
628 Similar to supported, except that it tests everything in this list
629 of one or more FTP commands passed to it to see if they are
630 supported. If the list is empty, or if even one command in the
631 list isn't supported, it returns FALSE. Otherwise it returns TRUE.
632 It will also ignore the Croak request.
633 fix_supported( MODE, CMD1 [, CMD2 [, CMD3 [, CMD4 [, ...]]]] )
635 Sometimes the FTPS server lies to us about what commands are
636 supported. This function provides a way to give the supported
637 command updates. This method is a NOOP if OverrideHELP => 1 was
638 used. Any other OverrideHELP option will cause HELP to be ignored
639 if it's one of the commands.
640 If MODE is true, it adds these commands to the list of supported
642 commands.
643 If MODE is false, it removes these commands as being supported.
645 Returns the number of FTP commands added/removed from support!
647 feat()
649 Asks the server for a list of features supported by this server.
650 It returns the list of commands as keys to a hash reference whose
651 value (behavior) is usually the empty string. But if a command
652 returns more details about the command, the command's value in the
653 hash will be those details (aka behavior).
654 Ex: MLST size*;create;modify*;perm;media-type, where MLST would be
655 the hash key & the rest of the line describes that command's
656 behavior.
657 While the OPTS command is never returned by a FEAT call to the
659 server, it will be automtically added to this hash if any command
660 listed has a behavior string after it. Since OPTS only has meaning
661 if at least one command has a behavior string defined. And many
662 servers only implement the OPTS command if there is a behavior that
663 can be modified. So in this case OPTS will point to a hash of
664 commands the OPTS command can modify!
665 So if the OPTS command appears in the hash, then each call to feat
667 will result in a server hit. Otherwise the result is cached. This
668 is because calls to OPTS could modify the behaviour of FEAT.
669 If OverrideHELP was used, HELP will be removed from the FEAT hash
671 returned since you stated this server doesn't support the HELP
672 command.
673 Should the FEAT command fail for any reason, the returned hash
675 reference will be empty or Croak will be called.
676 restart( OFFSET )
678 Set the byte offset at which to begin the next data transfer.
679 Net::FTPSSL simply records this value and uses it during the next
680 data transfer. For this reason this method will never return an
681 error, but setting it may cause subsequent data transfers to fail.
682 I recommend using the OFFSET directly in get(), put(), append() and
684 transfer() instead of using this method. It was only added to make
685 Net::FTPSSL compatible with Net::FTP. A non-zero offset in those
686 methods will override what you provide here. If you call any of
687 the other get()/put() variants after calling this function, you
688 will get an error.
689 It is OK to use an OFFSET of -1 here to have Net::FTPSSL calculate
691 the correct OFFSET for you before it get's used. Just like if you
692 had provided it directly to the get(), put(), append() and
693 transfer() calls.
694 This OFFSET will be automatically zeroed out after the 1st time it
696 is used.
697 is_file( FILE )
699 Returns true if the passed name is recognized as a regular file on
700 the remote server. It's assumed a regular file if the size
701 function works! (IE. returns a size >= 0 Bytes.)
702 is_dir( DIRECTORY )
704 Returns true if the passed name is recognized as a directory on the
705 remote server. It's assumed a directory if you can cwd into it.
706 If you don't have permission to cwd into that directory, this
708 function will not recognize it as a directory, even if it really is
709 one!
710 set_callback( [cb_func_ref, end_cb_func_ref [, cb_data_ref]] )
712 This function allows the user to define a callback function to use
713 whenever a data channel to the server is open. If either
714 cb_func_ref or end_cb_func_ref is undefined, it disables the
715 callback functionality, since both are required for call backs to
716 function properly.
717 The cb_func_ref is a reference to a function to handle processing
719 the data channel data. This is a void function that can be called
720 multiple times. It is called each time a chunk of data is read
721 from or written to the data channel.
722 The end_cb_func_ref is a reference to a function to handle closing
724 the callback for this data channel connection. This function is
725 allowed to return a string of additional data to process before the
726 data channel is closed. It is called only once per command after
727 processing all the data channel data.
728 The cb_data_ref is an optional reference to an array or hash that
730 the caller can use to store values between calls to the callback
731 function and the end callback function. If you don't need such a
732 work area, it's safe to not provide one. The Net::FTPSSL class
733 doesn't look at this reference.
734 The callback function must take the following 5 arguments:
736 B<callback> (ftps_func_name, data_ref, data_len_ref, total_len, cb_data_ref);
738 The ftps_func_name will tell what Net::FTPSSL function requested
740 the callback so that your callback function can determine what the
741 data is for and do conditional logic accordingly. We don't provide
742 a reference to the Net::FTPSSL object itself since the class is not
743 recursive. Each Net::FTPSSL object should have it's own cb_dat_ref
744 to work with. But methods within the class can share one.
745 Since we pass the data going through the data channel as a
747 reference, you are allowed to modify the data. But if you do, be
748 sure to update data_len_ref to the new data length as well if it
749 changes. Otherwise you will get buggy responses. Just be aware
750 that if you change the length, more than likely you'll be unable to
751 reliably restart an upload or download via restart() or using
752 OFFSET in the put & get commands.
753 Finally, the total_len is how many bytes have already been
755 processed. It does not include the data passed for the current
756 callback call. So it will always be zero the first time it's
757 called.
758 Once we finish processing data for the data channel, a different
760 callback function will be called to tell you that the data channel
761 is closing. That will be your last chance to affect what is going
762 over the data channel and to do any needed post processing. The
763 end callback function must take the following arguments:
764 $end = B<end_callback> (ftps_func_name, total_len, cb_data_ref);
766 These arguments have the same meaning as for the callback function,
768 except that this function allows you to optionally provide
769 additional data to/from the data channel. If reading from the data
770 channel, it will treat the return value as the last data returned
771 before it was closed. Otherwise it will be written to the data
772 channel before it is closed. Please return undef if there is
773 nothing extra for the Net::FTPSSL command to process.
774 You should also take care to clean up the contents of cb_data_ref
776 in the end_callback function. Otherwise the next callback sequence
777 that uses this work area may behave strangely.
778 As a final note, should the data channel be empty, it is very
780 likely that just the end_callback function will be called without
781 any calls to the callback function.
782 get_log_filehandle()
784 Returns the open file handle for the file specified by the
785 DebugLogFile option specified by "new()". If you did not use this
786 option, it will return undef.
787 Just be aware that once this object goes out of scope, the returned
789 file handle becomes invalid.
790 set_dc_from_hash( HASH )
792 This function provides you a way to micro manage the SSL
793 characteristics of the FTPS Data Channel without having to hack the
794 Net::FTPSSL code base. It should be called as soon as possible
795 after the call to new().
796 It takes a HASH as it's argument. Either by value or by address.
798 This hash of key/value pairs will be used to control the Data
799 Channel SSL options.
800 If the key's value is set to undef, it is an instruction to delete
802 an existing Data Channel option. If the key has a value it is an
803 instruction to add this key/value pair to the Data Channel options.
804 If the option already exists, it will override that value.
805 It returns the number of entries updated for the Data Channel.
807 copy_cc_to_dc( FORCE, ARRAY )
809 This function provides you a way to copy some of the SSL options
810 used to manage the Command Channel over to the Data Channel as well
811 without having to hack the Net::FTPSSL code base. It should be
812 called as soon as possible after the call to new().
813 It takes an ARRAY as it's arguments. Either by value or by
815 address. It looks up each array value in the Command Channel's SSL
816 characteristics and copies them over to use as a Data Channel
817 option.
818 If the option doen't exist for the Command Channel, that array
820 entry is ignored.
821 If the option is already set in the Data Channel, the array entry
823 overrides the current value in the Data Channel.
824 It returns the number of entries updated for the Data Channel.
826 trapWarn()
828 This method is only active if Debug is turned on with DebugLogFile
829 provided as well. Otherwise calling it does nothing. This trap
830 for warnings is automatically turned off when the the instance of
831 this class goes out of scope. It returns 1 if the trap was turned
832 on, else 0 if it wasn't.
833 Calling this method causes all Perl warnings to be written to the
835 log file you specified when you called new(). The warnings will
836 appear in the log file when they occur to assist in debugging this
837 module. It automatically puts the word WARNING: in front of the
838 message being logged.
839 So this method is only really useful if you wish to open a CPAN
841 ticket to report a problem with Net::FTPSSL and you think having
842 the generated warning showing up in the logs will help in getting
843 your issue resolved.
844 You may call this method for multiple Net::FTPSSL instances and it
846 will cause the warning to be written to multiple log files.
847 If your program already traps warnings before you call this method,
849 this code will forward the warning to your trap logic as well.
850
852 The logs generated by Net::FTPSSL are very easy to interpret. After
853 you get past the initial configuration information needed to support
854 opening a CPAN ticket, it's basically the FTPS traffic going back and
855 forth between your perl Client and the FTPS Server you are talking to.
856 Each line begins with a prefix that tells what is happening.
858 ">>>" - Represents outbound traffic sent to the FTPS Server.
860 "<<<" - Represents inbound traffic received from the FTPS Server.
862 "<<+" - Represents messages from Net::FTPSSL itself in response to a
864 request that doesn't hit the FTPS Server.
865 "WARNING:" - Represents a trapped perl warning written to the logs.
867 "SKT >>>" & "SKT <<<" represent socket traffic before the Net::FTPSSL
869 object gets created.
870 There are a couple of other rare variants to the above theme. But they
872 are purely information only. So this is basically it.
873
875 Marco Dalla Stella - <kral at paranoici dot org>
876 Curtis Leach - <cleach at cpan dot org> - As of v0.05
878
880 Net::Cmd
881 Net::FTP
883 Net::SSLeay::Handle
885 IO::Socket::SSL
887 RFC 959 - <http://www.rfc-editor.org/info/rfc959>
889 RFC 2228 - <http://www.rfc-editor.org/info/rfc2228>
891 RFC 2246 - <http://www.rfc-editor.org/info/rfc2246>
893 RFC 4217 - <http://www.rfc-editor.org/info/rfc4217>
895
897 Graham Barr <gbarr at pobox dot com> - for have written such a great
898 collection of modules (libnet).
899
901 Please report any bugs with a FTPS log file created via options
902 Debug=>1 and DebugLogFile=>"file.txt" along with your sample code at
903 <http://search.cpan.org/~cleach/Net-FTPSSL-0.40/FTPSSL.pm> or
904 <https://metacpan.org/pod/Net::FTPSSL>.
905 Patches are appreciated when a log file and sample code are also
907 provided.
908
910 Copyright (c) 2009 - 2018 Curtis Leach. All rights reserved.
911 Copyright (c) 2005 Marco Dalla Stella. All rights reserved.
913 This program is free software; you can redistribute it and/or modify it
915 under the same terms as Perl itself.
916perl v5.28.0 2018-02-27 FTPSSL(3)