1.\" $OpenBSD: sftp.1,v 1.61 2005/03/01 17:19:35 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 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 usually necessary to configure public key 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 RhostsRSAAuthentication 184.It RSAAuthentication 185.It SendEnv 186.It ServerAliveInterval 187.It ServerAliveCountMax 188.It SmartcardDevice 189.It StrictHostKeyChecking 190.It TCPKeepAlive 191.It UsePrivilegedPort 192.It User 193.It UserKnownHostsFile 194.It VerifyHostKeyDNS 195.El 196.It Fl P Ar sftp_server_path 197Connect directly to a local sftp server 198(rather than via 199.Xr ssh 1 ) . 200This option may be useful in debugging the client and server. 201.It Fl R Ar num_requests 202Specify how many requests may be outstanding at any one time. 203Increasing this may slightly improve file transfer speed 204but will increase memory usage. 205The default is 16 outstanding requests. 206.It Fl S Ar program 207Name of the 208.Ar program 209to use for the encrypted connection. 210The program must understand 211.Xr ssh 1 212options. 213.It Fl s Ar subsystem | sftp_server 214Specifies the SSH2 subsystem or the path for an sftp server 215on the remote host. 216A path is useful for using 217.Nm 218over protocol version 1, or when the remote 219.Xr sshd 8 220does not have an sftp subsystem configured. 221.It Fl v 222Raise logging level. 223This option is also passed to ssh. 224.El 225.Sh INTERACTIVE COMMANDS 226Once in interactive mode, 227.Nm 228understands a set of commands similar to those of 229.Xr ftp 1 . 230Commands are case insensitive. 231Pathnames that contain spaces must be enclosed in quotes. 232Any special characters contained within pathnames that are recognized by 233.Xr glob 3 234must be escaped with backslashes 235.Pq Sq \e . 236.Bl -tag -width Ds 237.It Ic bye 238Quit 239.Nm sftp . 240.It Ic cd Ar path 241Change remote directory to 242.Ar path . 243.It Ic chgrp Ar grp Ar path 244Change group of file 245.Ar path 246to 247.Ar grp . 248.Ar path 249may contain 250.Xr glob 3 251characters and may match multiple files. 252.Ar grp 253must be a numeric GID. 254.It Ic chmod Ar mode Ar path 255Change permissions of file 256.Ar path 257to 258.Ar mode . 259.Ar path 260may contain 261.Xr glob 3 262characters and may match multiple files. 263.It Ic chown Ar own Ar path 264Change owner of file 265.Ar path 266to 267.Ar own . 268.Ar path 269may contain 270.Xr glob 3 271characters and may match multiple files. 272.Ar own 273must be a numeric UID. 274.It Ic exit 275Quit 276.Nm sftp . 277.It Xo Ic get 278.Op Fl P 279.Ar remote-path 280.Op Ar local-path 281.Xc 282Retrieve the 283.Ar remote-path 284and store it on the local machine. 285If the local 286path name is not specified, it is given the same name it has on the 287remote machine. 288.Ar remote-path 289may contain 290.Xr glob 3 291characters and may match multiple files. 292If it does and 293.Ar local-path 294is specified, then 295.Ar local-path 296must specify a directory. 297If the 298.Fl P 299flag is specified, then full file permissions and access times are 300copied too. 301.It Ic help 302Display help text. 303.It Ic lcd Ar path 304Change local directory to 305.Ar path . 306.It Ic lls Op Ar ls-options Op Ar path 307Display local directory listing of either 308.Ar path 309or current directory if 310.Ar path 311is not specified. 312.Ar ls-options 313may contain any flags supported by the local system's 314.Xr ls 1 315command. 316.Ar path 317may contain 318.Xr glob 3 319characters and may match multiple files. 320.It Ic lmkdir Ar path 321Create local directory specified by 322.Ar path . 323.It Ic ln Ar oldpath Ar newpath 324Create a symbolic link from 325.Ar oldpath 326to 327.Ar newpath . 328.It Ic lpwd 329Print local working directory. 330.It Xo Ic ls 331.Op Fl 1aflnrSt 332.Op Ar path 333.Xc 334Display a remote directory listing of either 335.Ar path 336or the current directory if 337.Ar path 338is not specified. 339.Ar path 340may contain 341.Xr glob 3 342characters and may match multiple files. 343.Pp 344The following flags are recognized and alter the behaviour of 345.Ic ls 346accordingly: 347.Bl -tag -width Ds 348.It Fl 1 349Produce single columnar output. 350.It Fl a 351List files beginning with a dot 352.Pq Sq \&. . 353.It Fl f 354Do not sort the listing. 355The default sort order is lexicographical. 356.It Fl l 357Display additional details including permissions 358and ownership information. 359.It Fl n 360Produce a long listing with user and group information presented 361numerically. 362.It Fl r 363Reverse the sort order of the listing. 364.It Fl S 365Sort the listing by file size. 366.It Fl t 367Sort the listing by last modification time. 368.El 369.It Ic lumask Ar umask 370Set local umask to 371.Ar umask . 372.It Ic mkdir Ar path 373Create remote directory specified by 374.Ar path . 375.It Ic progress 376Toggle display of progress meter. 377.It Xo Ic put 378.Op Fl P 379.Ar local-path 380.Op Ar remote-path 381.Xc 382Upload 383.Ar local-path 384and store it on the remote machine. 385If the remote path name is not specified, it is given the same name it has 386on the local machine. 387.Ar local-path 388may contain 389.Xr glob 3 390characters and may match multiple files. 391If it does and 392.Ar remote-path 393is specified, then 394.Ar remote-path 395must specify a directory. 396If the 397.Fl P 398flag is specified, then the file's full permission and access time are 399copied too. 400.It Ic pwd 401Display remote working directory. 402.It Ic quit 403Quit 404.Nm sftp . 405.It Ic rename Ar oldpath Ar newpath 406Rename remote file from 407.Ar oldpath 408to 409.Ar newpath . 410.It Ic rm Ar path 411Delete remote file specified by 412.Ar path . 413.It Ic rmdir Ar path 414Remove remote directory specified by 415.Ar path . 416.It Ic symlink Ar oldpath Ar newpath 417Create a symbolic link from 418.Ar oldpath 419to 420.Ar newpath . 421.It Ic version 422Display the 423.Nm 424protocol version. 425.It Ic \&! Ar command 426Execute 427.Ar command 428in local shell. 429.It Ic \&! 430Escape to local shell. 431.It Ic \&? 432Synonym for help. 433.El 434.Sh SEE ALSO 435.Xr ftp 1 , 436.Xr ls 1 , 437.Xr scp 1 , 438.Xr ssh 1 , 439.Xr ssh-add 1 , 440.Xr ssh-keygen 1 , 441.Xr glob 3 , 442.Xr ssh_config 5 , 443.Xr sftp-server 8 , 444.Xr sshd 8 445.Rs 446.%A T. Ylonen 447.%A S. Lehtinen 448.%T "SSH File Transfer Protocol" 449.%N draft-ietf-secsh-filexfer-00.txt 450.%D January 2001 451.%O work in progress material 452.Re 453