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