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