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