1.\" $OpenBSD: sftp.1,v 1.99 2014/04/22 14:16:30 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 $Mdocdate: April 22 2014 $ 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 1246aCfpqrv 35.Op Fl B Ar buffer_size 36.Op Fl b Ar batchfile 37.Op Fl c Ar cipher 38.Op Fl D Ar sftp_server_path 39.Op Fl F Ar ssh_config 40.Op Fl i Ar identity_file 41.Op Fl l Ar limit 42.Op Fl o Ar ssh_option 43.Op Fl P Ar port 44.Op Fl R Ar num_requests 45.Op Fl S Ar program 46.Op Fl s Ar subsystem | sftp_server 47.Ar host 48.Ek 49.Nm sftp 50.Oo Ar user Ns @ Oc Ns 51.Ar host Ns Op : Ns Ar 52.Nm sftp 53.Oo 54.Ar user Ns @ Oc Ns 55.Ar host Ns Oo : Ns Ar dir Ns 56.Op Ar / 57.Oc 58.Nm sftp 59.Fl b Ar batchfile 60.Oo Ar user Ns @ Oc Ns Ar host 61.Sh DESCRIPTION 62.Nm 63is an interactive file transfer program, similar to 64.Xr ftp 1 , 65which performs all operations over an encrypted 66.Xr ssh 1 67transport. 68It may also use many features of ssh, such as public key authentication and 69compression. 70.Nm 71connects and logs into the specified 72.Ar host , 73then enters an interactive command mode. 74.Pp 75The second usage format will retrieve files automatically if a non-interactive 76authentication method is used; otherwise it will do so after 77successful interactive authentication. 78.Pp 79The third usage format allows 80.Nm 81to start in a remote directory. 82.Pp 83The final usage format allows for automated sessions using the 84.Fl b 85option. 86In such cases, it is necessary to configure non-interactive authentication 87to obviate the need to enter a password at connection time (see 88.Xr sshd 8 89and 90.Xr ssh-keygen 1 91for details). 92.Pp 93Since some usage formats use colon characters to delimit host names from path 94names, IPv6 addresses must be enclosed in square brackets to avoid ambiguity. 95.Pp 96The options are as follows: 97.Bl -tag -width Ds 98.It Fl 1 99Specify the use of protocol version 1. 100.It Fl 2 101Specify the use of protocol version 2. 102.It Fl 4 103Forces 104.Nm 105to use IPv4 addresses only. 106.It Fl 6 107Forces 108.Nm 109to use IPv6 addresses only. 110.It Fl a 111Attempt to continue interrupted transfers rather than overwriting 112existing partial or complete copies of files. 113If the partial contents differ from those being transferred, 114then the resultant file is likely to be corrupt. 115.It Fl B Ar buffer_size 116Specify the size of the buffer that 117.Nm 118uses when transferring files. 119Larger buffers require fewer round trips at the cost of higher 120memory consumption. 121The default is 32768 bytes. 122.It Fl b Ar batchfile 123Batch mode reads a series of commands from an input 124.Ar batchfile 125instead of 126.Em stdin . 127Since it lacks user interaction it should be used in conjunction with 128non-interactive authentication. 129A 130.Ar batchfile 131of 132.Sq \- 133may be used to indicate standard input. 134.Nm 135will abort if any of the following 136commands fail: 137.Ic get , put , reget , reput, rename , ln , 138.Ic rm , mkdir , chdir , ls , 139.Ic lchdir , chmod , chown , 140.Ic chgrp , lpwd , df , symlink , 141and 142.Ic lmkdir . 143Termination on error can be suppressed on a command by command basis by 144prefixing the command with a 145.Sq \- 146character (for example, 147.Ic -rm /tmp/blah* ) . 148.It Fl C 149Enables compression (via ssh's 150.Fl C 151flag). 152.It Fl c Ar cipher 153Selects the cipher to use for encrypting the data transfers. 154This option is directly passed to 155.Xr ssh 1 . 156.It Fl D Ar sftp_server_path 157Connect directly to a local sftp server 158(rather than via 159.Xr ssh 1 ) . 160This option may be useful in debugging the client and server. 161.It Fl F Ar ssh_config 162Specifies an alternative 163per-user configuration file for 164.Xr ssh 1 . 165This option is directly passed to 166.Xr ssh 1 . 167.It Fl f 168Requests that files be flushed to disk immediately after transfer. 169When uploading files, this feature is only enabled if the server 170implements the "fsync@openssh.com" extension. 171.It Fl i Ar identity_file 172Selects the file from which the identity (private key) for public key 173authentication is read. 174This option is directly passed to 175.Xr ssh 1 . 176.It Fl l Ar limit 177Limits the used bandwidth, specified in Kbit/s. 178.It Fl o Ar ssh_option 179Can be used to pass options to 180.Nm ssh 181in the format used in 182.Xr ssh_config 5 . 183This is useful for specifying options 184for which there is no separate 185.Nm sftp 186command-line flag. 187For example, to specify an alternate port use: 188.Ic sftp -oPort=24 . 189For full details of the options listed below, and their possible values, see 190.Xr ssh_config 5 . 191.Pp 192.Bl -tag -width Ds -offset indent -compact 193.It AddressFamily 194.It BatchMode 195.It BindAddress 196.It CanonicalDomains 197.It CanonicalizeFallbackLocal 198.It CanonicalizeHostname 199.It CanonicalizeMaxDots 200.It CanonicalizePermittedCNAMEs 201.It ChallengeResponseAuthentication 202.It CheckHostIP 203.It Cipher 204.It Ciphers 205.It Compression 206.It CompressionLevel 207.It ConnectionAttempts 208.It ConnectTimeout 209.It ControlMaster 210.It ControlPath 211.It ControlPersist 212.It GlobalKnownHostsFile 213.It GSSAPIAuthentication 214.It GSSAPIDelegateCredentials 215.It HashKnownHosts 216.It Host 217.It HostbasedAuthentication 218.It HostKeyAlgorithms 219.It HostKeyAlias 220.It HostName 221.It IdentityFile 222.It IdentitiesOnly 223.It IPQoS 224.It KbdInteractiveAuthentication 225.It KbdInteractiveDevices 226.It KexAlgorithms 227.It LogLevel 228.It MACs 229.It NoHostAuthenticationForLocalhost 230.It NumberOfPasswordPrompts 231.It PasswordAuthentication 232.It PKCS11Provider 233.It Port 234.It PreferredAuthentications 235.It Protocol 236.It ProxyCommand 237.It PubkeyAuthentication 238.It RekeyLimit 239.It RhostsRSAAuthentication 240.It RSAAuthentication 241.It SendEnv 242.It ServerAliveInterval 243.It ServerAliveCountMax 244.It StrictHostKeyChecking 245.It TCPKeepAlive 246.It UsePrivilegedPort 247.It User 248.It UserKnownHostsFile 249.It VerifyHostKeyDNS 250.El 251.It Fl P Ar port 252Specifies the port to connect to on the remote host. 253.It Fl p 254Preserves modification times, access times, and modes from the 255original files transferred. 256.It Fl q 257Quiet mode: disables the progress meter as well as warning and 258diagnostic messages from 259.Xr ssh 1 . 260.It Fl R Ar num_requests 261Specify how many requests may be outstanding at any one time. 262Increasing this may slightly improve file transfer speed 263but will increase memory usage. 264The default is 64 outstanding requests. 265.It Fl r 266Recursively copy entire directories when uploading and downloading. 267Note that 268.Nm 269does not follow symbolic links encountered in the tree traversal. 270.It Fl S Ar program 271Name of the 272.Ar program 273to use for the encrypted connection. 274The program must understand 275.Xr ssh 1 276options. 277.It Fl s Ar subsystem | sftp_server 278Specifies the SSH2 subsystem or the path for an sftp server 279on the remote host. 280A path is useful for using 281.Nm 282over protocol version 1, or when the remote 283.Xr sshd 8 284does not have an sftp subsystem configured. 285.It Fl v 286Raise logging level. 287This option is also passed to ssh. 288.El 289.Sh INTERACTIVE COMMANDS 290Once in interactive mode, 291.Nm 292understands a set of commands similar to those of 293.Xr ftp 1 . 294Commands are case insensitive. 295Pathnames that contain spaces must be enclosed in quotes. 296Any special characters contained within pathnames that are recognized by 297.Xr glob 3 298must be escaped with backslashes 299.Pq Sq \e . 300.Bl -tag -width Ds 301.It Ic bye 302Quit 303.Nm sftp . 304.It Ic cd Ar path 305Change remote directory to 306.Ar path . 307.It Ic chgrp Ar grp Ar path 308Change group of file 309.Ar path 310to 311.Ar grp . 312.Ar path 313may contain 314.Xr glob 3 315characters and may match multiple files. 316.Ar grp 317must be a numeric GID. 318.It Ic chmod Ar mode Ar path 319Change permissions of file 320.Ar path 321to 322.Ar mode . 323.Ar path 324may contain 325.Xr glob 3 326characters and may match multiple files. 327.It Ic chown Ar own Ar path 328Change owner of file 329.Ar path 330to 331.Ar own . 332.Ar path 333may contain 334.Xr glob 3 335characters and may match multiple files. 336.Ar own 337must be a numeric UID. 338.It Xo Ic df 339.Op Fl hi 340.Op Ar path 341.Xc 342Display usage information for the filesystem holding the current directory 343(or 344.Ar path 345if specified). 346If the 347.Fl h 348flag is specified, the capacity information will be displayed using 349"human-readable" suffixes. 350The 351.Fl i 352flag requests display of inode information in addition to capacity information. 353This command is only supported on servers that implement the 354.Dq statvfs@openssh.com 355extension. 356.It Ic exit 357Quit 358.Nm sftp . 359.It Xo Ic get 360.Op Fl afPpr 361.Ar remote-path 362.Op Ar local-path 363.Xc 364Retrieve the 365.Ar remote-path 366and store it on the local machine. 367If the local 368path name is not specified, it is given the same name it has on the 369remote machine. 370.Ar remote-path 371may contain 372.Xr glob 3 373characters and may match multiple files. 374If it does and 375.Ar local-path 376is specified, then 377.Ar local-path 378must specify a directory. 379.Pp 380If the 381.Fl a 382flag is specified, then attempt to resume partial transfers of existing files. 383Note that resumption assumes that any partial copy of the local file matches 384the remote copy. 385If the remote file contents differ from the partial local copy then the 386resultant file is likely to be corrupt. 387.Pp 388If the 389.Fl f 390flag is specified, then 391.Xr fsync 2 392will be called after the file transfer has completed to flush the file 393to disk. 394.Pp 395If either the 396.Fl P 397or 398.Fl p 399flag is specified, then full file permissions and access times are 400copied too. 401.Pp 402If the 403.Fl r 404flag is specified then directories will be copied recursively. 405Note that 406.Nm 407does not follow symbolic links when performing recursive transfers. 408.It Ic help 409Display help text. 410.It Ic lcd Ar path 411Change local directory to 412.Ar path . 413.It Ic lls Op Ar ls-options Op Ar path 414Display local directory listing of either 415.Ar path 416or current directory if 417.Ar path 418is not specified. 419.Ar ls-options 420may contain any flags supported by the local system's 421.Xr ls 1 422command. 423.Ar path 424may contain 425.Xr glob 3 426characters and may match multiple files. 427.It Ic lmkdir Ar path 428Create local directory specified by 429.Ar path . 430.It Xo Ic ln 431.Op Fl s 432.Ar oldpath 433.Ar newpath 434.Xc 435Create a link from 436.Ar oldpath 437to 438.Ar newpath . 439If the 440.Fl s 441flag is specified the created link is a symbolic link, otherwise it is 442a hard link. 443.It Ic lpwd 444Print local working directory. 445.It Xo Ic ls 446.Op Fl 1afhlnrSt 447.Op Ar path 448.Xc 449Display a remote directory listing of either 450.Ar path 451or the current directory if 452.Ar path 453is not specified. 454.Ar path 455may contain 456.Xr glob 3 457characters and may match multiple files. 458.Pp 459The following flags are recognized and alter the behaviour of 460.Ic ls 461accordingly: 462.Bl -tag -width Ds 463.It Fl 1 464Produce single columnar output. 465.It Fl a 466List files beginning with a dot 467.Pq Sq \&. . 468.It Fl f 469Do not sort the listing. 470The default sort order is lexicographical. 471.It Fl h 472When used with a long format option, use unit suffixes: Byte, Kilobyte, 473Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce 474the number of digits to four or fewer using powers of 2 for sizes (K=1024, 475M=1048576, etc.). 476.It Fl l 477Display additional details including permissions 478and ownership information. 479.It Fl n 480Produce a long listing with user and group information presented 481numerically. 482.It Fl r 483Reverse the sort order of the listing. 484.It Fl S 485Sort the listing by file size. 486.It Fl t 487Sort the listing by last modification time. 488.El 489.It Ic lumask Ar umask 490Set local umask to 491.Ar umask . 492.It Ic mkdir Ar path 493Create remote directory specified by 494.Ar path . 495.It Ic progress 496Toggle display of progress meter. 497.It Xo Ic put 498.Op Fl afPpr 499.Ar local-path 500.Op Ar remote-path 501.Xc 502Upload 503.Ar local-path 504and store it on the remote machine. 505If the remote path name is not specified, it is given the same name it has 506on the local machine. 507.Ar local-path 508may contain 509.Xr glob 3 510characters and may match multiple files. 511If it does and 512.Ar remote-path 513is specified, then 514.Ar remote-path 515must specify a directory. 516.Pp 517If the 518.Fl a 519flag is specified, then attempt to resume partial 520transfers of existing files. 521Note that resumption assumes that any partial copy of the remote file 522matches the local copy. 523If the local file contents differ from the remote local copy then 524the resultant file is likely to be corrupt. 525.Pp 526If the 527.Fl f 528flag is specified, then a request will be sent to the server to call 529.Xr fsync 2 530after the file has been transferred. 531Note that this is only supported by servers that implement 532the "fsync@openssh.com" extension. 533.Pp 534If either the 535.Fl P 536or 537.Fl p 538flag is specified, then full file permissions and access times are 539copied too. 540.Pp 541If the 542.Fl r 543flag is specified then directories will be copied recursively. 544Note that 545.Nm 546does not follow symbolic links when performing recursive transfers. 547.It Ic pwd 548Display remote working directory. 549.It Ic quit 550Quit 551.Nm sftp . 552.It Xo Ic reget 553.Op Fl Ppr 554.Ar remote-path 555.Op Ar local-path 556.Xc 557Resume download of 558.Ar remote-path . 559Equivalent to 560.Ic get 561with the 562.Fl a 563flag set. 564.It Xo Ic reput 565.Op Fl Ppr 566.Op Ar local-path 567.Ar remote-path 568.Xc 569Resume upload of 570.Op Ar local-path . 571Equivalent to 572.Ic put 573with the 574.Fl a 575flag set. 576.It Ic rename Ar oldpath Ar newpath 577Rename remote file from 578.Ar oldpath 579to 580.Ar newpath . 581.It Ic rm Ar path 582Delete remote file specified by 583.Ar path . 584.It Ic rmdir Ar path 585Remove remote directory specified by 586.Ar path . 587.It Ic symlink Ar oldpath Ar newpath 588Create a symbolic link from 589.Ar oldpath 590to 591.Ar newpath . 592.It Ic version 593Display the 594.Nm 595protocol version. 596.It Ic \&! Ns Ar command 597Execute 598.Ar command 599in local shell. 600.It Ic \&! 601Escape to local shell. 602.It Ic \&? 603Synonym for help. 604.El 605.Sh SEE ALSO 606.Xr ftp 1 , 607.Xr ls 1 , 608.Xr scp 1 , 609.Xr ssh 1 , 610.Xr ssh-add 1 , 611.Xr ssh-keygen 1 , 612.Xr glob 3 , 613.Xr ssh_config 5 , 614.Xr sftp-server 8 , 615.Xr sshd 8 616.Rs 617.%A T. Ylonen 618.%A S. Lehtinen 619.%T "SSH File Transfer Protocol" 620.%N draft-ietf-secsh-filexfer-00.txt 621.%D January 2001 622.%O work in progress material 623.Re 624