1FTPSSL(3)             User Contributed Perl Documentation            FTPSSL(3)
2
3
4

NAME

6       Net::FTPSSL - A FTP over TLS/SSL class
7

VERSION 0.42

SYNOPSIS

10         use Net::FTPSSL;
11
12         my $ftps = Net::FTPSSL->new('ftp.your-secure-server.com',
13                                     Encryption => EXP_CRYPT,
14                                     Debug => 1, DebugLogFile => "myLog.txt",
15                                     Croak => 1);
16
17         $ftps->trapWarn ();     # Only call if opening a CPAN bug report.
18
19         $ftps->login('anonymous', 'user@localhost');
20
21         $ftps->cwd("/pub");
22
23         $ftps->get("file");
24
25         $ftps->quit();
26
27       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

DESCRIPTION

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

CONSTRUCTOR

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
46           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
50           "OPTIONS" are:
51
52           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
59           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
64           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
71           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
78           PreserveTimestamp - During all puts and gets, attempt to preserve
79           the file's timestamp.  By default it will not preserve the
80           timestamps.
81
82           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
89           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
94           Trace - Turns on/off (1/0) put/get download tracing to STDERR.  The
95           default is off.
96
97           Debug - This turns the debug tracing option on/off. Default is off.
98           (0,1,2)
99
100           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
107           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
111           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
119           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
123           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
128           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
134           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
138           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
142           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
148           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
154           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
160           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
164           Timeout - Set a connection timeout value. Default value is 120.
165
166           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
173           LocalAddr - Local address to use for all socket connections, this
174           argument will be passed to all IO::Socket::INET calls.
175
176           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
185           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
192           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
200           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
204           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

METHODS

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
215       login( USER, PASSWORD )
216           Use the given information to log into the FTPS server.
217
218       quit()
219           This method breaks the connection to the FTPS server.
220
221       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
227           It does this by sending "EPSV ALL" to the server.  Afterwards the
228           server will reject all EPTR, PORT and PASV commands.
229
230           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
236           This method returns true if it succeeds, or false if it fails.
237
238       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
245       list( [DIRECTORY [, PATTERN]] )
246           This method returns a list of files in a format similar to this:
247           (Server Specific)
248
249            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
255           If DIRECTORY is omitted, the method will return the list of the
256           current directory.
257
258           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
265       nlst( [DIRECTORY [, PATTERN]] )
266           Same as "list" but returns the list in this format:
267
268            foo
269            pub
270            bar
271
272           Spaces in the filename do not cause problems with the PATTERN with
273           "nlst".  Personally, I suggest using nlst instead of list.
274
275       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
281            modify=20041027194930;type=file;size=28194; foo
282            modify=20041027194932;type=file;size=3201931; pub
283            modify=20180329120944;type=dir;size=256; bar
284
285           Spaces in the filename do not cause problems with the PATTERN with
286           "mlsd".
287
288           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
297       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
302           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
307           For example if we were looking for file pub again:
308             modify=20041027194932;type=file;size=3201931; /dir/pub
309
310       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
315           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
321           For example:
322             Type=File;Size=3201931; Pub
323             would return (Type=>File, Size=>3201931, ;file;=>Pub)
324
325           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
330       ascii()
331           Sets the file transfer mode to ASCII.  CR LF transformations will
332           be done.  ASCII is the default transfer mode.
333
334       binary()
335           Sets the file transfer mode to binary. No CR LF transformation will
336           be done.
337
338       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
343       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
348       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
353           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
367           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
373           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
377       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
384           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
391           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
395       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
401           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
407           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
411           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
422           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
425           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
431       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
437           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
442           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
446           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
451       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
465           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
470           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
476           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
480           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
484           So the temp scratch file would be called something like this by
485           default: _tmp.testclient.51243.tmp.
486
487           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
494       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
499           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
509           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
520           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
524       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
530           Just be aware that in this case LOCAL_FILE can no longer be a open
531           IO::Handle or glob.
532
533       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
539           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
545           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
550       xtransfer( dest_server, REMOTE_FILE, [DEST_FILE, [PREFIX,
551           [POSTFIX, [BODY]]]] )
552
553           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
557           See xput for the meaning of the remaining parameters.
558
559       delete( REMOTE_FILE )
560           Deletes the indicated REMOTE_FILE.
561
562       cwd( DIR )
563           Attempts to change directory to the directory given in DIR on the
564           remote server.
565
566       pwd( )
567           Returns the full pathname of the current directory on the remote
568           server.
569
570       cdup( )
571           Changes directory to the parent of the current directory on the
572           remote server.
573
574       mkdir( DIR )
575           Creates the indicated directory DIR on the remote server. No
576           recursion at the moment.
577
578       rmdir( DIR )
579           Removes the empty indicated directory DIR on the remote server. No
580           recursion at the moment.
581
582       noop( )
583           It requires no action other than the server send an OK reply.
584
585       rename( OLD, NEW )
586           Allows you to rename the file on the remote server.
587
588       site( ARGS )
589           Send a SITE command to the remote server and wait for a response.
590
591       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
599           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
604           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
610       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
616           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
623       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
631           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
636           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
640       dir( [DIRECTORY [, PATTERN]] )
641           This is an alias to list.  Returns an array of filenames in the
642           long detailed format.
643
644       ls( [DIRECTORY [, PATTERN]] )
645           This is an alias to nlst.  Returns an array of filenames in name
646           only format.
647
648       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
653           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
658       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
663           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
667       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
672           Returns the most significant digit of the response code.  So it
673           will ignore the Croak request.
674
675           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
680       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
690       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
694           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
698           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
703           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
709           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
713           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
719           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
724       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
731       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
738           If MODE is true, it adds these commands to the list of supported
739           commands.
740
741           If MODE is false, it removes these commands as being supported.
742
743           Returns the number of FTP commands added/removed from support!
744
745       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
755           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
763           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
767           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
771           Should the FEAT command fail for any reason, the returned hash
772           reference will be empty or Croak will be called.
773
774       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
780           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
787           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
792           This OFFSET will be automatically zeroed out after the 1st time it
793           is used.
794
795       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
799           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
803       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
808           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
812           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
816       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
823           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
828           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
834           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
840           The callback function must take the following 5 arguments:
841
842              B<callback> (ftps_func_name, data_ref, data_len_ref, total_len, cb_data_ref);
843
844           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
851           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
859           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
864           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
870              $end = B<end_callback> (ftps_func_name, total_len, cb_data_ref);
871
872           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
880           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
884           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
888       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
893           Just be aware that once this object goes out of scope, the returned
894           file handle becomes invalid.
895
896       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
902           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
906           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
911           It returns the number of entries updated for the Data Channel.
912
913       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
919           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
924           If the option doen't exist for the Command Channel, that array
925           entry is ignored.
926
927           If the option is already set in the Data Channel, the array entry
928           overrides the current value in the Data Channel.
929
930           It returns the number of entries updated for the Data Channel.
931
932       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
939           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
945           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
950           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
953           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

