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