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