INTERPRETING THE LOGS

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
962       Each line begins with a prefix that tells what is happening.
963
964       ">>>" - Represents outbound traffic sent to the FTPS Server.
965
966       "<<<" - Represents inbound traffic received from the FTPS Server.
967
968       "<<+" - Represents messages from Net::FTPSSL itself in response to a
969       request that doesn't hit the FTPS Server.
970
971       "WARNING:" - Represents a trapped perl warning written to the logs.
972
973       "SKT >>>" & "SKT <<<" represent socket traffic before the Net::FTPSSL
974       object gets created.
975
976       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

AUTHORS

980       Marco Dalla Stella - <kral at paranoici dot org>
981
982       Curtis Leach - <cleach at cpan dot org> - As of v0.05
983

SEE ALSO

985       Net::Cmd
986
987       Net::FTP
988
989       Net::SSLeay::Handle
990
991       IO::Socket::SSL
992
993       RFC 959 - <http://www.rfc-editor.org/info/rfc959>
994
995       RFC 2228 - <http://www.rfc-editor.org/info/rfc2228>
996
997       RFC 2246 - <http://www.rfc-editor.org/info/rfc2246>
998
999       RFC 4217 - <http://www.rfc-editor.org/info/rfc4217>
1000

CREDITS

1002       Graham Barr <gbarr at pobox dot com> - for have written such a great
1003       collection of modules (libnet).
1004

BUGS

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
1010       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
1016       Copyright (c) 2005 Marco Dalla Stella. All rights reserved.
1017
1018       This program is free software; you can redistribute it and/or modify it
1019       under the same terms as Perl itself.
1020
1021
1022
1023perl v5.36.0                      2023-01-20                         FTPSSL(3)
Impressum