1.\" $NetBSD: sftp.1,v 1.22 2020/05/28 17:05:49 christos Exp $ 2.\" $OpenBSD: sftp.1,v 1.131 2020/04/23 21:28:09 jmc Exp $ 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 April 23 2020 27.Dt SFTP 1 28.Os 29.Sh NAME 30.Nm sftp 31.Nd OpenSSH secure file transfer 32.Sh SYNOPSIS 33.Nm sftp 34.Op Fl 46aCfNpqrv 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 J Ar destination 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 destination 49.Sh DESCRIPTION 50.Nm 51is a file transfer program, similar to 52.Xr ftp 1 , 53which performs all operations over an encrypted 54.Xr ssh 1 55transport. 56It may also use many features of ssh, such as public key authentication and 57compression. 58.Pp 59The 60.Ar destination 61may be specified either as 62.Sm off 63.Oo user @ Oc host Op : path 64.Sm on 65or as a URI in the form 66.Sm off 67.No sftp:// Oo user @ Oc host Oo : port Oc Op / path . 68.Sm on 69.Pp 70If the 71.Ar destination 72includes a 73.Ar path 74and it is not a directory, 75.Nm 76will retrieve files automatically if a non-interactive 77authentication method is used; otherwise it will do so after 78successful interactive authentication. 79.Pp 80If no 81.Ar path 82is specified, or if the 83.Ar path 84is a directory, 85.Nm 86will log in to the specified 87.Ar host 88and enter interactive command mode, changing to the remote directory 89if one was specified. 90An optional trailing slash can be used to force the 91.Ar path 92to be interpreted as a directory. 93.Pp 94Since the destination formats use colon characters to delimit host 95names from path names or port numbers, IPv6 addresses must be 96enclosed in square brackets to avoid ambiguity. 97.Pp 98The options are as follows: 99.Bl -tag -width Ds 100.It Fl 4 101Forces 102.Nm 103to use IPv4 addresses only. 104.It Fl 6 105Forces 106.Nm 107to use IPv6 addresses only. 108.It Fl a 109Attempt to continue interrupted transfers rather than overwriting 110existing partial or complete copies of files. 111If the partial contents differ from those being transferred, 112then the resultant file is likely to be corrupt. 113.It Fl B Ar buffer_size 114Specify the size of the buffer that 115.Nm 116uses when transferring files. 117Larger buffers require fewer round trips at the cost of higher 118memory consumption. 119The default is 32768 bytes. 120.It Fl b Ar batchfile 121Batch mode reads a series of commands from an input 122.Ar batchfile 123instead of 124.Em stdin . 125Since it lacks user interaction it should be used in conjunction with 126non-interactive authentication to obviate the need to enter a password 127at connection time (see 128.Xr sshd 8 129and 130.Xr ssh-keygen 1 131for details). 132.Pp 133A 134.Ar batchfile 135of 136.Sq \- 137may be used to indicate standard input. 138.Nm 139will abort if any of the following 140commands fail: 141.Ic get , put , reget , reput , rename , ln , 142.Ic rm , mkdir , chdir , ls , 143.Ic lchdir , chmod , chown , 144.Ic chgrp , lpwd , df , symlink , 145and 146.Ic lmkdir . 147.Pp 148Termination on error can be suppressed on a command by command basis by 149prefixing the command with a 150.Sq \- 151character (for example, 152.Ic -rm /tmp/blah* ) . 153Echo of the command may be suppressed by prefixing the command with a 154.Sq @ 155character. 156These two prefixes may be combined in any order, for example 157.Ic -@ls /bsd . 158.It Fl C 159Enables compression (via ssh's 160.Fl C 161flag). 162.It Fl c Ar cipher 163Selects the cipher to use for encrypting the data transfers. 164This option is directly passed to 165.Xr ssh 1 . 166.It Fl D Ar sftp_server_path 167Connect directly to a local sftp server 168(rather than via 169.Xr ssh 1 ) . 170This option may be useful in debugging the client and server. 171.It Fl F Ar ssh_config 172Specifies an alternative 173per-user configuration file for 174.Xr ssh 1 . 175This option is directly passed to 176.Xr ssh 1 . 177.It Fl f 178Requests that files be flushed to disk immediately after transfer. 179When uploading files, this feature is only enabled if the server 180implements the "fsync@openssh.com" extension. 181.It Fl i Ar identity_file 182Selects the file from which the identity (private key) for public key 183authentication is read. 184This option is directly passed to 185.Xr ssh 1 . 186.It Fl J Ar destination 187Connect to the target host by first making an 188.Nm 189connection to the jump host described by 190.Ar destination 191and then establishing a TCP forwarding to the ultimate destination from 192there. 193Multiple jump hops may be specified separated by comma characters. 194This is a shortcut to specify a 195.Cm ProxyJump 196configuration directive. 197This option is directly passed to 198.Xr ssh 1 . 199.It Fl l Ar limit 200Limits the used bandwidth, specified in Kbit/s. 201.It Fl N 202Disables quiet mode, e.g. to override the implicit quiet mode set by the 203.Fl b 204flag. 205.It Fl o Ar ssh_option 206Can be used to pass options to 207.Nm ssh 208in the format used in 209.Xr ssh_config 5 . 210This is useful for specifying options 211for which there is no separate 212.Nm sftp 213command-line flag. 214For example, to specify an alternate port use: 215.Ic sftp -oPort=24 . 216For full details of the options listed below, and their possible values, see 217.Xr ssh_config 5 . 218.Pp 219.Bl -tag -width Ds -offset indent -compact 220.It AddressFamily 221.It BatchMode 222.It BindAddress 223.It BindInterface 224.It CanonicalDomains 225.It CanonicalizeFallbackLocal 226.It CanonicalizeHostname 227.It CanonicalizeMaxDots 228.It CanonicalizePermittedCNAMEs 229.It CASignatureAlgorithms 230.It CertificateFile 231.It ChallengeResponseAuthentication 232.It CheckHostIP 233.It Ciphers 234.It Compression 235.It ConnectionAttempts 236.It ConnectTimeout 237.It ControlMaster 238.It ControlPath 239.It ControlPersist 240.It GlobalKnownHostsFile 241.It GSSAPIAuthentication 242.It GSSAPIDelegateCredentials 243.It HashKnownHosts 244.It Host 245.It HostbasedAuthentication 246.It HostbasedKeyTypes 247.It HostKeyAlgorithms 248.It HostKeyAlias 249.It Hostname 250.It IdentitiesOnly 251.It IdentityAgent 252.It IdentityFile 253.It IPQoS 254.It KbdInteractiveAuthentication 255.It KbdInteractiveDevices 256.It KexAlgorithms 257.It LogLevel 258.It MACs 259.It NoHostAuthenticationForLocalhost 260.It NumberOfPasswordPrompts 261.It PasswordAuthentication 262.It PKCS11Provider 263.It Port 264.It PreferredAuthentications 265.It ProxyCommand 266.It ProxyJump 267.It PubkeyAcceptedKeyTypes 268.It PubkeyAuthentication 269.It RekeyLimit 270.It SendEnv 271.It ServerAliveInterval 272.It ServerAliveCountMax 273.It SetEnv 274.It StrictHostKeyChecking 275.It TCPKeepAlive 276.It UpdateHostKeys 277.It User 278.It UserKnownHostsFile 279.It VerifyHostKeyDNS 280.El 281.It Fl P Ar port 282Specifies the port to connect to on the remote host. 283.It Fl p 284Preserves modification times, access times, and modes from the 285original files transferred. 286.It Fl q 287Quiet mode: disables the progress meter as well as warning and 288diagnostic messages from 289.Xr ssh 1 . 290.It Fl R Ar num_requests 291Specify how many requests may be outstanding at any one time. 292Increasing this may slightly improve file transfer speed 293but will increase memory usage. 294The default is 256 outstanding requests providing for 8MB 295of outstanding data with a 32KB buffer. 296.It Fl r 297Recursively copy entire directories when uploading and downloading. 298Note that 299.Nm 300does not follow symbolic links encountered in the tree traversal. 301.It Fl S Ar program 302Name of the 303.Ar program 304to use for the encrypted connection. 305The program must understand 306.Xr ssh 1 307options. 308.It Fl s Ar subsystem | sftp_server 309Specifies the SSH2 subsystem or the path for an sftp server 310on the remote host. 311A path is useful when the remote 312.Xr sshd 8 313does not have an sftp subsystem configured. 314.It Fl v 315Raise logging level. 316This option is also passed to ssh. 317.El 318.Sh INTERACTIVE COMMANDS 319Once in interactive mode, 320.Nm 321understands a set of commands similar to those of 322.Xr ftp 1 . 323Commands are case insensitive. 324Pathnames that contain spaces must be enclosed in quotes. 325Any special characters contained within pathnames that are recognized by 326.Xr glob 3 327must be escaped with backslashes 328.Pq Sq \e . 329.Bl -tag -width Ds 330.It Ic bye 331Quit 332.Nm sftp . 333.It Ic cd Op Ar path 334Change remote directory to 335.Ar path . 336If 337.Ar path 338is not specified, then change directory to the one the session started in. 339.It Xo Ic chgrp 340.Op Fl h 341.Ar grp 342.Ar path 343.Xc 344Change group of file 345.Ar path 346to 347.Ar grp . 348If the 349.Fl h 350flag is specified, then symlinks will not be followed. 351.Ar path 352may contain 353.Xr glob 7 354characters and may match multiple files. 355.Ar grp 356must be a numeric GID. 357.It Xo Ic chmod 358.Op Fl h 359.Ar mode 360.Ar path 361.Xc 362Change permissions of file 363.Ar path 364to 365.Ar mode . 366If the 367.Fl h 368flag is specified, then symlinks will not be followed. 369.Ar path 370may contain 371.Xr glob 7 372characters and may match multiple files. 373.It Xo Ic chown 374.Op Fl h 375.Ar own 376.Ar path 377.Xc 378Change owner of file 379.Ar path 380to 381.Ar own . 382If the 383.Fl h 384flag is specified, then symlinks will not be followed. 385.Ar path 386may contain 387.Xr glob 7 388characters and may match multiple files. 389.Ar own 390must be a numeric UID. 391.It Ic df Oo Fl hi Oc Oo Ar path Oc 392Display usage information for the filesystem holding the current directory 393(or 394.Ar path 395if specified). 396If the 397.Fl h 398flag is specified, the capacity information will be displayed using 399"human-readable" suffixes. 400The 401.Fl i 402flag requests display of inode information in addition to capacity information. 403This command is only supported on servers that implement the 404.Dq statvfs@openssh.com 405extension. 406.It Ic exit 407Quit 408.Nm sftp . 409.It Xo Ic get 410.Op Fl afpR 411.Ar remote-path 412.Op Ar local-path 413.Xc 414Retrieve the 415.Ar remote-file 416and store it on the local machine. 417If the local 418path name is not specified, it is given the same name it has on the 419remote machine. 420.Ar remote-path 421may contain 422.Xr glob 7 423characters and may match multiple files. 424If it does and 425.Ar local-path 426is specified, then 427.Ar local-path 428must specify a directory. 429.Pp 430If the 431.Fl a 432flag is specified, then attempt to resume partial transfers of existing files. 433Note that resumption assumes that any partial copy of the local file matches 434the remote copy. 435If the remote file contents differ from the partial local copy then the 436resultant file is likely to be corrupt. 437.Pp 438If the 439.Fl f 440flag is specified, then 441.Xr fsync 2 442will be called after the file transfer has completed to flush the file 443to disk. 444.Pp 445If the 446.Fl p 447.\" undocumented redundant alias 448.\" or 449.\" .Fl P 450flag is specified, then full file permissions and access times are 451copied too. 452.Pp 453If the 454.Fl R 455.\" undocumented redundant alias 456.\" or 457.\" .Fl r 458flag is specified then directories will be copied recursively. 459Note that 460.Nm 461does not follow symbolic links when performing recursive transfers. 462.It Ic help 463Display help text. 464.It Ic lcd Op Ar path 465Change local directory to 466.Ar path . 467If 468.Ar path 469is not specified, then change directory to the local user's home directory. 470.It Ic lls Op Ar ls-options Op Ar path 471Display local directory listing of either 472.Ar path 473or current directory if 474.Ar path 475is not specified. 476.Ar ls-options 477may contain any flags supported by the local system's 478.Xr ls 1 479command. 480.Ar path 481may contain 482.Xr glob 7 483characters and may match multiple files. 484.It Ic lmkdir Ar path 485Create local directory specified by 486.Ar path . 487.It Xo Ic ln 488.Op Fl s 489.Ar oldpath 490.Ar newpath 491.Xc 492Create a link from 493.Ar oldpath 494to 495.Ar newpath . 496If the 497.Fl s 498flag is specified the created link is a symbolic link, otherwise it is 499a hard link. 500.It Ic lpwd 501Print local working directory. 502.It Ic ls Oo Fl 1afhlnrSt Oc Oo Ar path Oc 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 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 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