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