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