1.\" $OpenBSD: sftp.1,v 1.90 2011/08/07 12:55:30 dtucker 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 August 7, 2011 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 , 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 GlobalKnownHostsFile 199.It GSSAPIAuthentication 200.It GSSAPIDelegateCredentials 201.It HashKnownHosts 202.It Host 203.It HostbasedAuthentication 204.It HostKeyAlgorithms 205.It HostKeyAlias 206.It HostName 207.It IdentityFile 208.It IdentitiesOnly 209.It IPQoS 210.It KbdInteractiveDevices 211.It KexAlgorithms 212.It LogLevel 213.It MACs 214.It NoHostAuthenticationForLocalhost 215.It NumberOfPasswordPrompts 216.It PasswordAuthentication 217.It PKCS11Provider 218.It Port 219.It PreferredAuthentications 220.It Protocol 221.It ProxyCommand 222.It PubkeyAuthentication 223.It RekeyLimit 224.It RhostsRSAAuthentication 225.It RSAAuthentication 226.It SendEnv 227.It ServerAliveInterval 228.It ServerAliveCountMax 229.It StrictHostKeyChecking 230.It TCPKeepAlive 231.It UsePrivilegedPort 232.It User 233.It UserKnownHostsFile 234.It VerifyHostKeyDNS 235.El 236.It Fl P Ar port 237Specifies the port to connect to on the remote host. 238.It Fl p 239Preserves modification times, access times, and modes from the 240original files transferred. 241.It Fl q 242Quiet mode: disables the progress meter as well as warning and 243diagnostic messages from 244.Xr ssh 1 . 245.It Fl R Ar num_requests 246Specify how many requests may be outstanding at any one time. 247Increasing this may slightly improve file transfer speed 248but will increase memory usage. 249The default is 256 outstanding requests providing for 8MB 250of outstanding data with a 32KB buffer. 251.It Fl r 252Recursively copy entire directories when uploading and downloading. 253Note that 254.Nm 255does not follow symbolic links encountered in the tree traversal. 256.It Fl S Ar program 257Name of the 258.Ar program 259to use for the encrypted connection. 260The program must understand 261.Xr ssh 1 262options. 263.It Fl s Ar subsystem | sftp_server 264Specifies the SSH2 subsystem or the path for an sftp server 265on the remote host. 266A path is useful for using 267.Nm 268over protocol version 1, or when the remote 269.Xr sshd 8 270does not have an sftp subsystem configured. 271.It Fl v 272Raise logging level. 273This option is also passed to ssh. 274.El 275.Sh INTERACTIVE COMMANDS 276Once in interactive mode, 277.Nm 278understands a set of commands similar to those of 279.Xr ftp 1 . 280Commands are case insensitive. 281Pathnames that contain spaces must be enclosed in quotes. 282Any special characters contained within pathnames that are recognized by 283.Xr glob 3 284must be escaped with backslashes 285.Pq Sq \e . 286.Bl -tag -width Ds 287.It Ic bye 288Quit 289.Nm sftp . 290.It Ic cd Ar path 291Change remote directory to 292.Ar path . 293.It Ic chgrp Ar grp Ar path 294Change group of file 295.Ar path 296to 297.Ar grp . 298.Ar path 299may contain 300.Xr glob 3 301characters and may match multiple files. 302.Ar grp 303must be a numeric GID. 304.It Ic chmod Ar mode Ar path 305Change permissions of file 306.Ar path 307to 308.Ar mode . 309.Ar path 310may contain 311.Xr glob 3 312characters and may match multiple files. 313.It Ic chown Ar own Ar path 314Change owner of file 315.Ar path 316to 317.Ar own . 318.Ar path 319may contain 320.Xr glob 3 321characters and may match multiple files. 322.Ar own 323must be a numeric UID. 324.It Xo Ic df 325.Op Fl hi 326.Op Ar path 327.Xc 328Display usage information for the filesystem holding the current directory 329(or 330.Ar path 331if specified). 332If the 333.Fl h 334flag is specified, the capacity information will be displayed using 335"human-readable" suffixes. 336The 337.Fl i 338flag requests display of inode information in addition to capacity information. 339This command is only supported on servers that implement the 340.Dq statvfs@openssh.com 341extension. 342.It Ic exit 343Quit 344.Nm sftp . 345.It Xo Ic get 346.Op Fl Ppr 347.Ar remote-path 348.Op Ar local-path 349.Xc 350Retrieve the 351.Ar remote-path 352and store it on the local machine. 353If the local 354path name is not specified, it is given the same name it has on the 355remote machine. 356.Ar remote-path 357may contain 358.Xr glob 3 359characters and may match multiple files. 360If it does and 361.Ar local-path 362is specified, then 363.Ar local-path 364must specify a directory. 365.Pp 366If either the 367.Fl P 368or 369.Fl p 370flag is specified, then full file permissions and access times are 371copied too. 372.Pp 373If the 374.Fl r 375flag is specified then directories will be copied recursively. 376Note that 377.Nm 378does not follow symbolic links when performing recursive transfers. 379.It Ic help 380Display help text. 381.It Ic lcd Ar path 382Change local directory to 383.Ar path . 384.It Ic lls Op Ar ls-options Op Ar path 385Display local directory listing of either 386.Ar path 387or current directory if 388.Ar path 389is not specified. 390.Ar ls-options 391may contain any flags supported by the local system's 392.Xr ls 1 393command. 394.Ar path 395may contain 396.Xr glob 3 397characters and may match multiple files. 398.It Ic lmkdir Ar path 399Create local directory specified by 400.Ar path . 401.It Xo Ic ln 402.Op Fl s 403.Ar oldpath 404.Ar newpath 405.Xc 406Create a link from 407.Ar oldpath 408to 409.Ar newpath . 410If the 411.Fl s 412flag is specified the created link is a symbolic link, otherwise it is 413a hard link. 414.It Ic lpwd 415Print local working directory. 416.It Xo Ic ls 417.Op Fl 1afhlnrSt 418.Op Ar path 419.Xc 420Display a remote directory listing of either 421.Ar path 422or the current directory if 423.Ar path 424is not specified. 425.Ar path 426may contain 427.Xr glob 3 428characters and may match multiple files. 429.Pp 430The following flags are recognized and alter the behaviour of 431.Ic ls 432accordingly: 433.Bl -tag -width Ds 434.It Fl 1 435Produce single columnar output. 436.It Fl a 437List files beginning with a dot 438.Pq Sq \&. . 439.It Fl f 440Do not sort the listing. 441The default sort order is lexicographical. 442.It Fl h 443When used with a long format option, use unit suffixes: Byte, Kilobyte, 444Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce 445the number of digits to four or fewer using powers of 2 for sizes (K=1024, 446M=1048576, etc.). 447.It Fl l 448Display additional details including permissions 449and ownership information. 450.It Fl n 451Produce a long listing with user and group information presented 452numerically. 453.It Fl r 454Reverse the sort order of the listing. 455.It Fl S 456Sort the listing by file size. 457.It Fl t 458Sort the listing by last modification time. 459.El 460.It Ic lumask Ar umask 461Set local umask to 462.Ar umask . 463.It Ic mkdir Ar path 464Create remote directory specified by 465.Ar path . 466.It Ic progress 467Toggle display of progress meter. 468.It Xo Ic put 469.Op Fl Ppr 470.Ar local-path 471.Op Ar remote-path 472.Xc 473Upload 474.Ar local-path 475and store it on the remote machine. 476If the remote path name is not specified, it is given the same name it has 477on the local machine. 478.Ar local-path 479may contain 480.Xr glob 3 481characters and may match multiple files. 482If it does and 483.Ar remote-path 484is specified, then 485.Ar remote-path 486must specify a directory. 487.Pp 488If either the 489.Fl P 490or 491.Fl p 492flag is specified, then full file permissions and access times are 493copied too. 494.Pp 495If the 496.Fl r 497flag is specified then directories will be copied recursively. 498Note that 499.Nm 500does not follow symbolic links when performing recursive transfers. 501.It Ic pwd 502Display remote working directory. 503.It Ic quit 504Quit 505.Nm sftp . 506.It Ic rename Ar oldpath Ar newpath 507Rename remote file from 508.Ar oldpath 509to 510.Ar newpath . 511.It Ic rm Ar path 512Delete remote file specified by 513.Ar path . 514.It Ic rmdir Ar path 515Remove remote directory specified by 516.Ar path . 517.It Ic symlink Ar oldpath Ar newpath 518Create a symbolic link from 519.Ar oldpath 520to 521.Ar newpath . 522.It Ic version 523Display the 524.Nm 525protocol version. 526.It Ic \&! Ns Ar command 527Execute 528.Ar command 529in local shell. 530.It Ic \&! 531Escape to local shell. 532.It Ic \&? 533Synonym for help. 534.El 535.Sh SEE ALSO 536.Xr ftp 1 , 537.Xr ls 1 , 538.Xr scp 1 , 539.Xr ssh 1 , 540.Xr ssh-add 1 , 541.Xr ssh-keygen 1 , 542.Xr glob 3 , 543.Xr ssh_config 5 , 544.Xr sftp-server 8 , 545.Xr sshd 8 546.Rs 547.%A T. Ylonen 548.%A S. Lehtinen 549.%T "SSH File Transfer Protocol" 550.%N draft-ietf-secsh-filexfer-00.txt 551.%D January 2001 552.%O work in progress material 553.Re 554