xref: /freebsd/crypto/openssh/sftp.1 (revision 13de33a5dc2304b13d595d75d48c51793958474f)
1.\" $OpenBSD: sftp.1,v 1.92 2013/07/25 00:56:51 djm Exp $
2.\" $FreeBSD$
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.\"
26.Dd July 25, 2013
27.Dt SFTP 1
28.Os
29.Sh NAME
30.Nm sftp
31.Nd secure file transfer program
32.Sh SYNOPSIS
33.Nm sftp
34.Bk -words
35.Op Fl 1246Cpqrv
36.Op Fl B Ar buffer_size
37.Op Fl b Ar batchfile
38.Op Fl c Ar cipher
39.Op Fl D Ar sftp_server_path
40.Op Fl F Ar ssh_config
41.Op Fl i Ar identity_file
42.Op Fl l Ar limit
43.Op Fl o Ar ssh_option
44.Op Fl P Ar port
45.Op Fl R Ar num_requests
46.Op Fl S Ar program
47.Op Fl s Ar subsystem | sftp_server
48.Ar host
49.Ek
50.Nm sftp
51.Oo Ar user Ns @ Oc Ns
52.Ar host Ns Op : Ns Ar
53.Nm sftp
54.Oo
55.Ar user Ns @ Oc Ns
56.Ar host Ns Oo : Ns Ar dir Ns
57.Op Ar /
58.Oc
59.Nm sftp
60.Fl b Ar batchfile
61.Oo Ar user Ns @ Oc Ns Ar host
62.Sh DESCRIPTION
63.Nm
64is an interactive file transfer program, similar to
65.Xr ftp 1 ,
66which performs all operations over an encrypted
67.Xr ssh 1
68transport.
69It may also use many features of ssh, such as public key authentication and
70compression.
71.Nm
72connects and logs into the specified
73.Ar host ,
74then enters an interactive command mode.
75.Pp
76The second usage format will retrieve files automatically if a non-interactive
77authentication method is used; otherwise it will do so after
78successful interactive authentication.
79.Pp
80The third usage format allows
81.Nm
82to start in a remote directory.
83.Pp
84The final usage format allows for automated sessions using the
85.Fl b
86option.
87In such cases, it is necessary to configure non-interactive authentication
88to obviate the need to enter a password at connection time (see
89.Xr sshd 8
90and
91.Xr ssh-keygen 1
92for details).
93.Pp
94Since some usage formats use colon characters to delimit host names from path
95names, IPv6 addresses must be enclosed in square brackets to avoid ambiguity.
96.Pp
97The options are as follows:
98.Bl -tag -width Ds
99.It Fl 1
100Specify the use of protocol version 1.
101.It Fl 2
102Specify the use of protocol version 2.
103.It Fl 4
104Forces
105.Nm
106to use IPv4 addresses only.
107.It Fl 6
108Forces
109.Nm
110to use IPv6 addresses only.
111.It Fl B Ar buffer_size
112Specify the size of the buffer that
113.Nm
114uses when transferring files.
115Larger buffers require fewer round trips at the cost of higher
116memory consumption.
117The default is 32768 bytes.
118.It Fl b Ar batchfile
119Batch mode reads a series of commands from an input
120.Ar batchfile
121instead of
122.Em stdin .
123Since it lacks user interaction it should be used in conjunction with
124non-interactive authentication.
125A
126.Ar batchfile
127of
128.Sq \-
129may be used to indicate standard input.
130.Nm
131will abort if any of the following
132commands fail:
133.Ic get , put , reget , rename , ln ,
134.Ic rm , mkdir , chdir , ls ,
135.Ic lchdir , chmod , chown ,
136.Ic chgrp , lpwd , df , symlink ,
137and
138.Ic lmkdir .
139Termination on error can be suppressed on a command by command basis by
140prefixing the command with a
141.Sq \-
142character (for example,
143.Ic -rm /tmp/blah* ) .
144.It Fl C
145Enables compression (via ssh's
146.Fl C
147flag).
148.It Fl c Ar cipher
149Selects the cipher to use for encrypting the data transfers.
150This option is directly passed to
151.Xr ssh 1 .
152.It Fl D Ar sftp_server_path
153Connect directly to a local sftp server
154(rather than via
155.Xr ssh 1 ) .
156This option may be useful in debugging the client and server.
157.It Fl F Ar ssh_config
158Specifies an alternative
159per-user configuration file for
160.Xr ssh 1 .
161This option is directly passed to
162.Xr ssh 1 .
163.It Fl i Ar identity_file
164Selects the file from which the identity (private key) for public key
165authentication is read.
166This option is directly passed to
167.Xr ssh 1 .
168.It Fl l Ar limit
169Limits the used bandwidth, specified in Kbit/s.
170.It Fl o Ar ssh_option
171Can be used to pass options to
172.Nm ssh
173in the format used in
174.Xr ssh_config 5 .
175This is useful for specifying options
176for which there is no separate
177.Nm sftp
178command-line flag.
179For example, to specify an alternate port use:
180.Ic sftp -oPort=24 .
181For full details of the options listed below, and their possible values, see
182.Xr ssh_config 5 .
183.Pp
184.Bl -tag -width Ds -offset indent -compact
185.It AddressFamily
186.It BatchMode
187.It BindAddress
188.It ChallengeResponseAuthentication
189.It CheckHostIP
190.It Cipher
191.It Ciphers
192.It Compression
193.It CompressionLevel
194.It ConnectionAttempts
195.It ConnectTimeout
196.It ControlMaster
197.It ControlPath
198.It ControlPersist
199.It GlobalKnownHostsFile
200.It GSSAPIAuthentication
201.It GSSAPIDelegateCredentials
202.It HashKnownHosts
203.It Host
204.It HostbasedAuthentication
205.It HostKeyAlgorithms
206.It HostKeyAlias
207.It HostName
208.It IdentityFile
209.It IdentitiesOnly
210.It IPQoS
211.It KbdInteractiveAuthentication
212.It KbdInteractiveDevices
213.It KexAlgorithms
214.It LogLevel
215.It MACs
216.It NoHostAuthenticationForLocalhost
217.It NumberOfPasswordPrompts
218.It PasswordAuthentication
219.It PKCS11Provider
220.It Port
221.It PreferredAuthentications
222.It Protocol
223.It ProxyCommand
224.It PubkeyAuthentication
225.It RekeyLimit
226.It RhostsRSAAuthentication
227.It RSAAuthentication
228.It SendEnv
229.It ServerAliveInterval
230.It ServerAliveCountMax
231.It StrictHostKeyChecking
232.It TCPKeepAlive
233.It UsePrivilegedPort
234.It User
235.It UserKnownHostsFile
236.It VerifyHostKeyDNS
237.El
238.It Fl P Ar port
239Specifies the port to connect to on the remote host.
240.It Fl p
241Preserves modification times, access times, and modes from the
242original files transferred.
243.It Fl q
244Quiet mode: disables the progress meter as well as warning and
245diagnostic messages from
246.Xr ssh 1 .
247.It Fl R Ar num_requests
248Specify how many requests may be outstanding at any one time.
249Increasing this may slightly improve file transfer speed
250but will increase memory usage.
251The default is 256 outstanding requests providing for 8MB
252of outstanding data with a 32KB buffer.
253.It Fl r
254Recursively copy entire directories when uploading and downloading.
255Note that
256.Nm
257does not follow symbolic links encountered in the tree traversal.
258.It Fl S Ar program
259Name of the
260.Ar program
261to use for the encrypted connection.
262The program must understand
263.Xr ssh 1
264options.
265.It Fl s Ar subsystem | sftp_server
266Specifies the SSH2 subsystem or the path for an sftp server
267on the remote host.
268A path is useful for using
269.Nm
270over protocol version 1, or when the remote
271.Xr sshd 8
272does not have an sftp subsystem configured.
273.It Fl v
274Raise logging level.
275This option is also passed to ssh.
276.El
277.Sh INTERACTIVE COMMANDS
278Once in interactive mode,
279.Nm
280understands a set of commands similar to those of
281.Xr ftp 1 .
282Commands are case insensitive.
283Pathnames that contain spaces must be enclosed in quotes.
284Any special characters contained within pathnames that are recognized by
285.Xr glob 3
286must be escaped with backslashes
287.Pq Sq \e .
288.Bl -tag -width Ds
289.It Ic bye
290Quit
291.Nm sftp .
292.It Ic cd Ar path
293Change remote directory to
294.Ar path .
295.It Ic chgrp Ar grp Ar path
296Change group of file
297.Ar path
298to
299.Ar grp .
300.Ar path
301may contain
302.Xr glob 3
303characters and may match multiple files.
304.Ar grp
305must be a numeric GID.
306.It Ic chmod Ar mode Ar path
307Change permissions of file
308.Ar path
309to
310.Ar mode .
311.Ar path
312may contain
313.Xr glob 3
314characters and may match multiple files.
315.It Ic chown Ar own Ar path
316Change owner of file
317.Ar path
318to
319.Ar own .
320.Ar path
321may contain
322.Xr glob 3
323characters and may match multiple files.
324.Ar own
325must be a numeric UID.
326.It Xo Ic df
327.Op Fl hi
328.Op Ar path
329.Xc
330Display usage information for the filesystem holding the current directory
331(or
332.Ar path
333if specified).
334If the
335.Fl h
336flag is specified, the capacity information will be displayed using
337"human-readable" suffixes.
338The
339.Fl i
340flag requests display of inode information in addition to capacity information.
341This command is only supported on servers that implement the
342.Dq statvfs@openssh.com
343extension.
344.It Ic exit
345Quit
346.Nm sftp .
347.It Xo Ic get
348.Op Fl aPpr
349.Ar remote-path
350.Op Ar local-path
351.Xc
352Retrieve the
353.Ar remote-path
354and store it on the local machine.
355If the local
356path name is not specified, it is given the same name it has on the
357remote machine.
358.Ar remote-path
359may contain
360.Xr glob 3
361characters and may match multiple files.
362If it does and
363.Ar local-path
364is specified, then
365.Ar local-path
366must specify a directory.
367.Pp
368If the
369.Fl a
370flag is specified, then attempt to resume partial transfers of existing files.
371Note that resumption assumes that any partial copy of the local file matches
372the remote copy.
373If the remote file differs from the partial local copy then the resultant file
374is likely to be corrupt.
375.Pp
376If either the
377.Fl P
378or
379.Fl p
380flag is specified, then full file permissions and access times are
381copied too.
382.Pp
383If the
384.Fl r
385flag is specified then directories will be copied recursively.
386Note that
387.Nm
388does not follow symbolic links when performing recursive transfers.
389.It Ic help
390Display help text.
391.It Ic lcd Ar path
392Change local directory to
393.Ar path .
394.It Ic lls Op Ar ls-options Op Ar path
395Display local directory listing of either
396.Ar path
397or current directory if
398.Ar path
399is not specified.
400.Ar ls-options
401may contain any flags supported by the local system's
402.Xr ls 1
403command.
404.Ar path
405may contain
406.Xr glob 3
407characters and may match multiple files.
408.It Ic lmkdir Ar path
409Create local directory specified by
410.Ar path .
411.It Xo Ic ln
412.Op Fl s
413.Ar oldpath
414.Ar newpath
415.Xc
416Create a link from
417.Ar oldpath
418to
419.Ar newpath .
420If the
421.Fl s
422flag is specified the created link is a symbolic link, otherwise it is
423a hard link.
424.It Ic lpwd
425Print local working directory.
426.It Xo Ic ls
427.Op Fl 1afhlnrSt
428.Op Ar path
429.Xc
430Display a remote directory listing of either
431.Ar path
432or the current directory if
433.Ar path
434is not specified.
435.Ar path
436may contain
437.Xr glob 3
438characters and may match multiple files.
439.Pp
440The following flags are recognized and alter the behaviour of
441.Ic ls
442accordingly:
443.Bl -tag -width Ds
444.It Fl 1
445Produce single columnar output.
446.It Fl a
447List files beginning with a dot
448.Pq Sq \&. .
449.It Fl f
450Do not sort the listing.
451The default sort order is lexicographical.
452.It Fl h
453When used with a long format option, use unit suffixes: Byte, Kilobyte,
454Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce
455the number of digits to four or fewer using powers of 2 for sizes (K=1024,
456M=1048576, etc.).
457.It Fl l
458Display additional details including permissions
459and ownership information.
460.It Fl n
461Produce a long listing with user and group information presented
462numerically.
463.It Fl r
464Reverse the sort order of the listing.
465.It Fl S
466Sort the listing by file size.
467.It Fl t
468Sort the listing by last modification time.
469.El
470.It Ic lumask Ar umask
471Set local umask to
472.Ar umask .
473.It Ic mkdir Ar path
474Create remote directory specified by
475.Ar path .
476.It Ic progress
477Toggle display of progress meter.
478.It Xo Ic put
479.Op Fl Ppr
480.Ar local-path
481.Op Ar remote-path
482.Xc
483Upload
484.Ar local-path
485and store it on the remote machine.
486If the remote path name is not specified, it is given the same name it has
487on the local machine.
488.Ar local-path
489may contain
490.Xr glob 3
491characters and may match multiple files.
492If it does and
493.Ar remote-path
494is specified, then
495.Ar remote-path
496must specify a directory.
497.Pp
498If either the
499.Fl P
500or
501.Fl p
502flag is specified, then full file permissions and access times are
503copied too.
504.Pp
505If the
506.Fl r
507flag is specified then directories will be copied recursively.
508Note that
509.Nm
510does not follow symbolic links when performing recursive transfers.
511.It Ic pwd
512Display remote working directory.
513.It Ic quit
514Quit
515.Nm sftp .
516.It Xo Ic reget
517.Op Fl Ppr
518.Ar remote-path
519.Op Ar local-path
520.Xc
521Resume download of
522.Ar remote-path .
523Equivalent to
524.Ic get
525with the
526.Fl a
527flag set.
528.It Ic rename Ar oldpath Ar newpath
529Rename remote file from
530.Ar oldpath
531to
532.Ar newpath .
533.It Ic rm Ar path
534Delete remote file specified by
535.Ar path .
536.It Ic rmdir Ar path
537Remove remote directory specified by
538.Ar path .
539.It Ic symlink Ar oldpath Ar newpath
540Create a symbolic link from
541.Ar oldpath
542to
543.Ar newpath .
544.It Ic version
545Display the
546.Nm
547protocol version.
548.It Ic \&! Ns Ar command
549Execute
550.Ar command
551in local shell.
552.It Ic \&!
553Escape to local shell.
554.It Ic \&?
555Synonym for help.
556.El
557.Sh SEE ALSO
558.Xr ftp 1 ,
559.Xr ls 1 ,
560.Xr scp 1 ,
561.Xr ssh 1 ,
562.Xr ssh-add 1 ,
563.Xr ssh-keygen 1 ,
564.Xr glob 3 ,
565.Xr ssh_config 5 ,
566.Xr sftp-server 8 ,
567.Xr sshd 8
568.Rs
569.%A T. Ylonen
570.%A S. Lehtinen
571.%T "SSH File Transfer Protocol"
572.%N draft-ietf-secsh-filexfer-00.txt
573.%D January 2001
574.%O work in progress material
575.Re
576