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