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