Linux Certif

Toute la documentation sur la certification Linux LPI

Net::SFTP::Foreign.3pm

NAME

Net::SFTP::Foreign - SSH File Transfer Protocol client

SYNOPSIS

     use Net::SFTP::Foreign;
     my $sftp = Net::SFTP::Foreign->new($host);
     $sftp->error and
        die "Unable to stablish SFTP connection: " . $sftp->error;
 
     $sftp->setcwd($path) or die "unable to change cwd: " . $sftp->error;
 
     $sftp->get("foo", "bar") or die "get failed: " . $sftp->error;
 
     $sftp->put("bar", "baz") or die "put failed: " . $sftp->error;
 
 

DESCRIPTION

SFTP stands for SSH 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.

Net::SFTP::Foreign is a Perl client for the SFTP version 3 as defined in the SSH File Transfer Protocol IETF draft, which can be found at <http://www.openssh.org/txt/draft-ietf-secsh-filexfer-02.txt> (also included on this package distribution, on the "rfc" directory).

Net::SFTP::Foreign uses any compatible "ssh" command installed on the system (for instance, OpenSSH "ssh") to establish the secure connection to the remote server.

A wrapper module Net::SFTP::Foreign::Compat is also provided for compatibility with Net::SFTP.

Net::SFTP::Foreign Vs. Net::SFTP Vs. Net::SSH2::SFTP

Why should I prefer Net::SFTP::Foreign over Net::SFTP?

Well, both modules have their pros and cons:

Net::SFTP::Foreign does not require a bunch of additional modules and external libraries to work, just the OpenBSD SSH client (or any other client compatible enough).

I trust OpenSSH SSH client more than Net::SSH::Perl, there are lots of paranoid people ensuring that OpenSSH doesn't have security holes!!!

If you have an SSH infrastructure already deployed, by using the same binary SSH client, Net::SFTP::Foreign ensures a seamless integration within your environment (configuration files, keys, etc.).

Net::SFTP::Foreign is much faster transferring files, specially over networks with high (relative) latency.

Net::SFTP::Foreign provides several high level methods not available from Net::SFTP as for instance "find", "glob", "rget", "rput", "rremove", "mget", "mput".

On the other hand, using the external command means an additional proccess being launched and running, depending on your OS this could eat more resources than the in process pure perl implementation provided by Net::SSH::Perl.

Net::SSH2 is a module wrapping libssh2, an SSH version 2 client library written in C. It is a very active project that aims to replace Net::SSH::Perl. Unfortunately, libssh2 SFTP functionality (available in Perl via Net::SSH2::SFTP) is rather limited and its performance very poor.

Later versions of Net::SFTP::Foreign can use Net::SSH2 as the transport layer via the backend module Net::SFTP::Foreign::Backend::Net_SSH2.

Usage

Most of the methods available from this package return undef on failure and a true value or the requested data on success. "$sftp->error" can be used to check for errors explicitly after every method call.

Don't forget to read also the FAQ and BUGS sections at the end of this document!

Net::SFTP::Foreign->new($host, %args)

Net::SFTP::Foreign->new(%args)

Opens a new SFTP connection with a remote host $host, and returns a Net::SFTP::Foreign object representing that open connection.

An explicit check for errors should be included always after the constructor call:

   my $sftp = Net::SFTP::Foreign->new(...);
   $sftp->error and die "SSH connection failed: " . $sftp->error;
 
 

%args can contain:

host => $hostname

remote host name

user => $username

username 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.

port => $portnumber

port number where the remote SSH server is listening

more => [@more_ssh_args]

additional args passed to "ssh" command.

For debugging purposes you can run "ssh" in verbose mode passing it the "-v" option:

   my $sftp = Net::SFTP::Foreign->new($host, more => '-v');
 
 

Note that this option expects a single command argument or a reference to an array of arguments. For instance:

   more => '-v'         # right
   more => ['-v']       # right
   more => "-i $key"    # wrong!!!
   more => [-i => $key] # right
 
 

ssh_cmd_interface => 'plink' or 'ssh'

declares the command line interface that the SSH client used to connect to the remote host understands. Currently "plink" and "ssh" are supported.

This option would be rarely required as the module infers the interface from the SSH command name.

autoflush => $bool

by default, and for performance reasons, write operations are cached, and only when the write buffer becomes big enough is the data written to the remote file. Setting this flag makes the write operations inmediate.

timeout => $seconds

when this parameter is set, the connection is dropped if no data arrives on the SSH socket for the given time while waiting for some command to complete.

When the timeout expires, the current method is aborted and the SFTP connection becomes invalid.

fs_encoding => $encoding

Version 3 of the SFTP protocol (the one supported by this module) knows nothing about the character encoding used on the remote filesystem to represent file and directory names.

This option allows to select the encoding used in the remote machine. The default value is "utf8".

For instance:

   $sftp = Net::SFTP::Foreign->new('user@host', fs_encoding => latin1);
 
 

