/ 
Net-SFTP-Foreign-0.90_01
River stage two • 15 direct dependents • 16 total dependents
/ Net::SFTP::Foreign

NAME

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

SYNOPSIS

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

DESCRIPTION

WARNING: This is a development version, expect bugs on it!!!

WARNING: This package API is not compatible with Net::SFTP anymore!!!

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.

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 (and also included on this package distribution, on the rfc directory).

Net::SFTP::Foreign uses the ssh command to stablish the secure connection to the remote server and talk the sftp protocol on top of it.

Formelly Net::SFTP::Foreign was a hacked version of Net::SFTP, but from version 0.90 is has been almost completelly rewritten from scratch and a new much improved and incompatible API introduced (the adaptor module Net::SFTP::Foreign::Compat is also provided for backward compatibility).

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.

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

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

Those are the methods available from this package.

All methods return undef on failure and a true value or the requested data on success. $sftp->error can be used to check explicitly for an error after every method call.

Inside any method, a low-level network error as a broken ssh connection will cause the method to die.

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.

If stablishing the connection fails, an exception is raised, you can use eval to catch it:

my $sftp = eval { Net::SFTP::Foreign->new(foo) };
if ($@) {
    print STDERR "something went wrong ($@)"
}

The exit code for the ssh command is available in $?, though OpenSSH ssh does not return meaningful codes. For debugging purposes you can run ssh in verbose passing it the -v option via the more option.

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

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

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

$sftp->status

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

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

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

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

The method accepts several options (not all combinations are possible):

copytime => $bool

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

copyperms => $bool

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

umask => $umask

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

perm => $perm

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

blocksize => $bytes

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

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";
}
$sftp->get_content($remote)

Returns the content of the remote file.

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

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

This method accepts several options:

copytime => $bool

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

copyperms => $bool

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

umask => $umask

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

perm => $perm

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

blocksize => $bytes

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

callback => $callback

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

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

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

$sftp->ls($remote)

Fetches a directory listing of $remote.

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);
$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 "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->read($handle, $offset, $length)

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

On success returns the data read from the remote file and undef on failure.

You can test if the end of file has been reached through $sftp->status:

my $data = $sftp->read($handle, $offset, $length)
if (!defined $data) {
  if ($sftp->status == SSH2_FX_EOF) {
    # end of file
    ...
  }
  else {
    # other error
  }
}

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 the requested.

$sftp->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 true on success and undef on failure.

$sftp->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 open or opendir).

Returns true on success and undef on failure.

$sftp->stat($path)

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

Returns undef on failure.

$sftp->fstat($handle)

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

$sftp->lstat($path)

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

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

sets file attributes on remote file $path.

Returns true on success and undef on failure.

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

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

$sftp->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->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 should be initialized to $attrs, a Net::SFTP::Foreign::Attributes object. Returns a true value on success and undef on failure.

$sftp->rmdir($path)

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

$sftp->realpath($path)

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

Returns the absolute path on success, undef on failure.

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

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

BUGS

This is development version, expect bugs!!!

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 www.openssh.org and on the sftp(1) and sftp-server(8) manual pages.

COPYRIGHT

Copyright (c) 2005, 2006 Salvador Fandiño.

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

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.