crypto/openssh/sftp.1

   1 .\" $OpenBSD: sftp.1,v 1.69 2008/12/09 15:35:00 sobrado 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: December 9 2008 $
  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 Ar user Ns @ Oc Ns
  47 .Ar host Ns Op : Ns Ar
  48 .Nm sftp
  49 .Oo Ar user Ns @ Oc Ns
  50 .Ar host Ns Oo : Ns Ar dir Ns
  51 .Op Ar / Oc
  52 .Nm sftp
  53 .Fl b Ar batchfile
  54 .Oo Ar user Ns @ Oc Ns Ar host
  55 .Sh DESCRIPTION
  56 .Nm
  57 is an interactive file transfer program, similar to
  58 .Xr ftp 1 ,
  59 which performs all operations over an encrypted
  60 .Xr ssh 1
  61 transport.
  62 It may also use many features of ssh, such as public key authentication and
  63 compression.
  64 .Nm
  65 connects and logs into the specified
  66 .Ar host ,
  67 then enters an interactive command mode.
  68 .Pp
  69 The second usage format will retrieve files automatically if a non-interactive
  70 authentication method is used; otherwise it will do so after
  71 successful interactive authentication.
  72 .Pp
  73 The third usage format allows
  74 .Nm
  75 to start in a remote directory.
  76 .Pp
  77 The final usage format allows for automated sessions using the
  78 .Fl b
  79 option.
  80 In such cases, it is necessary to configure non-interactive authentication
  81 to obviate the need to enter a password at connection time (see
  82 .Xr sshd 8
  83 and
  84 .Xr ssh-keygen 1
  85 for details).
  86 The options are as follows:
  87 .Bl -tag -width Ds
  88 .It Fl 1
  89 Specify the use of protocol version 1.
  90 .It Fl B Ar buffer_size
  91 Specify the size of the buffer that
  92 .Nm
  93 uses when transferring files.
  94 Larger buffers require fewer round trips at the cost of higher
  95 memory consumption.
  96 The default is 32768 bytes.
  97 .It Fl b Ar batchfile
  98 Batch mode reads a series of commands from an input
  99 .Ar batchfile
 100 instead of
 101 .Em stdin .
 102 Since it lacks user interaction it should be used in conjunction with
 103 non-interactive authentication.
 104 A
 105 .Ar batchfile
 106 of
 107 .Sq \-
 108 may be used to indicate standard input.
 109 .Nm
 110 will abort if any of the following
 111 commands fail:
 112 .Ic get , put , rename , ln ,
 113 .Ic rm , mkdir , chdir , ls ,
 114 .Ic lchdir , chmod , chown ,
 115 .Ic chgrp , lpwd , df ,
 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 64 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 Xo Ic df
 276 .Op Fl hi
 277 .Op Ar path
 278 .Xc
 279 Display usage information for the filesystem holding the current directory
 280 (or
 281 .Ar path
 282 if specified).
 283 If the
 284 .Fl h
 285 flag is specified, the capacity information will be displayed using
 286 "human-readable" suffixes.
 287 The
 288 .Fl i
 289 flag requests display of inode information in addition to capacity information.
 290 This command is only supported on servers that implement the
 291 .Dq statvfs@openssh.com
 292 extension.
 293 .It Ic exit
 294 Quit
 295 .Nm sftp .
 296 .It Xo Ic get
 297 .Op Fl P
 298 .Ar remote-path
 299 .Op Ar local-path
 300 .Xc
 301 Retrieve the
 302 .Ar remote-path
 303 and store it on the local machine.
 304 If the local
 305 path name is not specified, it is given the same name it has on the
 306 remote machine.
 307 .Ar remote-path
 308 may contain
 309 .Xr glob 3
 310 characters and may match multiple files.
 311 If it does and
 312 .Ar local-path
 313 is specified, then
 314 .Ar local-path
 315 must specify a directory.
 316 If the
 317 .Fl P
 318 flag is specified, then full file permissions and access times are
 319 copied too.
 320 .It Ic help
 321 Display help text.
 322 .It Ic lcd Ar path
 323 Change local directory to
 324 .Ar path .
 325 .It Ic lls Op Ar ls-options Op Ar path
 326 Display local directory listing of either
 327 .Ar path
 328 or current directory if
 329 .Ar path
 330 is not specified.
 331 .Ar ls-options
 332 may contain any flags supported by the local system's
 333 .Xr ls 1
 334 command.
 335 .Ar path
 336 may contain
 337 .Xr glob 3
 338 characters and may match multiple files.
 339 .It Ic lmkdir Ar path
 340 Create local directory specified by
 341 .Ar path .
 342 .It Ic ln Ar oldpath Ar newpath
 343 Create a symbolic link from
 344 .Ar oldpath
 345 to
 346 .Ar newpath .
 347 .It Ic lpwd
 348 Print local working directory.
 349 .It Xo Ic ls
 350 .Op Fl 1aflnrSt
 351 .Op Ar path
 352 .Xc
 353 Display a remote directory listing of either
 354 .Ar path
 355 or the current directory if
 356 .Ar path
 357 is not specified.
 358 .Ar path
 359 may contain
 360 .Xr glob 3
 361 characters and may match multiple files.
 362 .Pp
 363 The following flags are recognized and alter the behaviour of
 364 .Ic ls
 365 accordingly:
 366 .Bl -tag -width Ds
 367 .It Fl 1
 368 Produce single columnar output.
 369 .It Fl a
 370 List files beginning with a dot
 371 .Pq Sq \&. .
 372 .It Fl f
 373 Do not sort the listing.
 374 The default sort order is lexicographical.
 375 .It Fl l
 376 Display additional details including permissions
 377 and ownership information.
 378 .It Fl n
 379 Produce a long listing with user and group information presented
 380 numerically.
 381 .It Fl r
 382 Reverse the sort order of the listing.
 383 .It Fl S
 384 Sort the listing by file size.
 385 .It Fl t
 386 Sort the listing by last modification time.
 387 .El
 388 .It Ic lumask Ar umask
 389 Set local umask to
 390 .Ar umask .
 391 .It Ic mkdir Ar path
 392 Create remote directory specified by
 393 .Ar path .
 394 .It Ic progress
 395 Toggle display of progress meter.
 396 .It Xo Ic put
 397 .Op Fl P
 398 .Ar local-path
 399 .Op Ar remote-path
 400 .Xc
 401 Upload
 402 .Ar local-path
 403 and store it on the remote machine.
 404 If the remote path name is not specified, it is given the same name it has
 405 on the local machine.
 406 .Ar local-path
 407 may contain
 408 .Xr glob 3
 409 characters and may match multiple files.
 410 If it does and
 411 .Ar remote-path
 412 is specified, then
 413 .Ar remote-path
 414 must specify a directory.
 415 If the
 416 .Fl P
 417 flag is specified, then the file's full permission and access time are
 418 copied too.
 419 .It Ic pwd
 420 Display remote working directory.
 421 .It Ic quit
 422 Quit
 423 .Nm sftp .
 424 .It Ic rename Ar oldpath Ar newpath
 425 Rename remote file from
 426 .Ar oldpath
 427 to
 428 .Ar newpath .
 429 .It Ic rm Ar path
 430 Delete remote file specified by
 431 .Ar path .
 432 .It Ic rmdir Ar path
 433 Remove remote directory specified by
 434 .Ar path .
 435 .It Ic symlink Ar oldpath Ar newpath
 436 Create a symbolic link from
 437 .Ar oldpath
 438 to
 439 .Ar newpath .
 440 .It Ic version
 441 Display the
 442 .Nm
 443 protocol version.
 444 .It Ic \&! Ns Ar command
 445 Execute
 446 .Ar command
 447 in local shell.
 448 .It Ic \&!
 449 Escape to local shell.
 450 .It Ic \&?
 451 Synonym for help.
 452 .El
 453 .Sh SEE ALSO
 454 .Xr ftp 1 ,
 455 .Xr ls 1 ,
 456 .Xr scp 1 ,
 457 .Xr ssh 1 ,
 458 .Xr ssh-add 1 ,
 459 .Xr ssh-keygen 1 ,
 460 .Xr glob 3 ,
 461 .Xr ssh_config 5 ,
 462 .Xr sftp-server 8 ,
 463 .Xr sshd 8
 464 .Rs
 465 .%A T. Ylonen
 466 .%A S. Lehtinen
 467 .%T "SSH File Transfer Protocol"
 468 .%N draft-ietf-secsh-filexfer-00.txt
 469 .%D January 2001
 470 .%O work in progress material
 471 .Re