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