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