1.\" $OpenBSD: sftp.1,v 1.41 2003/03/28 10:11:43 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 vC1 35.Op Fl b Ar batchfile 36.Op Fl o Ar ssh_option 37.Op Fl s Ar subsystem | sftp_server 38.Op Fl B Ar buffer_size 39.Op Fl F Ar ssh_config 40.Op Fl P Ar sftp_server path 41.Op Fl R Ar num_requests 42.Op Fl S Ar program 43.Ar host 44.Ek 45.Nm sftp 46.Oo Oo Ar user Ns No @ 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 No @ Oc Ns 51.Ar host Ns Oo : Ns Ar dir Ns 52.Oo Ar / Oc Oc Oc 53.Sh DESCRIPTION 54.Nm 55is an interactive file transfer program, similar to 56.Xr ftp 1 , 57which performs all operations over an encrypted 58.Xr ssh 1 59transport. 60It may also use many features of ssh, such as public key authentication and 61compression. 62.Nm 63connects and logs into the specified 64.Ar host , 65then enters an interactive command mode. 66.Pp 67The second usage format will retrieve files automatically if a non-interactive 68authentication method is used; otherwise it will do so after 69successful interactive authentication. 70.Pp 71The last usage format allows the sftp client to start in a remote directory. 72.Pp 73The options are as follows: 74.Bl -tag -width Ds 75.It Fl b Ar batchfile 76Batch mode reads a series of commands from an input 77.Ar batchfile 78instead of 79.Em stdin . 80Since it lacks user interaction it should be used in conjunction with 81non-interactive authentication. 82.Nm 83will abort if any of the following 84commands fail: 85.Ic get , put , rename , ln , 86.Ic rm , mkdir , chdir , ls , 87.Ic lchdir , chmod , chown , chgrp , lpwd 88and 89.Ic lmkdir . 90Termination on error can be suppressed on a command by command basis by 91prefixing the command with a 92.Ic '-' 93character (For example, 94.Ic -rm /tmp/blah* 95). 96.It Fl o Ar ssh_option 97Can be used to pass options to 98.Nm ssh 99in the format used in 100.Xr ssh_config 5 . 101This is useful for specifying options 102for which there is no separate 103.Nm sftp 104command-line flag. For example, to specify an alternate 105port use: 106.Ic sftp -oPort=24 . 107.It Fl s Ar subsystem | sftp_server 108Specifies the SSH2 subsystem or the path for an sftp server 109on the remote host. A path is useful for using sftp over 110protocol version 1, or when the remote 111.Nm sshd 112does not have an sftp subsystem configured. 113.It Fl v 114Raise logging level. This option is also passed to ssh. 115.It Fl B Ar buffer_size 116Specify the size of the buffer that 117.Nm 118uses when transferring files. Larger buffers require fewer round trips at 119the cost of higher memory consumption. The default is 32768 bytes. 120.It Fl C 121Enables compression (via ssh's 122.Fl C 123flag). 124.It Fl F Ar ssh_config 125Specifies an alternative 126per-user configuration file for 127.Nm ssh . 128This option is directly passed to 129.Xr ssh 1 . 130.It Fl P Ar sftp_server path 131Connect directly to a local 132.Nm sftp-server 133(rather than via 134.Nm ssh ) 135This option may be useful in debugging the client and server. 136.It Fl R Ar num_requests 137Specify how many requests may be outstanding at any one time. Increasing 138this may slightly improve file transfer speed but will increase memory 139usage. The default is 16 outstanding requests. 140.It Fl S Ar program 141Name of the 142.Ar program 143to use for the encrypted connection. 144The program must understand 145.Xr ssh 1 146options. 147.It Fl 1 148Specify the use of protocol version 1. 149.El 150.Sh INTERACTIVE COMMANDS 151Once in interactive mode, 152.Nm 153understands a set of commands similar to those of 154.Xr ftp 1 . 155Commands are case insensitive and pathnames may be enclosed in quotes if they 156contain spaces. 157.Bl -tag -width Ds 158.It Ic bye 159Quit sftp. 160.It Ic cd Ar path 161Change remote directory to 162.Ar path . 163.It Ic lcd Ar path 164Change local directory to 165.Ar path . 166.It Ic chgrp Ar grp Ar path 167Change group of file 168.Ar path 169to 170.Ar grp . 171.Ar grp 172must be a numeric GID. 173.It Ic chmod Ar mode Ar path 174Change permissions of file 175.Ar path 176to 177.Ar mode . 178.It Ic chown Ar own Ar path 179Change owner of file 180.Ar path 181to 182.Ar own . 183.Ar own 184must be a numeric UID. 185.It Ic exit 186Quit sftp. 187.It Xo Ic get 188.Op Ar flags 189.Ar remote-path 190.Op Ar local-path 191.Xc 192Retrieve the 193.Ar remote-path 194and store it on the local machine. 195If the local 196path name is not specified, it is given the same name it has on the 197remote machine. If the 198.Fl P 199flag is specified, then the file's full permission and access time are 200copied too. 201.It Ic help 202Display help text. 203.It Ic lls Op Ar ls-options Op Ar path 204Display local directory listing of either 205.Ar path 206or current directory if 207.Ar path 208is not specified. 209.It Ic lmkdir Ar path 210Create local directory specified by 211.Ar path . 212.It Ic ln Ar oldpath Ar newpath 213Create a symbolic link from 214.Ar oldpath 215to 216.Ar newpath . 217.It Ic lpwd 218Print local working directory. 219.It Xo Ic ls 220.Op Ar flags 221.Op Ar path 222.Xc 223Display remote directory listing of either 224.Ar path 225or current directory if 226.Ar path 227is not specified. If the 228.Fl l 229flag is specified, then display additional details including permissions 230and ownership information. 231.It Ic lumask Ar umask 232Set local umask to 233.Ar umask . 234.It Ic mkdir Ar path 235Create remote directory specified by 236.Ar path . 237.It Ic progress 238Toggle display of progress meter. 239.It Xo Ic put 240.Op Ar flags 241.Ar local-path 242.Op Ar remote-path 243.Xc 244Upload 245.Ar local-path 246and store it on the remote machine. If the remote path name is not 247specified, it is given the same name it has on the local machine. If the 248.Fl P 249flag is specified, then the file's full permission and access time are 250copied too. 251.It Ic pwd 252Display remote working directory. 253.It Ic quit 254Quit sftp. 255.It Ic rename Ar oldpath Ar newpath 256Rename remote file from 257.Ar oldpath 258to 259.Ar newpath . 260.It Ic rmdir Ar path 261Remove remote directory specified by 262.Ar path . 263.It Ic rm Ar path 264Delete remote file specified by 265.Ar path . 266.It Ic symlink Ar oldpath Ar newpath 267Create a symbolic link from 268.Ar oldpath 269to 270.Ar newpath . 271.It Ic version 272Display the 273.Nm 274protocol version. 275.It Ic ! Ar command 276Execute 277.Ar command 278in local shell. 279.It Ic ! 280Escape to local shell. 281.It Ic ? 282Synonym for help. 283.El 284.Sh AUTHORS 285Damien Miller <djm@mindrot.org> 286.Sh SEE ALSO 287.Xr scp 1 , 288.Xr ssh 1 , 289.Xr ssh-add 1 , 290.Xr ssh-keygen 1 , 291.Xr ssh_config 5 , 292.Xr sftp-server 8 , 293.Xr sshd 8 294.Rs 295.%A T. Ylonen 296.%A S. Lehtinen 297.%T "SSH File Transfer Protocol" 298.%N draft-ietf-secsh-filexfer-00.txt 299.%D January 2001 300.%O work in progress material 301.Re 302