Annotation of src/usr.bin/ssh/sftp.1, Revision 1.71
1.71 ! jmc 1: .\" $OpenBSD: sftp.1,v 1.70 2009/08/12 00:13:00 djm Exp $
1.1 djm 2: .\"
1.9 deraadt 3: .\" Copyright (c) 2001 Damien Miller. All rights reserved.
1.1 djm 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: .\"
1.71 ! jmc 25: .Dd $Mdocdate: August 12 2009 $
1.1 djm 26: .Dt SFTP 1
27: .Os
28: .Sh NAME
29: .Nm sftp
1.44 jmc 30: .Nd secure file transfer program
1.1 djm 31: .Sh SYNOPSIS
1.43 jmc 32: .Nm sftp
1.41 jmc 33: .Bk -words
1.70 djm 34: .Op Fl 1246Cqv
1.46 jmc 35: .Op Fl B Ar buffer_size
1.29 markus 36: .Op Fl b Ar batchfile
1.70 djm 37: .Op Fl c Ar cipher
1.46 jmc 38: .Op Fl F Ar ssh_config
1.70 djm 39: .Op Fl i Ar identity_path
1.29 markus 40: .Op Fl o Ar ssh_option
1.46 jmc 41: .Op Fl P Ar sftp_server_path
1.30 djm 42: .Op Fl R Ar num_requests
1.26 stevesk 43: .Op Fl S Ar program
1.46 jmc 44: .Op Fl s Ar subsystem | sftp_server
1.26 stevesk 45: .Ar host
1.41 jmc 46: .Ek
1.43 jmc 47: .Nm sftp
1.68 djm 48: .Oo Ar user Ns @ Oc Ns
49: .Ar host Ns Op : Ns Ar
1.43 jmc 50: .Nm sftp
1.68 djm 51: .Oo Ar user Ns @ Oc Ns
1.41 jmc 52: .Ar host Ns Oo : Ns Ar dir Ns
1.69 sobrado 53: .Op Ar / Oc
1.43 jmc 54: .Nm sftp
1.42 djm 55: .Fl b Ar batchfile
1.45 jmc 56: .Oo Ar user Ns @ Oc Ns Ar host
1.1 djm 57: .Sh DESCRIPTION
58: .Nm
59: is an interactive file transfer program, similar to
60: .Xr ftp 1 ,
61: which performs all operations over an encrypted
62: .Xr ssh 1
63: transport.
64: It may also use many features of ssh, such as public key authentication and
65: compression.
66: .Nm
67: connects and logs into the specified
1.18 stevesk 68: .Ar host ,
1.1 djm 69: then enters an interactive command mode.
1.15 mouring 70: .Pp
1.21 itojun 71: The second usage format will retrieve files automatically if a non-interactive
1.18 stevesk 72: authentication method is used; otherwise it will do so after
73: successful interactive authentication.
1.15 mouring 74: .Pp
1.60 jaredy 75: The third usage format allows
76: .Nm
77: to start in a remote directory.
1.1 djm 78: .Pp
1.44 jmc 79: The final usage format allows for automated sessions using the
1.42 djm 80: .Fl b
1.44 jmc 81: option.
1.62 jmc 82: In such cases, it is necessary to configure non-interactive authentication
1.44 jmc 83: to obviate the need to enter a password at connection time (see
1.42 djm 84: .Xr sshd 8
1.43 jmc 85: and
1.42 djm 86: .Xr ssh-keygen 1
1.44 jmc 87: for details).
1.1 djm 88: The options are as follows:
89: .Bl -tag -width Ds
1.46 jmc 90: .It Fl 1
91: Specify the use of protocol version 1.
1.70 djm 92: .It Fl 2
93: Specify the use of protocol version 2.
94: .It Fl 4
95: Forces
96: .Nm
97: to use IPv4 addresses only.
98: .It Fl 6
99: Forces
100: .Nm
101: to use IPv6 addresses only.
1.46 jmc 102: .It Fl B Ar buffer_size
103: Specify the size of the buffer that
104: .Nm
105: uses when transferring files.
106: Larger buffers require fewer round trips at the cost of higher
107: memory consumption.
108: The default is 32768 bytes.
1.10 deraadt 109: .It Fl b Ar batchfile
110: Batch mode reads a series of commands from an input
1.13 stevesk 111: .Ar batchfile
1.10 deraadt 112: instead of
1.13 stevesk 113: .Em stdin .
114: Since it lacks user interaction it should be used in conjunction with
1.51 jmc 115: non-interactive authentication.
1.50 djm 116: A
1.51 jmc 117: .Ar batchfile
118: of
119: .Sq \-
1.50 djm 120: may be used to indicate standard input.
1.13 stevesk 121: .Nm
1.21 itojun 122: will abort if any of the following
123: commands fail:
1.33 deraadt 124: .Ic get , put , rename , ln ,
1.41 jmc 125: .Ic rm , mkdir , chdir , ls ,
1.66 jmc 126: .Ic lchdir , chmod , chown ,
127: .Ic chgrp , lpwd , df ,
1.10 deraadt 128: and
1.13 stevesk 129: .Ic lmkdir .
1.41 jmc 130: Termination on error can be suppressed on a command by command basis by
131: prefixing the command with a
1.51 jmc 132: .Sq \-
1.44 jmc 133: character (for example,
134: .Ic -rm /tmp/blah* ) .
1.71 ! jmc 135: .It Fl C
! 136: Enables compression (via ssh's
! 137: .Fl C
! 138: flag).
1.70 djm 139: .It Fl c Ar cipher
140: Selects the cipher to use for encrypting the data transfers.
141: This option is directly passed to
142: .Xr ssh 1 .
1.46 jmc 143: .It Fl F Ar ssh_config
144: Specifies an alternative
145: per-user configuration file for
146: .Xr ssh 1 .
147: This option is directly passed to
148: .Xr ssh 1 .
1.70 djm 149: .It Fl i Ar identity_file
150: Selects the file from which the identity (private key) for public key
151: authentication is read.
152: This option is directly passed to
153: .Xr ssh 1 .
1.1 djm 154: .It Fl o Ar ssh_option
1.23 stevesk 155: Can be used to pass options to
156: .Nm ssh
1.35 stevesk 157: in the format used in
158: .Xr ssh_config 5 .
159: This is useful for specifying options
1.23 stevesk 160: for which there is no separate
161: .Nm sftp
1.44 jmc 162: command-line flag.
163: For example, to specify an alternate port use:
1.26 stevesk 164: .Ic sftp -oPort=24 .
1.46 jmc 165: For full details of the options listed below, and their possible values, see
166: .Xr ssh_config 5 .
167: .Pp
168: .Bl -tag -width Ds -offset indent -compact
169: .It AddressFamily
170: .It BatchMode
171: .It BindAddress
172: .It ChallengeResponseAuthentication
173: .It CheckHostIP
174: .It Cipher
175: .It Ciphers
176: .It Compression
177: .It CompressionLevel
178: .It ConnectionAttempts
1.54 dtucker 179: .It ConnectTimeout
1.55 djm 180: .It ControlMaster
181: .It ControlPath
1.46 jmc 182: .It GlobalKnownHostsFile
183: .It GSSAPIAuthentication
184: .It GSSAPIDelegateCredentials
1.61 jmc 185: .It HashKnownHosts
1.46 jmc 186: .It Host
187: .It HostbasedAuthentication
188: .It HostKeyAlgorithms
189: .It HostKeyAlias
190: .It HostName
191: .It IdentityFile
1.52 markus 192: .It IdentitiesOnly
1.58 djm 193: .It KbdInteractiveDevices
1.46 jmc 194: .It LogLevel
195: .It MACs
196: .It NoHostAuthenticationForLocalhost
197: .It NumberOfPasswordPrompts
198: .It PasswordAuthentication
199: .It Port
200: .It PreferredAuthentications
201: .It Protocol
202: .It ProxyCommand
203: .It PubkeyAuthentication
1.63 dtucker 204: .It RekeyLimit
1.46 jmc 205: .It RhostsRSAAuthentication
206: .It RSAAuthentication
1.53 jmc 207: .It SendEnv
1.49 markus 208: .It ServerAliveInterval
209: .It ServerAliveCountMax
1.46 jmc 210: .It SmartcardDevice
211: .It StrictHostKeyChecking
1.48 markus 212: .It TCPKeepAlive
1.46 jmc 213: .It UsePrivilegedPort
214: .It User
215: .It UserKnownHostsFile
216: .It VerifyHostKeyDNS
217: .El
218: .It Fl P Ar sftp_server_path
1.44 jmc 219: Connect directly to a local sftp server
1.29 markus 220: (rather than via
1.59 jmc 221: .Xr ssh 1 ) .
1.29 markus 222: This option may be useful in debugging the client and server.
1.70 djm 223: .It Fl q
224: Quiet mode: disables the progress meter as well as warning and
225: diagnostic messages from
226: .Xr ssh 1 .
1.30 djm 227: .It Fl R Ar num_requests
1.44 jmc 228: Specify how many requests may be outstanding at any one time.
229: Increasing this may slightly improve file transfer speed
230: but will increase memory usage.
1.67 djm 231: The default is 64 outstanding requests.
1.26 stevesk 232: .It Fl S Ar program
233: Name of the
234: .Ar program
235: to use for the encrypted connection.
236: The program must understand
237: .Xr ssh 1
238: options.
1.46 jmc 239: .It Fl s Ar subsystem | sftp_server
240: Specifies the SSH2 subsystem or the path for an sftp server
241: on the remote host.
242: A path is useful for using
243: .Nm
244: over protocol version 1, or when the remote
245: .Xr sshd 8
246: does not have an sftp subsystem configured.
247: .It Fl v
248: Raise logging level.
249: This option is also passed to ssh.
1.1 djm 250: .El
251: .Sh INTERACTIVE COMMANDS
1.2 djm 252: Once in interactive mode,
253: .Nm
1.21 itojun 254: understands a set of commands similar to those of
1.1 djm 255: .Xr ftp 1 .
1.60 jaredy 256: Commands are case insensitive.
257: Pathnames that contain spaces must be enclosed in quotes.
258: Any special characters contained within pathnames that are recognized by
259: .Xr glob 3
260: must be escaped with backslashes
261: .Pq Sq \e .
262: .Bl -tag -width Ds
1.22 markus 263: .It Ic bye
1.44 jmc 264: Quit
265: .Nm sftp .
1.3 deraadt 266: .It Ic cd Ar path
1.21 itojun 267: Change remote directory to
1.3 deraadt 268: .Ar path .
269: .It Ic chgrp Ar grp Ar path
1.21 itojun 270: Change group of file
1.5 stevesk 271: .Ar path
272: to
1.1 djm 273: .Ar grp .
1.60 jaredy 274: .Ar path
275: may contain
276: .Xr glob 3
277: characters and may match multiple files.
1.1 djm 278: .Ar grp
1.5 stevesk 279: must be a numeric GID.
1.3 deraadt 280: .It Ic chmod Ar mode Ar path
1.21 itojun 281: Change permissions of file
1.5 stevesk 282: .Ar path
283: to
1.3 deraadt 284: .Ar mode .
1.60 jaredy 285: .Ar path
286: may contain
287: .Xr glob 3
288: characters and may match multiple files.
1.3 deraadt 289: .It Ic chown Ar own Ar path
1.21 itojun 290: Change owner of file
1.5 stevesk 291: .Ar path
292: to
1.1 djm 293: .Ar own .
1.60 jaredy 294: .Ar path
295: may contain
296: .Xr glob 3
297: characters and may match multiple files.
1.1 djm 298: .Ar own
299: must be a numeric UID.
1.65 djm 300: .It Xo Ic df
301: .Op Fl hi
302: .Op Ar path
303: .Xc
304: Display usage information for the filesystem holding the current directory
305: (or
306: .Ar path
307: if specified).
308: If the
309: .Fl h
310: flag is specified, the capacity information will be displayed using
311: "human-readable" suffixes.
312: The
313: .Fl i
314: flag requests display of inode information in addition to capacity information.
315: This command is only supported on servers that implement the
316: .Dq statvfs@openssh.com
317: extension.
1.11 deraadt 318: .It Ic exit
1.44 jmc 319: Quit
320: .Nm sftp .
1.7 djm 321: .It Xo Ic get
1.60 jaredy 322: .Op Fl P
1.7 djm 323: .Ar remote-path
324: .Op Ar local-path
325: .Xc
1.1 djm 326: Retrieve the
1.5 stevesk 327: .Ar remote-path
1.1 djm 328: and store it on the local machine.
329: If the local
1.21 itojun 330: path name is not specified, it is given the same name it has on the
1.44 jmc 331: remote machine.
1.60 jaredy 332: .Ar remote-path
333: may contain
334: .Xr glob 3
335: characters and may match multiple files.
336: If it does and
337: .Ar local-path
338: is specified, then
339: .Ar local-path
340: must specify a directory.
1.44 jmc 341: If the
1.7 djm 342: .Fl P
1.60 jaredy 343: flag is specified, then full file permissions and access times are
1.7 djm 344: copied too.
1.11 deraadt 345: .It Ic help
346: Display help text.
1.46 jmc 347: .It Ic lcd Ar path
348: Change local directory to
349: .Ar path .
1.3 deraadt 350: .It Ic lls Op Ar ls-options Op Ar path
1.21 itojun 351: Display local directory listing of either
1.1 djm 352: .Ar path
353: or current directory if
354: .Ar path
1.5 stevesk 355: is not specified.
1.60 jaredy 356: .Ar ls-options
357: may contain any flags supported by the local system's
358: .Xr ls 1
359: command.
360: .Ar path
361: may contain
362: .Xr glob 3
363: characters and may match multiple files.
1.3 deraadt 364: .It Ic lmkdir Ar path
1.1 djm 365: Create local directory specified by
1.3 deraadt 366: .Ar path .
1.12 djm 367: .It Ic ln Ar oldpath Ar newpath
1.21 itojun 368: Create a symbolic link from
1.12 djm 369: .Ar oldpath
370: to
371: .Ar newpath .
1.3 deraadt 372: .It Ic lpwd
373: Print local working directory.
1.36 djm 374: .It Xo Ic ls
1.60 jaredy 375: .Op Fl 1aflnrSt
1.36 djm 376: .Op Ar path
377: .Xc
1.60 jaredy 378: Display a remote directory listing of either
1.1 djm 379: .Ar path
1.60 jaredy 380: or the current directory if
1.5 stevesk 381: .Ar path
1.44 jmc 382: is not specified.
1.60 jaredy 383: .Ar path
384: may contain
385: .Xr glob 3
386: characters and may match multiple files.
387: .Pp
388: The following flags are recognized and alter the behaviour of
389: .Ic ls
390: accordingly:
391: .Bl -tag -width Ds
392: .It Fl 1
393: Produce single columnar output.
394: .It Fl a
395: List files beginning with a dot
396: .Pq Sq \&. .
397: .It Fl f
398: Do not sort the listing.
399: The default sort order is lexicographical.
400: .It Fl l
401: Display additional details including permissions
1.36 djm 402: and ownership information.
1.60 jaredy 403: .It Fl n
404: Produce a long listing with user and group information presented
1.56 djm 405: numerically.
1.60 jaredy 406: .It Fl r
407: Reverse the sort order of the listing.
408: .It Fl S
409: Sort the listing by file size.
410: .It Fl t
411: Sort the listing by last modification time.
412: .El
1.3 deraadt 413: .It Ic lumask Ar umask
1.21 itojun 414: Set local umask to
1.3 deraadt 415: .Ar umask .
416: .It Ic mkdir Ar path
1.1 djm 417: Create remote directory specified by
1.3 deraadt 418: .Ar path .
1.40 fgsch 419: .It Ic progress
420: Toggle display of progress meter.
1.7 djm 421: .It Xo Ic put
1.60 jaredy 422: .Op Fl P
1.7 djm 423: .Ar local-path
1.37 djm 424: .Op Ar remote-path
1.7 djm 425: .Xc
1.1 djm 426: Upload
1.5 stevesk 427: .Ar local-path
1.44 jmc 428: and store it on the remote machine.
429: If the remote path name is not specified, it is given the same name it has
430: on the local machine.
1.60 jaredy 431: .Ar local-path
432: may contain
433: .Xr glob 3
434: characters and may match multiple files.
435: If it does and
436: .Ar remote-path
437: is specified, then
438: .Ar remote-path
439: must specify a directory.
1.44 jmc 440: If the
1.7 djm 441: .Fl P
442: flag is specified, then the file's full permission and access time are
443: copied too.
1.3 deraadt 444: .It Ic pwd
445: Display remote working directory.
446: .It Ic quit
1.44 jmc 447: Quit
448: .Nm sftp .
1.3 deraadt 449: .It Ic rename Ar oldpath Ar newpath
1.1 djm 450: Rename remote file from
451: .Ar oldpath
452: to
1.3 deraadt 453: .Ar newpath .
1.46 jmc 454: .It Ic rm Ar path
455: Delete remote file specified by
456: .Ar path .
1.3 deraadt 457: .It Ic rmdir Ar path
1.1 djm 458: Remove remote directory specified by
1.3 deraadt 459: .Ar path .
1.12 djm 460: .It Ic symlink Ar oldpath Ar newpath
1.21 itojun 461: Create a symbolic link from
1.12 djm 462: .Ar oldpath
463: to
464: .Ar newpath .
1.38 fgsch 465: .It Ic version
466: Display the
467: .Nm
468: protocol version.
1.69 sobrado 469: .It Ic \&! Ns Ar command
1.21 itojun 470: Execute
1.1 djm 471: .Ar command
1.3 deraadt 472: in local shell.
1.45 jmc 473: .It Ic \&!
1.3 deraadt 474: Escape to local shell.
1.45 jmc 475: .It Ic \&?
1.5 stevesk 476: Synonym for help.
1.4 itojun 477: .El
1.1 djm 478: .Sh SEE ALSO
1.46 jmc 479: .Xr ftp 1 ,
1.60 jaredy 480: .Xr ls 1 ,
1.17 markus 481: .Xr scp 1 ,
1.1 djm 482: .Xr ssh 1 ,
483: .Xr ssh-add 1 ,
484: .Xr ssh-keygen 1 ,
1.60 jaredy 485: .Xr glob 3 ,
1.35 stevesk 486: .Xr ssh_config 5 ,
1.17 markus 487: .Xr sftp-server 8 ,
488: .Xr sshd 8
489: .Rs
1.20 deraadt 490: .%A T. Ylonen
491: .%A S. Lehtinen
1.17 markus 492: .%T "SSH File Transfer Protocol"
493: .%N draft-ietf-secsh-filexfer-00.txt
494: .%D January 2001
495: .%O work in progress material
496: .Re
![[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 [local] / src / usr.bin / ssh