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