1Net::SFTP(3)          User Contributed Perl Documentation         Net::SFTP(3)
2
3
4

NAME

6       Net::SFTP - Secure File Transfer Protocol client
7

SYNOPSIS

9           use Net::SFTP;
10           my $sftp = Net::SFTP->new($host);
11           $sftp->get("foo", "bar");
12           $sftp->put("bar", "baz");
13

DESCRIPTION

15       Net::SFTP is a pure-Perl implementation of the Secure File Transfer
16       Protocol (SFTP) - file transfer built on top of the SSH2 protocol.
17       Net::SFTP uses Net::SSH::Perl to build a secure, encrypted tunnel
18       through which files can be transferred and managed. It provides a
19       subset of the commands listed in the SSH File Transfer Protocol IETF
20       draft, which can be found at
21       http://www.openssh.com/txt/draft-ietf-secsh-filexfer-00.txt.
22
23       SFTP stands for Secure File Transfer Protocol and is a method of
24       transferring files between machines over a secure, encrypted connection
25       (as opposed to regular FTP, which functions over an insecure
26       connection). The security in SFTP comes through its integration with
27       SSH, which provides an encrypted transport layer over which the SFTP
28       commands are executed, and over which files can be transferred. The
29       SFTP protocol defines a client and a server; only the client, not the
30       server, is implemented in Net::SFTP.
31
32       Because it is built upon SSH, SFTP inherits all of the built-in
33       functionality provided by Net::SSH::Perl: encrypted communications
34       between client and server, multiple supported authentication methods
35       (eg. password, public key, etc.).
36

USAGE

