crypto/openssh/sftp.1

   1 .\" $OpenBSD: sftp.1,v 1.140 2022/03/31 17:27:27 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: March 31 2022 $
  26 .Dt SFTP 1
  27 .Os
  28 .Sh NAME
  29 .Nm sftp
  30 .Nd OpenSSH secure file transfer
  31 .Sh SYNOPSIS
  32 .Nm sftp
  33 .Op Fl 46AaCfNpqrv
  34 .Op Fl B Ar buffer_size
  35 .Op Fl b Ar batchfile
  36 .Op Fl c Ar cipher
  37 .Op Fl D Ar sftp_server_path
  38 .Op Fl F Ar ssh_config
  39 .Op Fl i Ar identity_file
  40 .Op Fl J Ar destination
  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 destination
  48 .Sh DESCRIPTION
  49 .Nm
  50 is a file transfer program, similar to
  51 .Xr ftp 1 ,
  52 which performs all operations over an encrypted
  53 .Xr ssh 1
  54 transport.
  55 It may also use many features of ssh, such as public key authentication and
  56 compression.
  57 .Pp
  58 The
  59 .Ar destination
  60 may be specified either as
  61 .Sm off
  62 .Oo user @ Oc host Op : path
  63 .Sm on
  64 or as a URI in the form
  65 .Sm off
  66 .No sftp:// Oo user @ Oc host Oo : port Oc Op / path .
  67 .Sm on
  68 .Pp
  69 If the
  70 .Ar destination
  71 includes a
  72 .Ar path
  73 and it is not a directory,
  74 .Nm
  75 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 If no
  80 .Ar path
  81 is specified, or if the
  82 .Ar path
  83 is a directory,
  84 .Nm
  85 will log in to the specified
  86 .Ar host
  87 and enter interactive command mode, changing to the remote directory
  88 if one was specified.
  89 An optional trailing slash can be used to force the
  90 .Ar path
  91 to be interpreted as a directory.
  92 .Pp
  93 Since the destination formats use colon characters to delimit host
  94 names from path names or port numbers, IPv6 addresses must be
  95 enclosed in square brackets to avoid ambiguity.
  96 .Pp
  97 The options are as follows:
  98 .Bl -tag -width Ds
  99 .It Fl 4
 100 Forces
 101 .Nm
 102 to use IPv4 addresses only.
 103 .It Fl 6
 104 Forces
 105 .Nm
 106 to use IPv6 addresses only.
 107 .It Fl A
 108 Allows forwarding of
 109 .Xr ssh-agent 1
 110 to the remote system.
 111 The default is not to forward an authentication agent.
 112 .It Fl a
 113 Attempt to continue interrupted transfers rather than overwriting
 114 existing partial or complete copies of files.
 115 If the partial contents differ from those being transferred,
 116 then the resultant file is likely to be corrupt.
 117 .It Fl B Ar buffer_size
 118 Specify the size of the buffer that
 119 .Nm
 120 uses when transferring files.
 121 Larger buffers require fewer round trips at the cost of higher
 122 memory consumption.
 123 The default is 32768 bytes.
 124 .It Fl b Ar batchfile
 125 Batch mode reads a series of commands from an input
 126 .Ar batchfile
 127 instead of
 128 .Em stdin .
 129 Since it lacks user interaction, it should be used in conjunction with
 130 non-interactive authentication to obviate the need to enter a password
 131 at connection time (see
 132 .Xr sshd 8
 133 and
 134 .Xr ssh-keygen 1
 135 for details).
 136 .Pp
 137 A
 138 .Ar batchfile
 139 of
 140 .Sq \-
 141 may be used to indicate standard input.
 142 .Nm
 143 will abort if any of the following
 144 commands fail:
 145 .Ic get , put , reget , reput , rename , ln ,
 146 .Ic rm , mkdir , chdir , ls ,
 147 .Ic lchdir , copy , cp , chmod , chown ,
 148 .Ic chgrp , lpwd , df , symlink ,
 149 and
 150 .Ic lmkdir .
 151 .Pp
 152 Termination on error can be suppressed on a command by command basis by
 153 prefixing the command with a
 154 .Sq \-
 155 character (for example,
 156 .Ic -rm /tmp/blah* ) .
 157 Echo of the command may be suppressed by prefixing the command with a
 158 .Sq @
 159 character.
 160 These two prefixes may be combined in any order, for example
 161 .Ic -@ls /bsd .
 162 .It Fl C
 163 Enables compression (via ssh's
 164 .Fl C
 165 flag).
 166 .It Fl c Ar cipher
 167 Selects the cipher to use for encrypting the data transfers.
 168 This option is directly passed to
 169 .Xr ssh 1 .
 170 .It Fl D Ar sftp_server_path
 171 Connect directly to a local sftp server
 172 (rather than via
 173 .Xr ssh 1 ) .
 174 This option may be useful in debugging the client and server.
 175 .It Fl F Ar ssh_config
 176 Specifies an alternative
 177 per-user configuration file for
 178 .Xr ssh 1 .
 179 This option is directly passed to
 180 .Xr ssh 1 .
 181 .It Fl f
 182 Requests that files be flushed to disk immediately after transfer.
 183 When uploading files, this feature is only enabled if the server
 184 implements the "fsync@openssh.com" extension.
 185 .It Fl i Ar identity_file
 186 Selects the file from which the identity (private key) for public key
 187 authentication is read.
 188 This option is directly passed to
 189 .Xr ssh 1 .
 190 .It Fl J Ar destination
 191 Connect to the target host by first making an
 192 .Nm
 193 connection to the jump host described by
 194 .Ar destination
 195 and then establishing a TCP forwarding to the ultimate destination from
 196 there.
 197 Multiple jump hops may be specified separated by comma characters.
 198 This is a shortcut to specify a
 199 .Cm ProxyJump
 200 configuration directive.
 201 This option is directly passed to
 202 .Xr ssh 1 .
 203 .It Fl l Ar limit
 204 Limits the used bandwidth, specified in Kbit/s.
 205 .It Fl N
 206 Disables quiet mode, e.g. to override the implicit quiet mode set by the
 207 .Fl b
 208 flag.
 209 .It Fl o Ar ssh_option
 210 Can be used to pass options to
 211 .Nm ssh
 212 in the format used in
 213 .Xr ssh_config 5 .
 214 This is useful for specifying options
 215 for which there is no separate
 216 .Nm sftp
 217 command-line flag.
 218 For example, to specify an alternate port use:
 219 .Ic sftp -oPort=24 .
 220 For full details of the options listed below, and their possible values, see
 221 .Xr ssh_config 5 .
 222 .Pp
 223 .Bl -tag -width Ds -offset indent -compact
 224 .It AddressFamily
 225 .It BatchMode
 226 .It BindAddress
 227 .It BindInterface
 228 .It CanonicalDomains
 229 .It CanonicalizeFallbackLocal
 230 .It CanonicalizeHostname
 231 .It CanonicalizeMaxDots
 232 .It CanonicalizePermittedCNAMEs
 233 .It CASignatureAlgorithms
 234 .It CertificateFile
 235 .It CheckHostIP
 236 .It Ciphers
 237 .It Compression
 238 .It ConnectionAttempts
 239 .It ConnectTimeout
 240 .It ControlMaster
 241 .It ControlPath
 242 .It ControlPersist
 243 .It GlobalKnownHostsFile
 244 .It GSSAPIAuthentication
 245 .It GSSAPIDelegateCredentials
 246 .It HashKnownHosts
 247 .It Host
 248 .It HostbasedAcceptedAlgorithms
 249 .It HostbasedAuthentication
 250 .It HostKeyAlgorithms
 251 .It HostKeyAlias
 252 .It Hostname
 253 .It IdentitiesOnly
 254 .It IdentityAgent
 255 .It IdentityFile
 256 .It IPQoS
 257 .It KbdInteractiveAuthentication
 258 .It KbdInteractiveDevices
 259 .It KexAlgorithms
 260 .It KnownHostsCommand
 261 .It LogLevel
 262 .It MACs
 263 .It NoHostAuthenticationForLocalhost
 264 .It NumberOfPasswordPrompts
 265 .It PasswordAuthentication
 266 .It PKCS11Provider
 267 .It Port
 268 .It PreferredAuthentications
 269 .It ProxyCommand
 270 .It ProxyJump
 271 .It PubkeyAcceptedAlgorithms
 272 .It PubkeyAuthentication
 273 .It RekeyLimit
 274 .It SendEnv
 275 .It ServerAliveInterval
 276 .It ServerAliveCountMax
 277 .It SetEnv
 278 .It StrictHostKeyChecking
 279 .It TCPKeepAlive
 280 .It UpdateHostKeys
 281 .It User
 282 .It UserKnownHostsFile
 283 .It VerifyHostKeyDNS
 284 .El
 285 .It Fl P Ar port
 286 Specifies the port to connect to on the remote host.
 287 .It Fl p
 288 Preserves modification times, access times, and modes from the
 289 original files transferred.
 290 .It Fl q
 291 Quiet mode: disables the progress meter as well as warning and
 292 diagnostic messages from
 293 .Xr ssh 1 .
 294 .It Fl R Ar num_requests
 295 Specify how many requests may be outstanding at any one time.
 296 Increasing this may slightly improve file transfer speed
 297 but will increase memory usage.
 298 The default is 64 outstanding requests.
 299 .It Fl r
 300 Recursively copy entire directories when uploading and downloading.
 301 Note that
 302 .Nm
 303 does not follow symbolic links encountered in the tree traversal.
 304 .It Fl S Ar program
 305 Name of the
 306 .Ar program
 307 to use for the encrypted connection.
 308 The program must understand
 309 .Xr ssh 1
 310 options.
 311 .It Fl s Ar subsystem | sftp_server
 312 Specifies the SSH2 subsystem or the path for an sftp server
 313 on the remote host.
 314 A path is useful when the remote
 315 .Xr sshd 8
 316 does not have an sftp subsystem configured.
 317 .It Fl v
 318 Raise logging level.
 319 This option is also passed to ssh.
 320 .El
 321 .Sh INTERACTIVE COMMANDS
 322 Once in interactive mode,
 323 .Nm
 324 understands a set of commands similar to those of
 325 .Xr ftp 1 .
 326 Commands are case insensitive.
 327 Pathnames that contain spaces must be enclosed in quotes.
 328 Any special characters contained within pathnames that are recognized by
 329 .Xr glob 3
 330 must be escaped with backslashes
 331 .Pq Sq \e .
 332 .Bl -tag -width Ds
 333 .It Ic bye
 334 Quit
 335 .Nm sftp .
 336 .It Ic cd Op Ar path
 337 Change remote directory to
 338 .Ar path .
 339 If
 340 .Ar path
 341 is not specified, then change directory to the one the session started in.
 342 .It Xo Ic chgrp
 343 .Op Fl h
 344 .Ar grp
 345 .Ar path
 346 .Xc
 347 Change group of file
 348 .Ar path
 349 to
 350 .Ar grp .
 351 .Ar path
 352 may contain
 353 .Xr glob 7
 354 characters and may match multiple files.
 355 .Ar grp
 356 must be a numeric GID.
 357 .Pp
 358 If the
 359 .Fl h
 360 flag is specified, then symlinks will not be followed.
 361 Note that this is only supported by servers that implement
 362 the "lsetstat@openssh.com" extension.
 363 .It Xo Ic chmod
 364 .Op Fl h
 365 .Ar mode
 366 .Ar path
 367 .Xc
 368 Change permissions of file
 369 .Ar path
 370 to
 371 .Ar mode .
 372 .Ar path
 373 may contain
 374 .Xr glob 7
 375 characters and may match multiple files.
 376 .Pp
 377 If the
 378 .Fl h
 379 flag is specified, then symlinks will not be followed.
 380 Note that this is only supported by servers that implement
 381 the "lsetstat@openssh.com" extension.
 382 .It Xo Ic chown
 383 .Op Fl h
 384 .Ar own
 385 .Ar path
 386 .Xc
 387 Change owner of file
 388 .Ar path
 389 to
 390 .Ar own .
 391 .Ar path
 392 may contain
 393 .Xr glob 7
 394 characters and may match multiple files.
 395 .Ar own
 396 must be a numeric UID.
 397 .Pp
 398 If the
 399 .Fl h
 400 flag is specified, then symlinks will not be followed.
 401 Note that this is only supported by servers that implement
 402 the "lsetstat@openssh.com" extension.
 403 .It Ic copy Ar oldpath Ar newpath
 404 Copy remote file from
 405 .Ar oldpath
 406 to
 407 .Ar newpath .
 408 .Pp
 409 Note that this is only supported by servers that implement the "copy-data"
 410 extension.
 411 .It Ic cp Ar oldpath Ar newpath
 412 Alias to
 413 .Ic copy
 414 command.
 415 .It Xo Ic df
 416 .Op Fl hi
 417 .Op Ar path
 418 .Xc
 419 Display usage information for the filesystem holding the current directory
 420 (or
 421 .Ar path
 422 if specified).
 423 If the
 424 .Fl h
 425 flag is specified, the capacity information will be displayed using
 426 "human-readable" suffixes.
 427 The
 428 .Fl i
 429 flag requests display of inode information in addition to capacity information.
 430 This command is only supported on servers that implement the
 431 .Dq statvfs@openssh.com
 432 extension.
 433 .It Ic exit
 434 Quit
 435 .Nm sftp .
 436 .It Xo Ic get
 437 .Op Fl afpR
 438 .Ar remote-path
 439 .Op Ar local-path
 440 .Xc
 441 Retrieve the
 442 .Ar remote-path
 443 and store it on the local machine.
 444 If the local
 445 path name is not specified, it is given the same name it has on the
 446 remote machine.
 447 .Ar remote-path
 448 may contain
 449 .Xr glob 7
 450 characters and may match multiple files.
 451 If it does and
 452 .Ar local-path
 453 is specified, then
 454 .Ar local-path
 455 must specify a directory.
 456 .Pp
 457 If the
 458 .Fl a
 459 flag is specified, then attempt to resume partial transfers of existing files.
 460 Note that resumption assumes that any partial copy of the local file matches
 461 the remote copy.
 462 If the remote file contents differ from the partial local copy then the
 463 resultant file is likely to be corrupt.
 464 .Pp
 465 If the
 466 .Fl f
 467 flag is specified, then
 468 .Xr fsync 2
 469 will be called after the file transfer has completed to flush the file
 470 to disk.
 471 .Pp
 472 If the
 473 .Fl p
 474 .\" undocumented redundant alias
 475 .\" or
 476 .\" .Fl P
 477 flag is specified, then full file permissions and access times are
 478 copied too.
 479 .Pp
 480 If the
 481 .Fl R
 482 .\" undocumented redundant alias
 483 .\" or
 484 .\" .Fl r
 485 flag is specified then directories will be copied recursively.
 486 Note that
 487 .Nm
 488 does not follow symbolic links when performing recursive transfers.
 489 .It Ic help
 490 Display help text.
 491 .It Ic lcd Op Ar path
 492 Change local directory to
 493 .Ar path .
 494 If
 495 .Ar path
 496 is not specified, then change directory to the local user's home directory.
 497 .It Ic lls Op Ar ls-options Op Ar path
 498 Display local directory listing of either
 499 .Ar path
 500 or current directory if
 501 .Ar path
 502 is not specified.
 503 .Ar ls-options
 504 may contain any flags supported by the local system's
 505 .Xr ls 1
 506 command.
 507 .Ar path
 508 may contain
 509 .Xr glob 7
 510 characters and may match multiple files.
 511 .It Ic lmkdir Ar path
 512 Create local directory specified by
 513 .Ar path .
 514 .It Xo Ic ln
 515 .Op Fl s
 516 .Ar oldpath
 517 .Ar newpath
 518 .Xc
 519 Create a link from
 520 .Ar oldpath
 521 to
 522 .Ar newpath .
 523 If the
 524 .Fl s
 525 flag is specified the created link is a symbolic link, otherwise it is
 526 a hard link.
 527 .It Ic lpwd
 528 Print local working directory.
 529 .It Xo Ic ls
 530 .Op Fl 1afhlnrSt
 531 .Op Ar path
 532 .Xc
 533 Display a remote directory listing of either
 534 .Ar path
 535 or the current directory if
 536 .Ar path
 537 is not specified.
 538 .Ar path
 539 may contain
 540 .Xr glob 7
 541 characters and may match multiple files.
 542 .Pp
 543 The following flags are recognized and alter the behaviour of
 544 .Ic ls
 545 accordingly:
 546 .Bl -tag -width Ds
 547 .It Fl 1
 548 Produce single columnar output.
 549 .It Fl a
 550 List files beginning with a dot
 551 .Pq Sq \&. .
 552 .It Fl f
 553 Do not sort the listing.
 554 The default sort order is lexicographical.
 555 .It Fl h
 556 When used with a long format option, use unit suffixes: Byte, Kilobyte,
 557 Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce
 558 the number of digits to four or fewer using powers of 2 for sizes (K=1024,
 559 M=1048576, etc.).
 560 .It Fl l
 561 Display additional details including permissions
 562 and ownership information.
 563 .It Fl n
 564 Produce a long listing with user and group information presented
 565 numerically.
 566 .It Fl r
 567 Reverse the sort order of the listing.
 568 .It Fl S
 569 Sort the listing by file size.
 570 .It Fl t
 571 Sort the listing by last modification time.
 572 .El
 573 .It Ic lumask Ar umask
 574 Set local umask to
 575 .Ar umask .
 576 .It Ic mkdir Ar path
 577 Create remote directory specified by
 578 .Ar path .
 579 .It Ic progress
 580 Toggle display of progress meter.
 581 .It Xo Ic put
 582 .Op Fl afpR
 583 .Ar local-path
 584 .Op Ar remote-path
 585 .Xc
 586 Upload
 587 .Ar local-path
 588 and store it on the remote machine.
 589 If the remote path name is not specified, it is given the same name it has
 590 on the local machine.
 591 .Ar local-path
 592 may contain
 593 .Xr glob 7
 594 characters and may match multiple files.
 595 If it does and
 596 .Ar remote-path
 597 is specified, then
 598 .Ar remote-path
 599 must specify a directory.
 600 .Pp
 601 If the
 602 .Fl a
 603 flag is specified, then attempt to resume partial
 604 transfers of existing files.
 605 Note that resumption assumes that any partial copy of the remote file
 606 matches the local copy.
 607 If the local file contents differ from the remote local copy then
 608 the resultant file is likely to be corrupt.
 609 .Pp
 610 If the
 611 .Fl f
 612 flag is specified, then a request will be sent to the server to call
 613 .Xr fsync 2
 614 after the file has been transferred.
 615 Note that this is only supported by servers that implement
 616 the "fsync@openssh.com" extension.
 617 .Pp
 618 If the
 619 .Fl p
 620 .\" undocumented redundant alias
 621 .\" or
 622 .\" .Fl P
 623 flag is specified, then full file permissions and access times are
 624 copied too.
 625 .Pp
 626 If the
 627 .Fl R
 628 .\" undocumented redundant alias
 629 .\" or
 630 .\" .Fl r
 631 flag is specified then directories will be copied recursively.
 632 Note that
 633 .Nm
 634 does not follow symbolic links when performing recursive transfers.
 635 .It Ic pwd
 636 Display remote working directory.
 637 .It Ic quit
 638 Quit
 639 .Nm sftp .
 640 .It Xo Ic reget
 641 .Op Fl fpR
 642 .Ar remote-path
 643 .Op Ar local-path
 644 .Xc
 645 Resume download of
 646 .Ar remote-path .
 647 Equivalent to
 648 .Ic get
 649 with the
 650 .Fl a
 651 flag set.
 652 .It Xo Ic reput
 653 .Op Fl fpR
 654 .Ar local-path
 655 .Op Ar remote-path
 656 .Xc
 657 Resume upload of
 658 .Ar local-path .
 659 Equivalent to
 660 .Ic put
 661 with the
 662 .Fl a
 663 flag set.
 664 .It Ic rename Ar oldpath newpath
 665 Rename remote file from
 666 .Ar oldpath
 667 to
 668 .Ar newpath .
 669 .It Ic rm Ar path
 670 Delete remote file specified by
 671 .Ar path .
 672 .It Ic rmdir Ar path
 673 Remove remote directory specified by
 674 .Ar path .
 675 .It Ic symlink Ar oldpath newpath
 676 Create a symbolic link from
 677 .Ar oldpath
 678 to
 679 .Ar newpath .
 680 .It Ic version
 681 Display the
 682 .Nm
 683 protocol version.
 684 .It Ic \&! Ns Ar command
 685 Execute
 686 .Ar command
 687 in local shell.
 688 .It Ic \&!
 689 Escape to local shell.
 690 .It Ic \&?
 691 Synonym for help.
 692 .El
 693 .Sh SEE ALSO
 694 .Xr ftp 1 ,
 695 .Xr ls 1 ,
 696 .Xr scp 1 ,
 697 .Xr ssh 1 ,
 698 .Xr ssh-add 1 ,
 699 .Xr ssh-keygen 1 ,
 700 .Xr ssh_config 5 ,
 701 .Xr glob 7 ,
 702 .Xr sftp-server 8 ,
 703 .Xr sshd 8
 704 .Rs
 705 .%A T. Ylonen
 706 .%A S. Lehtinen
 707 .%T "SSH File Transfer Protocol"
 708 .%N draft-ietf-secsh-filexfer-00.txt
 709 .%D January 2001
 710 .%O work in progress material
 711 .Re