Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::SFTP(3)	      User Contributed Perl Documentation	  Net::SFTP(3)

NAME
       Net::SFTP - Secure File Transfer	Protocol client

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

DESCRIPTION
       Net::SFTP is a pure-Perl	implementation of the Secure File Transfer
       Protocol	(SFTP) - file transfer built on	top of the SSH2	protocol.
       Net::SFTP uses Net::SSH::Perl to	build a	secure,	encrypted tunnel
       through which files can be transferred and managed. It provides a
       subset of the commands listed in	the SSH	File Transfer Protocol IETF
       draft, which can	be found at
       http://www.openssh.com/txt/draft-ietf-secsh-filexfer-00.txt.

       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.

       Because it is built upon	SSH, SFTP inherits all of the built-in
       functionality provided by Net::SSH::Perl: encrypted communications
       between client and server, multiple supported authentication methods
       (eg. password, public key, etc.).

USAGE
   Net::SFTP->new($host, %args)
       Opens a new SFTP	connection with	a remote host $host, and returns a
       Net::SFTP object	representing that open connection.

       %args can contain:

       o   user

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

	   See the login method	in Net::SSH::Perl for more details.

       o   password

	   The password	to use to log in to the	remote server. This should be
	   your	SSH password, if you use password authentication in SSH; if
	   you use public key authentication, this argument is unused.

	   See the login method	in Net::SSH::Perl for more details.

       o   debug

	   If set to a true value, debugging messages will be printed out for
	   both	the SSH	and SFTP protocols. This automatically turns on	the
	   debug parameter in Net::SSH::Perl.

	   The default is false.

       o   warn

	   If given a sub ref, the sub is called with $self and	any warning
	   message; if set to false, warnings are supressed; otherwise they
	   are output with 'warn' (default).

       o   ssh_args

	   Specifies a reference to a list or hash of named arguments that
	   should be given to the constructor of the Net::SSH::Perl object
	   underlying the Net::SFTP connection.

	   For example,	you could use this to set up your authentication
	   identity files, to set a specific cipher for	encryption, etc., e.g.
	   "ssh_args =>	[ cipher => 'aes256-cbc', options =<gt"	[ "MACs
	   +hmac-sha1",	"HashKnownHosts	yes" ] ]>.

	   See the new method in Net::SSH::Perl	for more details.

   $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 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 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::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 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::Constants:

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

       $attrs should be	a Net::SFTP::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::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::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::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::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::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::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::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::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::Util.

SUPPORT
       For samples/tutorials, take a look at the scripts in eg/	in the
       distribution directory.

       There is	a mailing list for development discussion and usage questions.
       Posting is limited to subscribers only.	You can	sign up	at
       http://lists.sourceforge.net/lists/listinfo/ssh-sftp-perl-users

       Please report all bugs via rt.cpan.org at
       https://rt.cpan.org/NoAuth/ReportBug.html?Queue=net%3A%3Asftp

AUTHOR
       Current maintainer is David Robins, dbrobins@cpan.org.

       Previous	maintainer was Dave Rolsky, autarch@urth.org.

       Originally written by Benjamin Trott.

COPYRIGHT
       Copyright (c) 2001-2003 Benjamin	Trott, Copyright (c) 2003-2004 David
       Rolsky.	Copyright (c) David Robins.  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.

perl v5.32.1			  2017-06-27			  Net::SFTP(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | COMMAND METHODS | SUPPORT | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::SFTP&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help