| blob | 6e025bc99d023e1a815f3fadbbc4a412730fe31c |
1 .\" $OpenBSD: sftp.1,v 1.64 2007/05/31 19:20:16 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: June 5 2007 $
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 1Cv
35 .Op Fl B Ar buffer_size
36 .Op Fl b Ar batchfile
37 .Op Fl F Ar ssh_config
38 .Op Fl o Ar ssh_option
39 .Op Fl P Ar sftp_server_path
40 .Op Fl R Ar num_requests
41 .Op Fl S Ar program
42 .Op Fl s Ar subsystem | sftp_server
43 .Ar host
44 .Ek
45 .Nm sftp
46 .Oo Oo Ar user Ns @ Oc Ns
47 .Ar host Ns Oo : Ns Ar file Oo
48 .Ar file Oc Oc Oc
49 .Nm sftp
50 .Oo Oo Ar user Ns @ Oc Ns
51 .Ar host Ns Oo : Ns Ar dir Ns
52 .Oo Ar / Oc Oc 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 , chgrp , lpwd
116 and
117 .Ic lmkdir .
118 Termination on error can be suppressed on a command by command basis by
119 prefixing the command with a
120 .Sq \-
121 character (for example,
122 .Ic -rm /tmp/blah* ) .
123 .It Fl C
124 Enables compression (via ssh's
125 .Fl C
126 flag).
127 .It Fl F Ar ssh_config
128 Specifies an alternative
129 per-user configuration file for
130 .Xr ssh 1 .
131 This option is directly passed to
132 .Xr ssh 1 .
133 .It Fl o Ar ssh_option
134 Can be used to pass options to
135 .Nm ssh
136 in the format used in
137 .Xr ssh_config 5 .
138 This is useful for specifying options
139 for which there is no separate
140 .Nm sftp
141 command-line flag.
142 For example, to specify an alternate port use:
143 .Ic sftp -oPort=24 .
144 For full details of the options listed below, and their possible values, see
145 .Xr ssh_config 5 .
146 .Pp
147 .Bl -tag -width Ds -offset indent -compact
148 .It AddressFamily
149 .It BatchMode
150 .It BindAddress
151 .It ChallengeResponseAuthentication
152 .It CheckHostIP
153 .It Cipher
154 .It Ciphers
155 .It Compression
156 .It CompressionLevel
157 .It ConnectionAttempts
158 .It ConnectTimeout
159 .It ControlMaster
160 .It ControlPath
161 .It GlobalKnownHostsFile
162 .It GSSAPIAuthentication
163 .It GSSAPIDelegateCredentials
164 .It HashKnownHosts
165 .It Host
166 .It HostbasedAuthentication
167 .It HostKeyAlgorithms
168 .It HostKeyAlias
169 .It HostName
170 .It IdentityFile
171 .It IdentitiesOnly
172 .It KbdInteractiveDevices
173 .It LogLevel
174 .It MACs
175 .It NoHostAuthenticationForLocalhost
176 .It NumberOfPasswordPrompts
177 .It PasswordAuthentication
178 .It Port
179 .It PreferredAuthentications
180 .It Protocol
181 .It ProxyCommand
182 .It PubkeyAuthentication
183 .It RekeyLimit
184 .It RhostsRSAAuthentication
185 .It RSAAuthentication
186 .It SendEnv
187 .It ServerAliveInterval
188 .It ServerAliveCountMax
189 .It SmartcardDevice
190 .It StrictHostKeyChecking
191 .It TCPKeepAlive
192 .It UsePrivilegedPort
193 .It User
194 .It UserKnownHostsFile
195 .It VerifyHostKeyDNS
196 .El
197 .It Fl P Ar sftp_server_path
198 Connect directly to a local sftp server
199 (rather than via
200 .Xr ssh 1 ) .
201 This option may be useful in debugging the client and server.
202 .It Fl R Ar num_requests
203 Specify how many requests may be outstanding at any one time.
204 Increasing this may slightly improve file transfer speed
205 but will increase memory usage.
206 The default is 16 outstanding requests.
207 .It Fl S Ar program
208 Name of the
209 .Ar program
210 to use for the encrypted connection.
211 The program must understand
212 .Xr ssh 1
213 options.
214 .It Fl s Ar subsystem | sftp_server
215 Specifies the SSH2 subsystem or the path for an sftp server
216 on the remote host.
217 A path is useful for using
218 .Nm
219 over protocol version 1, or when the remote
220 .Xr sshd 8
221 does not have an sftp subsystem configured.
222 .It Fl v
223 Raise logging level.
224 This option is also passed to ssh.
225 .El
226 .Sh INTERACTIVE COMMANDS
227 Once in interactive mode,
228 .Nm
229 understands a set of commands similar to those of
230 .Xr ftp 1 .
231 Commands are case insensitive.
232 Pathnames that contain spaces must be enclosed in quotes.
233 Any special characters contained within pathnames that are recognized by
234 .Xr glob 3
235 must be escaped with backslashes
236 .Pq Sq \e .
237 .Bl -tag -width Ds
238 .It Ic bye
239 Quit
240 .Nm sftp .
241 .It Ic cd Ar path
242 Change remote directory to
243 .Ar path .
244 .It Ic chgrp Ar grp Ar path
245 Change group of file
246 .Ar path
247 to
248 .Ar grp .
249 .Ar path
250 may contain
251 .Xr glob 3
252 characters and may match multiple files.
253 .Ar grp
254 must be a numeric GID.
255 .It Ic chmod Ar mode Ar path
256 Change permissions of file
257 .Ar path
258 to
259 .Ar mode .
260 .Ar path
261 may contain
262 .Xr glob 3
263 characters and may match multiple files.
264 .It Ic chown Ar own Ar path
265 Change owner of file
266 .Ar path
267 to
268 .Ar own .
269 .Ar path
270 may contain
271 .Xr glob 3
272 characters and may match multiple files.
273 .Ar own
274 must be a numeric UID.
275 .It Ic exit
276 Quit
277 .Nm sftp .
278 .It Xo Ic get
279 .Op Fl P
280 .Ar remote-path
281 .Op Ar local-path
282 .Xc
283 Retrieve the
284 .Ar remote-path
285 and store it on the local machine.
286 If the local
287 path name is not specified, it is given the same name it has on the
288 remote machine.
289 .Ar remote-path
290 may contain
291 .Xr glob 3
292 characters and may match multiple files.
293 If it does and
294 .Ar local-path
295 is specified, then
296 .Ar local-path
297 must specify a directory.
298 If the
299 .Fl P
300 flag is specified, then full file permissions and access times are
301 copied too.
302 .It Ic help
303 Display help text.
304 .It Ic lcd Ar path
305 Change local directory to
306 .Ar path .
307 .It Ic lls Op Ar ls-options Op Ar path
308 Display local directory listing of either
309 .Ar path
310 or current directory if
311 .Ar path
312 is not specified.
313 .Ar ls-options
314 may contain any flags supported by the local system's
315 .Xr ls 1
316 command.
317 .Ar path
318 may contain
319 .Xr glob 3
320 characters and may match multiple files.
321 .It Ic lmkdir Ar path
322 Create local directory specified by
323 .Ar path .
324 .It Ic ln Ar oldpath Ar newpath
325 Create a symbolic link from
326 .Ar oldpath
327 to
328 .Ar newpath .
329 .It Ic lpwd
330 Print local working directory.
331 .It Xo Ic ls
332 .Op Fl 1aflnrSt
333 .Op Ar path
334 .Xc
335 Display a remote directory listing of either
336 .Ar path
337 or the current directory if
338 .Ar path
339 is not specified.
340 .Ar path
341 may contain
342 .Xr glob 3
343 characters and may match multiple files.
344 .Pp
345 The following flags are recognized and alter the behaviour of
346 .Ic ls
347 accordingly:
348 .Bl -tag -width Ds
349 .It Fl 1
350 Produce single columnar output.
351 .It Fl a
352 List files beginning with a dot
353 .Pq Sq \&. .
354 .It Fl f
355 Do not sort the listing.
356 The default sort order is lexicographical.
357 .It Fl l
358 Display additional details including permissions
359 and ownership information.
360 .It Fl n
361 Produce a long listing with user and group information presented
362 numerically.
363 .It Fl r
364 Reverse the sort order of the listing.
365 .It Fl S
366 Sort the listing by file size.
367 .It Fl t
368 Sort the listing by last modification time.
369 .El
370 .It Ic lumask Ar umask
371 Set local umask to
372 .Ar umask .
373 .It Ic mkdir Ar path
374 Create remote directory specified by
375 .Ar path .
376 .It Ic progress
377 Toggle display of progress meter.
378 .It Xo Ic put
379 .Op Fl P
380 .Ar local-path
381 .Op Ar remote-path
382 .Xc
383 Upload
384 .Ar local-path
385 and store it on the remote machine.
386 If the remote path name is not specified, it is given the same name it has
387 on the local machine.
388 .Ar local-path
389 may contain
390 .Xr glob 3
391 characters and may match multiple files.
392 If it does and
393 .Ar remote-path
394 is specified, then
395 .Ar remote-path
396 must specify a directory.
397 If the
398 .Fl P
399 flag is specified, then the file's full permission and access time are
400 copied too.
401 .It Ic pwd
402 Display remote working directory.
403 .It Ic quit
404 Quit
405 .Nm sftp .
406 .It Ic rename Ar oldpath Ar newpath
407 Rename remote file from
408 .Ar oldpath
409 to
410 .Ar newpath .
411 .It Ic rm Ar path
412 Delete remote file specified by
413 .Ar path .
414 .It Ic rmdir Ar path
415 Remove remote directory specified by
416 .Ar path .
417 .It Ic symlink Ar oldpath Ar newpath
418 Create a symbolic link from
419 .Ar oldpath
420 to
421 .Ar newpath .
422 .It Ic version
423 Display the
424 .Nm
425 protocol version.
426 .It Ic \&! Ar command
427 Execute
428 .Ar command
429 in local shell.
430 .It Ic \&!
431 Escape to local shell.
432 .It Ic \&?
433 Synonym for help.
434 .El
435 .Sh SEE ALSO
436 .Xr ftp 1 ,
437 .Xr ls 1 ,
438 .Xr scp 1 ,
439 .Xr ssh 1 ,
440 .Xr ssh-add 1 ,
441 .Xr ssh-keygen 1 ,
442 .Xr glob 3 ,
443 .Xr ssh_config 5 ,
444 .Xr sftp-server 8 ,
445 .Xr sshd 8
446 .Rs
447 .%A T. Ylonen
448 .%A S. Lehtinen
449 .%T "SSH File Transfer Protocol"
450 .%N draft-ietf-secsh-filexfer-00.txt
451 .%D January 2001
452 .%O work in progress material
453 .Re