crypto/openssh/sftp.1

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