1.\" $OpenBSD: sftp.1,v 1.69 2008/12/09 15:35:00 sobrado 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 $Mdocdate: December 9 2008 $ 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 Ar user Ns @ Oc Ns 47.Ar host Ns Op : Ns Ar 48.Nm sftp 49.Oo Ar user Ns @ Oc Ns 50.Ar host Ns Oo : Ns Ar dir Ns 51.Op Ar / Oc 52.Nm sftp 53.Fl b Ar batchfile 54.Oo Ar user Ns @ Oc Ns Ar host 55.Sh DESCRIPTION 56.Nm 57is an interactive file transfer program, similar to 58.Xr ftp 1 , 59which performs all operations over an encrypted 60.Xr ssh 1 61transport. 62It may also use many features of ssh, such as public key authentication and 63compression. 64.Nm 65connects and logs into the specified 66.Ar host , 67then enters an interactive command mode. 68.Pp 69The second usage format will retrieve files automatically if a non-interactive 70authentication method is used; otherwise it will do so after 71successful interactive authentication. 72.Pp 73The third usage format allows 74.Nm 75to start in a remote directory. 76.Pp 77The final usage format allows for automated sessions using the 78.Fl b 79option. 80In such cases, it is necessary to configure non-interactive authentication 81to obviate the need to enter a password at connection time (see 82.Xr sshd 8 83and 84.Xr ssh-keygen 1 85for details). 86The options are as follows: 87.Bl -tag -width Ds 88.It Fl 1 89Specify the use of protocol version 1. 90.It Fl B Ar buffer_size 91Specify the size of the buffer that 92.Nm 93uses when transferring files. 94Larger buffers require fewer round trips at the cost of higher 95memory consumption. 96The default is 32768 bytes. 97.It Fl b Ar batchfile 98Batch mode reads a series of commands from an input 99.Ar batchfile 100instead of 101.Em stdin . 102Since it lacks user interaction it should be used in conjunction with 103non-interactive authentication. 104A 105.Ar batchfile 106of 107.Sq \- 108may be used to indicate standard input. 109.Nm 110will abort if any of the following 111commands fail: 112.Ic get , put , rename , ln , 113.Ic rm , mkdir , chdir , ls , 114.Ic lchdir , chmod , chown , 115.Ic chgrp , lpwd , df , 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 256 outstanding requests providing for 8MB 207of outstanding data with a 32KB buffer. 208.It Fl S Ar program 209Name of the 210.Ar program 211to use for the encrypted connection. 212The program must understand 213.Xr ssh 1 214options. 215.It Fl s Ar subsystem | sftp_server 216Specifies the SSH2 subsystem or the path for an sftp server 217on the remote host. 218A path is useful for using 219.Nm 220over protocol version 1, or when the remote 221.Xr sshd 8 222does not have an sftp subsystem configured. 223.It Fl v 224Raise logging level. 225This option is also passed to ssh. 226.El 227.Sh INTERACTIVE COMMANDS 228Once in interactive mode, 229.Nm 230understands a set of commands similar to those of 231.Xr ftp 1 . 232Commands are case insensitive. 233Pathnames that contain spaces must be enclosed in quotes. 234Any special characters contained within pathnames that are recognized by 235.Xr glob 3 236must be escaped with backslashes 237.Pq Sq \e . 238.Bl -tag -width Ds 239.It Ic bye 240Quit 241.Nm sftp . 242.It Ic cd Ar path 243Change remote directory to 244.Ar path . 245.It Ic chgrp Ar grp Ar path 246Change group of file 247.Ar path 248to 249.Ar grp . 250.Ar path 251may contain 252.Xr glob 3 253characters and may match multiple files. 254.Ar grp 255must be a numeric GID. 256.It Ic chmod Ar mode Ar path 257Change permissions of file 258.Ar path 259to 260.Ar mode . 261.Ar path 262may contain 263.Xr glob 3 264characters and may match multiple files. 265.It Ic chown Ar own Ar path 266Change owner of file 267.Ar path 268to 269.Ar own . 270.Ar path 271may contain 272.Xr glob 3 273characters and may match multiple files. 274.Ar own 275must be a numeric UID. 276.It Xo Ic df 277.Op Fl hi 278.Op Ar path 279.Xc 280Display usage information for the filesystem holding the current directory 281(or 282.Ar path 283if specified). 284If the 285.Fl h 286flag is specified, the capacity information will be displayed using 287"human-readable" suffixes. 288The 289.Fl i 290flag requests display of inode information in addition to capacity information. 291This command is only supported on servers that implement the 292.Dq statvfs@openssh.com 293extension. 294.It Ic exit 295Quit 296.Nm sftp . 297.It Xo Ic get 298.Op Fl P 299.Ar remote-path 300.Op Ar local-path 301.Xc 302Retrieve the 303.Ar remote-path 304and store it on the local machine. 305If the local 306path name is not specified, it is given the same name it has on the 307remote machine. 308.Ar remote-path 309may contain 310.Xr glob 3 311characters and may match multiple files. 312If it does and 313.Ar local-path 314is specified, then 315.Ar local-path 316must specify a directory. 317If the 318.Fl P 319flag is specified, then full file permissions and access times are 320copied too. 321.It Ic help 322Display help text. 323.It Ic lcd Ar path 324Change local directory to 325.Ar path . 326.It Ic lls Op Ar ls-options Op Ar path 327Display local directory listing of either 328.Ar path 329or current directory if 330.Ar path 331is not specified. 332.Ar ls-options 333may contain any flags supported by the local system's 334.Xr ls 1 335command. 336.Ar path 337may contain 338.Xr glob 3 339characters and may match multiple files. 340.It Ic lmkdir Ar path 341Create local directory specified by 342.Ar path . 343.It Ic ln Ar oldpath Ar newpath 344Create a symbolic link from 345.Ar oldpath 346to 347.Ar newpath . 348.It Ic lpwd 349Print local working directory. 350.It Xo Ic ls 351.Op Fl 1aflnrSt 352.Op Ar path 353.Xc 354Display a remote directory listing of either 355.Ar path 356or the current directory if 357.Ar path 358is not specified. 359.Ar path 360may contain 361.Xr glob 3 362characters and may match multiple files. 363.Pp 364The following flags are recognized and alter the behaviour of 365.Ic ls 366accordingly: 367.Bl -tag -width Ds 368.It Fl 1 369Produce single columnar output. 370.It Fl a 371List files beginning with a dot 372.Pq Sq \&. . 373.It Fl f 374Do not sort the listing. 375The default sort order is lexicographical. 376.It Fl l 377Display additional details including permissions 378and ownership information. 379.It Fl n 380Produce a long listing with user and group information presented 381numerically. 382.It Fl r 383Reverse the sort order of the listing. 384.It Fl S 385Sort the listing by file size. 386.It Fl t 387Sort the listing by last modification time. 388.El 389.It Ic lumask Ar umask 390Set local umask to 391.Ar umask . 392.It Ic mkdir Ar path 393Create remote directory specified by 394.Ar path . 395.It Ic progress 396Toggle display of progress meter. 397.It Xo Ic put 398.Op Fl P 399.Ar local-path 400.Op Ar remote-path 401.Xc 402Upload 403.Ar local-path 404and store it on the remote machine. 405If the remote path name is not specified, it is given the same name it has 406on the local machine. 407.Ar local-path 408may contain 409.Xr glob 3 410characters and may match multiple files. 411If it does and 412.Ar remote-path 413is specified, then 414.Ar remote-path 415must specify a directory. 416If the 417.Fl P 418flag is specified, then the file's full permission and access time are 419copied too. 420.It Ic pwd 421Display remote working directory. 422.It Ic quit 423Quit 424.Nm sftp . 425.It Ic rename Ar oldpath Ar newpath 426Rename remote file from 427.Ar oldpath 428to 429.Ar newpath . 430.It Ic rm Ar path 431Delete remote file specified by 432.Ar path . 433.It Ic rmdir Ar path 434Remove remote directory specified by 435.Ar path . 436.It Ic symlink Ar oldpath Ar newpath 437Create a symbolic link from 438.Ar oldpath 439to 440.Ar newpath . 441.It Ic version 442Display the 443.Nm 444protocol version. 445.It Ic \&! Ns Ar command 446Execute 447.Ar command 448in local shell. 449.It Ic \&! 450Escape to local shell. 451.It Ic \&? 452Synonym for help. 453.El 454.Sh SEE ALSO 455.Xr ftp 1 , 456.Xr ls 1 , 457.Xr scp 1 , 458.Xr ssh 1 , 459.Xr ssh-add 1 , 460.Xr ssh-keygen 1 , 461.Xr glob 3 , 462.Xr ssh_config 5 , 463.Xr sftp-server 8 , 464.Xr sshd 8 465.Rs 466.%A T. Ylonen 467.%A S. Lehtinen 468.%T "SSH File Transfer Protocol" 469.%N draft-ietf-secsh-filexfer-00.txt 470.%D January 2001 471.%O work in progress material 472.Re 473