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