1.\" $OpenBSD: sftp.1,v 1.90 2011/08/07 12:55:30 dtucker 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: August 7 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 GlobalKnownHostsFile 198.It GSSAPIAuthentication 199.It GSSAPIDelegateCredentials 200.It HashKnownHosts 201.It Host 202.It HostbasedAuthentication 203.It HostKeyAlgorithms 204.It HostKeyAlias 205.It HostName 206.It IdentityFile 207.It IdentitiesOnly 208.It IPQoS 209.It KbdInteractiveDevices 210.It KexAlgorithms 211.It LogLevel 212.It MACs 213.It NoHostAuthenticationForLocalhost 214.It NumberOfPasswordPrompts 215.It PasswordAuthentication 216.It PKCS11Provider 217.It Port 218.It PreferredAuthentications 219.It Protocol 220.It ProxyCommand 221.It PubkeyAuthentication 222.It RekeyLimit 223.It RhostsRSAAuthentication 224.It RSAAuthentication 225.It SendEnv 226.It ServerAliveInterval 227.It ServerAliveCountMax 228.It StrictHostKeyChecking 229.It TCPKeepAlive 230.It UsePrivilegedPort 231.It User 232.It UserKnownHostsFile 233.It VerifyHostKeyDNS 234.El 235.It Fl P Ar port 236Specifies the port to connect to on the remote host. 237.It Fl p 238Preserves modification times, access times, and modes from the 239original files transferred. 240.It Fl q 241Quiet mode: disables the progress meter as well as warning and 242diagnostic messages from 243.Xr ssh 1 . 244.It Fl R Ar num_requests 245Specify how many requests may be outstanding at any one time. 246Increasing this may slightly improve file transfer speed 247but will increase memory usage. 248The default is 256 outstanding requests providing for 8MB 249of outstanding data with a 32KB buffer. 250.It Fl r 251Recursively copy entire directories when uploading and downloading. 252Note that 253.Nm 254does not follow symbolic links encountered in the tree traversal. 255.It Fl S Ar program 256Name of the 257.Ar program 258to use for the encrypted connection. 259The program must understand 260.Xr ssh 1 261options. 262.It Fl s Ar subsystem | sftp_server 263Specifies the SSH2 subsystem or the path for an sftp server 264on the remote host. 265A path is useful for using 266.Nm 267over protocol version 1, or when the remote 268.Xr sshd 8 269does not have an sftp subsystem configured. 270.It Fl v 271Raise logging level. 272This option is also passed to ssh. 273.El 274.Sh INTERACTIVE COMMANDS 275Once in interactive mode, 276.Nm 277understands a set of commands similar to those of 278.Xr ftp 1 . 279Commands are case insensitive. 280Pathnames that contain spaces must be enclosed in quotes. 281Any special characters contained within pathnames that are recognized by 282.Xr glob 3 283must be escaped with backslashes 284.Pq Sq \e . 285.Bl -tag -width Ds 286.It Ic bye 287Quit 288.Nm sftp . 289.It Ic cd Ar path 290Change remote directory to 291.Ar path . 292.It Ic chgrp Ar grp Ar path 293Change group of file 294.Ar path 295to 296.Ar grp . 297.Ar path 298may contain 299.Xr glob 3 300characters and may match multiple files. 301.Ar grp 302must be a numeric GID. 303.It Ic chmod Ar mode Ar path 304Change permissions of file 305.Ar path 306to 307.Ar mode . 308.Ar path 309may contain 310.Xr glob 3 311characters and may match multiple files. 312.It Ic chown Ar own Ar path 313Change owner of file 314.Ar path 315to 316.Ar own . 317.Ar path 318may contain 319.Xr glob 3 320characters and may match multiple files. 321.Ar own 322must be a numeric UID. 323.It Xo Ic df 324.Op Fl hi 325.Op Ar path 326.Xc 327Display usage information for the filesystem holding the current directory 328(or 329.Ar path 330if specified). 331If the 332.Fl h 333flag is specified, the capacity information will be displayed using 334"human-readable" suffixes. 335The 336.Fl i 337flag requests display of inode information in addition to capacity information. 338This command is only supported on servers that implement the 339.Dq statvfs@openssh.com 340extension. 341.It Ic exit 342Quit 343.Nm sftp . 344.It Xo Ic get 345.Op Fl Ppr 346.Ar remote-path 347.Op Ar local-path 348.Xc 349Retrieve the 350.Ar remote-path 351and store it on the local machine. 352If the local 353path name is not specified, it is given the same name it has on the 354remote machine. 355.Ar remote-path 356may contain 357.Xr glob 3 358characters and may match multiple files. 359If it does and 360.Ar local-path 361is specified, then 362.Ar local-path 363must specify a directory. 364.Pp 365If either the 366.Fl P 367or 368.Fl p 369flag is specified, then full file permissions and access times are 370copied too. 371.Pp 372If the 373.Fl r 374flag is specified then directories will be copied recursively. 375Note that 376.Nm 377does not follow symbolic links when performing recursive transfers. 378.It Ic help 379Display help text. 380.It Ic lcd Ar path 381Change local directory to 382.Ar path . 383.It Ic lls Op Ar ls-options Op Ar path 384Display local directory listing of either 385.Ar path 386or current directory if 387.Ar path 388is not specified. 389.Ar ls-options 390may contain any flags supported by the local system's 391.Xr ls 1 392command. 393.Ar path 394may contain 395.Xr glob 3 396characters and may match multiple files. 397.It Ic lmkdir Ar path 398Create local directory specified by 399.Ar path . 400.It Xo Ic ln 401.Op Fl s 402.Ar oldpath 403.Ar newpath 404.Xc 405Create a link from 406.Ar oldpath 407to 408.Ar newpath . 409If the 410.Fl s 411flag is specified the created link is a symbolic link, otherwise it is 412a hard link. 413.It Ic lpwd 414Print local working directory. 415.It Xo Ic ls 416.Op Fl 1afhlnrSt 417.Op Ar path 418.Xc 419Display a remote directory listing of either 420.Ar path 421or the current directory if 422.Ar path 423is not specified. 424.Ar path 425may contain 426.Xr glob 3 427characters and may match multiple files. 428.Pp 429The following flags are recognized and alter the behaviour of 430.Ic ls 431accordingly: 432.Bl -tag -width Ds 433.It Fl 1 434Produce single columnar output. 435.It Fl a 436List files beginning with a dot 437.Pq Sq \&. . 438.It Fl f 439Do not sort the listing. 440The default sort order is lexicographical. 441.It Fl h 442When used with a long format option, use unit suffixes: Byte, Kilobyte, 443Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce 444the number of digits to four or fewer using powers of 2 for sizes (K=1024, 445M=1048576, etc.). 446.It Fl l 447Display additional details including permissions 448and ownership information. 449.It Fl n 450Produce a long listing with user and group information presented 451numerically. 452.It Fl r 453Reverse the sort order of the listing. 454.It Fl S 455Sort the listing by file size. 456.It Fl t 457Sort the listing by last modification time. 458.El 459.It Ic lumask Ar umask 460Set local umask to 461.Ar umask . 462.It Ic mkdir Ar path 463Create remote directory specified by 464.Ar path . 465.It Ic progress 466Toggle display of progress meter. 467.It Xo Ic put 468.Op Fl Ppr 469.Ar local-path 470.Op Ar remote-path 471.Xc 472Upload 473.Ar local-path 474and store it on the remote machine. 475If the remote path name is not specified, it is given the same name it has 476on the local machine. 477.Ar local-path 478may contain 479.Xr glob 3 480characters and may match multiple files. 481If it does and 482.Ar remote-path 483is specified, then 484.Ar remote-path 485must specify a directory. 486.Pp 487If either the 488.Fl P 489or 490.Fl p 491flag is specified, then full file permissions and access times are 492copied too. 493.Pp 494If the 495.Fl r 496flag is specified then directories will be copied recursively. 497Note that 498.Nm 499does not follow symbolic links when performing recursive transfers. 500.It Ic pwd 501Display remote working directory. 502.It Ic quit 503Quit 504.Nm sftp . 505.It Ic rename Ar oldpath Ar newpath 506Rename remote file from 507.Ar oldpath 508to 509.Ar newpath . 510.It Ic rm Ar path 511Delete remote file specified by 512.Ar path . 513.It Ic rmdir Ar path 514Remove remote directory specified by 515.Ar path . 516.It Ic symlink Ar oldpath Ar newpath 517Create a symbolic link from 518.Ar oldpath 519to 520.Ar newpath . 521.It Ic version 522Display the 523.Nm 524protocol version. 525.It Ic \&! Ns Ar command 526Execute 527.Ar command 528in local shell. 529.It Ic \&! 530Escape to local shell. 531.It Ic \&? 532Synonym for help. 533.El 534.Sh SEE ALSO 535.Xr ftp 1 , 536.Xr ls 1 , 537.Xr scp 1 , 538.Xr ssh 1 , 539.Xr ssh-add 1 , 540.Xr ssh-keygen 1 , 541.Xr glob 3 , 542.Xr ssh_config 5 , 543.Xr sftp-server 8 , 544.Xr sshd 8 545.Rs 546.%A T. Ylonen 547.%A S. Lehtinen 548.%T "SSH File Transfer Protocol" 549.%N draft-ietf-secsh-filexfer-00.txt 550.%D January 2001 551.%O work in progress material 552.Re 553