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