1Net::SFTP(3) User Contributed Perl Documentation Net::SFTP(3)
2
6 Net::SFTP - Secure File Transfer Protocol client
7
9 use Net::SFTP;
10 my $sftp = Net::SFTP->new($host);
11 $sftp->get("foo", "bar");
12 $sftp->put("bar", "baz");
13
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 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 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
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 %args can contain:
43 • user
45 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 See the login method in Net::SSH::Perl for more details.
51 • password
53 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 See the login method in Net::SSH::Perl for more details.
59 • debug
61 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 The default is false.
67 • warn
69 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 • ssh_args
75 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 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 See the new method in Net::SSH::Perl for more details.
86 $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 If a low-level protocol error or unexpected local error occurs, we die
94 with an error message.
95 $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 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 $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 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 sub callback {
122 my($sftp, $data, $offset, $size) = @_;
123 print "Read $offset / $size bytes\r";
124 }
125 $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 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 sub callback {
140 my($sftp, $data, $offset, $size) = @_;
141 print "Wrote $offset / $size bytes\r";
142 }
143 Returns true on success, undef on error.
145 $sftp->ls($remote [, $subref ])
147 Fetches a directory listing of $remote.
148 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 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
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 These are the available command methods:
167 $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 $flags should be a bitmask of open flags, whose values can be obtained
176 from Net::SFTP::Constants:
177 use Net::SFTP::Constants qw( :flags );
179 $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 $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 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 $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 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 $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 Emits a warning if the CLOSE fails.
213 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 $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 On failure, all three methods return undef, and emit a warning.
226 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 do_fstat sends a SSH_FXP_FSTAT command to obtain file attributes for an
233 open file handle $handle.
234 $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 do_setstat sends a SSH_FXP_SETSTAT command to set file attributes for a
242 remote named file $path to $attrs.
243 do_fsetstat sends a SSH_FXP_FSETSTAT command to set the attributes of
245 an open file handle $handle to $attrs.
246 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 $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 $sftp->do_remove($path)
256 Sends a SSH_FXP_REMOVE command to remove the remote file $path.
257 Emits a warning if the operation fails.
259 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 $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 Emits a warning if the operation fails.
270 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 $sftp->do_rmdir($path)
276 Sends a SSH_FXP_RMDIR command to remove a remote directory $path.
277 Emits a warning if the operation fails.
279 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 $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 Returns the absolute path on success, undef on failure.
290 $sftp->do_rename($old, $new)
292 Sends a SSH_FXP_RENAME command to rename $old to $new.
293 Emits a warning if the operation fails.
295 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
301 For samples/tutorials, take a look at the scripts in eg/ in the
302 distribution directory.
303 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 Please report all bugs via rt.cpan.org at
309 https://rt.cpan.org/NoAuth/ReportBug.html?Queue=net%3A%3Asftp
310
312 Current maintainer is David Robins, dbrobins@cpan.org.
313 Previous maintainer was Dave Rolsky, autarch@urth.org.
315 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 The full text of the license can be found in the LICENSE file included
325 with this module.
326perl v5.38.0 2023-07-21 Net::SFTP(3)