crypto/openssh/sftp.1

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