38   Net::SFTP->new($host, %args)
39       Opens a new SFTP connection with a remote host $host, and returns a
40       Net::SFTP object representing that open connection.
41
42       %args can contain:
43
44       •   user
45
46           The username to use to log in to the remote server. This should be
47           your SSH login, and can be empty, in which case the username is
48           drawn from the user executing the process.
49
50           See the login method in Net::SSH::Perl for more details.
51
52       •   password
53
54           The password to use to log in to the remote server. This should be
55           your SSH password, if you use password authentication in SSH; if
56           you use public key authentication, this argument is unused.
57
58           See the login method in Net::SSH::Perl for more details.
59
60       •   debug
61
62           If set to a true value, debugging messages will be printed out for
63           both the SSH and SFTP protocols. This automatically turns on the
64           debug parameter in Net::SSH::Perl.
65
66           The default is false.
67
68       •   warn
69
70           If given a sub ref, the sub is called with $self and any warning
71           message; if set to false, warnings are supressed; otherwise they
72           are output with 'warn' (default).
73
74       •   ssh_args
75
76           Specifies a reference to a list or hash of named arguments that
77           should be given to the constructor of the Net::SSH::Perl object
78           underlying the Net::SFTP connection.
79
80           For example, you could use this to set up your authentication
81           identity files, to set a specific cipher for encryption, etc., e.g.
82           "ssh_args => [ cipher => 'aes256-cbc', options =<gt" [ "MACs
83           +hmac-sha1", "HashKnownHosts yes" ] ]>.
84
85           See the new method in Net::SSH::Perl for more details.
86
87   $sftp->status
88       Returns the last remote SFTP status value.  Only useful after one of
89       the following methods has failed.  Returns SSH2_FX_OK if there is no
90       remote error (e.g. local file not found).  In list context, returns a
91       list of (status code, status text from "fx2txt").
92
93       If a low-level protocol error or unexpected local error occurs, we die
94       with an error message.
95
96   $sftp->get($remote [, $local [, \&callback ] ])
97       Downloads a file $remote from the remote host. If $local is specified,
98       it is opened/created, and the contents of the remote file $remote are
99       written to $local. In addition, its filesystem attributes (atime,
100       mtime, permissions, etc.)  will be set to those of the remote file.
101
102       If get is called in a non-void context, returns the contents of $remote
103       (as well as writing them to $local, if $local is provided.  Undef is
104       returned on failure.
105
106       $local is optional. If not provided, the contents of the remote file
107       $remote will be either discarded, if get is called in void context, or
108       returned from get if called in a non-void context. Presumably, in the
109       former case, you will use the callback function \&callback to "do
110       something" with the contents of $remote.
111
112       If \&callback is specified, it should be a reference to a subroutine.
113       The subroutine will be executed at each iteration of the read loop
114       (files are generally read in 8192-byte blocks, although this depends on
115       the server implementation).  The callback function will receive as
116       arguments: a Net::SFTP object with an open SFTP connection; the data
117       read from the SFTP server; the offset from the beginning of the file
118       (in bytes); and the total size of the file (in bytes). You can use this
119       mechanism to provide status messages, download progress meters, etc.:
120
121           sub callback {
122               my($sftp, $data, $offset, $size) = @_;
123               print "Read $offset / $size bytes\r";
124           }
125
126   $sftp->put($local, $remote [, \&callback ])
127       Uploads a file $local from the local host to the remote host, and saves
128       it as $remote.
129
130       If \&callback is specified, it should be a reference to a subroutine.
131       The subroutine will be executed at each iteration of the write loop,
132       directly after the data has been read from the local file. The callback
133       function will receive as arguments: a Net::SFTP object with an open
134       SFTP connection; the data read from $local, generally in 8192-byte
135       chunks;; the offset from the beginning of the file (in bytes); and the
136       total size of the file (in bytes). You can use this mechanism to
137       provide status messages, upload progress meters, etc.:
138
139           sub callback {
140               my($sftp, $data, $offset, $size) = @_;
141               print "Wrote $offset / $size bytes\r";
142           }
143
144       Returns true on success, undef on error.
145
146   $sftp->ls($remote [, $subref ])
147       Fetches a directory listing of $remote.
148
149       If $subref is specified, for each entry in the directory, $subref will
150       be called and given a reference to a hash with three keys: filename,
151       the name of the entry in the directory listing; longname, an entry in a
152       "long" listing like "ls -l"; and a, a Net::SFTP::Attributes object,
153       which contains the file attributes of the entry (atime, mtime,
154       permissions, etc.).
155
156       If $subref is not specified, returns a list of directory entries, each
157       of which is a reference to a hash as described in the previous
158       paragraph.
159

COMMAND METHODS

161       Net::SFTP supports all of the commands listed in the SFTP version 3
162       protocol specification. Each command is available for execution as a
163       separate method, with a few exceptions: SSH_FXP_INIT, SSH_FXP_VERSION,
164       and SSH_FXP_READDIR.
165
166       These are the available command methods:
167
168   $sftp->do_open($path, $flags [, $attrs ])
169       Sends the SSH_FXP_OPEN command to open a remote file $path, and returns
170       an open handle on success. On failure returns undef. The "open handle"
171       is not a Perl filehandle, nor is it a file descriptor; it is merely a
172       marker used to identify the open file between the client and the
173       server.
174
175       $flags should be a bitmask of open flags, whose values can be obtained
176       from Net::SFTP::Constants:
177
178           use Net::SFTP::Constants qw( :flags );
179
180       $attrs should be a Net::SFTP::Attributes object, specifying the initial
181       attributes for the file $path. If you're opening the file for reading
182       only, $attrs can be left blank, in which case it will be initialized to
183       an empty set of attributes.
184
185   $sftp->do_read($handle, $offset, $copy_size)
186       Sends the SSH_FXP_READ command to read from an open file handle
187       $handle, starting at $offset, and reading at most $copy_size bytes.
188
189       Returns a two-element list consisting of the data read from the SFTP
190       server in the first slot, and the status code (if any) in the second.
191       In the case of a successful read, the status code will be undef, and
192       the data will be defined and true. In the case of EOF, the status code
193       will be SSH2_FX_EOF, and the data will be undef. And in the case of an
194       error in the read, a warning will be emitted, the status code will
195       contain the error code, and the data will be undef.
196
197   $sftp->do_write($handle, $offset, $data)
198       Sends the SSH_FXP_WRITE command to write to an open file handle
199       $handle, starting at $offset, and where the data to be written is in
200       $data.
201
202       Returns the status code. On a successful write, the status code will be
203       equal to SSH2_FX_OK; in the case of an unsuccessful write, a warning
204       will be emitted, and the status code will contain the error returned
205       from the server.
206
207   $sftp->do_close($handle)
208       Sends the SSH_FXP_CLOSE command to close either an open file or open
209       directory, identified by $handle (the handle returned from either
210       do_open or do_opendir).
211
212       Emits a warning if the CLOSE fails.
213
214       Returns the status code for the operation. To turn the status code into
215       a text message, take a look at the "fx2txt" function in
216       Net::SFTP::Util.
217
218   $sftp->do_lstat($path)
219   $sftp->do_fstat($handle)
220   $sftp->do_stat($path)
221       These three methods all perform similar functionality: they run a stat
222       on a remote file and return the results in a Net::SFTP::Attributes
223       object on success.
224
225       On failure, all three methods return undef, and emit a warning.
226
227       do_lstat sends a SSH_FXP_LSTAT command to obtain file attributes for a
228       named file $path. do_stat sends a SSH_FXP_STAT command, and differs
229       from do_lstat only in that do_stat follows symbolic links on the
230       server, whereas do_lstat does not follow symbolic links.
231
232       do_fstat sends a SSH_FXP_FSTAT command to obtain file attributes for an
233       open file handle $handle.
234
235   $sftp->do_setstat($path, $attrs)
236   $sftp->do_fsetstat($handle, $attrs)
237       These two methods both perform similar functionality: they set the file
238       attributes of a remote file. In both cases $attrs should be a
239       Net::SFTP::Attributes object.
240
241       do_setstat sends a SSH_FXP_SETSTAT command to set file attributes for a
242       remote named file $path to $attrs.
243
244       do_fsetstat sends a SSH_FXP_FSETSTAT command to set the attributes of
245       an open file handle $handle to $attrs.
246
247       Both methods emit a warning if the operation failes, and both return
248       the status code for the operation. To turn the status code into a text
249       message, take a look at the "fx2txt" function in Net::SFTP::Util.
250
251   $sftp->do_opendir($path)
252       Sends a SSH_FXP_OPENDIR command to open the remote directory $path, and
253       returns an open handle on success.  On failure returns undef.
254
255   $sftp->do_remove($path)
256       Sends a SSH_FXP_REMOVE command to remove the remote file $path.
257
258       Emits a warning if the operation fails.
259
260       Returns the status code for the operation. To turn the status code into
261       a text message, take a look at the "fx2txt" function in
262       Net::SFTP::Util.
263
264   $sftp->do_mkdir($path, $attrs)
265       Sends a SSH_FXP_MKDIR command to create a remote directory $path whose
266       attributes should be initialized to $attrs, a Net::SFTP::Attributes
267       object.
268
269       Emits a warning if the operation fails.
270
271       Returns the status code for the operation. To turn the status code into
272       a text message, take a look at the "fx2txt" function in
273       Net::SFTP::Util.
274
275   $sftp->do_rmdir($path)
276       Sends a SSH_FXP_RMDIR command to remove a remote directory $path.
277
278       Emits a warning if the operation fails.
279
280       Returns the status code for the operation. To turn the status code into
281       a text message, take a look at the "fx2txt" function in
282       Net::SFTP::Util.
283
284   $sftp->do_realpath($path)
285       Sends a SSH_FXP_REALPATH command to canonicalise $path to an absolute
286       path. This can be useful for turning paths containing '..' into
287       absolute paths.
288
289       Returns the absolute path on success, undef on failure.
290
291   $sftp->do_rename($old, $new)
292       Sends a SSH_FXP_RENAME command to rename $old to $new.
293
294       Emits a warning if the operation fails.
295
296       Returns the status code for the operation. To turn the status code into
297       a text message, take a look at the "fx2txt" function in
298       Net::SFTP::Util.
299

SUPPORT

301       For samples/tutorials, take a look at the scripts in eg/ in the
302       distribution directory.
303
304       There is a mailing list for development discussion and usage questions.
305       Posting is limited to subscribers only.  You can sign up at
306       http://lists.sourceforge.net/lists/listinfo/ssh-sftp-perl-users
307
308       Please report all bugs via rt.cpan.org at
309       https://rt.cpan.org/NoAuth/ReportBug.html?Queue=net%3A%3Asftp
310

AUTHOR

312       Current maintainer is David Robins, dbrobins@cpan.org.
313
314       Previous maintainer was Dave Rolsky, autarch@urth.org.
315
316       Originally written by Benjamin Trott.
317
319       Copyright (c) 2001-2003 Benjamin Trott, Copyright (c) 2003-2004 David
320       Rolsky.  Copyright (c) David Robins.  All rights reserved.  This
321       program is free software; you can redistribute it and/or modify it
322       under the same terms as Perl itself.
323
324       The full text of the license can be found in the LICENSE file included
325       with this module.
326
327
328
329perl v5.36.0                      2023-01-20                      Net::SFTP(3)
Impressum