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 64 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 Xo Ic df 276.Op Fl hi 277.Op Ar path 278.Xc 279Display usage information for the filesystem holding the current directory 280(or 281.Ar path 282if specified). 283If the 284.Fl h 285flag is specified, the capacity information will be displayed using 286"human-readable" suffixes. 287The 288.Fl i 289flag requests display of inode information in addition to capacity information. 290This command is only supported on servers that implement the 291.Dq statvfs@openssh.com 292extension. 293.It Ic exit 294Quit 295.Nm sftp . 296.It Xo Ic get 297.Op Fl P 298.Ar remote-path 299.Op Ar local-path 300.Xc 301Retrieve the 302.Ar remote-path 303and store it on the local machine. 304If the local 305path name is not specified, it is given the same name it has on the 306remote machine. 307.Ar remote-path 308may contain 309.Xr glob 3 310characters and may match multiple files. 311If it does and 312.Ar local-path 313is specified, then 314.Ar local-path 315must specify a directory. 316If the 317.Fl P 318flag is specified, then full file permissions and access times are 319copied too. 320.It Ic help 321Display help text. 322.It Ic lcd Ar path 323Change local directory to 324.Ar path . 325.It Ic lls Op Ar ls-options Op Ar path 326Display local directory listing of either 327.Ar path 328or current directory if 329.Ar path 330is not specified. 331.Ar ls-options 332may contain any flags supported by the local system's 333.Xr ls 1 334command. 335.Ar path 336may contain 337.Xr glob 3 338characters and may match multiple files. 339.It Ic lmkdir Ar path 340Create local directory specified by 341.Ar path . 342.It Ic ln Ar oldpath Ar newpath 343Create a symbolic link from 344.Ar oldpath 345to 346.Ar newpath . 347.It Ic lpwd 348Print local working directory. 349.It Xo Ic ls 350.Op Fl 1aflnrSt 351.Op Ar path 352.Xc 353Display a remote directory listing of either 354.Ar path 355or the current directory if 356.Ar path 357is not specified. 358.Ar path 359may contain 360.Xr glob 3 361characters and may match multiple files. 362.Pp 363The following flags are recognized and alter the behaviour of 364.Ic ls 365accordingly: 366.Bl -tag -width Ds 367.It Fl 1 368Produce single columnar output. 369.It Fl a 370List files beginning with a dot 371.Pq Sq \&. . 372.It Fl f 373Do not sort the listing. 374The default sort order is lexicographical. 375.It Fl l 376Display additional details including permissions 377and ownership information. 378.It Fl n 379Produce a long listing with user and group information presented 380numerically. 381.It Fl r 382Reverse the sort order of the listing. 383.It Fl S 384Sort the listing by file size. 385.It Fl t 386Sort the listing by last modification time. 387.El 388.It Ic lumask Ar umask 389Set local umask to 390.Ar umask . 391.It Ic mkdir Ar path 392Create remote directory specified by 393.Ar path . 394.It Ic progress 395Toggle display of progress meter. 396.It Xo Ic put 397.Op Fl P 398.Ar local-path 399.Op Ar remote-path 400.Xc 401Upload 402.Ar local-path 403and store it on the remote machine. 404If the remote path name is not specified, it is given the same name it has 405on the local machine. 406.Ar local-path 407may contain 408.Xr glob 3 409characters and may match multiple files. 410If it does and 411.Ar remote-path 412is specified, then 413.Ar remote-path 414must specify a directory. 415If the 416.Fl P 417flag is specified, then the file's full permission and access time are 418copied too. 419.It Ic pwd 420Display remote working directory. 421.It Ic quit 422Quit 423.Nm sftp . 424.It Ic rename Ar oldpath Ar newpath 425Rename remote file from 426.Ar oldpath 427to 428.Ar newpath . 429.It Ic rm Ar path 430Delete remote file specified by 431.Ar path . 432.It Ic rmdir Ar path 433Remove remote directory specified by 434.Ar path . 435.It Ic symlink Ar oldpath Ar newpath 436Create a symbolic link from 437.Ar oldpath 438to 439.Ar newpath . 440.It Ic version 441Display the 442.Nm 443protocol version. 444.It Ic \&! Ns Ar command 445Execute 446.Ar command 447in local shell. 448.It Ic \&! 449Escape to local shell. 450.It Ic \&? 451Synonym for help. 452.El 453.Sh SEE ALSO 454.Xr ftp 1 , 455.Xr ls 1 , 456.Xr scp 1 , 457.Xr ssh 1 , 458.Xr ssh-add 1 , 459.Xr ssh-keygen 1 , 460.Xr glob 3 , 461.Xr ssh_config 5 , 462.Xr sftp-server 8 , 463.Xr sshd 8 464.Rs 465.%A T. Ylonen 466.%A S. Lehtinen 467.%T "SSH File Transfer Protocol" 468.%N draft-ietf-secsh-filexfer-00.txt 469.%D January 2001 470.%O work in progress material 471.Re 472