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