Net::FTPSSL
FTPSSL(3) User Contributed Perl Documentation FTPSSL(3)
NAME
Net::FTPSSL - A FTP over SSL/TLS class
VERSION 0.08
SYNOPSIS
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) connec-
tion 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:
Port - The port number to connect to on the remote FTP server.
Default value is 21 for EXP_CRYPT and CLR_CRYPT or 990 for
IMP_CRYPT.
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.
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.
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 times-
tamps.
Buffer - This is the block size that Net::FTPSSL will use when a
transfer is made. Default value is 10240.
Debug - This turns the debug information option on/off. Default is
off.
Trace - Turns on/off put/get download tracing to STDERR. Default
is off.
Croak - Force most methods to call croak() on failure instead of
returning FALSE. The default is to return FALSE or undef on fail-
ure. 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 FTP server.
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 and the Windows Command Window 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
Personally, I suggest using list instead of nlst.
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 sup-
ports 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 sup-
ports 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 ftp 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 fail-
ure this method will return undef.
If the option PreserveTimestamp was used, and the FTPS server sup-
ports 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 moni-
tored 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 trans-
fer successfully completes, it will be renamed to REMOTE_FILE for
immediate pickup by the file recognizer. If you requested to pre-
serve 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. But if it was done before the rename, other
more serious problems could crop up.
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 FTP 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.
delete( REMOTE_FILE )
Deletes the indicated REMOTE_FILE.
cwd( DIR )
Attempts to change directory to the directory given in DIR.
pwd()
Returns the full pathname of the current directory.
cdup()
Changes directory to the parent of the current directory.
mkdir( DIR )
Creates the indicated directory DIR. No recursion at the moment.
rmdir( DIR )
Removes the empty indicated directory DIR. 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 server.
site( ARGS )
Send a SITE command to the remote server and wait for a response.
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 sup-
ported. 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.
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 con-
nection 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 FTP server.
This is the same response printed to STDERR when trace 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.
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 call-
back 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 pro-
vide 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 refer-
ence, 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 pro-
cessed. It does not include the data passed for the current call-
back 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 func-
tion, 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.
AUTHOR
Marco Dalla Stella - <kral at paranoici dot org>
MAINTAINER
Curtis Leach - 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>
RFC 2228 - <ftp://ftp.rfc-editor.org/in-notes/rfc2228.txt>
RFC 4217 - <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
I’m currently testing the module with proftpd and Titan FTP. I’m hav-
ing a lot of trouble with the second at the moment. Put or get phases
seem to work ok (sysread and syswrite don’t return any errors) but the
server doesn’t receive all the sent data. I’m working on it.
COPYRIGHT
Copyright (c) 2005 Marco Dalla Stella. All rights reserved.
Copyright (c) 2009 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.8.8 2009-03-17 FTPSSL(3)
