1.\" $OpenBSD: sftp.1,v 1.51 2004/01/13 12:17:33 jmc 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 LogLevel 167.It MACs 168.It NoHostAuthenticationForLocalhost 169.It NumberOfPasswordPrompts 170.It PasswordAuthentication 171.It Port 172.It PreferredAuthentications 173.It Protocol 174.It ProxyCommand 175.It PubkeyAuthentication 176.It RhostsRSAAuthentication 177.It RSAAuthentication 178.It ServerAliveInterval 179.It ServerAliveCountMax 180.It SmartcardDevice 181.It StrictHostKeyChecking 182.It TCPKeepAlive 183.It UsePrivilegedPort 184.It User 185.It UserKnownHostsFile 186.It VerifyHostKeyDNS 187.El 188.It Fl P Ar sftp_server_path 189Connect directly to a local sftp server 190(rather than via 191.Xr ssh 1 ) 192This option may be useful in debugging the client and server. 193.It Fl R Ar num_requests 194Specify how many requests may be outstanding at any one time. 195Increasing this may slightly improve file transfer speed 196but will increase memory usage. 197The default is 16 outstanding requests. 198.It Fl S Ar program 199Name of the 200.Ar program 201to use for the encrypted connection. 202The program must understand 203.Xr ssh 1 204options. 205.It Fl s Ar subsystem | sftp_server 206Specifies the SSH2 subsystem or the path for an sftp server 207on the remote host. 208A path is useful for using 209.Nm 210over protocol version 1, or when the remote 211.Xr sshd 8 212does not have an sftp subsystem configured. 213.It Fl v 214Raise logging level. 215This option is also passed to ssh. 216.El 217.Sh INTERACTIVE COMMANDS 218Once in interactive mode, 219.Nm 220understands a set of commands similar to those of 221.Xr ftp 1 . 222Commands are case insensitive and pathnames may be enclosed in quotes if they 223contain spaces. 224.Bl -tag -width "lmdir path" 225.It Ic bye 226Quit 227.Nm sftp . 228.It Ic cd Ar path 229Change remote directory to 230.Ar path . 231.It Ic chgrp Ar grp Ar path 232Change group of file 233.Ar path 234to 235.Ar grp . 236.Ar grp 237must be a numeric GID. 238.It Ic chmod Ar mode Ar path 239Change permissions of file 240.Ar path 241to 242.Ar mode . 243.It Ic chown Ar own Ar path 244Change owner of file 245.Ar path 246to 247.Ar own . 248.Ar own 249must be a numeric UID. 250.It Ic exit 251Quit 252.Nm sftp . 253.It Xo Ic get 254.Op Ar flags 255.Ar remote-path 256.Op Ar local-path 257.Xc 258Retrieve the 259.Ar remote-path 260and store it on the local machine. 261If the local 262path name is not specified, it is given the same name it has on the 263remote machine. 264If the 265.Fl P 266flag is specified, then the file's full permission and access time are 267copied too. 268.It Ic help 269Display help text. 270.It Ic lcd Ar path 271Change local directory to 272.Ar path . 273.It Ic lls Op Ar ls-options Op Ar path 274Display local directory listing of either 275.Ar path 276or current directory if 277.Ar path 278is not specified. 279.It Ic lmkdir Ar path 280Create local directory specified by 281.Ar path . 282.It Ic ln Ar oldpath Ar newpath 283Create a symbolic link from 284.Ar oldpath 285to 286.Ar newpath . 287.It Ic lpwd 288Print local working directory. 289.It Xo Ic ls 290.Op Ar flags 291.Op Ar path 292.Xc 293Display remote directory listing of either 294.Ar path 295or current directory if 296.Ar path 297is not specified. 298If the 299.Fl l 300flag is specified, then display additional details including permissions 301and ownership information. 302.It Ic lumask Ar umask 303Set local umask to 304.Ar umask . 305.It Ic mkdir Ar path 306Create remote directory specified by 307.Ar path . 308.It Ic progress 309Toggle display of progress meter. 310.It Xo Ic put 311.Op Ar flags 312.Ar local-path 313.Op Ar remote-path 314.Xc 315Upload 316.Ar local-path 317and store it on the remote machine. 318If the remote path name is not specified, it is given the same name it has 319on the local machine. 320If the 321.Fl P 322flag is specified, then the file's full permission and access time are 323copied too. 324.It Ic pwd 325Display remote working directory. 326.It Ic quit 327Quit 328.Nm sftp . 329.It Ic rename Ar oldpath Ar newpath 330Rename remote file from 331.Ar oldpath 332to 333.Ar newpath . 334.It Ic rm Ar path 335Delete remote file specified by 336.Ar path . 337.It Ic rmdir Ar path 338Remove remote directory specified by 339.Ar path . 340.It Ic symlink Ar oldpath Ar newpath 341Create a symbolic link from 342.Ar oldpath 343to 344.Ar newpath . 345.It Ic version 346Display the 347.Nm 348protocol version. 349.It Ic \&! Ar command 350Execute 351.Ar command 352in local shell. 353.It Ic \&! 354Escape to local shell. 355.It Ic \&? 356Synonym for help. 357.El 358.Sh SEE ALSO 359.Xr ftp 1 , 360.Xr scp 1 , 361.Xr ssh 1 , 362.Xr ssh-add 1 , 363.Xr ssh-keygen 1 , 364.Xr ssh_config 5 , 365.Xr sftp-server 8 , 366.Xr sshd 8 367.Rs 368.%A T. Ylonen 369.%A S. Lehtinen 370.%T "SSH File Transfer Protocol" 371.%N draft-ietf-secsh-filexfer-00.txt 372.%D January 2001 373.%O work in progress material 374.Re 375