Net::SFTP(3) User Contributed Perl Documentation Net::SFTP(3)NAMENet::SFTP - Secure File Transfer Protocol client
SYNOPSIS
use Net::SFTP;
my $sftp = Net::SFTP->new($host);
$sftp->get("foo", "bar");
$sftp->put("bar", "baz");
DESCRIPTIONNet::SFTP is a pure-Perl implementation of the Secure File Transfer
Protocol (SFTP) - file transfer built on top of the SSH2 protocol.
Net::SFTP uses Net::SSH::Perl to build a secure, encrypted tunnel
through which files can be transferred and managed. It provides a
subset of the commands listed in the SSH File Transfer Protocol IETF
draft, which can be found at
http://www.openssh.com/txt/draft-ietf-secsh-filexfer-00.txt.
SFTP stands for Secure File Transfer Protocol and is a method of
transferring files between machines over a secure, encrypted connection
(as opposed to regular FTP, which functions over an insecure
connection). The security in SFTP comes through its integration with
SSH, which provides an encrypted transport layer over which the SFTP
commands are executed, and over which files can be transferred. The
SFTP protocol defines a client and a server; only the client, not the
server, is implemented in Net::SFTP.
Because it is built upon SSH, SFTP inherits all of the built-in
functionality provided by Net::SSH::Perl: encrypted communications
between client and server, multiple supported authentication methods
(eg. password, public key, etc.).
USAGE
Net::SFTP->new($host, %args)
Opens a new SFTP connection with a remote host $host, and returns a
Net::SFTP object representing that open connection.
%args can contain:
· user
The username to use to log in to the remote server. This should be
your SSH login, and can be empty, in which case the username is
drawn from the user executing the process.
See the login method in Net::SSH::Perl for more details.
· password
The password to use to log in to the remote server. This should be
your SSH password, if you use password authentication in SSH; if
you use public key authentication, this argument is unused.
See the login method in Net::SSH::Perl for more details.
· debug
If set to a true value, debugging messages will be printed out for
both the SSH and SFTP protocols. This automatically turns on the
debug parameter in Net::SSH::Perl.
The default is false.
· warn
If given a sub ref, the sub is called with $self and any warning
message; if set to false, warnings are supressed; otherwise they
are output with 'warn' (default).
· ssh_args
Specifies a reference to a list or hash of named arguments that
should be given to the constructor of the Net::SSH::Perl object
underlying the Net::SFTP connection.
For example, you could use this to set up your authentication
identity files, to set a specific cipher for encryption, etc., e.g.
"ssh_args => [ cipher => 'arcfour' ]".
See the new method in Net::SSH::Perl for more details.
$sftp->status
Returns the last remote SFTP status value. Only useful after one of
the following methods has failed. Returns SSH2_FX_OK if there is no
remote error (e.g. local file not found). In list context, returns a
list of (status code, status text from "fx2txt").
If a low-level protocol error or unexpected local error occurs, we die
with an error message.
$sftp->get($remote [, $local [, \&callback ] ])
Downloads a file $remote from the remote host. If $local is specified,
it is opened/created, and the contents of the remote file $remote are
written to $local. In addition, its filesystem attributes (atime,
mtime, permissions, etc.) will be set to those of the remote file.
If get is called in a non-void context, returns the contents of $remote
(as well as writing them to $local, if $local is provided. Undef is
returned on failure.
$local is optional. If not provided, the contents of the remote file
$remote will be either discarded, if get is called in void context, or
returned from get if called in a non-void context. Presumably, in the
former case, you will use the callback function \&callback to "do
something" with the contents of $remote.
If \&callback is specified, it should be a reference to a subroutine.
The subroutine will be executed at each iteration of the read loop
(files are generally read in 8192-byte blocks, although this depends on
the server implementation). The callback function will receive as
arguments: a Net::SFTP object with an open SFTP connection; the data
read from the SFTP server; the offset from the beginning of the file
(in bytes); and the total size of the file (in bytes). You can use this
mechanism to provide status messages, download progress meters, etc.:
sub callback {
my($sftp, $data, $offset, $size) = @_;
print "Read $offset / $size bytes\r";
}
$sftp->put($local, $remote [, \&callback ])
Uploads a file $local from the local host to the remote host, and saves
it as $remote.
If \&callback is specified, it should be a reference to a subroutine.
The subroutine will be executed at each iteration of the write loop,
directly after the data has been read from the local file. The callback
function will receive as arguments: a Net::SFTP object with an open
SFTP connection; the data read from $local, generally in 8192-byte
chunks;; the offset from the beginning of the file (in bytes); and the
total size of the file (in bytes). You can use this mechanism to
provide status messages, upload progress meters, etc.:
sub callback {
my($sftp, $data, $offset, $size) = @_;
print "Wrote $offset / $size bytes\r";
}
Returns true on success, undef on error.
$sftp->ls($remote [, $subref ])
Fetches a directory listing of $remote.
If $subref is specified, for each entry in the directory, $subref will
be called and given a reference to a hash with three keys: filename,
the name of the entry in the directory listing; longname, an entry in a
"long" listing like "ls -l"; and a, a Net::SFTP::Attributes object,
which contains the file attributes of the entry (atime, mtime,
permissions, etc.).
If $subref is not specified, returns a list of directory entries, each
of which is a reference to a hash as described in the previous
paragraph.
COMMAND METHODSNet::SFTP supports all of the commands listed in the SFTP version 3
protocol specification. Each command is available for execution as a
separate method, with a few exceptions: SSH_FXP_INIT, SSH_FXP_VERSION,
and SSH_FXP_READDIR.
These are the available command methods:
$sftp->do_open($path, $flags [, $attrs ])
Sends the SSH_FXP_OPEN command to open a remote file $path, and returns
an open handle on success. On failure returns undef. The "open handle"
is not a Perl filehandle, nor is it a file descriptor; it is merely a
marker used to identify the open file between the client and the
server.
$flags should be a bitmask of open flags, whose values can be obtained
from Net::SFTP::Constants:
use Net::SFTP::Constants qw( :flags );
$attrs should be a Net::SFTP::Attributes object, specifying the initial
attributes for the file $path. If you're opening the file for reading
only, $attrs can be left blank, in which case it will be initialized to
an empty set of attributes.
$sftp->do_read($handle, $offset, $copy_size)
Sends the SSH_FXP_READ command to read from an open file handle
$handle, starting at $offset, and reading at most $copy_size bytes.
Returns a two-element list consisting of the data read from the SFTP
server in the first slot, and the status code (if any) in the second.
In the case of a successful read, the status code will be undef, and
the data will be defined and true. In the case of EOF, the status code
will be SSH2_FX_EOF, and the data will be undef. And in the case of an
error in the read, a warning will be emitted, the status code will
contain the error code, and the data will be undef.
$sftp->do_write($handle, $offset, $data)
Sends the SSH_FXP_WRITE command to write to an open file handle
$handle, starting at $offset, and where the data to be written is in
$data.
Returns the status code. On a successful write, the status code will be
equal to SSH2_FX_OK; in the case of an unsuccessful write, a warning
will be emitted, and the status code will contain the error returned
from the server.
$sftp->do_close($handle)
Sends the SSH_FXP_CLOSE command to close either an open file or open
directory, identified by $handle (the handle returned from either
do_open or do_opendir).
Emits a warning if the CLOSE fails.
Returns the status code for the operation. To turn the status code into
a text message, take a look at the "fx2txt" function in
Net::SFTP::Util.
$sftp->do_lstat($path)
$sftp->do_fstat($handle)
$sftp->do_stat($path)
These three methods all perform similar functionality: they run a stat
on a remote file and return the results in a Net::SFTP::Attributes
object on success.
On failure, all three methods return undef, and emit a warning.
do_lstat sends a SSH_FXP_LSTAT command to obtain file attributes for a
named file $path. do_stat sends a SSH_FXP_STAT command, and differs
from do_lstat only in that do_stat follows symbolic links on the
server, whereas do_lstat does not follow symbolic links.
do_fstat sends a SSH_FXP_FSTAT command to obtain file attributes for an
open file handle $handle.
$sftp->do_setstat($path, $attrs)
$sftp->do_fsetstat($handle, $attrs)
These two methods both perform similar functionality: they set the file
attributes of a remote file. In both cases $attrs should be a
Net::SFTP::Attributes object.
do_setstat sends a SSH_FXP_SETSTAT command to set file attributes for a
remote named file $path to $attrs.
do_fsetstat sends a SSH_FXP_FSETSTAT command to set the attributes of
an open file handle $handle to $attrs.
Both methods emit a warning if the operation failes, and both return
the status code for the operation. To turn the status code into a text
message, take a look at the "fx2txt" function in Net::SFTP::Util.
$sftp->do_opendir($path)
Sends a SSH_FXP_OPENDIR command to open the remote directory $path, and
returns an open handle on success. On failure returns undef.
$sftp->do_remove($path)
Sends a SSH_FXP_REMOVE command to remove the remote file $path.
Emits a warning if the operation fails.
Returns the status code for the operation. To turn the status code into
a text message, take a look at the "fx2txt" function in
Net::SFTP::Util.
$sftp->do_mkdir($path, $attrs)
Sends a SSH_FXP_MKDIR command to create a remote directory $path whose
attributes should be initialized to $attrs, a Net::SFTP::Attributes
object.
Emits a warning if the operation fails.
Returns the status code for the operation. To turn the status code into
a text message, take a look at the "fx2txt" function in
Net::SFTP::Util.
$sftp->do_rmdir($path)
Sends a SSH_FXP_RMDIR command to remove a remote directory $path.
Emits a warning if the operation fails.
Returns the status code for the operation. To turn the status code into
a text message, take a look at the "fx2txt" function in
Net::SFTP::Util.
$sftp->do_realpath($path)
Sends a SSH_FXP_REALPATH command to canonicalise $path to an absolute
path. This can be useful for turning paths containing '..' into
absolute paths.
Returns the absolute path on success, undef on failure.
$sftp->do_rename($old, $new)
Sends a SSH_FXP_RENAME command to rename $old to $new.
Emits a warning if the operation fails.
Returns the status code for the operation. To turn the status code into
a text message, take a look at the "fx2txt" function in
Net::SFTP::Util.
SUPPORT
For samples/tutorials, take a look at the scripts in eg/ in the
distribution directory.
There is a mailing list for development discussion and usage questions.
Posting is limited to subscribers only. You can sign up at
http://lists.sourceforge.net/lists/listinfo/ssh-sftp-perl-users
Please report all bugs via rt.cpan.org at
https://rt.cpan.org/NoAuth/ReportBug.html?Queue=net%3A%3Asftp
AUTHOR
Current maintainer is David Robins, dbrobins@cpan.org.
Previous maintainer was Dave Rolsky, autarch@urth.org.
Originally written by Benjamin Trott.
COPYRIGHT
Copyright (c) 2001-2003 Benjamin Trott, Copyright (c) 2003-2004 David
Rolsky. Copyright (c) David Robins. All rights reserved. This
program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.
perl v5.14.1 2005-10-05 Net::SFTP(3)
