FTPSSL(3) User Contributed Perl Documentation FTPSSL(3)NAMENet::FTPSSL - A FTP over SSL/TLS class
VERSION 0.15SYNOPSIS
use Net::FTPSSL;
my $ftps = Net::FTPSSL->new('ftp.yoursecureserver.com',
Port => 21,
Encryption => EXP_CRYPT,
Debug => 1)
or die "Can't open ftp.yoursecureserver.com";
$ftps->login('anonymous', 'user@localhost')
or die "Can't login: ", $ftps->last_message();
$ftps->cwd("/pub") or die "Can't change directory: " . $ftps->last_message();
$ftps->get("file") or die "Can't get file: " . $ftps->last_message();
$ftps->quit();
Had you included Croak => 1 as an option to new, you could have left
off the or die checks and your die messages would be more specific to
the actual problem encountered!
DESCRIPTION
"Net::FTPSSL" is a class implementing a simple FTP client over a Secure
Sockets Layer (SSL) or Transport Layer Security (TLS) connection
written in Perl as described in RFC959 and RFC2228. It will use TLS by
default.
CONSTRUCTOR
new( HOST [, OPTIONS ] )
Creates a new Net::FTPSSL object and opens a connection with the
"HOST". "HOST" is the address of the FTP server and it's a required
argument. OPTIONS are passed in a hash like fashion, using key and
value pairs.
If it can't create a new Net::FTPSSL object, it will return undef
unless you set the Croak option. In either case you will find the
cause of the failure in $Net::FTPSSL::ERRSTR.
"OPTIONS" are:
Encryption - The connection can be implicitly (IMP_CRYPT)
encrypted, explicitly (EXP_CRYPT) encrypted, or regular FTP
(CLR_CRYPT). In explicit cases the connection begins clear and
became encrypted after an "AUTH" command is sent, while implicit
starts off encrypted. For CLR_CRYPT, the connection never becomes
encrypted. Default value is EXP_CRYPT.
Port - The port number to connect to on the remote FTPS server.
The default port is 21 for EXP_CRYPT and CLR_CRYPT. But for
IMP_CRYPT the default port is 990. You only need to provide a port
if you need to override the default value.
DataProtLevel - The level of security on the data channel. The
default is DATA_PROT_PRIVATE, where the data is also encrypted.
DATA_PROT_CLEAR is for data sent as clear text. DATA_PROT_SAFE and
DATA_PROT_CONFIDENTIAL are not currently supported. If CLR_CRYPT
was selected, the data channel is always DATA_PROT_CLEAR and can't
be overridden.
useSSL - Use this option to connect to the server using SSL instead
of TLS. TLS is the default encryption type and the more secure of
the two protocols. Set useSSL => 1 to use SSL.
Timeout - Set a connection timeout value. Default value is 120.
PreserveTimestamp - During all puts and gets, attempt to preserve
the file's timestamp. By default it will not preserve the
timestamps.
Buffer - This is the block size that Net::FTPSSL will use when a
transfer is made. Default value is 10240.
Trace - Turns on/off put/get download tracing to STDERR. Default
is off.
Debug - This turns the debug tracing option on/off. Default is off.
(0,1,2)
DebugLogFile - Redirects the output of Debug from STDERR to the
requested error log file name. This option is ignored unless Debug
is also turned on. Enforced this way for backwards compatability.
If Debug is set to 2, the log file will be opened in append mode
instead of creating a new log file. This file is closed when quit
is called and Debug messages go back to STDERR again afterwards.
Croak - Force most methods to call croak() on failure instead of
returning FALSE. The default is to return FALSE or undef on
failure. When it croaks, it will attempt to close the FTPS
connection as well, preserving the last message before it attempts
to close the connection. Allowing the server to know the client is
going away. This will cause $Net::FTPSSL::ERRSTR to be set as
well.
SSL_Advanced - Expects a reference to a hash. This feature is
totally unsupported. It is only provided so you can attempt to use
the more obscure options when start_SSL() is called. If an option
here conflicts with other options we would normally use, entries in
this hash take precedence. See IO::Socket::SSL for these options.
METHODS
Most of the methods return true or false, true when the operation was a
success and false when failed. Methods like list or nlst return an
empty array when they fail. This behavior can be modified by the Croak
option.
login( USER, PASSWORD )
Use the given information to log into the FTPS server.
quit()
This method breaks the connection to the FTPS server. It will also
close the file pointed to by option DebugLogFile.
list( [DIRECTORY [, PATTERN]] )
This method returns a list of files in a format simalar to this:
(Server Specific)
drwxrwx--- 1 owner group 512 May 31 11:16 .
drwxrwx--- 1 owner group 512 May 31 11:16 ..
drwxrwx--- 1 owner group 512 Oct 27 2004 foo
drwxrwx--- 1 owner group 512 Oct 27 2004 pub
drwxrwx--- 1 owner group 512 Mar 29 12:09 bar
If DIRECTORY is omitted, the method will return the list of the
current directory.
If PATTERN is provided, it would limit the result similar to the
unix ls command or the Windows dir command. The only wild cards
supported are * and ?. (Match 0 or more chars. Or any one char.)
So a pattern of f*, ?Oo or FOO would find just foo from the list
above. Files with spaces in their name can cause strange results
when searching for a pattern.
nlst( [DIRECTORY [, PATTERN]] )
Same as "list" but returns the list in this format:
foo
pub
bar
Spaces in the filename do not cause problems with the PATTERN with
"nlst". Personally, I suggest using nlst instead of list.
ascii()
Sets the file transfer mode to ASCII. CR LF transformations will
be done.
binary()
Sets the file transfer mode to binary. No transformation will be
done.
get( REMOTE_FILE, [LOCAL_FILE] )
Retrieves the REMOTE_FILE from the ftp server. LOCAL_FILE may be a
filename or a filehandle. Return undef if it fails.
If the option PreserveTimestamp was used, and the FTPS server
supports it, it will attempt to reset the timestamp on LOCAL_FILE
to the timestamp on REMOTE_FILE.
put( LOCAL_FILE, [REMOTE_FILE] )
Stores the LOCAL_FILE onto the remote ftp server. LOCAL_FILE may be
a filehandle, but in this case REMOTE_FILE is required. Return
undef if it fails.
If the option PreserveTimestamp was used, and the FTPS server
supports it, it will attempt to reset the timestamp on REMOTE_FILE
to the timestamp on LOCAL_FILE.
uput( LOCAL_FILE, [REMOTE_FILE] )
Stores the LOCAL_FILE onto the remote ftp server. LOCAL_FILE may be
a filehandle, but in this case REMOTE_FILE is required. If
REMOTE_FILE already exists on the ftps server, a unique name is
calculated for use instead.
If the file transfer succeeds, this function will return the actual
name used on the remote ftps server. If it can't figure that out,
it will return what was used for REMOTE_FILE. On failure this
method will return undef.
If the option PreserveTimestamp was used, and the FTPS server
supports it, it will attempt to reset the timestamp on the remote
file using the file name being returned by this function to the
timestamp on LOCAL_FILE. So if the wrong name is being returned,
the wrong file will get it's timestamp updated.
xput( LOCAL_FILE, [REMOTE_FILE, [PREFIX, [POSTFIX, [BODY]]]] )
Use when the directory you are dropping REMOTE_FILE into is
monitored by a file recognizer that might pick the file up before
the file transfer has completed. So the file is transferred using
a temporary name using a naming convention that the file recognizer
will ignore and is guaranteed to be unique. Once the file transfer
successfully completes, it will be renamed to REMOTE_FILE for
immediate pickup by the file recognizer. If you requested to
preserve the file's timestamp, this step is done after the file is
renamed and so can't be 100% guaranteed if the file recognizer
picks it up first. Since if it was done before the rename, other
more serious problems could crop up if the resulting timestamp was
old enough.
On failure this function will attempt to delete the scratch file
for you if its at all possible. You will have to talk to your FTP
server administrator on good values for PREFIX and POSTFIX if the
defaults are no good for you.
PREFIX defaults to _tmp. unless you override it. Set to "" if you
need to suppress the PREFIX. This PREFIX can be a path to another
directory if needed, but that directory must already exist! Set to
undef to keep this default and you need to change the default for
POSTFIX or BODY.
POSTFIX defaults to .tmp unless you override it. Set to "" if you
need to suppress the POSTFIX. Set to undef to keep this default
and you need to change the default for BODY.
BODY defaults to client-name.PID so that you are guaranteed the
temp file will have an unique name on the remote server. It is
strongly recommended that you don't override this value.
So the temp scratch file would be called something like this by
default: _tmp.testclient.51243.tmp.
As a final note, if REMOTE_FILE has path information in it's name,
the temp scratch file will have the same directory added to it
unless you override the PREFIX with a different directory to drop
the scratch file into. This avoids forcing you to change into the
requested directory first when you have multiple files to send out
into multiple directories.
xget( REMOTE_FILE, [LOCAL_FILE, [PREFIX, [POSTFIX, [BODY]]]] )
The inverse of xput, where the file recognizer is on the client
side. The only other difference being what BODY defaults to. It
defaults to reverse(testclient).PID. So your default scratch file
would be something like: _tmp.tneilctset.51243.tmp.
Just be aware that in this case LOCAL_FILE can no longer be a file
handle.
delete( REMOTE_FILE )
Deletes the indicated REMOTE_FILE.
cwd( DIR )
Attempts to change directory to the directory given in DIR on the
remote server.
pwd()
Returns the full pathname of the current directory on the remote
server.
cdup()
Changes directory to the parent of the current directory on the
remote server.
mkdir( DIR )
Creates the indicated directory DIR on the remote server. No
recursion at the moment.
rmdir( DIR )
Removes the empty indicated directory DIR on the remote server. No
recursion at the moment.
noop()
It specifies no action other than the server send an OK reply.
rename( OLD, NEW )
Allows you to rename the file on the remote server.
ccc( [ DataProtLevel ] )
Sends the clear command channel request to the FTPS server. If you
provide the DataProtLevel, it will change it from the current data
protection level to this one before it sends the CCC command.
After the CCC command, the data channel protection level can not be
changed again and will always remain at this setting. Once you
execute the CCC request, you will have to create a new Net::FTPSSL
object to secure the command channel again. Due to security
concerns it is recommended that you do not use this method.
If the version of IO::Socket::SSL you have installed is too old,
this function will not work since stop_SSL won't be defined (like
in v1.08). So it is recommended that you be on at least version
1.18 or later if you plan on using this function.
site( ARGS )
Send a SITE command to the remote server and wait for a response.
mfmt( time_str, remote_file ) or _mfmt( timestamp, remote_file )
Both are boolean functions that attempt to reset the remote file's
timestamp on the FTPS server and returns true on success. The 1st
version can call croak on failure if Croak is turned on, while the
2nd version will not do this. The other difference between these
two functions is the format of the file's timestamp to use.
time_str expects the timestamp to be GMT time in format
YYYYMMDDHHMMSS. While timestamp expects to be in the same format
as returned by localtime().
mdtm( remote_file ) or _mdtm( remote_file )
The 1st version returns the file's timestamp as a string in
YYYYMMDDHHMMSS format using GMT time, it will return undef or call
croak on failure.
The 2nd version returns the file's timestamp in the same format as
returned by localtime() and will never call croak.
size( remote_file )
This function will return undef or croak on failure. Otherwise it
will return the file's size in bytes, which may also be zero bytes!
Just be aware for text files that the size returned may not match
the file's actual size when the file is downloaded to your system
in ASCII mode. This is an OS specific issue. It will always match
if you are using BINARY mode.
supported( CMD [,SITE_OPT] )
Returns TRUE if the remote server supports the given command. CMD
must match exactly. If the CMD is SITE and SITE_OPT is supplied,
it will also check if the specified SITE_OPT sub-command is
supported. Not all servers will support the use of SITE_OPT. This
function ignores the Croak request.
quot( CMD [,ARGS] )
Send a command, that Net::FTPSSL does not directly support, to the
remote server and wait for a response. You are responsible for
parsing anything you need from message() yourself.
Returns the most significant digit of the response code. So it
will ignore the Croak request.
WARNING This call should only be used on commands that do not
require data connections. Misuse of this method can hang the
connection if the internal list of FTP commands using a data
channel is incomplete.
last_message() or message()
Use either one to collect the last response from the FTPS server.
This is the same response printed to STDERR when Debug is turned
on. It may also contain any fatal error message encountered.
If you couldn't create a Net::FTPSSL object, you should get your
error message from $Net::FTPSSL::ERRSTR instead. Be careful since
$Net::FTPSSL::ERRSTR is shared between instances of Net::FTPSSL,
while message & last_message are not shared between instances!
last_status_code()
Returns the one digit status code associated with the last response
from the FTPS server.
set_croak( [1/0] )
Used to turn the Croak option on/off after the Net::FTPSSL object
has been created. It returns the previous Croak settings before
the change is made. If you don't provide an argument, all it does
is return the current setting. Provided in case the Croak option
proves to be too restrictive in some cases.
set_callback( [cb_func_ref, end_cb_func_ref [, cb_data_ref]] )
This function allows the user to define a callback function to use
whenever a data channel to the server is open. If either
cb_func_ref or end_cb_func_ref is undefined, it disables the
callback functionality, since both are required for call backs to
function properly.
The cb_func_ref is a reference to a function to handle processing
the data channel data. This is a void function that can be called
multiple times. It is called each time a chunk of data is read
from or written to the data channel.
The end_cb_func_ref is a reference to a function to handle closing
the callback for this data channel connection. This function is
allowed to return a string of additional data to process before the
data channel is closed. It is called only once per command after
processing all the data channel data.
The cb_data_ref is an optional reference to an array or hash that
the caller can use to store values between calls to the callback
function and the end callback function. If you don't need such a
work area, it's safe to not provide one. The Net::FTPSSL class
doesn't look at this reference.
The callback function must take the following 5 arguments:
B<callback> (ftps_func_name, data_ref, data_len_ref, total_len, cb_data_ref);
The ftps_func_name will tell what Net::FTPSSL function requested
the callback so that your callback function can determine what the
data is for and do conditional logic accordingly. We don't provide
a reference to the Net::FTPSSL object itself since the class is not
recursive. Each Net::FTPSSL object should have it's own cb_dat_ref
to work with. But methods within the class can share one.
Since we pass the data going through the data channel as a
reference, you are allowed to modify the data. But if you do, be
sure to update data_len_ref to the new data length as well.
Otherwise you will get buggy responses.
Finally, the total_len is how many bytes have already been
processed. It does not include the data passed for the current
callback call. So it will always be zero the first time it's
called.
Once we finish processing data for the data channel, a different
callback function will be called to tell you that the data channel
is closing. This is your last chance to affect what is going over
the data channel and to do any needed post processing. The end
callback function must take the following arguments:
$end = B<end_callback> (ftps_func_name, total_len, cb_data_ref);
These arguments have the same meaning as for the callback function,
except that this function allows you to optionally provide
additional data to/from the data channel. If reading from the data
channel, it will treat the return value as the last data returned
before it was closed. Otherwise it will be written to the data
channel before it is closed. Please return undef if there is
nothing extra for the Net::FTPSSL command to process.
You should also take care to clean up the contents of cb_data_ref
in the end_callback function. Otherwise the next callback sequence
that uses this work area may behave strangely.
As a final note, should the data channel be empty, it is likely
that just the end_callback function is called without any calls to
the callback function.
AUTHORS
Marco Dalla Stella - <kral at paranoici dot org>
Curtis Leach - <cleach at cpan dot org> - As of v0.05
SEE ALSO
Net::Cmd
Net::FTP
Net::SSLeay::Handle
IO::Socket::SSL
RFC 959 - ftp://ftp.rfc-editor.org/in-notes/rfc959.txt <ftp://ftp.rfc-
editor.org/in-notes/rfc959.txt>
RFC 2228 - ftp://ftp.rfc-editor.org/in-notes/rfc2228.txt
<ftp://ftp.rfc-editor.org/in-notes/rfc2228.txt>
RFC 4217 - ftp://ftp.rfc-editor.org/in-notes/rfc4217.txt
<ftp://ftp.rfc-editor.org/in-notes/rfc4217.txt>
CREDITS
Graham Barr <gbarr at pobox dot com> - for have written such a great
collection of modules (libnet).
BUGS
Please report any bugs with a FTPS log file created via options
Debug=>1 and DebugLogFile=>"file.txt" along with your sample code at
http://search.cpan.org/~cleach/Net-FTPSSL-0.15/FTPSSL.pm
<http://search.cpan.org/~cleach/Net-FTPSSL-0.15/FTPSSL.pm>.
Patches are appreciated when a log file and sample code are also
provided.
COPYRIGHT
Copyright (c) 2005 Marco Dalla Stella. All rights reserved.
Copyright (c) 2009, 2010 Curtis Leach. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2010-04-27 FTPSSL(3)
