1.\" $OpenBSD: sftp.1,v 1.144 2024/12/06 15:12:56 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 6 2024 $ 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 AddKeysToAgent 228.It AddressFamily 229.It BatchMode 230.It BindAddress 231.It BindInterface 232.It CASignatureAlgorithms 233.It CanonicalDomains 234.It CanonicalizeFallbackLocal 235.It CanonicalizeHostname 236.It CanonicalizeMaxDots 237.It CanonicalizePermittedCNAMEs 238.It CertificateFile 239.It ChannelTimeout 240.It CheckHostIP 241.It Ciphers 242.It ClearAllForwardings 243.It Compression 244.It ConnectTimeout 245.It ConnectionAttempts 246.It ControlMaster 247.It ControlPath 248.It ControlPersist 249.It DynamicForward 250.It EnableEscapeCommandline 251.It EnableSSHKeysign 252.It EscapeChar 253.It ExitOnForwardFailure 254.It FingerprintHash 255.It ForkAfterAuthentication 256.It ForwardAgent 257.It ForwardX11 258.It ForwardX11Timeout 259.It ForwardX11Trusted 260.It GSSAPIAuthentication 261.It GSSAPIDelegateCredentials 262.It GatewayPorts 263.It GlobalKnownHostsFile 264.It HashKnownHosts 265.It Host 266.It HostKeyAlgorithms 267.It HostKeyAlias 268.It HostbasedAcceptedAlgorithms 269.It HostbasedAuthentication 270.It Hostname 271.It IPQoS 272.It IdentitiesOnly 273.It IdentityAgent 274.It IdentityFile 275.It IgnoreUnknown 276.It Include 277.It KbdInteractiveAuthentication 278.It KbdInteractiveDevices 279.It KexAlgorithms 280.It KnownHostsCommand 281.It LocalCommand 282.It LocalForward 283.It LogLevel 284.It LogVerbose 285.It MACs 286.It NoHostAuthenticationForLocalhost 287.It NumberOfPasswordPrompts 288.It ObscureKeystrokeTiming 289.It PKCS11Provider 290.It PasswordAuthentication 291.It PermitLocalCommand 292.It PermitRemoteOpen 293.It Port 294.It PreferredAuthentications 295.It ProxyCommand 296.It ProxyJump 297.It ProxyUseFdpass 298.It PubkeyAcceptedAlgorithms 299.It PubkeyAuthentication 300.It RekeyLimit 301.It RemoteCommand 302.It RemoteForward 303.It RequestTTY 304.It RequiredRSASize 305.It RevokedHostKeys 306.It SecurityKeyProvider 307.It SendEnv 308.It ServerAliveCountMax 309.It ServerAliveInterval 310.It SessionType 311.It SetEnv 312.It StdinNull 313.It StreamLocalBindMask 314.It StreamLocalBindUnlink 315.It StrictHostKeyChecking 316.It SyslogFacility 317.It TCPKeepAlive 318.It Tag 319.It Tunnel 320.It TunnelDevice 321.It UpdateHostKeys 322.It User 323.It UserKnownHostsFile 324.It VerifyHostKeyDNS 325.It VisualHostKey 326.It XAuthLocation 327.El 328.It Fl P Ar port 329Specifies the port to connect to on the remote host. 330.It Fl p 331Preserves modification times, access times, and modes from the 332original files transferred. 333.It Fl q 334Quiet mode: disables the progress meter as well as warning and 335diagnostic messages from 336.Xr ssh 1 . 337.It Fl R Ar num_requests 338Specify how many requests may be outstanding at any one time. 339Increasing this may slightly improve file transfer speed 340but will increase memory usage. 341The default is 64 outstanding requests. 342.It Fl r 343Recursively copy entire directories when uploading and downloading. 344Note that 345.Nm 346does not follow symbolic links encountered in the tree traversal. 347.It Fl S Ar program 348Name of the 349.Ar program 350to use for the encrypted connection. 351The program must understand 352.Xr ssh 1 353options. 354.It Fl s Ar subsystem | sftp_server 355Specifies the SSH2 subsystem or the path for an sftp server 356on the remote host. 357A path is useful when the remote 358.Xr sshd 8 359does not have an sftp subsystem configured. 360.It Fl v 361Raise logging level. 362This option is also passed to ssh. 363.It Fl X Ar sftp_option 364Specify an option that controls aspects of SFTP protocol behaviour. 365The valid options are: 366.Bl -tag -width Ds 367.It Cm nrequests Ns = Ns Ar value 368Controls how many concurrent SFTP read or write requests may be in progress 369at any point in time during a download or upload. 370By default 64 requests may be active concurrently. 371.It Cm buffer Ns = Ns Ar value 372Controls the maximum buffer size for a single SFTP read/write operation used 373during download or upload. 374By default a 32KB buffer is used. 375.El 376.El 377.Sh INTERACTIVE COMMANDS 378Once in interactive mode, 379.Nm 380understands a set of commands similar to those of 381.Xr ftp 1 . 382Commands are case insensitive. 383Pathnames that contain spaces must be enclosed in quotes. 384Any special characters contained within pathnames that are recognized by 385.Xr glob 3 386must be escaped with backslashes 387.Pq Sq \e . 388.Bl -tag -width Ds 389.It Ic bye 390Quit 391.Nm sftp . 392.It Ic cd Op Ar path 393Change remote directory to 394.Ar path . 395If 396.Ar path 397is not specified, then change directory to the one the session started in. 398.It Xo Ic chgrp 399.Op Fl h 400.Ar grp 401.Ar path 402.Xc 403Change group of file 404.Ar path 405to 406.Ar grp . 407.Ar path 408may contain 409.Xr glob 7 410characters and may match multiple files. 411.Ar grp 412must be a numeric GID. 413.Pp 414If the 415.Fl h 416flag is specified, then symlinks will not be followed. 417Note that this is only supported by servers that implement 418the "lsetstat@openssh.com" extension. 419.It Xo Ic chmod 420.Op Fl h 421.Ar mode 422.Ar path 423.Xc 424Change permissions of file 425.Ar path 426to 427.Ar mode . 428.Ar path 429may contain 430.Xr glob 7 431characters and may match multiple files. 432.Pp 433If the 434.Fl h 435flag is specified, then symlinks will not be followed. 436Note that this is only supported by servers that implement 437the "lsetstat@openssh.com" extension. 438.It Xo Ic chown 439.Op Fl h 440.Ar own 441.Ar path 442.Xc 443Change owner of file 444.Ar path 445to 446.Ar own . 447.Ar path 448may contain 449.Xr glob 7 450characters and may match multiple files. 451.Ar own 452must be a numeric UID. 453.Pp 454If the 455.Fl h 456flag is specified, then symlinks will not be followed. 457Note that this is only supported by servers that implement 458the "lsetstat@openssh.com" extension. 459.It Ic copy Ar oldpath Ar newpath 460Copy remote file from 461.Ar oldpath 462to 463.Ar newpath . 464.Pp 465Note that this is only supported by servers that implement the "copy-data" 466extension. 467.It Ic cp Ar oldpath Ar newpath 468Alias to 469.Ic copy 470command. 471.It Xo Ic df 472.Op Fl hi 473.Op Ar path 474.Xc 475Display usage information for the filesystem holding the current directory 476(or 477.Ar path 478if specified). 479If the 480.Fl h 481flag is specified, the capacity information will be displayed using 482"human-readable" suffixes. 483The 484.Fl i 485flag requests display of inode information in addition to capacity information. 486This command is only supported on servers that implement the 487.Dq statvfs@openssh.com 488extension. 489.It Ic exit 490Quit 491.Nm sftp . 492.It Xo Ic get 493.Op Fl afpR 494.Ar remote-path 495.Op Ar local-path 496.Xc 497Retrieve the 498.Ar remote-path 499and store it on the local machine. 500If the local 501path name is not specified, it is given the same name it has on the 502remote machine. 503.Ar remote-path 504may contain 505.Xr glob 7 506characters and may match multiple files. 507If it does and 508.Ar local-path 509is specified, then 510.Ar local-path 511must specify a directory. 512.Pp 513If the 514.Fl a 515flag is specified, then attempt to resume partial transfers of existing files. 516Note that resumption assumes that any partial copy of the local file matches 517the remote copy. 518If the remote file contents differ from the partial local copy then the 519resultant file is likely to be corrupt. 520.Pp 521If the 522.Fl f 523flag is specified, then 524.Xr fsync 2 525will be called after the file transfer has completed to flush the file 526to disk. 527.Pp 528If the 529.Fl p 530.\" undocumented redundant alias 531.\" or 532.\" .Fl P 533flag is specified, then full file permissions and access times are 534copied too. 535.Pp 536If the 537.Fl R 538.\" undocumented redundant alias 539.\" or 540.\" .Fl r 541flag is specified then directories will be copied recursively. 542Note that 543.Nm 544does not follow symbolic links when performing recursive transfers. 545.It Ic help 546Display help text. 547.It Ic lcd Op Ar path 548Change local directory to 549.Ar path . 550If 551.Ar path 552is not specified, then change directory to the local user's home directory. 553.It Ic lls Op Ar ls-options Op Ar path 554Display local directory listing of either 555.Ar path 556or current directory if 557.Ar path 558is not specified. 559.Ar ls-options 560may contain any flags supported by the local system's 561.Xr ls 1 562command. 563.Ar path 564may contain 565.Xr glob 7 566characters and may match multiple files. 567.It Ic lmkdir Ar path 568Create local directory specified by 569.Ar path . 570.It Xo Ic ln 571.Op Fl s 572.Ar oldpath 573.Ar newpath 574.Xc 575Create a link from 576.Ar oldpath 577to 578.Ar newpath . 579If the 580.Fl s 581flag is specified the created link is a symbolic link, otherwise it is 582a hard link. 583.It Ic lpwd 584Print local working directory. 585.It Xo Ic ls 586.Op Fl 1afhlnrSt 587.Op Ar path 588.Xc 589Display a remote directory listing of either 590.Ar path 591or the current directory if 592.Ar path 593is not specified. 594.Ar path 595may contain 596.Xr glob 7 597characters and may match multiple files. 598.Pp 599The following flags are recognized and alter the behaviour of 600.Ic ls 601accordingly: 602.Bl -tag -width Ds 603.It Fl 1 604Produce single columnar output. 605.It Fl a 606List files beginning with a dot 607.Pq Sq \&. . 608.It Fl f 609Do not sort the listing. 610The default sort order is lexicographical. 611.It Fl h 612When used with a long format option, use unit suffixes: Byte, Kilobyte, 613Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce 614the number of digits to four or fewer using powers of 2 for sizes (K=1024, 615M=1048576, etc.). 616.It Fl l 617Display additional details including permissions 618and ownership information. 619.It Fl n 620Produce a long listing with user and group information presented 621numerically. 622.It Fl r 623Reverse the sort order of the listing. 624.It Fl S 625Sort the listing by file size. 626.It Fl t 627Sort the listing by last modification time. 628.El 629.It Ic lumask Ar umask 630Set local umask to 631.Ar umask . 632.It Ic mkdir Ar path 633Create remote directory specified by 634.Ar path . 635.It Ic progress 636Toggle display of progress meter. 637.It Xo Ic put 638.Op Fl afpR 639.Ar local-path 640.Op Ar remote-path 641.Xc 642Upload 643.Ar local-path 644and store it on the remote machine. 645If the remote path name is not specified, it is given the same name it has 646on the local machine. 647.Ar local-path 648may contain 649.Xr glob 7 650characters and may match multiple files. 651If it does and 652.Ar remote-path 653is specified, then 654.Ar remote-path 655must specify a directory. 656.Pp 657If the 658.Fl a 659flag is specified, then attempt to resume partial 660transfers of existing files. 661Note that resumption assumes that any partial copy of the remote file 662matches the local copy. 663If the local file contents differ from the remote local copy then 664the resultant file is likely to be corrupt. 665.Pp 666If the 667.Fl f 668flag is specified, then a request will be sent to the server to call 669.Xr fsync 2 670after the file has been transferred. 671Note that this is only supported by servers that implement 672the "fsync@openssh.com" extension. 673.Pp 674If the 675.Fl p 676.\" undocumented redundant alias 677.\" or 678.\" .Fl P 679flag is specified, then full file permissions and access times are 680copied too. 681.Pp 682If the 683.Fl R 684.\" undocumented redundant alias 685.\" or 686.\" .Fl r 687flag is specified then directories will be copied recursively. 688Note that 689.Nm 690does not follow symbolic links when performing recursive transfers. 691.It Ic pwd 692Display remote working directory. 693.It Ic quit 694Quit 695.Nm sftp . 696.It Xo Ic reget 697.Op Fl fpR 698.Ar remote-path 699.Op Ar local-path 700.Xc 701Resume download of 702.Ar remote-path . 703Equivalent to 704.Ic get 705with the 706.Fl a 707flag set. 708.It Xo Ic reput 709.Op Fl fpR 710.Ar local-path 711.Op Ar remote-path 712.Xc 713Resume upload of 714.Ar local-path . 715Equivalent to 716.Ic put 717with the 718.Fl a 719flag set. 720.It Ic rename Ar oldpath newpath 721Rename remote file from 722.Ar oldpath 723to 724.Ar newpath . 725.It Ic rm Ar path 726Delete remote file specified by 727.Ar path . 728.It Ic rmdir Ar path 729Remove remote directory specified by 730.Ar path . 731.It Ic symlink Ar oldpath newpath 732Create a symbolic link from 733.Ar oldpath 734to 735.Ar newpath . 736.It Ic version 737Display the 738.Nm 739protocol version. 740.It Ic \&! Ns Ar command 741Execute 742.Ar command 743in local shell. 744.It Ic \&! 745Escape to local shell. 746.It Ic \&? 747Synonym for help. 748.El 749.Sh SEE ALSO 750.Xr ftp 1 , 751.Xr ls 1 , 752.Xr scp 1 , 753.Xr ssh 1 , 754.Xr ssh-add 1 , 755.Xr ssh-keygen 1 , 756.Xr ssh_config 5 , 757.Xr glob 7 , 758.Xr sftp-server 8 , 759.Xr sshd 8 760.Rs 761.%A T. Ylonen 762.%A S. Lehtinen 763.%T "SSH File Transfer Protocol" 764.%N draft-ietf-secsh-filexfer-00.txt 765.%D January 2001 766.%O work in progress material 767.Re 768