1.\" $OpenBSD: sftp.1,v 1.63 2006/01/20 00:14:55 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 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 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 , chgrp , lpwd 116and 117.Ic lmkdir . 118Termination on error can be suppressed on a command by command basis by 119prefixing the command with a 120.Sq \- 121character (for example, 122.Ic -rm /tmp/blah* ) . 123.It Fl C 124Enables compression (via ssh's 125.Fl C 126flag). 127.It Fl F Ar ssh_config 128Specifies an alternative 129per-user configuration file for 130.Xr ssh 1 . 131This option is directly passed to 132.Xr ssh 1 . 133.It Fl o Ar ssh_option 134Can be used to pass options to 135.Nm ssh 136in the format used in 137.Xr ssh_config 5 . 138This is useful for specifying options 139for which there is no separate 140.Nm sftp 141command-line flag. 142For example, to specify an alternate port use: 143.Ic sftp -oPort=24 . 144For full details of the options listed below, and their possible values, see 145.Xr ssh_config 5 . 146.Pp 147.Bl -tag -width Ds -offset indent -compact 148.It AddressFamily 149.It BatchMode 150.It BindAddress 151.It ChallengeResponseAuthentication 152.It CheckHostIP 153.It Cipher 154.It Ciphers 155.It Compression 156.It CompressionLevel 157.It ConnectionAttempts 158.It ConnectTimeout 159.It ControlMaster 160.It ControlPath 161.It GlobalKnownHostsFile 162.It GSSAPIAuthentication 163.It GSSAPIDelegateCredentials 164.It HashKnownHosts 165.It Host 166.It HostbasedAuthentication 167.It HostKeyAlgorithms 168.It HostKeyAlias 169.It HostName 170.It IdentityFile 171.It IdentitiesOnly 172.It KbdInteractiveDevices 173.It LogLevel 174.It MACs 175.It NoHostAuthenticationForLocalhost 176.It NumberOfPasswordPrompts 177.It PasswordAuthentication 178.It Port 179.It PreferredAuthentications 180.It Protocol 181.It ProxyCommand 182.It PubkeyAuthentication 183.It RekeyLimit 184.It RhostsRSAAuthentication 185.It RSAAuthentication 186.It SendEnv 187.It ServerAliveInterval 188.It ServerAliveCountMax 189.It SmartcardDevice 190.It StrictHostKeyChecking 191.It TCPKeepAlive 192.It UsePrivilegedPort 193.It User 194.It UserKnownHostsFile 195.It VerifyHostKeyDNS 196.El 197.It Fl P Ar sftp_server_path 198Connect directly to a local sftp server 199(rather than via 200.Xr ssh 1 ) . 201This option may be useful in debugging the client and server. 202.It Fl R Ar num_requests 203Specify how many requests may be outstanding at any one time. 204Increasing this may slightly improve file transfer speed 205but will increase memory usage. 206The default is 16 outstanding requests. 207.It Fl S Ar program 208Name of the 209.Ar program 210to use for the encrypted connection. 211The program must understand 212.Xr ssh 1 213options. 214.It Fl s Ar subsystem | sftp_server 215Specifies the SSH2 subsystem or the path for an sftp server 216on the remote host. 217A path is useful for using 218.Nm 219over protocol version 1, or when the remote 220.Xr sshd 8 221does not have an sftp subsystem configured. 222.It Fl v 223Raise logging level. 224This option is also passed to ssh. 225.El 226.Sh INTERACTIVE COMMANDS 227Once in interactive mode, 228.Nm 229understands a set of commands similar to those of 230.Xr ftp 1 . 231Commands are case insensitive. 232Pathnames that contain spaces must be enclosed in quotes. 233Any special characters contained within pathnames that are recognized by 234.Xr glob 3 235must be escaped with backslashes 236.Pq Sq \e . 237.Bl -tag -width Ds 238.It Ic bye 239Quit 240.Nm sftp . 241.It Ic cd Ar path 242Change remote directory to 243.Ar path . 244.It Ic chgrp Ar grp Ar path 245Change group of file 246.Ar path 247to 248.Ar grp . 249.Ar path 250may contain 251.Xr glob 3 252characters and may match multiple files. 253.Ar grp 254must be a numeric GID. 255.It Ic chmod Ar mode Ar path 256Change permissions of file 257.Ar path 258to 259.Ar mode . 260.Ar path 261may contain 262.Xr glob 3 263characters and may match multiple files. 264.It Ic chown Ar own Ar path 265Change owner of file 266.Ar path 267to 268.Ar own . 269.Ar path 270may contain 271.Xr glob 3 272characters and may match multiple files. 273.Ar own 274must be a numeric UID. 275.It Ic exit 276Quit 277.Nm sftp . 278.It Xo Ic get 279.Op Fl P 280.Ar remote-path 281.Op Ar local-path 282.Xc 283Retrieve the 284.Ar remote-path 285and store it on the local machine. 286If the local 287path name is not specified, it is given the same name it has on the 288remote machine. 289.Ar remote-path 290may contain 291.Xr glob 3 292characters and may match multiple files. 293If it does and 294.Ar local-path 295is specified, then 296.Ar local-path 297must specify a directory. 298If the 299.Fl P 300flag is specified, then full file permissions and access times are 301copied too. 302.It Ic help 303Display help text. 304.It Ic lcd Ar path 305Change local directory to 306.Ar path . 307.It Ic lls Op Ar ls-options Op Ar path 308Display local directory listing of either 309.Ar path 310or current directory if 311.Ar path 312is not specified. 313.Ar ls-options 314may contain any flags supported by the local system's 315.Xr ls 1 316command. 317.Ar path 318may contain 319.Xr glob 3 320characters and may match multiple files. 321.It Ic lmkdir Ar path 322Create local directory specified by 323.Ar path . 324.It Ic ln Ar oldpath Ar newpath 325Create a symbolic link from 326.Ar oldpath 327to 328.Ar newpath . 329.It Ic lpwd 330Print local working directory. 331.It Xo Ic ls 332.Op Fl 1aflnrSt 333.Op Ar path 334.Xc 335Display a remote directory listing of either 336.Ar path 337or the current directory if 338.Ar path 339is not specified. 340.Ar path 341may contain 342.Xr glob 3 343characters and may match multiple files. 344.Pp 345The following flags are recognized and alter the behaviour of 346.Ic ls 347accordingly: 348.Bl -tag -width Ds 349.It Fl 1 350Produce single columnar output. 351.It Fl a 352List files beginning with a dot 353.Pq Sq \&. . 354.It Fl f 355Do not sort the listing. 356The default sort order is lexicographical. 357.It Fl l 358Display additional details including permissions 359and ownership information. 360.It Fl n 361Produce a long listing with user and group information presented 362numerically. 363.It Fl r 364Reverse the sort order of the listing. 365.It Fl S 366Sort the listing by file size. 367.It Fl t 368Sort the listing by last modification time. 369.El 370.It Ic lumask Ar umask 371Set local umask to 372.Ar umask . 373.It Ic mkdir Ar path 374Create remote directory specified by 375.Ar path . 376.It Ic progress 377Toggle display of progress meter. 378.It Xo Ic put 379.Op Fl P 380.Ar local-path 381.Op Ar remote-path 382.Xc 383Upload 384.Ar local-path 385and store it on the remote machine. 386If the remote path name is not specified, it is given the same name it has 387on the local machine. 388.Ar local-path 389may contain 390.Xr glob 3 391characters and may match multiple files. 392If it does and 393.Ar remote-path 394is specified, then 395.Ar remote-path 396must specify a directory. 397If the 398.Fl P 399flag is specified, then the file's full permission and access time are 400copied too. 401.It Ic pwd 402Display remote working directory. 403.It Ic quit 404Quit 405.Nm sftp . 406.It Ic rename Ar oldpath Ar newpath 407Rename remote file from 408.Ar oldpath 409to 410.Ar newpath . 411.It Ic rm Ar path 412Delete remote file specified by 413.Ar path . 414.It Ic rmdir Ar path 415Remove remote directory specified by 416.Ar path . 417.It Ic symlink Ar oldpath Ar newpath 418Create a symbolic link from 419.Ar oldpath 420to 421.Ar newpath . 422.It Ic version 423Display the 424.Nm 425protocol version. 426.It Ic \&! Ar command 427Execute 428.Ar command 429in local shell. 430.It Ic \&! 431Escape to local shell. 432.It Ic \&? 433Synonym for help. 434.El 435.Sh SEE ALSO 436.Xr ftp 1 , 437.Xr ls 1 , 438.Xr scp 1 , 439.Xr ssh 1 , 440.Xr ssh-add 1 , 441.Xr ssh-keygen 1 , 442.Xr glob 3 , 443.Xr ssh_config 5 , 444.Xr sftp-server 8 , 445.Xr sshd 8 446.Rs 447.%A T. Ylonen 448.%A S. Lehtinen 449.%T "SSH File Transfer Protocol" 450.%N draft-ietf-secsh-filexfer-00.txt 451.%D January 2001 452.%O work in progress material 453.Re 454