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