will convert any path name passed to any method in this package to its "latin1" representation before sending it to the remote side.

Note that this option will not affect file contents in any way.

This feature is not supported in perl 5.6 due to incomplete Unicode support in the interpreter.

password => $password

passphrase => $passphrase

uses Expect to handle password authentication or keys requiring a passphrase.

Note that password authentication on Windows OSs only works when the Cygwin port of Perl is used.

expect_log_user => $bool

activates password/passphrase authentication interaction logging (see "Expect::log_user" method documentation).

ssh_cmd => $sshcmd

name of the external SSH client. By default "ssh" is used.

For instance:

   my $sftp = Net::SFTP::Foreign->new($host, ssh_cmd => 'plink');
 
 

ssh1 => 1

Use old SSH1 approach for starting the remote SFTP server.

transport => $fh

transport => [$in_fh, $out_fh]

transport => [$in_fh, $out_fh, $pid]

allows to use an already open pipe or socket as the transport for the SFTP protocol.

It can be (ab)used to make this module work with password authentication or with keys requiring a passphrase.

"in_fh" is the file handler used to read data from the remote server, "out_fh" is the file handler used to write data.

On some systems, when using a pipe as the transport, closing it, does not cause the process at the other side to exit. The additional $pid argument can be used to instruct this module to kill that process if it doesn't exit by itself.

open2_cmd => [@cmd]

open2_cmd => $cmd;

allows to completely redefine how "ssh" is called. Its arguments are passed to IPC::Open2::open2 to open a pipe to the remote server.

block_size => $default_block_size

queue_size => $default_queue_size

default "block_size" and "queue_size" used for read and write operations (see the "put" or "get" documentation).

autodisconnect => $ad

By default, the SSH connection is closed from the DESTROY method when the object goes out of scope. But on scripts that fork new processes, that results on the SSH connection being closed by the first process where the object goes out of scope, something undesirable.

This option allows to work-around this issue to some extend.

The acceptable values for $ad are:

0

Never try to disconnect this object when exiting from any process.

On most operative systems, the SSH process will exit when the last process connected to it ends, but this is not guaranteed.

1

Disconnect on exit from any process. This is the default.

2

Disconnect on exit from the current process only.

See also the disconnect and autodisconnect methods.

late_set_perm => $bool

See the FAQ below.

dirty_cleanup => $bool

Sets the "dirty_cleanup" flag in a per object basis (see the BUGS section).

backend => $backend

From version 1.57 Net::SFTP::Foreign supports plugable backends in order to allow other ways to comunicate with the remote server in addition to the default pipe-to-ssh-process.

Custom backends may change the set of options supported by the "new" method.

$sftp->error

Returns the error code from the last executed command. The value returned is similar to $!, when used as a string it yields the corresponding error string.

See Net::SFTP::Foreign::Constants for a list of possible error codes and how to import them on your scripts.

$sftp->status

Returns the code from the last SSH2_FXP_STATUS response. It is also a dualvar that yields the status string when used as a string.

Usually "$sftp->error" should be checked first to see if there was any error and then "$sftp->status" to find out its low level cause.

$sftp->cwd

Returns the remote current working directory.

When a relative remote path is passed to any of the methods on this package, this directory is used to compose the absolute path.

$sftp->setcwd($dir)

Changes the remote current working directory. The remote directory should exist, otherwise the call fails.

Returns the new remote current working directory or undef on failure.

$sftp->get($remote, $local, %options)

