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

ssh1 => 1

use old SSH1 approach for starting the remote SFTP server.

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 => "-c $cipher"    # wrong!!!
  more => [-c => $cipher] # right
    

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.

Note that the given value is used internally to time out low level operations. The high level operations available through the API may take longer to expire (sometimes up to 4 times longer).

The "Windows" backend used by default when the operating system is MS Windows (though, not under Cygwin perl), does not support timeouts. To overcome this limitation you can switch to the "Net_SSH2" backend or use Net::SSH::Any that provides its own backend supporting timeouts.

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

key_path => $filename

key_path => \@filenames

asks "ssh" to use the key(s) in the given file(s) for authentication.

password => $password

Logs into the remote host using password authentication with the given password.

Password authentication is only available if the module IO::Pty is installed. Note also, that on Windows this module is only available when running the Cygwin port of Perl.

asks_for_username_at_login => 0|'auto'|1

During the interactive authentication dialog, most SSH servers only ask for the user password as the login name is passed inside the SSH protocol. But under some uncommon servers or configurations it is possible that a username is also requested.

When this flag is set to 1, the username will be send unconditionally at the first remote prompt and then the password at the second.

When it is set to "auto" the module will use some heuristics in order to determine if it is being asked for an username.

When set to 0, the username will never be sent during the authentication dialog. This is the default.

password_prompt => $regex_or_str

The module expects the password prompt from the remote server to end in a colon or a question mark. This seems to cover correctly 99% of real life cases.

Otherwise this option can be used to handle the exceptional cases. For instance:

  $sftp = Net::SFTP::Foreign->new($host, password => $password,
                                  password_prompt => qr/\bpassword>\s*$/);
    

Note that your script will hang at the login phase if the wrong prompt is used.

passphrase => $passphrase

Logs into the remote server using a passphrase protected private key.

Requires also the module IO::Pty.

expect_log_user => $bool

This feature is obsolete as Expect is not used anymore to handle password authentication.

ssh_cmd => $sshcmd

ssh_cmd => \@sshcmd

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

For instance:

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

When an array reference is used, its elements are inserted at the beginning of the system call. That allows one, for instance, to connect to the target host through some SSH proxy:

  $sftp = Net::SFTP::Foreign->new($host,
              ssh_cmd => [qw(ssh -l user proxy.server ssh)]);
    

But note that the module will not handle password authentication for those proxies.

ssh_cmd_interface => 'plink' or 'ssh' or 'tectia'

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

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

transport => $fh

transport => [$in_fh, $out_fh]

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

allows one 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 one to completely redefine how "ssh" is called. Its arguments are passed to IPC::Open2::open2 to open a pipe to the remote server.

stderr_fh => $fh

redirects the output sent to stderr by the SSH subprocess to the given file handle.

It can be used to suppress banners:

  open my $ssherr, '>', '/dev/null' or die "unable to open /dev/null";
  my $sftp = Net::SFTP::Foreign->new($host,
                                     stderr_fh => $ssherr);
    

Or to send SSH stderr to a file in order to capture errors for later analysis:

  my $ssherr = File::Temp->new or die "File::Temp->new failed";
  my $sftp = Net::SFTP::Foreign->new($hostname, more => ['-v'],
                                     stderr_fh => $ssherr);
  if ($sftp->error) {
    print "sftp error: ".$sftp->error."\n";
    seek($ssherr, 0, 0);
    while (<$ssherr>) {
      print "captured stderr: $_";
    }
  }
    

stderr_discard => 1

redirects stderr to /dev/null

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

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

write_delay => $bytes

This option determines how many bytes are buffered before the real SFTP write operation is performed.

read_ahead => $bytes

On read operations this option determines how many bytes to read in advance so that later read operations can be fulfilled from the buffer.

Using a high value will increase the performance of the module for a sequential reads access pattern but degrade it for a short random reads access pattern. It can also cause synchronization problems if the file is concurrently modified by other parties ("flush" can be used to discard all the data inside the read buffer on demand).

The default value is set dynamically considering some runtime parameters and given options, though it tends to favor the sequential read access pattern.

autodisconnect => $ad

by default, the SSH connection is closed from the DESTROY method when the object goes out of scope on the process and thread where it was created. This option allows one to customize this behaviour.

The acceptable values for $ad are:

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

autodie => $bool

Enables the autodie mode that will cause the module to die when any error is found (a la autodie).

check => 0

By default the given target directory is checked against the remote server to ensure that it actually exists and that it is a directory. Some servers may fail to honor those requests even for valid directories (i.e. when the directory has the hidden flag set).

This option allows one to disable those checks and just sets the cwd to the given value blindly.

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 permission attributes have to be copied from remote file. Default is to copy them after applying the local process umask.

umask => $umask

allows one to select the umask to apply when setting the permissions of the copied file. Default is to use the umask for the current process or 0 if the "perm" option is also used.

