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