1 .\" $OpenBSD: sftp.1,v 1.143 2022/12/16 03:40:03 djm Exp $
3 .\" Copyright (c) 2001 Damien Miller. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
17 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 .Dd $Mdocdate: December 16 2022 $
30 .Nd OpenSSH secure file transfer
34 .Op Fl B Ar buffer_size
37 .Op Fl D Ar sftp_server_command
38 .Op Fl F Ar ssh_config
39 .Op Fl i Ar identity_file
40 .Op Fl J Ar destination
42 .Op Fl o Ar ssh_option
44 .Op Fl R Ar num_requests
46 .Op Fl s Ar subsystem | sftp_server
47 .Op Fl X Ar sftp_option
51 is a file transfer program, similar to
53 which performs all operations over an encrypted
56 It may also use many features of ssh, such as public key authentication and
61 may be specified either as
63 .Oo user @ Oc host Op : path
65 or as a URI in the form
67 .No sftp:// Oo user @ Oc host Oo : port Oc Op / path .
74 and it is not a directory,
76 will retrieve files automatically if a non-interactive
77 authentication method is used; otherwise it will do so after
78 successful interactive authentication.
82 is specified, or if the
86 will log in to the specified
88 and enter interactive command mode, changing to the remote directory
90 An optional trailing slash can be used to force the
92 to be interpreted as a directory.
94 Since the destination formats use colon characters to delimit host
95 names from path names or port numbers, IPv6 addresses must be
96 enclosed in square brackets to avoid ambiguity.
98 The options are as follows:
103 to use IPv4 addresses only.
107 to use IPv6 addresses only.
111 to the remote system.
112 The default is not to forward an authentication agent.
114 Attempt to continue interrupted transfers rather than overwriting
115 existing partial or complete copies of files.
116 If the partial contents differ from those being transferred,
117 then the resultant file is likely to be corrupt.
118 .It Fl B Ar buffer_size
119 Specify the size of the buffer that
121 uses when transferring files.
122 Larger buffers require fewer round trips at the cost of higher
124 The default is 32768 bytes.
125 .It Fl b Ar batchfile
126 Batch mode reads a series of commands from an input
130 Since it lacks user interaction, it should be used in conjunction with
131 non-interactive authentication to obviate the need to enter a password
132 at connection time (see
142 may be used to indicate standard input.
144 will abort if any of the following
146 .Ic get , put , reget , reput , rename , ln ,
147 .Ic rm , mkdir , chdir , ls ,
148 .Ic lchdir , copy , cp , chmod , chown ,
149 .Ic chgrp , lpwd , df , symlink ,
153 Termination on error can be suppressed on a command by command basis by
154 prefixing the command with a
156 character (for example,
157 .Ic -rm /tmp/blah* ) .
158 Echo of the command may be suppressed by prefixing the command with a
161 These two prefixes may be combined in any order, for example
164 Enables compression (via ssh's
168 Selects the cipher to use for encrypting the data transfers.
169 This option is directly passed to
171 .It Fl D Ar sftp_server_command
172 Connect directly to a local sftp server
175 A command and arguments may be specified, for example
176 .Qq /path/sftp-server -el debug3 .
177 This option may be useful in debugging the client and server.
178 .It Fl F Ar ssh_config
179 Specifies an alternative
180 per-user configuration file for
182 This option is directly passed to
185 Requests that files be flushed to disk immediately after transfer.
186 When uploading files, this feature is only enabled if the server
187 implements the "fsync@openssh.com" extension.
188 .It Fl i Ar identity_file
189 Selects the file from which the identity (private key) for public key
190 authentication is read.
191 This option is directly passed to
193 .It Fl J Ar destination
194 Connect to the target host by first making an
196 connection to the jump host described by
198 and then establishing a TCP forwarding to the ultimate destination from
200 Multiple jump hops may be specified separated by comma characters.
201 This is a shortcut to specify a
203 configuration directive.
204 This option is directly passed to
207 Limits the used bandwidth, specified in Kbit/s.
209 Disables quiet mode, e.g. to override the implicit quiet mode set by the
212 .It Fl o Ar ssh_option
213 Can be used to pass options to
215 in the format used in
217 This is useful for specifying options
218 for which there is no separate
221 For example, to specify an alternate port use:
223 For full details of the options listed below, and their possible values, see
226 .Bl -tag -width Ds -offset indent -compact
232 .It CanonicalizeFallbackLocal
233 .It CanonicalizeHostname
234 .It CanonicalizeMaxDots
235 .It CanonicalizePermittedCNAMEs
236 .It CASignatureAlgorithms
241 .It ConnectionAttempts
246 .It GlobalKnownHostsFile
247 .It GSSAPIAuthentication
248 .It GSSAPIDelegateCredentials
251 .It HostbasedAcceptedAlgorithms
252 .It HostbasedAuthentication
253 .It HostKeyAlgorithms
260 .It KbdInteractiveAuthentication
261 .It KbdInteractiveDevices
263 .It KnownHostsCommand
266 .It NoHostAuthenticationForLocalhost
267 .It NumberOfPasswordPrompts
268 .It PasswordAuthentication
271 .It PreferredAuthentications
274 .It PubkeyAcceptedAlgorithms
275 .It PubkeyAuthentication
279 .It ServerAliveInterval
280 .It ServerAliveCountMax
282 .It StrictHostKeyChecking
286 .It UserKnownHostsFile
290 Specifies the port to connect to on the remote host.
292 Preserves modification times, access times, and modes from the
293 original files transferred.
295 Quiet mode: disables the progress meter as well as warning and
296 diagnostic messages from
298 .It Fl R Ar num_requests
299 Specify how many requests may be outstanding at any one time.
300 Increasing this may slightly improve file transfer speed
301 but will increase memory usage.
302 The default is 64 outstanding requests.
304 Recursively copy entire directories when uploading and downloading.
307 does not follow symbolic links encountered in the tree traversal.
311 to use for the encrypted connection.
312 The program must understand
315 .It Fl s Ar subsystem | sftp_server
316 Specifies the SSH2 subsystem or the path for an sftp server
318 A path is useful when the remote
320 does not have an sftp subsystem configured.
323 This option is also passed to ssh.
324 .It Fl X Ar sftp_option
325 Specify an option that controls aspects of SFTP protocol behaviour.
326 The valid options are:
328 .It Cm nrequests Ns = Ns Ar value
329 Controls how many concurrent SFTP read or write requests may be in progress
330 at any point in time during a download or upload.
331 By default 64 requests may be active concurrently.
332 .It Cm buffer Ns = Ns Ar value
333 Controls the maximum buffer size for a single SFTP read/write operation used
334 during download or upload.
335 By default a 32KB buffer is used.
338 .Sh INTERACTIVE COMMANDS
339 Once in interactive mode,
341 understands a set of commands similar to those of
343 Commands are case insensitive.
344 Pathnames that contain spaces must be enclosed in quotes.
345 Any special characters contained within pathnames that are recognized by
347 must be escaped with backslashes
354 Change remote directory to
358 is not specified, then change directory to the one the session started in.
371 characters and may match multiple files.
373 must be a numeric GID.
377 flag is specified, then symlinks will not be followed.
378 Note that this is only supported by servers that implement
379 the "lsetstat@openssh.com" extension.
385 Change permissions of file
392 characters and may match multiple files.
396 flag is specified, then symlinks will not be followed.
397 Note that this is only supported by servers that implement
398 the "lsetstat@openssh.com" extension.
411 characters and may match multiple files.
413 must be a numeric UID.
417 flag is specified, then symlinks will not be followed.
418 Note that this is only supported by servers that implement
419 the "lsetstat@openssh.com" extension.
420 .It Ic copy Ar oldpath Ar newpath
421 Copy remote file from
426 Note that this is only supported by servers that implement the "copy-data"
428 .It Ic cp Ar oldpath Ar newpath
436 Display usage information for the filesystem holding the current directory
442 flag is specified, the capacity information will be displayed using
443 "human-readable" suffixes.
446 flag requests display of inode information in addition to capacity information.
447 This command is only supported on servers that implement the
448 .Dq statvfs@openssh.com
460 and store it on the local machine.
462 path name is not specified, it is given the same name it has on the
467 characters and may match multiple files.
472 must specify a directory.
476 flag is specified, then attempt to resume partial transfers of existing files.
477 Note that resumption assumes that any partial copy of the local file matches
479 If the remote file contents differ from the partial local copy then the
480 resultant file is likely to be corrupt.
484 flag is specified, then
486 will be called after the file transfer has completed to flush the file
491 .\" undocumented redundant alias
494 flag is specified, then full file permissions and access times are
499 .\" undocumented redundant alias
502 flag is specified then directories will be copied recursively.
505 does not follow symbolic links when performing recursive transfers.
508 .It Ic lcd Op Ar path
509 Change local directory to
513 is not specified, then change directory to the local user's home directory.
514 .It Ic lls Op Ar ls-options Op Ar path
515 Display local directory listing of either
517 or current directory if
521 may contain any flags supported by the local system's
527 characters and may match multiple files.
528 .It Ic lmkdir Ar path
529 Create local directory specified by
542 flag is specified the created link is a symbolic link, otherwise it is
545 Print local working directory.
550 Display a remote directory listing of either
552 or the current directory if
558 characters and may match multiple files.
560 The following flags are recognized and alter the behaviour of
565 Produce single columnar output.
567 List files beginning with a dot
570 Do not sort the listing.
571 The default sort order is lexicographical.
573 When used with a long format option, use unit suffixes: Byte, Kilobyte,
574 Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce
575 the number of digits to four or fewer using powers of 2 for sizes (K=1024,
578 Display additional details including permissions
579 and ownership information.
581 Produce a long listing with user and group information presented
584 Reverse the sort order of the listing.
586 Sort the listing by file size.
588 Sort the listing by last modification time.
590 .It Ic lumask Ar umask
594 Create remote directory specified by
597 Toggle display of progress meter.
605 and store it on the remote machine.
606 If the remote path name is not specified, it is given the same name it has
607 on the local machine.
611 characters and may match multiple files.
616 must specify a directory.
620 flag is specified, then attempt to resume partial
621 transfers of existing files.
622 Note that resumption assumes that any partial copy of the remote file
623 matches the local copy.
624 If the local file contents differ from the remote local copy then
625 the resultant file is likely to be corrupt.
629 flag is specified, then a request will be sent to the server to call
631 after the file has been transferred.
632 Note that this is only supported by servers that implement
633 the "fsync@openssh.com" extension.
637 .\" undocumented redundant alias
640 flag is specified, then full file permissions and access times are
645 .\" undocumented redundant alias
648 flag is specified then directories will be copied recursively.
651 does not follow symbolic links when performing recursive transfers.
653 Display remote working directory.
681 .It Ic rename Ar oldpath newpath
682 Rename remote file from
687 Delete remote file specified by
690 Remove remote directory specified by
692 .It Ic symlink Ar oldpath newpath
693 Create a symbolic link from
701 .It Ic \&! Ns Ar command
706 Escape to local shell.
724 .%T "SSH File Transfer Protocol"
725 .%N draft-ietf-secsh-filexfer-00.txt
727 .%O work in progress material