Provided by: libnet-sftp-foreign-perl_1.93+dfsg-1_all bug

NAME

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

SYNOPSIS

           use Net::SFTP::Foreign;
           my $sftp = Net::SFTP::Foreign->new($host);
           $sftp->die_on_error("Unable to establish SFTP connection");

           $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 process 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.

   Error handling
       The method "$sftp->error" can be used to check for errors after every method call. For
       instance:

         $sftp = Net::SFTP::Foreign->new($host);
         $sftp->error and die "unable to connect to remote host: " . $sftp->error;

       Also, the "die_on_error" method provides a handy shortcut for the last line:

         $sftp = Net::SFTP::Foreign->new($host);
         $sftp->die_on_error("unable to connect to remote host");

       The "status" method can also be used to get the value for the last SFTP status response,
       but that is only useful when calling low level methods mapping to single SFTP primitives.
       In any case, it should be considered an implementation detail of the module usable only
       for troubleshooting and error reporting.

   autodie mode
       When the "autodie" mode is set at construction time, non-recoverable errors are
       automatically promoted to exceptions. For instance:

         $sftp = Net::SFTP::Foreign->new($host, autodie => 1);
         my $ls = $sftp->ls("/bar");
         # dies as: "Couldn't open remote dir '/bar': No such file"

       Error handling in non-recursive methods

       Most of the non-recursive methods available from this package return undef on failure and
       a true value or the requested data on success.

       For instance:

         $sftp->get($from, $to) or die "get failed!";

       Error handling in recursive methods

       Recursive methods (i.e. "find", "rget", "rput", "rremove") do not stop on errors but just
       skip the affected files and directories and keep going.

       After a call to a recursive method, the error indicator is only set when an unrecoverable
       error is found (i.e. a connection lost). For instance, this code doesn't work as expected:

         $sftp->rremove($dir);
         $sftp->error and die "rremove failed"; # this is wrong!!!

       This does:

         my $errors;
         $sftp->rremove($dir, on_error => sub { $errors++});
         $errors and die "rremove failed";

       The "autodie" mode is disabled when an "on_error" handler is passed to methods accepting
       it:

         my $sftp = Net::SFTP::Foreign->new($host, autodie => 1);
         # prints "foo!" and does not die:
         $sftp->find("/sdfjkalshfl", # nonexistent directory
                     on_error => sub { print "foo!\n" });
         # dies:
         $sftp->find("/sdfjkalshfl");

   API
       The methods available from this module are described below.

       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->die_on_error("SSH connection failed");

           The optional arguments accepted are as follows:

           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:

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

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

                   You can always call the "disconnect" method explicitly to end the connection
                   at the right time from the right place.

               '1' Disconnect on exit from any thread or process.

               '2' Disconnect on exit from the current process/thread only. This is the default.

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

       $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->die_on_error($msg)
           Convenience method:

             $sftp->die_on_error("Something bad happened");
             # is a shortcut for...
             $sftp->error and die "Something bad happened: " . $sftp->error;

       $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, %opts)
           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.

           Passing "undef" as the $dir argument resets the cwd to the server default which is
           usually the user home but not always.

           The method accepts the following options:

           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.

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

       $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 saving 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. 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 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.

       $sftp->put_content($bytes, $remote, %opts)
           Creates (or overwrites) a remote file whose content is the passed data.

       $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 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('.')};

       $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 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);

       $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 given pattern can be a UNIX style pattern (see glob(7)) or a Regexp object (i.e
           "qr/foo/"). In the later case, only files on the current working directory will be
           matched against the Regexp.

           Accepted options:

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

       $sftp->rget($remote, $local, %opts)
           Recursively copies the contents of remote directory $remote to local directory $local.
           Returns the total number of elements (files, directories 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 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.

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

           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.

       $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 (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.

       $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 current working directory ("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>) { ... }

             # writing 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, "writing 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 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.

       $sftp->close($handle)
           Closes the remote file handle $handle.

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

           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.

           Note that unless the file has been open in "autoflush" mode, data will be cached until
           the buffer fills, the file is closed or "flush" is explicitly called. That could also
           mask write errors that would become unnoticed until later when the write operation is
           actually performed.

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

           Note that this operation just sends data cached locally to the remote server. You may
           like to call "fsync" (when supported) afterwards to ensure that data is actually
           flushed to disc.

       $sftp->fsync($fh)
           On servers supporting the "fsync@openssh.com" extension, this method calls fysnc(2) on
           the remote side, which usually flushes buffered changes to disk.

       $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_or_fh)
           performs a "stat" on the remote file and returns a Net::SFTP::Foreign::Attributes
           object with the result values. Both paths and open remote file handles can be passed
           to this method.

           Returns undef on failure.

       $sftp->fstat($handle)
           this method is deprecated.

       $sftp->lstat($path)
           this method is similar to "stat" method but stats a symbolic link instead of the file
           the symbolic links points to.

       $sftp->setstat($path_or_fh, $attrs)
           sets file attributes on the remote file. Accepts both paths and open remote file
           handles.

           Returns true on success and undef on failure.

       $sftp->fsetstat($handle, $attrs)
           this method is deprecated.

       $sftp->truncate($path_or_fh, $size)
       $sftp->chown($path_or_fh, $uid, $gid)
       $sftp->chmod($path_or_fh, $perm)
       $sftp->utime($path_or_fh, $atime, $mtime)
           Shortcuts around "setstat" method.

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

           Returns a true value on success and undef on failure.

           The $attrs argument is optional.

       $sftp->mkpath($path, $attrs, $parent)
           This method is similar to "mkdir" but also creates any non-existent parent directories
           recursively.

           When the optional argument $parent has a true value, just the parent directory of the
           given path (and its ancestors as required) is created.

           For instance:

             $sftp->mkpath("/tmp/work", undef, 1);
             my $fh = $sftp->open("/tmp/work/data.txt",
                                  SSH2_FXF_WRITE|SSH2_FXF_CREAT);

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

           When the given path points to an nonexistent location, what one gets back is server
           dependent. Some servers return a failure message and others a canonical version of the
           path.

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

       $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 symbolic 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. Use "realpath"
           to normalize it:

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

       $sftp->hardlink($hl, $target)
           Creates a hardlink on the server.

           This command requires support for the 'hardlink@openssh.com' extension on the server
           (available in OpenSSH from version 5.7).

       $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->test_d($path)
           Checks whether the given path corresponds to a directory.

       $sftp->test_e($path)
           Checks whether a file system object (file, directory, etc.) exists at the given path.

       $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 one to perform on the fly data conversion via the
       "conversion" option that accepts the following values:

       conversion => 'dos2unix'
           Converts CR+LF line endings (as commonly used under MS-DOS) to LF (UNIX).

       conversion => 'unix2dos'
           Converts LF line endings (UNIX) to CR+LF (DOS).

       conversion => sub { CONVERT $_[0] }
           When a callback is given, it is invoked repeatedly 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)]);

           Note also that latest versions of Net::SFTP::Foreign support the "key_path" argument:

             my $sftp = Net::SFTP::Foreign->new($host,
                                                 key_path => '/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.

           Newer versions of Net::SFTP::Foreign pass the password to "plink" using its "-pw"
           option. As this feature is not completely secure a warning is generated.

           It can be silenced (though, don't do it without understanding why it is there,
           please!) as follows:

             no warnings 'Net::SFTP::Foreign';
             my $sftp = Net::SFTP::Foreign->new('foo@bar',
                                                ssh_cmd => 'plink',
                                                password => $password);
             $sftp->die_on_error;

       Plink
           Q: What is "plink"?

           A: Plink is a command line tool distributed with the PuTTY
           <http://the.earth.li/~sgtatham/putty/> SSH client. Very popular between MS Windows
           users, it is also available for Linux and other UNIX now.

       Put method fails
           Q: put fails with the following error:

             Couldn't setstat remote file: 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" operation on open file handles. Setting
           this flag allows one to delay that operation until the file has been completely
           transferred and the remote file handle closed.

           Also, 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.

       Put method fails even with late_set_perm set
           Q: I added "late_set_perm => 1" to the put call, but we are still receiving the error
           "Couldn't setstat remote file (setstat)".

           A: Some servers forbid the SFTP "setstat" operation used by the "put" method for
           replicating the file permissions and time-stamps on the remote side.

           As a work around you can just disable the feature:

             $sftp->put($local_file, $remote_file,
                        copy_perm => 0, copy_time => 0);

       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";
               }
             }

       Host key checking
           Q: Connecting to a remote server with password authentication fails with the following
           error:

             The authenticity of the target host can not be established,
             connect from the command line first

           A: That probably means that the public key from the remote server is not stored in the
           "~/.ssh/known_hosts" file. Run an SSH Connection from the command line as the same
           user as the script and answer "yes" when asked to confirm the key supplied.

           Example:

             $ ssh pluto /bin/true
             The authenticity of host 'pluto (172.25.1.4)' can't be established.
             RSA key fingerprint is 41:b1:a7:86:d2:a9:7b:b0:7f:a1:00:b7:26:51:76:52.
             Are you sure you want to continue connecting (yes/no)? yes

           Your SSH client may also support some flag to disable this check, but doing it can
           ruin the security of the SSH protocol so I advise against its usage.

           Example:

             # Warning: don't do that unless you fully understand
             # its security implications!!!
             $sftp = Net::SFTP::Foreign->new($host,
                                             more => [-o => 'StrictHostKeyChecking no'],
                                             ...);