Copies remote file $remote to local $local. By default file attributes are also copied (permissions, atime and mtime). For instance:

   $sftp->get('/var/log/messages', /tmp/messages')
     or die "file transfer failed: " . $sftp->error;
 
 

A file handle can also be used as the local target. In that case, the remote file contents are retrieved and written to the given file handle. Note also that the handle is not closed when the transmission finish.

   open F, '| gzip -c > /tmp/foo' or die ...;
   $sftp->get("/etc/passwd", \*F)
     or die "get failed: " . $sftp->error;
   close F or die ...;
 
 

Accepted options (not all combinations are possible):

copy_time => $bool

determines if access and modification time attributes have to be copied from remote file. Default is to copy them.

copy_perm => $bool

determines if permision attributes have to be copied from remote file. Default is to copy them after applying the local process umask.

umask => $umask

allows to select the umask to apply when setting the permissions of the copied file. Default is to use the umask for the current process.

perm => $perm

sets the permision mask of the file to be $perm, umask and remote permissions are ignored.

resume => 1 | 'auto'

resumes an interrupted transfer.

If the "auto" value is given, the transfer will be resumed only when the local file is newer than the remote one.

"get" transfers can not be resumed when a data conversion is in place.

append => 1

appends the contents of the remote file at the end of the local one instead of overwriting it. If the local file does not exist a new one is created.

overwrite => 0

setting this option to zero cancels the transfer when a local file of the same name already exists.

numbered => 1

modifies the local file name inserting a sequence number when required in order to avoid overwriting local files.

For instance:

   for (1..2) {
     $sftp->get("data.txt", "data.txt", numbered => 1);
   }
 
 

will copy the remote file as ``data.txt'' the first time and as ``data(1).txt'' the second one.

conversion => $conversion

on the fly data conversion of the file contents can be performed with this option. See ``On the fly data conversion'' bellow.

callback => $callback

$callback is a reference to a subroutine that will be called after every iteration of the download process.

The callback function will receive as arguments: the current Net::SFTP::Foreign object; the data read from the remote file; the offset from the beginning of the file in bytes; and the total size of the file in bytes.

This mechanism can be used to provide status messages, download progress meters, etc.:

     sub callback {
         my($sftp, $data, $offset, $size) = @_;
         print "Read $offset / $size bytes\r";
     }
 
 

The "abort" method can be called from inside the callback to abort the transfer:

     sub callback {
         my($sftp, $data, $offset, $size) = @_;
         if (want_to_abort_transfer()) {
             $sftp->abort("You wanted to abort the transfer");
         }
     }
 
 

The callback will be called one last time with an empty data argument to indicate the end of the file transfer.

The size argument can change between different calls as data is transferred (for instance, when on-the-fly data conversion is being performed or when the size of the file can not be retrieved with the "stat" SFTP command before the data transfer starts).

block_size => $bytes

size of the blocks the file is being splittered on for transfer. Incrementing this value can improve performance but some servers limit the maximum size.

queue_size => $size

read and write requests are pipelined in order to maximize transfer throughput. This option allows to set the maximum number of requests that can be concurrently waiting for a server response.

$sftp->get_content($remote)

Returns the content of the remote file.

$sftp->get_symlink($remote, $local, %opts)

copies a symlink from the remote server to the local file system

The accepted options are "overwrite" and "numbered". They have the same effect as for the "get" method.

$sftp->put($local, $remote, %opts)

Uploads a file $local from the local host to the remote host, and saves it as $remote. By default file attributes are also copied. For instance:

   $sftp->put("test.txt", "test.txt")
     or die "put failed: " . $sftp->error;
 
 

A file handle can also be passed in the $local argument. In that case, data is read from there and stored in the remote file. UTF8 data is not supported unless a custom converter callback is used to transform it to bytes and the method will croak if it encounters any data in perl internal UTF8 format. Note also that the handle is not closed when the transmission finish.

Example:

   binmode STDIN;
   $sftp->put(\*STDIN, "stdin.dat") or die "put failed";
   close STDIN;
 
 

This method accepts several options:

copy_time => $bool

determines if access and modification time attributes have to be copied from remote file. Default is to copy them.

copy_perm => $bool

determines if permision attributes have to be copied from remote file. Default is to copy them after applying the local process umask.

umask => $umask

allows to select the umask to apply when setting the permissions of the copied file. Default is to use the umask for the current process.

perm => $perm

sets the permision mask of the file to be $perm, umask and local permissions are ignored.

append => 1

appends the local file at the end of the remote file instead of overwriting it. If the remote file does not exist a new one is created.

resume => 1 | 'auto'

resumes an interrupted transfer.

If the "auto" value is given, the transfer will be resumed only when the remote file is newer than the local one.

conversion => $conversion

on the fly data conversion of the file contents can be performed with this option. See ``On the fly data conversion'' bellow.

callback => $callback

$callback is a reference to a subrutine that will be called after every iteration of the upload process.

The callback function will receive as arguments: the current Net::SFTP::Foreign object; the data that is going to be written to the remote file; the offset from the beginning of the file in bytes; and the total size of the file in bytes.

The callback will be called one last time with an empty data argument to indicate the end of the file transfer.

The size argument can change between calls as data is transferred (for instance, when on the fly data conversion is being performed).

This mechanism can be used to provide status messages, download progress meters, etc.

The "abort" method can be called from inside the callback to abort the transfer.

block_size => $bytes

size of the blocks the file is being splittered on for transfer. Incrementing this value can improve performance but some servers limit its size and if this limit is overpassed the command will fail.

queue_size => $size

read and write requests are pipelined in order to maximize transfer throughput. This option allows to set the maximum number of requests that can be concurrently waiting for a server response.

late_set_perm => $bool

See the FAQ below.

$sftp->put_symlink($local, $remote, %opts)

copies a local symlink to the remote host.

The accepted options are "overwrite" and "numbered".

$sftp->abort()

$sftp->abort($msg)

This method, when called from inside a callback sub, causes the current transfer to be aborted

The error state is set to SFTP_ERR_ABORTED and the optional $msg argument is used as its textual value.

$sftp->ls($remote, %opts)

Fetches a listing of the remote directory $remote. If $remote is not given, the current remote working directory is listed.

Returns a reference to a list of entries. Every entry is a reference to a hash with three keys: "filename", the name of the entry; "longname", an entry in a ``long'' listing like "ls -l"; and "a", a Net::SFTP::Foreign::Attributes object containing file atime, mtime, permissions and size.

     my $ls = $sftp->ls('/home/foo')
         or die "unable to retrieve directory: ".$sftp->error;
 
     print "$_->{filename}\n" for (@$ls);
 
 

The options accepted by this method are as follows (note that usage of some of them can degrade the method performance when reading large directories):

wanted => qr/.../

Only elements which filename match the regular expression are included on the listing.

wanted => sub {...}

Only elements for which the callback returns a true value are included on the listing. The callback is called with two arguments: the $sftp object and the current entry (a hash reference as described before). For instance:

   use Fcntl ':mode';
 
   my $files = $sftp->ls ( '/home/hommer',
                           wanted => sub {
                               my $entry = $_[1];
                               S_ISREG($entry->{a}->perm)
                           } )
         or die "ls failed: ".$sftp->error;
 
 

no_wanted => qr/.../

no_wanted => sub {...}

those options have the oposite result to their "wanted" counterparts:

   my $no_hidden = $sftp->ls( '/home/homer',
                              no_wanted => qr/^\./ )
         or die "ls failed";
 
 

When both "no_wanted" and "wanted" rules are used, the "no_wanted" rule is applied first and then the "wanted" one (order is important if the callbacks have side effects, experiment!).

ordered => 1

the list of entries is ordered by filename.

follow_links => 1

by default, the attributes on the listing correspond to a "lstat" operation, setting this option causes the method to perform "stat" requests instead. "lstat" attributes will stil appear for links pointing to non existant places.

atomic_readdir => 1

reading a directory is not an atomic SFTP operation and the protocol draft does not define what happens if "readdir" requests and write operations (for instance "remove" or "open") affecting the same directory are intermixed.

This flag ensures that no callback call ("wanted", "no_wanted") is performed in the middle of reading a directory and has to be set if any of the callbacks can modify the file system.

realpath => 1

for every file object, performs a realpath operation and populates the "realpath" entry.

names_only => 1

makes the method return a simple array containing the file names from the remote directory only. For instance, these two sentences are equivalent:

   my @ls1 = @{ $sftp->ls('.', names_only => 1) };
 
   my @ls2 = map { $_->{filename} } @{$sftp->ls('.')};
 
 

$sftp->find($path, %opts)

$sftp->find(\@paths, %opts)

Does a recursive search over the given directory $path (or directories @path) and returns a list of the entries found or the total number of them on scalar context.

Every entry is a reference to a hash with two keys: "filename", the full path of the entry; and "a", a Net::SFTP::Foreign::Attributes object containing file atime, mtime, permissions and size.

This method tries to recover and continue under error conditions.

The options accepted:

on_error => sub { ... }

the callback is called when some error is detected, two arguments are passed: the $sftp object and the entry that was being processed when the error happened. For instance:

   my @find = $sftp->find( '/',
                           on_error => sub {
                               my ($sftp, $e) = @_;
                               print STDERR "error processing $e->{filename}: "
                                    . $sftp->error;
                           } );
 
 

realpath => 1

calls method "realpath" for every entry, the result is stored under the key "realpath". This option slows down the process as a new remote query is performed for every entry, specially on networks with high latency.

follow_links => 1

By default symbolic links are not resolved and appear as that on the final listing. This option causes then to be resolved and substituted by the target file system object. Dangling links are ignored, though they generate a call to the "on_error" callback when stat'ing them fails.

Following sym links can introduce loops on the search. Infinite loops are detected and broken but files can still appear repeated on the final listing under different names unless the option "realpath" is also actived.

ordered => 1

By default, the file system is searched in an implementation dependent order (actually optimized for low memory comsumption). If this option is included, the file system is searched in a deep-first, sorted by filename fashion.

wanted => qr/.../

wanted => sub { ... }

no_wanted => qr/.../

no_wanted => sub { ... }

These options have the same effect as on the "ls" method, allowing to filter out unwanted entries (note that filename keys contain full paths here).

The callbacks can also be used to perform some action instead of creating the full listing of entries in memory (that could use huge amounts of RAM for big file trees):

   $sftp->find($src_dir,
               wanted => sub {
                   my $fn = $_[1]->{filename}
                   print "$fn\n" if $fn =~ /\.p[ml]$/;
                   return undef # so it is discarded
               });
 
 

descend => qr/.../

descend => sub { ... }

no_descend => qr/.../

no_descend => sub { ... }

These options, similar to the "wanted" ones, allow to prune the search, discarding full subdirectories. For instance:

     use Fcntl ':mode';
     my @files = $sftp->find( '.',
                              no_descend => qr/\.svn$/,
                              wanted => sub {
                                  S_ISREG($_[1]->{a}->perm)
                              } );
 
 

"descend" and "wanted" rules are unrelated. A directory discarded by a "wanted" rule will still be recursively searched unless it is also discarded on a "descend" rule and vice-versa.

atomic_readdir => 1

see "ls" method documentation.

names_only => 1

makes the method return a list with the names of the files only (see "ls" method documentation).

equivalent:

   my $ls1 = $sftp->ls('.', names_only => 1);
 
 

$sftp->glob($pattern, %opts)

performs a remote glob and returns the list of matching entries in the same format as the ``find'' method.

This method tries to recover and continue under error conditions.

The options accepted:

ignore_case => 1

by default the matching over the file system is carried out in a case sensitive fashion, this flag changes it to be case insensitive.

strict_leading_dot => 0

by default, a dot character at the beginning of a file or directory name is not matched by willcards ("*" or "?"). Setting this flags to a false value changes this behaviour.

follow_links => 1

ordered => 1

names_only => 1

realpath => 1

on_error => sub { ... }

wanted => ...

no_wanted => ...

these options perform as on the "ls" method.

$sftp->rget($remote, $local, %opts)

Recursively copies the contents of remote directory $remote to local directory $local. Returns the total number of elements (files, dirs and symbolic links) successfully copied.

This method tries to recover and continue when some error happens.

The options accepted are:

umask => $umask

use umask $umask to set permissions on the files and directories created.

copy_perm => $bool;

if set to a true value, file and directory permissions are copied to the remote server (after applying the umask). On by default.

copy_time => $bool;

if set to a true value, file atime and mtime are copied from the remote server. By default it is on.

overwrite => $bool

if set to a true value, when a local file with the same name already exists it is overwritten. On by default.

numbered => $bool

when required adds a sequence number to local file names in order to avoid overwriting already existent files. Off by default.

newer_only => $bool

if set to a true value, when a local file with the same name already exists it is overwritten only if the remote file is newer.

ignore_links => $bool

if set to a true value, symbolic links are not copied.

on_error => sub { ... }

the passed sub is called when some error happens. It is called with two arguments, the $sftp object and the entry causing the error.

wanted => ...

no_wanted => ...

This option allows to select which files and directories have to be copied. See also "ls" method docs.

If a directory is discarded all of its contents are also discarded (as it is not possible to copy child files without creating the directory first!).

block_size => $block_size

queue_size => $queue_size

conversion => $conversion

resume => $resume

See "get" method docs.

$sftp->rput($local, $remote, %opts)

Recursively copies the contents of local directory $local to remote directory $remote.

This method tries to recover and continue when some error happens.

Accepted options are:

umask => $umask

use umask $umask to set permissions on the files and directories created.

copy_perm => $bool;

if set to a true value, file and directory permissions are copied to the remote server (after applying the umask). On by default.

copy_time => $bool;

if set to a true value, file atime and mtime are copied to the remote server. On by default.

overwrite => $bool

if set to a true value, when a remote file with the same name already exists it is overwritten. On by default.

newer_only => $bool

if set to a true value, when a remote file with the same name already exists it is overwritten only if the local file is newer.

ignore_links => $bool

if set to a true value, symbolic links are not copied

on_error => sub { ... }

the passed sub is called when some error happens. It is called with two arguments, the $sftp object and the entry causing the error.

wanted => ...

no_wanted => ...

This option allows to select which files and directories have to be copied. See also "ls" method docs.

If a directory is discarded all of its contents are also discarded (as it is not possible to copy child files without creating the directory first!).

block_size => $block_size

queue_size => $queue_size

conversion => $conversion

resume => $resume

late_set_perm => $bool

see "put" method docs.

$sftp->rremove($dir, %opts)

$sftp->rremove(\@dirs, %opts)

recursively remove directory $dir (or directories @dirs) and its contents. Returns the number of elements successfully removed.

This method tries to recover and continue when some error happens.

The options accepted are:

on_error => sub { ... }

This callback is called when some error is occurs. The arguments passed are the $sftp object and the current entry (see "ls" docs for more information).

wanted => ...

no_wanted => ...

Allow to select which file system objects have to be deleted.

$sftp->mget($remote, $localdir, %opts)

$sftp->mget(\@remote, $localdir, %opts)

expands the wildcards on $remote or @remote and retrieves all the matching files.

For instance:

   $sftp->mget(['/etc/hostname.*', '/etc/init.d/*'], '/tmp');
 
 

The method accepts all the options valid for ``glob'' and for ``get'' (except those that do not make sense :-)

$localdir is optional and defaults to the process cwd.

Files are saved with the same name they have in the remote server excluding the directory parts.

Note that name collisions are not detected. For instance:

  $sftp->mget(["foo/file.txt", "bar/file.txt"], "/tmp")
 
 

will transfer the first file to ``/tmp/file.txt'' and later overwrite it with the second one. The "numbered" option can be used to avoid this issue.

$sftp->mput($local, $remotedir, %opts)

$sftp->mput(\@local, $remotedir, %opts)

similar to ``mget'' but works in the opposite direction transferring files from the local side to the remote one.

$sftp->join(@paths)

returns the given path fragments joined in one path (currently the remote file system is expected to be Unix like).

$sftp->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 returned value is a tied handle (see Tie::Handle) that can be used to access the remote file both with the methods available from this module and with perl built-ins. For instance:

   # reading from the remote file
   my $fh1 = $sftp->open("/etc/passwd")
     or die $sftp->error;
   while (<$fh1>) { ... }
 
   # writting to the remote file
   use Net::SFTP::Foreign::Constants qw(:flags);
   my $fh2 = $sftp->open("/foo/bar", SSH2_FXF_WRITE|SSH2_FXF_CREAT)
     or die $sftp->error;
   print $fh2 "printing on the remote file\n";
   $sftp->write($fh2, "writting more");
 
 

The $flags bitmap determines how to open the remote file as defined in the SFTP protocol draft (the following constants can be imported from Net::SFTP::Foreign::Constants):

SSH2_FXF_READ

Open the file for reading. It is the default mode.

SSH2_FXF_WRITE

Open the file for writing. If both this and "SSH2_FXF_READ" are specified, the file is opened for both reading and writing.

SSH2_FXF_APPEND

Force all writes to append data at the end of the file.

As OpenSSH SFTP server implementation ignores this flag, the module emulates it (I will appreciate receiving feedback about the interoperation of this module with other server implementations when this flag is used).

SSH2_FXF_CREAT

If this flag is specified, then a new file will be created if one does not already exist.

SSH2_FXF_TRUNC

Forces an existing file with the same name to be truncated to zero length when creating a file. "SSH2_FXF_CREAT" must also be specified if this flag is used.

SSH2_FXF_EXCL

Causes the request to fail if the named file already exists. "SSH2_FXF_CREAT" must also be specified if this flag is used.

When creating a new remote file, $attrs allows to set its initial attributes. $attrs has to be an object of class Net::SFTP::Foreign::Attributes.

$sftp->close($handle)

Closes the remote file handle $handle.

Files are automatically closed on the handle "DESTROY" method when not done explicitelly.

Returns true on success and undef on failure.

$sftp->read($handle, $length)

reads $length bytes from an open file handle $handle. On success returns the data read from the remote file and undef on failure (including EOF).

$sftp->write($handle, $data)

writes $data to the remote file $handle. Returns the number of bytes written or undef on failure.

$sftp->readline($handle)

$sftp->readline($handle, $sep)

in scalar context reads and returns the next line from the remote file. In list context, it returns all the lines from the current position to the end of the file.

By default ``\n'' is used as the separator between lines, but a different one can be used passing it as the second method argument. If the empty string is used, it returns all the data from the current position to the end of the file as one line.

$sftp->getc($handle)

returns the next character from the file.

$sftp->seek($handle, $pos, $whence)

sets the current position for the remote file handle $handle. If $whence is 0, the position is set relative to the beginning of the file; if $whence is 1, position is relative to current position and if $<$whence> is 2, position is relative to the end of the file.

returns a trues value on success, undef on failure.

$sftp->tell($fh)

returns the current position for the remote file handle $handle.

$sftp->eof($fh)

reports whether the remote file handler points at the end of the file.

$sftp->flush($fh)

writes to the remote file any pending data and discards the read cache.

$sftp->sftpread($handle, $offset, $length)

low level method that sends a SSH2_FXP_READ request to read from an open file handle $handle, $length bytes starting at $offset.

Returns the data read on success and undef on failure.

Some servers (for instance OpenSSH SFTP server) limit the size of the read requests and so the length of data returned can be smaller than requested.

$sftp->sftpwrite($handle, $offset, $data)

low level method that sends a "SSH_FXP_WRITE" request to write to an open file handle $handle, starting at $offset, and where the data to be written is in $data.

Returns true on success and undef on failure.

$sftp->opendir($path)

Sends a "SSH_FXP_OPENDIR" command to open the remote directory $path, and returns an open handle on success (unfortunately, current versions of perl does not support directory operations via tied handles, so it is not possible to use the returned handle as a native one).

On failure returns "undef".

$sftp->closedir($handle)

closes the remote directory handle $handle.

Directory handles are closed from their "DESTROY" method when not done explicitly.

Return true on success, undef on failure.

$sftp->readdir($handle)

returns the next entry from the remote directory $handle (or all the remaining entries when called in list context).

The return values are a hash with three keys: "filename", "longname" and "a". The "a" value contains a Net::SFTP::Foreign::Attributes object describing the entry.

Returns undef on error or when no more entries exist on the directory.

$sftp->stat($path)

performs a "stat" on the remote file $path and returns a Net::SFTP::Foreign::Attributes object with the result values.

Returns undef on failure.

$sftp->fstat($handle)

is similar to the previous method but its argument has to be a handle to an already open remote file instead of a file name.

$sftp->lstat($path)

is similar to "stat" method but stats a symbolic link instead of the file the symbolic links points to.

$sftp->setstat($path, $attrs)

sets file attributes on remote file $path.

Returns true on success and undef on failure.

$sftp->fsetstat($handle, $attrs)

is similar to setstat but its first argument has to be an open remote file handle instead of a file name.

$sftp->remove($path)

Sends a "SSH_FXP_REMOVE" command to remove the remote file $path. Returns a true value on success and undef on failure.

$sftp->mkdir($path)

$sftp->mkdir($path, $attrs)

Sends a "SSH_FXP_MKDIR" command to create a remote directory $path whose attributes are initialized to $attrs (a Net::SFTP::Foreign::Attributes object) if given.

Returns a true value on success and undef on failure.

$sftp->mkpath($path)

$sftp->mkpath($path, $attrs)

This method is similar to "mkdir" but also creates any non-existant parent directories recursively.

$sftp->rmdir($path)

Sends a "SSH_FXP_RMDIR" command to remove a remote directory $path. Returns a true value on success and undef on failure.

$sftp->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->rename($old, $new, %opts)

Sends a "SSH_FXP_RENAME" command to rename $old to $new. Returns a true value on success and undef on failure.

Accepted options are:

overwrite => $bool

By default, the rename operation fails when a file $new already exists. When this options is set, any previous existant file is deleted first (the "atomic_rename" operation will be used if available).

Note than under some conditions the target file could be deleted and afterwards the rename operation fail.

$sftp->atomic_rename($old, $new)

Renames a file using the "posix-rename@openssh.com" extension when available.

Unlike the "rename" method, it overwrites any previous $new file.

$sftp->readlink($path)

Sends a "SSH_FXP_READLINK" command to read the path where the simbolic link is pointing.

Returns the target path on success and undef on failure.

$sftp->symlink($sl, $target)

Sends a "SSH_FXP_SYMLINK" command to create a new symbolic link $sl pointing to $target.

$target is stored as-is, without any path expansion taken place on it. User "realpath" to normalize it:

   $sftp->symlink("foo.lnk" => $sftp->realpath("../bar"))
 
 

$sftp->statvfs($path)

$sftp->fstatvfs($fh)

On servers supporting "statvfs@openssh.com" and "fstatvfs@openssh.com" extensions respectively, these methods return a hash reference with information about the file system where the file named $path or the open file $fh resides.

The hash entries are:

   bsize   => file system block size
   frsize  => fundamental fs block size
   blocks  => number of blocks (unit f_frsize)
   bfree   => free blocks in file system
   bavail  => free blocks for non-root
   files   => total file inodes
   ffree   => free file inodes
   favail  => free file inodes for to non-root
   fsid    => file system id
   flag    => bit mask of f_flag values
   namemax => maximum filename length
 
 

The values of the f_flag bit mask are as follows:

   SSH2_FXE_STATVFS_ST_RDONLY => read-only
   SSH2_FXE_STATVFS_ST_NOSUID => no setuid
 
 

$sftp->disconnect

Closes the SSH connection to the remote host. From this point the object becomes mostly useless.

Usually, this method should not be called explicitly, but implicitly from the DESTROY method when the object goes out of scope.

See also the documentation for the "autodiscconnect" constructor argument.

$sftp->autodisconnect($ad)

Sets the "autodisconnect" behaviour.

See also the documentation for the "autodiscconnect" constructor argument. The values accepted here are the same as there.

On the fly data conversion

Some of the methods on this module allow to perform on the fly data conversion via the "conversion" option that accepts the following values:

conversion => 'dos2unix'

Converts LF+CR line endings (as commonly used under MS-DOS) to LF (Unix).

conversion => 'unix2dos'

Converts LF line endings (Unix) to LF+CR (DOS).

conversion => sub { CONVERT $_[0] }

When a callback is given, it is called repeatly as chunks of data become available. It has to change $_[0] in place in order to perform the conversion.

Also, the subroutine is called one last time with and empty data string to indicate that the transfer has finished, so that intermediate buffers can be flushed.

Note that when writing conversion subroutines, special care has to be taken to handle sequences crossing chunk borders.

The data conversion is always performed before any other callback subroutine is called.

See the Wikipedia entry on line endings <http://en.wikipedia.org/wiki/Newline> or the article Understanding Newlines by Xavier Noria (<http://www.onlamp.com/pub/a/onlamp/2006/08/17/understanding-newlines.html>) for details about the different conventions.

FAQ

Closing the connection:

Q: How do I close the connection to the remote server?

A: let the $sftp object go out of scope or just undefine it:

   undef $sftp;
 
 

Using Net::SFTP::Foreign from a cron script:

Q: I wrote a script for performing sftp file transfers that works beautifully from the command line. However when I try to run the same script from cron it fails with a broken pipe error:

   open2: exec of ssh -l user some.location.com -s sftp
     failed at Net/SFTP/Foreign.pm line 67
 
 

A: "ssh" is not on your cron PATH.

The remedy is either to add the location of the "ssh" application to your cron PATH or to use the "ssh_cmd" option of the "new" method to hardcode the location of "ssh" inside your script, for instance:

   my $ssh = Net::SFTP::Foreign->new($host,
                                     ssh_cmd => '/usr/local/ssh/bin/ssh');
 
 

"more" constructor option expects an array reference:

Q: I'm trying to pass in the private key file using the -i option, but it keep saying it couldn't find the key. What I'm doing wrong?

A: The "more" argument on the constructor expects a single option or a reference to an array of options. It will not split an string containing several options.

Arguments to SSH options have to be also passed as different entries on the array:

   my $sftp = Net::SFTP::Foreign->new($host,
                                       more => [qw(-i /home/foo/.ssh/id_dsa)]);
 
 

Plink and password authentication

Q: Why password authentication is not supported for the plink SSH client?

A: A bug in plink breaks it.

As a work around, you can use plink "-pw" argument to pass the password on the command line, but it is highly insecure, anyone with a shell account on the machine would be able to get the password. Use at your own risk!:

   # HIGHLY INSECURE!!!
   my $sftp = Net::SFTP::Foreign->new('foo@bar',
                                      ssh_cmd => 'plink',
                                      more => [-pw => $password]);
   $sftp->error and die $sftp->error;
 
 

Plink

Q: What is "plink"?

A: Plink is a command line tool distributed with the <PuTTY> SSH client. Very popular between MS Windows users, it is also available for Linux and other Unixes now.

Put method fails

Q: put fails with the following error:

   Couldn't setstat remote file (fsetstat): The requested operation
     cannot be performed because there is a file transfer in progress.
 
 

A: Try passing the "late_set_perm" option to the put method:

   $sftp->put($local, $remote, late_set_perm => 1)
      or die "unable to transfer file: " . $sftp->error;
 
 

Some servers do not support the "fsetstat" method on open file handles. Setting this flag allows to delay that operation until the file has been completely transferred and the remote file handle closed.

Send me a bug report containing a dump of your $sftp object so I can add code for your particular server software to activate the work-around automatically.

Disable password authentication completely

Q: When we try to open a session and the key either doesn't exist or is invalid, the child SSH hangs waiting for a password to be entered. Is there a way to make this fail back to the Perl program to be handled?

A: Disable anything but public key SSH authentication calling the new method as follows:

   $sftp = Net::SFTP::Foreign->new($host,
                 more => [qw(-o PreferredAuthentications=publickey)])
 
 

See ssh_config(5) for the details.

Understanding "$attr->perm" bits

Q: How can I know if a directory entry is a (directory|link|file|...)?

A: Use the "S_IS*" functions from Fcntl. For instance:

   use Fcntl qw(S_ISDIR);
   my $ls = $sftp->ls or die $sftp->error;
   for my $entry (@$ls) {
     if (S_ISDIR($entry->{a}->perm)) {
       print "$entry->{filename} is a directory\n";
     }
   }
 
 

BUGS

These are the currently known bugs:

- Doesn't work on VMS:

The problem is related to IPC::Open2 not working on VMS. Patches are welcome!

- Dirty cleanup:

On some operative systems, closing the pipes used to comunicate with the slave SSH process does not terminate it and a work around has to be applied. If you find that your scripts hung when the $sftp object gets out of scope, try setting $Net::SFTP::Foreign::dirty_cleanup to a true value and also send me a report including the value of $^O on your machine and the OpenSSH version.

From version 0.90_18 upwards, a dirty cleanup is performed anyway when the SSH process does not terminate by itself in 8 seconds or less.

- Reversed symlink arguments:

This package uses the non-conforming OpenSSH argument order for the SSH_FXP_SYMLINK command that seems to be the de facto standard. When interacting with SFTP servers that follow the SFTP specification, the "symlink" method will interpret its arguments in reverse order.

Also, the following features should be considered experimental:

- multi-backend support

- passing file handles to put and get methods

- mput and mget methods

- numbered option

SUPPORT

To report bugs, send me and email or use the CPAN bug tracking system at <http://rt.cpan.org>.

Commercial support

Commercial support, professional services and custom software development around this module are available through my current company. Drop me an email with a rough description of your requirements and we will get back to you ASAP.

My wishlist

If you like this module and you're feeling generous, take a look at my Amazon Wish List: <http://amzn.com/w/1WU1P6IR5QZ42>

SEE ALSO

Information about the constants used on this module is available from Net::SFTP::Foreign::Constants. Information about attribute objects is available from Net::SFTP::Foreign::Attributes.

General information about SSH and the OpenSSH implementation is available from the OpenSSH web site at <http://www.openssh.org/> and from the sftp(1) and sftp-server(8) manual pages.

Net::SFTP::Foreign integrates nicely with my other module Net::OpenSSH.

Modules offering similar functionality available from CPAN are Net::SFTP and Net::SSH2.

Net::SFTP::Foreign::Backend::Net_SSH2 allows to run Net::SFTP::Foreign on top of Net::SSH2.

COPYRIGHT

Copyright (c) 2005-2010 Salvador Fandin~o (sfandino@yahoo.com).

Copyright (c) 2001 Benjamin Trott, Copyright (c) 2003 David Rolsky.

_glob_to_regex method based on code (c) 2002 Richard Clamp.

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.