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