| blob | 7eebeeacbf3f12fcbd7f1b3b1a701ce1046dc687 |
1 .\" $OpenBSD: sftp.1,v 1.138 2021/07/02 05:11:21 dtucker Exp $
2 .\"
3 .\" Copyright (c) 2001 Damien Miller. All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
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.
13 .\"
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.
24 .\"
25 .Dd $Mdocdate: July 2 2021 $
26 .Dt SFTP 1
27 .Os
28 .Sh NAME
29 .Nm sftp
30 .Nd OpenSSH secure file transfer
31 .Sh SYNOPSIS
32 .Nm sftp
33 .Op Fl 46AaCfNpqrv
34 .Op Fl B Ar buffer_size
35 .Op Fl b Ar batchfile
36 .Op Fl c Ar cipher
37 .Op Fl D Ar sftp_server_path
38 .Op Fl F Ar ssh_config
39 .Op Fl i Ar identity_file
40 .Op Fl J Ar destination
41 .Op Fl l Ar limit
42 .Op Fl o Ar ssh_option
43 .Op Fl P Ar port
44 .Op Fl R Ar num_requests
45 .Op Fl S Ar program
46 .Op Fl s Ar subsystem | sftp_server
47 .Ar destination
48 .Sh DESCRIPTION
49 .Nm
50 is a file transfer program, similar to
51 .Xr ftp 1 ,
52 which performs all operations over an encrypted
53 .Xr ssh 1
54 transport.
55 It may also use many features of ssh, such as public key authentication and
56 compression.
57 .Pp
58 The
59 .Ar destination
60 may be specified either as
61 .Sm off
62 .Oo user @ Oc host Op : path
63 .Sm on
64 or as a URI in the form
65 .Sm off
66 .No sftp:// Oo user @ Oc host Oo : port Oc Op / path .
67 .Sm on
68 .Pp
69 If the
70 .Ar destination
71 includes a
72 .Ar path
73 and it is not a directory,
74 .Nm
75 will retrieve files automatically if a non-interactive
76 authentication method is used; otherwise it will do so after
77 successful interactive authentication.
78 .Pp
79 If no
80 .Ar path
81 is specified, or if the
82 .Ar path
83 is a directory,
84 .Nm
85 will log in to the specified
86 .Ar host
87 and enter interactive command mode, changing to the remote directory
88 if one was specified.
89 An optional trailing slash can be used to force the
90 .Ar path
91 to be interpreted as a directory.
92 .Pp
93 Since the destination formats use colon characters to delimit host
94 names from path names or port numbers, IPv6 addresses must be
95 enclosed in square brackets to avoid ambiguity.
96 .Pp
97 The options are as follows:
98 .Bl -tag -width Ds
99 .It Fl 4
100 Forces
101 .Nm
102 to use IPv4 addresses only.
103 .It Fl 6
104 Forces
105 .Nm
106 to use IPv6 addresses only.
107 .It Fl A
108 Allows forwarding of
109 .Xr ssh-agent 1
110 to the remote system.
111 The default is not to forward an authentication agent.
112 .It Fl a
113 Attempt to continue interrupted transfers rather than overwriting
114 existing partial or complete copies of files.
115 If the partial contents differ from those being transferred,
116 then the resultant file is likely to be corrupt.
117 .It Fl B Ar buffer_size
118 Specify the size of the buffer that
119 .Nm
120 uses when transferring files.
121 Larger buffers require fewer round trips at the cost of higher
122 memory consumption.
123 The default is 32768 bytes.
124 .It Fl b Ar batchfile
125 Batch mode reads a series of commands from an input
126 .Ar batchfile
127 instead of
128 .Em stdin .
129 Since it lacks user interaction it should be used in conjunction with
130 non-interactive authentication to obviate the need to enter a password
131 at connection time (see
132 .Xr sshd 8
133 and
134 .Xr ssh-keygen 1
135 for details).
136 .Pp
137 A
138 .Ar batchfile
139 of
140 .Sq \-
141 may be used to indicate standard input.
142 .Nm
143 will abort if any of the following
144 commands fail:
145 .Ic get , put , reget , reput , rename , ln ,
146 .Ic rm , mkdir , chdir , ls ,
147 .Ic lchdir , chmod , chown ,
148 .Ic chgrp , lpwd , df , symlink ,
149 and
150 .Ic lmkdir .
151 .Pp
152 Termination on error can be suppressed on a command by command basis by
153 prefixing the command with a
154 .Sq \-
155 character (for example,
156 .Ic -rm /tmp/blah* ) .
157 Echo of the command may be suppressed by prefixing the command with a
158 .Sq @
159 character.
160 These two prefixes may be combined in any order, for example
161 .Ic -@ls /bsd .
162 .It Fl C
163 Enables compression (via ssh's
164 .Fl C
165 flag).
166 .It Fl c Ar cipher
167 Selects the cipher to use for encrypting the data transfers.
168 This option is directly passed to
169 .Xr ssh 1 .
170 .It Fl D Ar sftp_server_path
171 Connect directly to a local sftp server
172 (rather than via
173 .Xr ssh 1 ) .
174 This option may be useful in debugging the client and server.
175 .It Fl F Ar ssh_config
176 Specifies an alternative
177 per-user configuration file for
178 .Xr ssh 1 .
179 This option is directly passed to
180 .Xr ssh 1 .
181 .It Fl f
182 Requests that files be flushed to disk immediately after transfer.
183 When uploading files, this feature is only enabled if the server
184 implements the "fsync@openssh.com" extension.
185 .It Fl i Ar identity_file
186 Selects the file from which the identity (private key) for public key
187 authentication is read.
188 This option is directly passed to
189 .Xr ssh 1 .
190 .It Fl J Ar destination
191 Connect to the target host by first making an
192 .Nm
193 connection to the jump host described by
194 .Ar destination
195 and then establishing a TCP forwarding to the ultimate destination from
196 there.
197 Multiple jump hops may be specified separated by comma characters.
198 This is a shortcut to specify a
199 .Cm ProxyJump
200 configuration directive.
201 This option is directly passed to
202 .Xr ssh 1 .
203 .It Fl l Ar limit
204 Limits the used bandwidth, specified in Kbit/s.
205 .It Fl N
206 Disables quiet mode, e.g. to override the implicit quiet mode set by the
207 .Fl b
208 flag.
209 .It Fl o Ar ssh_option
210 Can be used to pass options to
211 .Nm ssh
212 in the format used in
213 .Xr ssh_config 5 .
214 This is useful for specifying options
215 for which there is no separate
216 .Nm sftp
217 command-line flag.
218 For example, to specify an alternate port use:
219 .Ic sftp -oPort=24 .
220 For full details of the options listed below, and their possible values, see
221 .Xr ssh_config 5 .
222 .Pp
223 .Bl -tag -width Ds -offset indent -compact
224 .It AddressFamily
225 .It BatchMode
226 .It BindAddress
227 .It BindInterface
228 .It CanonicalDomains
229 .It CanonicalizeFallbackLocal
230 .It CanonicalizeHostname
231 .It CanonicalizeMaxDots
232 .It CanonicalizePermittedCNAMEs
233 .It CASignatureAlgorithms
234 .It CertificateFile
235 .It CheckHostIP
236 .It Ciphers
237 .It Compression
238 .It ConnectionAttempts
239 .It ConnectTimeout
240 .It ControlMaster
241 .It ControlPath
242 .It ControlPersist
243 .It GlobalKnownHostsFile
244 .It GSSAPIAuthentication
245 .It GSSAPIDelegateCredentials
246 .It HashKnownHosts
247 .It Host
248 .It HostbasedAcceptedAlgorithms
249 .It HostbasedAuthentication
250 .It HostKeyAlgorithms
251 .It HostKeyAlias
252 .It Hostname
253 .It IdentitiesOnly
254 .It IdentityAgent
255 .It IdentityFile
256 .It IPQoS
257 .It KbdInteractiveAuthentication
258 .It KbdInteractiveDevices
259 .It KexAlgorithms
260 .It KnownHostsCommand
261 .It LogLevel
262 .It MACs
263 .It NoHostAuthenticationForLocalhost
264 .It NumberOfPasswordPrompts
265 .It PasswordAuthentication
266 .It PKCS11Provider
267 .It Port
268 .It PreferredAuthentications
269 .It ProxyCommand
270 .It ProxyJump
271 .It PubkeyAcceptedAlgorithms
272 .It PubkeyAuthentication
273 .It RekeyLimit
274 .It SendEnv
275 .It ServerAliveInterval
276 .It ServerAliveCountMax
277 .It SetEnv
278 .It StrictHostKeyChecking
279 .It TCPKeepAlive
280 .It UpdateHostKeys
281 .It User
282 .It UserKnownHostsFile
283 .It VerifyHostKeyDNS
284 .El
285 .It Fl P Ar port
286 Specifies the port to connect to on the remote host.
287 .It Fl p
288 Preserves modification times, access times, and modes from the
289 original files transferred.
290 .It Fl q
291 Quiet mode: disables the progress meter as well as warning and
292 diagnostic messages from
293 .Xr ssh 1 .
294 .It Fl R Ar num_requests
295 Specify how many requests may be outstanding at any one time.
296 Increasing this may slightly improve file transfer speed
297 but will increase memory usage.
298 The default is 64 outstanding requests.
299 .It Fl r
300 Recursively copy entire directories when uploading and downloading.
301 Note that
302 .Nm
303 does not follow symbolic links encountered in the tree traversal.
304 .It Fl S Ar program
305 Name of the
306 .Ar program
307 to use for the encrypted connection.
308 The program must understand
309 .Xr ssh 1
310 options.
311 .It Fl s Ar subsystem | sftp_server
312 Specifies the SSH2 subsystem or the path for an sftp server
313 on the remote host.
314 A path is useful when the remote
315 .Xr sshd 8
316 does not have an sftp subsystem configured.
317 .It Fl v
318 Raise logging level.
319 This option is also passed to ssh.
320 .El
321 .Sh INTERACTIVE COMMANDS
322 Once in interactive mode,
323 .Nm
324 understands a set of commands similar to those of
325 .Xr ftp 1 .
326 Commands are case insensitive.
327 Pathnames that contain spaces must be enclosed in quotes.
328 Any special characters contained within pathnames that are recognized by
329 .Xr glob 3
330 must be escaped with backslashes
331 .Pq Sq \e .
332 .Bl -tag -width Ds
333 .It Ic bye
334 Quit
335 .Nm sftp .
336 .It Ic cd Op Ar path
337 Change remote directory to
338 .Ar path .
339 If
340 .Ar path
341 is not specified, then change directory to the one the session started in.
342 .It Xo Ic chgrp
343 .Op Fl h
344 .Ar grp
345 .Ar path
346 .Xc
347 Change group of file
348 .Ar path
349 to
350 .Ar grp .
351 .Ar path
352 may contain
353 .Xr glob 7
354 characters and may match multiple files.
355 .Ar grp
356 must be a numeric GID.
357 .Pp
358 If the
359 .Fl h
360 flag is specified, then symlinks will not be followed.
361 Note that this is only supported by servers that implement
362 the "lsetstat@openssh.com" extension.
363 .It Xo Ic chmod
364 .Op Fl h
365 .Ar mode
366 .Ar path
367 .Xc
368 Change permissions of file
369 .Ar path
370 to
371 .Ar mode .
372 .Ar path
373 may contain
374 .Xr glob 7
375 characters and may match multiple files.
376 .Pp
377 If the
378 .Fl h
379 flag is specified, then symlinks will not be followed.
380 Note that this is only supported by servers that implement
381 the "lsetstat@openssh.com" extension.
382 .It Xo Ic chown
383 .Op Fl h
384 .Ar own
385 .Ar path
386 .Xc
387 Change owner of file
388 .Ar path
389 to
390 .Ar own .
391 .Ar path
392 may contain
393 .Xr glob 7
394 characters and may match multiple files.
395 .Ar own
396 must be a numeric UID.
397 .Pp
398 If the
399 .Fl h
400 flag is specified, then symlinks will not be followed.
401 Note that this is only supported by servers that implement
402 the "lsetstat@openssh.com" extension.
403 .It Xo Ic df
404 .Op Fl hi
405 .Op Ar path
406 .Xc
407 Display usage information for the filesystem holding the current directory
408 (or
409 .Ar path
410 if specified).
411 If the
412 .Fl h
413 flag is specified, the capacity information will be displayed using
414 "human-readable" suffixes.
415 The
416 .Fl i
417 flag requests display of inode information in addition to capacity information.
418 This command is only supported on servers that implement the
419 .Dq statvfs@openssh.com
420 extension.
421 .It Ic exit
422 Quit
423 .Nm sftp .
424 .It Xo Ic get
425 .Op Fl afpR
426 .Ar remote-path
427 .Op Ar local-path
428 .Xc
429 Retrieve the
430 .Ar remote-path
431 and store it on the local machine.
432 If the local
433 path name is not specified, it is given the same name it has on the
434 remote machine.
435 .Ar remote-path
436 may contain
437 .Xr glob 7
438 characters and may match multiple files.
439 If it does and
440 .Ar local-path
441 is specified, then
442 .Ar local-path
443 must specify a directory.
444 .Pp
445 If the
446 .Fl a
447 flag is specified, then attempt to resume partial transfers of existing files.
448 Note that resumption assumes that any partial copy of the local file matches
449 the remote copy.
450 If the remote file contents differ from the partial local copy then the
451 resultant file is likely to be corrupt.
452 .Pp
453 If the
454 .Fl f
455 flag is specified, then
456 .Xr fsync 2
457 will be called after the file transfer has completed to flush the file
458 to disk.
459 .Pp
460 If the
461 .Fl p
462 .\" undocumented redundant alias
463 .\" or
464 .\" .Fl P
465 flag is specified, then full file permissions and access times are
466 copied too.
467 .Pp
468 If the
469 .Fl R
470 .\" undocumented redundant alias
471 .\" or
472 .\" .Fl r
473 flag is specified then directories will be copied recursively.
474 Note that
475 .Nm
476 does not follow symbolic links when performing recursive transfers.
477 .It Ic help
478 Display help text.
479 .It Ic lcd Op Ar path
480 Change local directory to
481 .Ar path .
482 If
483 .Ar path
484 is not specified, then change directory to the local user's home directory.
485 .It Ic lls Op Ar ls-options Op Ar path
486 Display local directory listing of either
487 .Ar path
488 or current directory if
489 .Ar path
490 is not specified.
491 .Ar ls-options
492 may contain any flags supported by the local system's
493 .Xr ls 1
494 command.
495 .Ar path
496 may contain
497 .Xr glob 7
498 characters and may match multiple files.
499 .It Ic lmkdir Ar path
500 Create local directory specified by
501 .Ar path .
502 .It Xo Ic ln
503 .Op Fl s
504 .Ar oldpath
505 .Ar newpath
506 .Xc
507 Create a link from
508 .Ar oldpath
509 to
510 .Ar newpath .
511 If the
512 .Fl s
513 flag is specified the created link is a symbolic link, otherwise it is
514 a hard link.
515 .It Ic lpwd
516 Print local working directory.
517 .It Xo Ic ls
518 .Op Fl 1afhlnrSt
519 .Op Ar path
520 .Xc
521 Display a remote directory listing of either
522 .Ar path
523 or the current directory if
524 .Ar path
525 is not specified.
526 .Ar path
527 may contain
528 .Xr glob 7
529 characters and may match multiple files.
530 .Pp
531 The following flags are recognized and alter the behaviour of
532 .Ic ls
533 accordingly:
534 .Bl -tag -width Ds
535 .It Fl 1
536 Produce single columnar output.
537 .It Fl a
538 List files beginning with a dot
539 .Pq Sq \&. .
540 .It Fl f
541 Do not sort the listing.
542 The default sort order is lexicographical.
543 .It Fl h
544 When used with a long format option, use unit suffixes: Byte, Kilobyte,
545 Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce
546 the number of digits to four or fewer using powers of 2 for sizes (K=1024,
547 M=1048576, etc.).
548 .It Fl l
549 Display additional details including permissions
550 and ownership information.
551 .It Fl n
552 Produce a long listing with user and group information presented
553 numerically.
554 .It Fl r
555 Reverse the sort order of the listing.
556 .It Fl S
557 Sort the listing by file size.
558 .It Fl t
559 Sort the listing by last modification time.
560 .El
561 .It Ic lumask Ar umask
562 Set local umask to
563 .Ar umask .
564 .It Ic mkdir Ar path
565 Create remote directory specified by
566 .Ar path .
567 .It Ic progress
568 Toggle display of progress meter.
569 .It Xo Ic put
570 .Op Fl afpR
571 .Ar local-path
572 .Op Ar remote-path
573 .Xc
574 Upload
575 .Ar local-path
576 and store it on the remote machine.
577 If the remote path name is not specified, it is given the same name it has
578 on the local machine.
579 .Ar local-path
580 may contain
581 .Xr glob 7
582 characters and may match multiple files.
583 If it does and
584 .Ar remote-path
585 is specified, then
586 .Ar remote-path
587 must specify a directory.
588 .Pp
589 If the
590 .Fl a
591 flag is specified, then attempt to resume partial
592 transfers of existing files.
593 Note that resumption assumes that any partial copy of the remote file
594 matches the local copy.
595 If the local file contents differ from the remote local copy then
596 the resultant file is likely to be corrupt.
597 .Pp
598 If the
599 .Fl f
600 flag is specified, then a request will be sent to the server to call
601 .Xr fsync 2
602 after the file has been transferred.
603 Note that this is only supported by servers that implement
604 the "fsync@openssh.com" extension.
605 .Pp
606 If the
607 .Fl p
608 .\" undocumented redundant alias
609 .\" or
610 .\" .Fl P
611 flag is specified, then full file permissions and access times are
612 copied too.
613 .Pp
614 If the
615 .Fl R
616 .\" undocumented redundant alias
617 .\" or
618 .\" .Fl r
619 flag is specified then directories will be copied recursively.
620 Note that
621 .Nm
622 does not follow symbolic links when performing recursive transfers.
623 .It Ic pwd
624 Display remote working directory.
625 .It Ic quit
626 Quit
627 .Nm sftp .
628 .It Xo Ic reget
629 .Op Fl fpR
630 .Ar remote-path
631 .Op Ar local-path
632 .Xc
633 Resume download of
634 .Ar remote-path .
635 Equivalent to
636 .Ic get
637 with the
638 .Fl a
639 flag set.
640 .It Xo Ic reput
641 .Op Fl fpR
642 .Ar local-path
643 .Op Ar remote-path
644 .Xc
645 Resume upload of
646 .Ar local-path .
647 Equivalent to
648 .Ic put
649 with the
650 .Fl a
651 flag set.
652 .It Ic rename Ar oldpath newpath
653 Rename remote file from
654 .Ar oldpath
655 to
656 .Ar newpath .
657 .It Ic rm Ar path
658 Delete remote file specified by
659 .Ar path .
660 .It Ic rmdir Ar path
661 Remove remote directory specified by
662 .Ar path .
663 .It Ic symlink Ar oldpath newpath
664 Create a symbolic link from
665 .Ar oldpath
666 to
667 .Ar newpath .
668 .It Ic version
669 Display the
670 .Nm
671 protocol version.
672 .It Ic \&! Ns Ar command
673 Execute
674 .Ar command
675 in local shell.
676 .It Ic \&!
677 Escape to local shell.
678 .It Ic \&?
679 Synonym for help.
680 .El
681 .Sh SEE ALSO
682 .Xr ftp 1 ,
683 .Xr ls 1 ,
684 .Xr scp 1 ,
685 .Xr ssh 1 ,
686 .Xr ssh-add 1 ,
687 .Xr ssh-keygen 1 ,
688 .Xr ssh_config 5 ,
689 .Xr glob 7 ,
690 .Xr sftp-server 8 ,
691 .Xr sshd 8
692 .Rs
693 .%A T. Ylonen
694 .%A S. Lehtinen
695 .%T "SSH File Transfer Protocol"
696 .%N draft-ietf-secsh-filexfer-00.txt
697 .%D January 2001
698 .%O work in progress material
699 .Re