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