perm => $perm

sets the permission mask of the file to be $perm, 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.

If a scalar reference is passed as the numbered value, the final target will be stored in the value pointed by the reference. For instance:

  my $target;
  $sftp->get("data.txt", "data.txt", numbered => \$target);
  say "file was saved as $target" unless $sftp->error
    

atomic => 1

The remote file contents are transferred into a temporal file that once the copy completes is renamed to the target destination.

If not-overwrite of remote files is also requested, an empty file may appear at the target destination before the rename operation is performed. This is due to limitations of some operating/file systems.

mkpath => 0

By default the method creates any non-existent parent directory for the given target path. That feature can be disabled setting this flag to 0.

cleanup => 1

If the transfer fails, remove the incomplete file.

This option is set to by default when there is not possible to resume the transfer afterwards (i.e., when using `atomic` or `numbered` options).

best_effort => 1

Ignore minor errors as setting time or permissions.

conversion => $conversion

on the fly data conversion of the file contents can be performed with this option. See "On the fly data conversion" below.

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 split on for transfer. Incrementing this value can improve performance but most servers limit the maximum size.

queue_size => $size

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

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 permission attributes have to be copied from remote file. Default is to copy them after applying the local process umask.

umask => $umask

allows one 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 permission mask of the file to be $perm, umask and local permissions are ignored.

overwrite => 0

by default "put" will overwrite any pre-existent file with the same name at the remote side. Setting this flag to zero will make the method fail in that case.

numbered => 1

when set, a sequence number is added to the remote file name in order to avoid overwriting pre-existent files. Off by default.

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. Off by default.

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.

sparse => 1

Blocks that are all zeros are skipped possibly creating an sparse file on the remote host.

mkpath => 0

By default the method creates any non-existent parent directory for the given target path. That feature can be disabled setting this flag to 0.

atomic => 1

The local file contents are transferred into a temporal file that once the copy completes is renamed to the target destination.

This operation relies on the SSH server to perform an overwriting/non-overwriting atomic rename operation free of race conditions.

OpenSSH server does it correctly on top of Linux/UNIX native file systems (i.e. ext[234]>, ffs or zfs) but has problems on file systems not supporting hard links (i.e. FAT) or on operating systems with broken POSIX semantics as Windows.

cleanup => 1

If the transfer fails, attempts to remove the incomplete file. Cleanup may fail (for example, if the SSH connection gets broken).

This option is set by default when the transfer is not resumable (i.e., when using `atomic` or `numbered` options).

best_effort => 1

Ignore minor errors, as setting time and permissions on the remote file.

conversion => $conversion

on the fly data conversion of the file contents can be performed with this option. See "On the fly data conversion" below.

callback => $callback

$callback is a reference to a subroutine 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 split 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 one to set the maximum number of requests that can be concurrently waiting for a server response.

late_set_perm => $bool

See the FAQ below.

wanted => qr/.../

Only elements whose name matches the given 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 opposite 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 still appear for links pointing to non existent 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('.')};
    

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 fails on them.

Following symbolic 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 active.

ordered => 1

By default, the file system is searched in an implementation dependent order (actually optimized for low memory consumption). 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 one 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);
    

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.

This flag is ignored when a Regexp object is used as the pattern.

strict_leading_dot => 0

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

This flag is ignored when a Regexp object is used as the pattern.

follow_links => 1

ordered => 1

names_only => 1

realpath => 1

on_error => sub { ... }

wanted => ...

no_wanted => ...

these options perform as on the "ls" method.

Some usage samples:

  my $files = $sftp->glob("*/lib");

  my $files = $sftp->glob("/var/log/dmesg.*.gz");

  $sftp->set_cwd("/var/log");
  my $files = $sftp->glob(qr/^dmesg\.[\d+]\.gz$/);

  my $files = $sftp->glob("*/*.pdf", strict_leading_dot => 0);

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 pre-existent remote 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 one 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!).

atomic => 1

block_size => $block_size

queue_size => $queue_size

conversion => $conversion

resume => $resume

best_effort => $best_effort

See "get" method docs.

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.

perm => $perm

Sets the permission of the copied files to $perm. For directories the value "$perm|0300" is used.

Note that when this option is used, umask and local permissions are ignored.

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 one 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!).

atomic => 1

block_size => $block_size

queue_size => $queue_size

conversion => $conversion

resume => $resume

best_effort => $best_effort

late_set_perm => $bool

see "put" method docs.

on_error => sub { ... }

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

wanted => ...

no_wanted => ...

Allows one to select which file system objects have to be deleted.

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 inter-operation 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 one to set its initial attributes. $attrs has to be an object of class Net::SFTP::Foreign::Attributes.

overwrite => $bool

By default, the rename operation fails when a file $new already exists. When this options is set, any previous existent 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.