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