NAME

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

SYNOPSIS

use Net::SFTP::Foreign::Compat;
my $sftp = Net::SFTP::Foreign::Compat->new($host);
$sftp->get("foo", "bar");
$sftp->put("bar", "baz");

DESCRIPTION

*** WARNING!!!

The old Net::SFTP::Foreign API inherited from the Net::SFTP package
is being obsolete. New versions of Net::SFTP::Foreign are going to
provide a new much improved but backward incompatible API.

Development versions exposing this new API are already available
from CPAN, they use version numbers as 0.9x_xx and so are not
automatically installed by the CPAN module.

If you want to continue using the old API you should change your
scripts to use the adaptor package Net::SFTP::Foreign::Compat
available from this distribution.

Net::SFTP::Foreign is a Perl client for the SFTP. It provides a subset of the commands listed in the SSH File Transfer Protocol IETF draft, which can be found at http://www.openssh.org/txt/draft-ietf-secsh-filexfer-02.txt.

Net::SFTP::Foreign is a forked version of Net::SFTP that uses an external ssh client (i.e. OpenSSH, http://www.openssh.org/) instead of Net::SSH::Perl to connect to the server.

SFTP stands for Secure File Transfer Protocol and is a method of transferring files between machines over a secure, encrypted connection (as opposed to regular FTP, which functions over an insecure connection). The security in SFTP comes through its integration with SSH, which provides an encrypted transport layer over which the SFTP commands are executed, and over which files can be transferred. The SFTP protocol defines a client and a server; only the client, not the server, is implemented in Net::SFTP::Foreign.

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

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

Well, both modules have their pros and cons:

Net::SFTP::Foreign does not requiere a bunch of additional modules and external libraries to work, just the OpenBSD ssh client (or the commercial one).

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 in your environment, using the binary ssh client ensures a seamless integration with it.

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

Net::SFTP::Foreign supports version 2 of the ssh protocol only.

Finally Net::SFTP::Foreign does not (and will never) allow to use passwords for authentication, as Net::SFTP does.

USAGE

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

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

%args can contain:

host => $hostname

remote host name
user => $username

username to use to log in to the remote server. This should be your SSH login, and can be empty, in which case the username is drawn from the user executing the process.
port => $portnumber

port number where the remote ssh server is listening
more => [@more_ssh_args]

additional args passed to ssh command.
ssh_cmd => $sshcmd

name of the external ssh client.
debug => 1

if set to a true value, debugging messages will be printed out. The default is false.
open2_cmd => [@cmd]
open2_cmd => $cmd;

allows to completely redefine how ssh is called. Its arguments are passed to IPC::Open2::open2 to open a pipe to the remote server. When present, other options are ignored (host, user, etc.)

$sftp->status

Returns the last remote SFTP status value. Only useful after one of the following methods has failed. Returns SSH2_FX_OK if there is no remote error (e.g. local file not found). In list context, returns a list of (status code, status text from fx2txt).

If a low-level protocol error or unexpected local error occurs, we die with an error message.

$sftp->get($remote [, $local [, \&callback ] ])

Downloads a file $remote from the remote host. If $local is specified, it is opened/created, and the contents of the remote file $remote are written to $local. In addition, its filesystem attributes (atime, mtime, permissions, etc.) will be set to those of the remote file.

If get is called in a non-void context, returns the contents of $remote (as well as writing them to $local, if $local is provided. Undef is returned on failure.

$local is optional. If not provided, the contents of the remote file $remote will be either discarded, if get is called in void context, or returned from get if called in a non-void context. Presumably, in the former case, you will use the callback function \&callback to "do something" with the contents of $remote.

If \&callback is specified, it should be a reference to a subroutine. The subroutine will be executed at each iteration of the read loop (files are generally read in 8192-byte blocks, although this depends on the server implementation). The callback function will receive as arguments: a Net::SFTP::Foreign object with an open SFTP connection; the data read from the SFTP server; the offset from the beginning of the file (in bytes); and the total size of the file (in bytes). You can use this mechanism to provide status messages, download progress meters, etc.:

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

$sftp->put($local, $remote [, \&callback ])

Uploads a file $local from the local host to the remote host, and saves it as $remote.

If \&callback is specified, it should be a reference to a subroutine. The subroutine will be executed at each iteration of the write loop, directly after the data has been read from the local file. The callback function will receive as arguments: a Net::SFTP::Foreign object with an open SFTP connection; the data read from $local, generally in 8192-byte chunks;; the offset from the beginning of the file (in bytes); and the total size of the file (in bytes). You can use this mechanism to provide status messages, upload progress meters, etc.:

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

Returns true on success, undef on error.

$sftp->ls($remote [, $subref ])

Fetches a directory listing of $remote.

If $subref is specified, for each entry in the directory, $subref will be called and given a reference to a hash with three keys: filename, the name of the entry in the directory listing; longname, an entry in a "long" listing like ls -l; and a, a Net::SFTP::Foreign::Attributes object, which contains the file attributes of the entry (atime, mtime, permissions, etc.).

If $subref is not specified, returns a list of directory entries, each of which is a reference to a hash as described in the previous paragraph.

COMMAND METHODS

Net::SFTP::Foreign supports all of the commands listed in the SFTP version 3 protocol specification. Each command is available for execution as a separate method, with a few exceptions: SSH_FXP_INIT, SSH_FXP_VERSION, and SSH_FXP_READDIR.

These are the available command methods:

$sftp->do_open($path, $flags [, $attrs ])

Sends the SSH_FXP_OPEN command to open a remote file $path, and returns an open handle on success. On failure returns undef. The "open handle" is not a Perl filehandle, nor is it a file descriptor; it is merely a marker used to identify the open file between the client and the server.

$flags should be a bitmask of open flags, whose values can be obtained from Net::SFTP::Foreign::Constants:

use Net::SFTP::Foreign::Constants qw( :flags );

$attrs should be a Net::SFTP::Foreign::Attributes object, specifying the initial attributes for the file $path. If you're opening the file for reading only, $attrs can be left blank, in which case it will be initialized to an empty set of attributes.

$sftp->do_read($handle, $offset, $copy_size)

Sends the SSH_FXP_READ command to read from an open file handle $handle, starting at $offset, and reading at most $copy_size bytes.

Returns a two-element list consisting of the data read from the SFTP server in the first slot, and the status code (if any) in the second. In the case of a successful read, the status code will be undef, and the data will be defined and true. In the case of EOF, the status code will be SSH2_FX_EOF, and the data will be undef. And in the case of an error in the read, a warning will be emitted, the status code will contain the error code, and the data will be undef.

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

Sends the SSH_FXP_WRITE command to write to an open file handle $handle, starting at $offset, and where the data to be written is in $data.

Returns the status code. On a successful write, the status code will be equal to SSH2_FX_OK; in the case of an unsuccessful write, a warning will be emitted, and the status code will contain the error returned from the server.

$sftp->do_close($handle)

Sends the SSH_FXP_CLOSE command to close either an open file or open directory, identified by $handle (the handle returned from either do_open or do_opendir).

Emits a warning if the CLOSE fails.

Returns the status code for the operation. To turn the status code into a text message, take a look at the fx2txt function in Net::SFTP::Foreign::Util.

$sftp->do_lstat($path)

$sftp->do_fstat($handle)

$sftp->do_stat($path)

These three methods all perform similar functionality: they run a stat on a remote file and return the results in a Net::SFTP::Foreign::Attributes object on success.

On failure, all three methods return undef, and emit a warning.

do_lstat sends a SSH_FXP_LSTAT command to obtain file attributes for a named file $path. do_stat sends a SSH_FXP_STAT command, and differs from do_lstat only in that do_stat follows symbolic links on the server, whereas do_lstat does not follow symbolic links.

do_fstat sends a SSH_FXP_FSTAT command to obtain file attributes for an open file handle $handle.

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

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

These two methods both perform similar functionality: they set the file attributes of a remote file. In both cases $attrs should be a Net::SFTP::Foreign::Attributes object.

do_setstat sends a SSH_FXP_SETSTAT command to set file attributes for a remote named file $path to $attrs.

do_fsetstat sends a SSH_FXP_FSETSTAT command to set the attributes of an open file handle $handle to $attrs.

Both methods emit a warning if the operation failes, and both return the status code for the operation. To turn the status code into a text message, take a look at the fx2txt function in Net::SFTP::Foreign::Util.

$sftp->do_opendir($path)

Sends a SSH_FXP_OPENDIR command to open the remote directory $path, and returns an open handle on success. On failure returns undef.

$sftp->do_remove($path)

Sends a SSH_FXP_REMOVE command to remove the remote file $path.

Emits a warning if the operation fails.

Returns the status code for the operation. To turn the status code into a text message, take a look at the fx2txt function in Net::SFTP::Foreign::Util.

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

Sends a SSH_FXP_MKDIR command to create a remote directory $path whose attributes should be initialized to $attrs, a Net::SFTP::Foreign::Attributes object.

Emits a warning if the operation fails.

Returns the status code for the operation. To turn the status code into a text message, take a look at the fx2txt function in Net::SFTP::Foreign::Util.

$sftp->do_rmdir($path)

Sends a SSH_FXP_RMDIR command to remove a remote directory $path.

Emits a warning if the operation fails.

Returns the status code for the operation. To turn the status code into a text message, take a look at the fx2txt function in Net::SFTP::Foreign::Util.

$sftp->do_realpath($path)

Sends a SSH_FXP_REALPATH command to canonicalise $path to an absolute path. This can be useful for turning paths containing '..' into absolute paths.

Returns the absolute path on success, undef on failure.

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

Sends a SSH_FXP_RENAME command to rename $old to $new.

Emits a warning if the operation fails.

Returns the status code for the operation. To turn the status code into a text message, take a look at the fx2txt function in Net::SFTP::Foreign::Util.

BUGS

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

To report bugs, please, send me and email or use http://rt.cpan.org.

AUTHOR

Salvador Fandiño <sfandino@yahoo.com>.

Net::SFTP::Foreign is based on Net::SFTP (95% of the code comes from there!) developed by Benjamin Trott and Dave Rolsky.

COPYRIGHT

The full text of the license can be found in the LICENSE file included with this module.

To install Net::SFTP::Foreign, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::SFTP::Foreign

CPAN shell

perl -MCPAN -e shell
install Net::SFTP::Foreign

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

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

USAGE

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

$sftp->status

$sftp->get($remote [, $local [, \&callback ] ])

$sftp->put($local, $remote [, \&callback ])

$sftp->ls($remote [, $subref ])

COMMAND METHODS

$sftp->do_open($path, $flags [, $attrs ])

$sftp->do_read($handle, $offset, $copy_size)

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

$sftp->do_close($handle)

$sftp->do_lstat($path)

$sftp->do_fstat($handle)

$sftp->do_stat($path)

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

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

$sftp->do_opendir($path)

$sftp->do_remove($path)

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

$sftp->do_rmdir($path)

$sftp->do_realpath($path)

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

BUGS

SEE ALSO

AUTHOR

COPYRIGHT

Module Install Instructions