1.\" $OpenBSD: sftp.1,v 1.52 2004/03/05 10:53:58 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 February 4, 2001 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 the sftp client to start in a remote directory. 75.Pp 76The final usage format allows for automated sessions using the 77.Fl b 78option. 79In such cases, it is usually necessary to configure public key authentication 80to obviate the need to enter a password at connection time (see 81.Xr sshd 8 82and 83.Xr ssh-keygen 1 84for details). 85The options are as follows: 86.Bl -tag -width Ds 87.It Fl 1 88Specify the use of protocol version 1. 89.It Fl B Ar buffer_size 90Specify the size of the buffer that 91.Nm 92uses when transferring files. 93Larger buffers require fewer round trips at the cost of higher 94memory consumption. 95The default is 32768 bytes. 96.It Fl b Ar batchfile 97Batch mode reads a series of commands from an input 98.Ar batchfile 99instead of 100.Em stdin . 101Since it lacks user interaction it should be used in conjunction with 102non-interactive authentication. 103A 104.Ar batchfile 105of 106.Sq \- 107may be used to indicate standard input. 108.Nm 109will abort if any of the following 110commands fail: 111.Ic get , put , rename , ln , 112.Ic rm , mkdir , chdir , ls , 113.Ic lchdir , chmod , chown , chgrp , lpwd 114and 115.Ic lmkdir . 116Termination on error can be suppressed on a command by command basis by 117prefixing the command with a 118.Sq \- 119character (for example, 120.Ic -rm /tmp/blah* ) . 121.It Fl C 122Enables compression (via ssh's 123.Fl C 124flag). 125.It Fl F Ar ssh_config 126Specifies an alternative 127per-user configuration file for 128.Xr ssh 1 . 129This option is directly passed to 130.Xr ssh 1 . 131.It Fl o Ar ssh_option 132Can be used to pass options to 133.Nm ssh 134in the format used in 135.Xr ssh_config 5 . 136This is useful for specifying options 137for which there is no separate 138.Nm sftp 139command-line flag. 140For example, to specify an alternate port use: 141.Ic sftp -oPort=24 . 142For full details of the options listed below, and their possible values, see 143.Xr ssh_config 5 . 144.Pp 145.Bl -tag -width Ds -offset indent -compact 146.It AddressFamily 147.It BatchMode 148.It BindAddress 149.It ChallengeResponseAuthentication 150.It CheckHostIP 151.It Cipher 152.It Ciphers 153.It Compression 154.It CompressionLevel 155.It ConnectionAttempts 156.It ConnectionTimeout 157.It GlobalKnownHostsFile 158.It GSSAPIAuthentication 159.It GSSAPIDelegateCredentials 160.It Host 161.It HostbasedAuthentication 162.It HostKeyAlgorithms 163.It HostKeyAlias 164.It HostName 165.It IdentityFile 166.It IdentitiesOnly 167.It LogLevel 168.It MACs 169.It NoHostAuthenticationForLocalhost 170.It NumberOfPasswordPrompts 171.It PasswordAuthentication 172.It Port 173.It PreferredAuthentications 174.It Protocol 175.It ProxyCommand 176.It PubkeyAuthentication 177.It RhostsRSAAuthentication 178.It RSAAuthentication 179.It ServerAliveInterval 180.It ServerAliveCountMax 181.It SmartcardDevice 182.It StrictHostKeyChecking 183.It TCPKeepAlive 184.It UsePrivilegedPort 185.It User 186.It UserKnownHostsFile 187.It VerifyHostKeyDNS 188.El 189.It Fl P Ar sftp_server_path 190Connect directly to a local sftp server 191(rather than via 192.Xr ssh 1 ) 193This option may be useful in debugging the client and server. 194.It Fl R Ar num_requests 195Specify how many requests may be outstanding at any one time. 196Increasing this may slightly improve file transfer speed 197but will increase memory usage. 198The default is 16 outstanding requests. 199.It Fl S Ar program 200Name of the 201.Ar program 202to use for the encrypted connection. 203The program must understand 204.Xr ssh 1 205options. 206.It Fl s Ar subsystem | sftp_server 207Specifies the SSH2 subsystem or the path for an sftp server 208on the remote host. 209A path is useful for using 210.Nm 211over protocol version 1, or when the remote 212.Xr sshd 8 213does not have an sftp subsystem configured. 214.It Fl v 215Raise logging level. 216This option is also passed to ssh. 217.El 218.Sh INTERACTIVE COMMANDS 219Once in interactive mode, 220.Nm 221understands a set of commands similar to those of 222.Xr ftp 1 . 223Commands are case insensitive and pathnames may be enclosed in quotes if they 224contain spaces. 225.Bl -tag -width "lmdir path" 226.It Ic bye 227Quit 228.Nm sftp . 229.It Ic cd Ar path 230Change remote directory to 231.Ar path . 232.It Ic chgrp Ar grp Ar path 233Change group of file 234.Ar path 235to 236.Ar grp . 237.Ar grp 238must be a numeric GID. 239.It Ic chmod Ar mode Ar path 240Change permissions of file 241.Ar path 242to 243.Ar mode . 244.It Ic chown Ar own Ar path 245Change owner of file 246.Ar path 247to 248.Ar own . 249.Ar own 250must be a numeric UID. 251.It Ic exit 252Quit 253.Nm sftp . 254.It Xo Ic get 255.Op Ar flags 256.Ar remote-path 257.Op Ar local-path 258.Xc 259Retrieve the 260.Ar remote-path 261and store it on the local machine. 262If the local 263path name is not specified, it is given the same name it has on the 264remote machine. 265If the 266.Fl P 267flag is specified, then the file's full permission and access time are 268copied too. 269.It Ic help 270Display help text. 271.It Ic lcd Ar path 272Change local directory to 273.Ar path . 274.It Ic lls Op Ar ls-options Op Ar path 275Display local directory listing of either 276.Ar path 277or current directory if 278.Ar path 279is not specified. 280.It Ic lmkdir Ar path 281Create local directory specified by 282.Ar path . 283.It Ic ln Ar oldpath Ar newpath 284Create a symbolic link from 285.Ar oldpath 286to 287.Ar newpath . 288.It Ic lpwd 289Print local working directory. 290.It Xo Ic ls 291.Op Ar flags 292.Op Ar path 293.Xc 294Display remote directory listing of either 295.Ar path 296or current directory if 297.Ar path 298is not specified. 299If the 300.Fl l 301flag is specified, then display additional details including permissions 302and ownership information. 303.It Ic lumask Ar umask 304Set local umask to 305.Ar umask . 306.It Ic mkdir Ar path 307Create remote directory specified by 308.Ar path . 309.It Ic progress 310Toggle display of progress meter. 311.It Xo Ic put 312.Op Ar flags 313.Ar local-path 314.Op Ar remote-path 315.Xc 316Upload 317.Ar local-path 318and store it on the remote machine. 319If the remote path name is not specified, it is given the same name it has 320on the local machine. 321If the 322.Fl P 323flag is specified, then the file's full permission and access time are 324copied too. 325.It Ic pwd 326Display remote working directory. 327.It Ic quit 328Quit 329.Nm sftp . 330.It Ic rename Ar oldpath Ar newpath 331Rename remote file from 332.Ar oldpath 333to 334.Ar newpath . 335.It Ic rm Ar path 336Delete remote file specified by 337.Ar path . 338.It Ic rmdir Ar path 339Remove remote directory specified by 340.Ar path . 341.It Ic symlink Ar oldpath Ar newpath 342Create a symbolic link from 343.Ar oldpath 344to 345.Ar newpath . 346.It Ic version 347Display the 348.Nm 349protocol version. 350.It Ic \&! Ar command 351Execute 352.Ar command 353in local shell. 354.It Ic \&! 355Escape to local shell. 356.It Ic \&? 357Synonym for help. 358.El 359.Sh SEE ALSO 360.Xr ftp 1 , 361.Xr scp 1 , 362.Xr ssh 1 , 363.Xr ssh-add 1 , 364.Xr ssh-keygen 1 , 365.Xr ssh_config 5 , 366.Xr sftp-server 8 , 367.Xr sshd 8 368.Rs 369.%A T. Ylonen 370.%A S. Lehtinen 371.%T "SSH File Transfer Protocol" 372.%N draft-ietf-secsh-filexfer-00.txt 373.%D January 2001 374.%O work in progress material 375.Re 376