1.\" $OpenBSD: sftp.1,v 1.105 2016/07/16 06:57:55 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: July 16 2016 $ 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 CertificateFile 202.It ChallengeResponseAuthentication 203.It CheckHostIP 204.It Cipher 205.It Ciphers 206.It Compression 207.It CompressionLevel 208.It ConnectionAttempts 209.It ConnectTimeout 210.It ControlMaster 211.It ControlPath 212.It ControlPersist 213.It GlobalKnownHostsFile 214.It GSSAPIAuthentication 215.It GSSAPIDelegateCredentials 216.It HashKnownHosts 217.It Host 218.It HostbasedAuthentication 219.It HostbasedKeyTypes 220.It HostKeyAlgorithms 221.It HostKeyAlias 222.It HostName 223.It IdentitiesOnly 224.It IdentityAgent 225.It IdentityFile 226.It IPQoS 227.It KbdInteractiveAuthentication 228.It KbdInteractiveDevices 229.It KexAlgorithms 230.It LogLevel 231.It MACs 232.It NoHostAuthenticationForLocalhost 233.It NumberOfPasswordPrompts 234.It PasswordAuthentication 235.It PKCS11Provider 236.It Port 237.It PreferredAuthentications 238.It Protocol 239.It ProxyCommand 240.It ProxyJump 241.It PubkeyAuthentication 242.It RekeyLimit 243.It RhostsRSAAuthentication 244.It RSAAuthentication 245.It SendEnv 246.It ServerAliveInterval 247.It ServerAliveCountMax 248.It StrictHostKeyChecking 249.It TCPKeepAlive 250.It UpdateHostKeys 251.It UsePrivilegedPort 252.It User 253.It UserKnownHostsFile 254.It VerifyHostKeyDNS 255.El 256.It Fl P Ar port 257Specifies the port to connect to on the remote host. 258.It Fl p 259Preserves modification times, access times, and modes from the 260original files transferred. 261.It Fl q 262Quiet mode: disables the progress meter as well as warning and 263diagnostic messages from 264.Xr ssh 1 . 265.It Fl R Ar num_requests 266Specify how many requests may be outstanding at any one time. 267Increasing this may slightly improve file transfer speed 268but will increase memory usage. 269The default is 64 outstanding requests. 270.It Fl r 271Recursively copy entire directories when uploading and downloading. 272Note that 273.Nm 274does not follow symbolic links encountered in the tree traversal. 275.It Fl S Ar program 276Name of the 277.Ar program 278to use for the encrypted connection. 279The program must understand 280.Xr ssh 1 281options. 282.It Fl s Ar subsystem | sftp_server 283Specifies the SSH2 subsystem or the path for an sftp server 284on the remote host. 285A path is useful for using 286.Nm 287over protocol version 1, or when the remote 288.Xr sshd 8 289does not have an sftp subsystem configured. 290.It Fl v 291Raise logging level. 292This option is also passed to ssh. 293.El 294.Sh INTERACTIVE COMMANDS 295Once in interactive mode, 296.Nm 297understands a set of commands similar to those of 298.Xr ftp 1 . 299Commands are case insensitive. 300Pathnames that contain spaces must be enclosed in quotes. 301Any special characters contained within pathnames that are recognized by 302.Xr glob 3 303must be escaped with backslashes 304.Pq Sq \e . 305.Bl -tag -width Ds 306.It Ic bye 307Quit 308.Nm sftp . 309.It Ic cd Ar path 310Change remote directory to 311.Ar path . 312.It Ic chgrp Ar grp Ar path 313Change group of file 314.Ar path 315to 316.Ar grp . 317.Ar path 318may contain 319.Xr glob 3 320characters and may match multiple files. 321.Ar grp 322must be a numeric GID. 323.It Ic chmod Ar mode Ar path 324Change permissions of file 325.Ar path 326to 327.Ar mode . 328.Ar path 329may contain 330.Xr glob 3 331characters and may match multiple files. 332.It Ic chown Ar own Ar path 333Change owner of file 334.Ar path 335to 336.Ar own . 337.Ar path 338may contain 339.Xr glob 3 340characters and may match multiple files. 341.Ar own 342must be a numeric UID. 343.It Xo Ic df 344.Op Fl hi 345.Op Ar path 346.Xc 347Display usage information for the filesystem holding the current directory 348(or 349.Ar path 350if specified). 351If the 352.Fl h 353flag is specified, the capacity information will be displayed using 354"human-readable" suffixes. 355The 356.Fl i 357flag requests display of inode information in addition to capacity information. 358This command is only supported on servers that implement the 359.Dq statvfs@openssh.com 360extension. 361.It Ic exit 362Quit 363.Nm sftp . 364.It Xo Ic get 365.Op Fl afPpr 366.Ar remote-path 367.Op Ar local-path 368.Xc 369Retrieve the 370.Ar remote-path 371and store it on the local machine. 372If the local 373path name is not specified, it is given the same name it has on the 374remote machine. 375.Ar remote-path 376may contain 377.Xr glob 3 378characters and may match multiple files. 379If it does and 380.Ar local-path 381is specified, then 382.Ar local-path 383must specify a directory. 384.Pp 385If the 386.Fl a 387flag is specified, then attempt to resume partial transfers of existing files. 388Note that resumption assumes that any partial copy of the local file matches 389the remote copy. 390If the remote file contents differ from the partial local copy then the 391resultant file is likely to be corrupt. 392.Pp 393If the 394.Fl f 395flag is specified, then 396.Xr fsync 2 397will be called after the file transfer has completed to flush the file 398to disk. 399.Pp 400If either the 401.Fl P 402or 403.Fl p 404flag is specified, then full file permissions and access times are 405copied too. 406.Pp 407If the 408.Fl r 409flag is specified then directories will be copied recursively. 410Note that 411.Nm 412does not follow symbolic links when performing recursive transfers. 413.It Ic help 414Display help text. 415.It Ic lcd Ar path 416Change local directory to 417.Ar path . 418.It Ic lls Op Ar ls-options Op Ar path 419Display local directory listing of either 420.Ar path 421or current directory if 422.Ar path 423is not specified. 424.Ar ls-options 425may contain any flags supported by the local system's 426.Xr ls 1 427command. 428.Ar path 429may contain 430.Xr glob 3 431characters and may match multiple files. 432.It Ic lmkdir Ar path 433Create local directory specified by 434.Ar path . 435.It Xo Ic ln 436.Op Fl s 437.Ar oldpath 438.Ar newpath 439.Xc 440Create a link from 441.Ar oldpath 442to 443.Ar newpath . 444If the 445.Fl s 446flag is specified the created link is a symbolic link, otherwise it is 447a hard link. 448.It Ic lpwd 449Print local working directory. 450.It Xo Ic ls 451.Op Fl 1afhlnrSt 452.Op Ar path 453.Xc 454Display a remote directory listing of either 455.Ar path 456or the current directory if 457.Ar path 458is not specified. 459.Ar path 460may contain 461.Xr glob 3 462characters and may match multiple files. 463.Pp 464The following flags are recognized and alter the behaviour of 465.Ic ls 466accordingly: 467.Bl -tag -width Ds 468.It Fl 1 469Produce single columnar output. 470.It Fl a 471List files beginning with a dot 472.Pq Sq \&. . 473.It Fl f 474Do not sort the listing. 475The default sort order is lexicographical. 476.It Fl h 477When used with a long format option, use unit suffixes: Byte, Kilobyte, 478Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce 479the number of digits to four or fewer using powers of 2 for sizes (K=1024, 480M=1048576, etc.). 481.It Fl l 482Display additional details including permissions 483and ownership information. 484.It Fl n 485Produce a long listing with user and group information presented 486numerically. 487.It Fl r 488Reverse the sort order of the listing. 489.It Fl S 490Sort the listing by file size. 491.It Fl t 492Sort the listing by last modification time. 493.El 494.It Ic lumask Ar umask 495Set local umask to 496.Ar umask . 497.It Ic mkdir Ar path 498Create remote directory specified by 499.Ar path . 500.It Ic progress 501Toggle display of progress meter. 502.It Xo Ic put 503.Op Fl afPpr 504.Ar local-path 505.Op Ar remote-path 506.Xc 507Upload 508.Ar local-path 509and store it on the remote machine. 510If the remote path name is not specified, it is given the same name it has 511on the local machine. 512.Ar local-path 513may contain 514.Xr glob 3 515characters and may match multiple files. 516If it does and 517.Ar remote-path 518is specified, then 519.Ar remote-path 520must specify a directory. 521.Pp 522If the 523.Fl a 524flag is specified, then attempt to resume partial 525transfers of existing files. 526Note that resumption assumes that any partial copy of the remote file 527matches the local copy. 528If the local file contents differ from the remote local copy then 529the resultant file is likely to be corrupt. 530.Pp 531If the 532.Fl f 533flag is specified, then a request will be sent to the server to call 534.Xr fsync 2 535after the file has been transferred. 536Note that this is only supported by servers that implement 537the "fsync@openssh.com" extension. 538.Pp 539If either the 540.Fl P 541or 542.Fl p 543flag is specified, then full file permissions and access times are 544copied too. 545.Pp 546If the 547.Fl r 548flag is specified then directories will be copied recursively. 549Note that 550.Nm 551does not follow symbolic links when performing recursive transfers. 552.It Ic pwd 553Display remote working directory. 554.It Ic quit 555Quit 556.Nm sftp . 557.It Xo Ic reget 558.Op Fl Ppr 559.Ar remote-path 560.Op Ar local-path 561.Xc 562Resume download of 563.Ar remote-path . 564Equivalent to 565.Ic get 566with the 567.Fl a 568flag set. 569.It Xo Ic reput 570.Op Fl Ppr 571.Op Ar local-path 572.Ar remote-path 573.Xc 574Resume upload of 575.Op Ar local-path . 576Equivalent to 577.Ic put 578with the 579.Fl a 580flag set. 581.It Ic rename Ar oldpath Ar newpath 582Rename remote file from 583.Ar oldpath 584to 585.Ar newpath . 586.It Ic rm Ar path 587Delete remote file specified by 588.Ar path . 589.It Ic rmdir Ar path 590Remove remote directory specified by 591.Ar path . 592.It Ic symlink Ar oldpath Ar newpath 593Create a symbolic link from 594.Ar oldpath 595to 596.Ar newpath . 597.It Ic version 598Display the 599.Nm 600protocol version. 601.It Ic \&! Ns Ar command 602Execute 603.Ar command 604in local shell. 605.It Ic \&! 606Escape to local shell. 607.It Ic \&? 608Synonym for help. 609.El 610.Sh SEE ALSO 611.Xr ftp 1 , 612.Xr ls 1 , 613.Xr scp 1 , 614.Xr ssh 1 , 615.Xr ssh-add 1 , 616.Xr ssh-keygen 1 , 617.Xr glob 3 , 618.Xr ssh_config 5 , 619.Xr sftp-server 8 , 620.Xr sshd 8 621.Rs 622.%A T. Ylonen 623.%A S. Lehtinen 624.%T "SSH File Transfer Protocol" 625.%N draft-ietf-secsh-filexfer-00.txt 626.%D January 2001 627.%O work in progress material 628.Re 629