BUGS

       These are the currently known bugs:

       - Doesn't work on VMS:
           The problem is related to IPC::Open3 not working on VMS. Patches are welcome!

       - Dirty cleanup:
           On some operating systems, closing the pipes used to communicate 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.

       - IPC::Open3 bugs on Windows
           On Windows the IPC::Open3 module is used to spawn the slave SSH process. That module
           has several nasty bugs (related to STDIN, STDOUT and STDERR being closed or not being
           assigned to file descriptors 0, 1 and 2 respectively) that will cause the connection
           to fail.

           Specifically this is known to happen under mod_perl/mod_perl2.

       - Password authentication on HP-UX
           For some unknown reason, it seems that when using the module on HP-UX, number signs
           ("#") in password need to be escaped ("\#"). For instance:

             my $password = "foo#2014";
             $password =~ s/#/\\#/g if $running_in_hp_ux;
             my $ssh = Net::OpenSSH->new($host, user => $user,
                                         password => $password);

           I don't have access to an HP-UX machine, and so far nobody using it has been able to
           explain this behaviour. Patches welcome!

       - Taint mode and data coming through SFTP
           When the module finds it is being used from a script started in taint mode, on every
           method call it checks all the arguments passed and dies if any of them is tainted.
           Also, any data coming through the SFTP connection is marked as tainted.

           That generates an internal conflict for those methods that under the hood query the
           remote server multiple times, using data from responses to previous queries (tainted)
           to build new ones (die!).

           I don't think a generic solution could be applied to this issue while honoring the
           taint-mode spirit (and erring on the safe side), so my plan is to fix that in a case
           by case manner.

           So, please report any issue you find with taint mode!

       Also, the following features should be considered experimental:

       - support for Tectia server

       - numbered feature

       - autodie mode

       - best_effort feature

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>

       Also consider contributing to the OpenSSH project this module builds upon:
       <http://www.openssh.org/donations.html>.

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.

       Net::SFTP::Foreign::Backend::Net_SSH2 allows one to run Net::SFTP::Foreign on top of
       Net::SSH2 (nowadays, this combination is probably the best option under Windows).

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

       Test::SFTP allows one to run tests against a remote SFTP server.

       autodie.

COPYRIGHT

       Copyright (c) 2005-2021 Salvador FandiƱ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.