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