1.\" $OpenBSD: sftp.1,v 1.138 2021/07/02 05:11:21 dtucker 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 2 2021 $ 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 , 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 Xo Ic df 404.Op Fl hi 405.Op Ar path 406.Xc 407Display usage information for the filesystem holding the current directory 408(or 409.Ar path 410if specified). 411If the 412.Fl h 413flag is specified, the capacity information will be displayed using 414"human-readable" suffixes. 415The 416.Fl i 417flag requests display of inode information in addition to capacity information. 418This command is only supported on servers that implement the 419.Dq statvfs@openssh.com 420extension. 421.It Ic exit 422Quit 423.Nm sftp . 424.It Xo Ic get 425.Op Fl afpR 426.Ar remote-path 427.Op Ar local-path 428.Xc 429Retrieve the 430.Ar remote-path 431and store it on the local machine. 432If the local 433path name is not specified, it is given the same name it has on the 434remote machine. 435.Ar remote-path 436may contain 437.Xr glob 7 438characters and may match multiple files. 439If it does and 440.Ar local-path 441is specified, then 442.Ar local-path 443must specify a directory. 444.Pp 445If the 446.Fl a 447flag is specified, then attempt to resume partial transfers of existing files. 448Note that resumption assumes that any partial copy of the local file matches 449the remote copy. 450If the remote file contents differ from the partial local copy then the 451resultant file is likely to be corrupt. 452.Pp 453If the 454.Fl f 455flag is specified, then 456.Xr fsync 2 457will be called after the file transfer has completed to flush the file 458to disk. 459.Pp 460If the 461.Fl p 462.\" undocumented redundant alias 463.\" or 464.\" .Fl P 465flag is specified, then full file permissions and access times are 466copied too. 467.Pp 468If the 469.Fl R 470.\" undocumented redundant alias 471.\" or 472.\" .Fl r 473flag is specified then directories will be copied recursively. 474Note that 475.Nm 476does not follow symbolic links when performing recursive transfers. 477.It Ic help 478Display help text. 479.It Ic lcd Op Ar path 480Change local directory to 481.Ar path . 482If 483.Ar path 484is not specified, then change directory to the local user's home directory. 485.It Ic lls Op Ar ls-options Op Ar path 486Display local directory listing of either 487.Ar path 488or current directory if 489.Ar path 490is not specified. 491.Ar ls-options 492may contain any flags supported by the local system's 493.Xr ls 1 494command. 495.Ar path 496may contain 497.Xr glob 7 498characters and may match multiple files. 499.It Ic lmkdir Ar path 500Create local directory specified by 501.Ar path . 502.It Xo Ic ln 503.Op Fl s 504.Ar oldpath 505.Ar newpath 506.Xc 507Create a link from 508.Ar oldpath 509to 510.Ar newpath . 511If the 512.Fl s 513flag is specified the created link is a symbolic link, otherwise it is 514a hard link. 515.It Ic lpwd 516Print local working directory. 517.It Xo Ic ls 518.Op Fl 1afhlnrSt 519.Op Ar path 520.Xc 521Display a remote directory listing of either 522.Ar path 523or the current directory if 524.Ar path 525is not specified. 526.Ar path 527may contain 528.Xr glob 7 529characters and may match multiple files. 530.Pp 531The following flags are recognized and alter the behaviour of 532.Ic ls 533accordingly: 534.Bl -tag -width Ds 535.It Fl 1 536Produce single columnar output. 537.It Fl a 538List files beginning with a dot 539.Pq Sq \&. . 540.It Fl f 541Do not sort the listing. 542The default sort order is lexicographical. 543.It Fl h 544When used with a long format option, use unit suffixes: Byte, Kilobyte, 545Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce 546the number of digits to four or fewer using powers of 2 for sizes (K=1024, 547M=1048576, etc.). 548.It Fl l 549Display additional details including permissions 550and ownership information. 551.It Fl n 552Produce a long listing with user and group information presented 553numerically. 554.It Fl r 555Reverse the sort order of the listing. 556.It Fl S 557Sort the listing by file size. 558.It Fl t 559Sort the listing by last modification time. 560.El 561.It Ic lumask Ar umask 562Set local umask to 563.Ar umask . 564.It Ic mkdir Ar path 565Create remote directory specified by 566.Ar path . 567.It Ic progress 568Toggle display of progress meter. 569.It Xo Ic put 570.Op Fl afpR 571.Ar local-path 572.Op Ar remote-path 573.Xc 574Upload 575.Ar local-path 576and store it on the remote machine. 577If the remote path name is not specified, it is given the same name it has 578on the local machine. 579.Ar local-path 580may contain 581.Xr glob 7 582characters and may match multiple files. 583If it does and 584.Ar remote-path 585is specified, then 586.Ar remote-path 587must specify a directory. 588.Pp 589If the 590.Fl a 591flag is specified, then attempt to resume partial 592transfers of existing files. 593Note that resumption assumes that any partial copy of the remote file 594matches the local copy. 595If the local file contents differ from the remote local copy then 596the resultant file is likely to be corrupt. 597.Pp 598If the 599.Fl f 600flag is specified, then a request will be sent to the server to call 601.Xr fsync 2 602after the file has been transferred. 603Note that this is only supported by servers that implement 604the "fsync@openssh.com" extension. 605.Pp 606If the 607.Fl p 608.\" undocumented redundant alias 609.\" or 610.\" .Fl P 611flag is specified, then full file permissions and access times are 612copied too. 613.Pp 614If the 615.Fl R 616.\" undocumented redundant alias 617.\" or 618.\" .Fl r 619flag is specified then directories will be copied recursively. 620Note that 621.Nm 622does not follow symbolic links when performing recursive transfers. 623.It Ic pwd 624Display remote working directory. 625.It Ic quit 626Quit 627.Nm sftp . 628.It Xo Ic reget 629.Op Fl fpR 630.Ar remote-path 631.Op Ar local-path 632.Xc 633Resume download of 634.Ar remote-path . 635Equivalent to 636.Ic get 637with the 638.Fl a 639flag set. 640.It Xo Ic reput 641.Op Fl fpR 642.Ar local-path 643.Op Ar remote-path 644.Xc 645Resume upload of 646.Ar local-path . 647Equivalent to 648.Ic put 649with the 650.Fl a 651flag set. 652.It Ic rename Ar oldpath newpath 653Rename remote file from 654.Ar oldpath 655to 656.Ar newpath . 657.It Ic rm Ar path 658Delete remote file specified by 659.Ar path . 660.It Ic rmdir Ar path 661Remove remote directory specified by 662.Ar path . 663.It Ic symlink Ar oldpath newpath 664Create a symbolic link from 665.Ar oldpath 666to 667.Ar newpath . 668.It Ic version 669Display the 670.Nm 671protocol version. 672.It Ic \&! Ns Ar command 673Execute 674.Ar command 675in local shell. 676.It Ic \&! 677Escape to local shell. 678.It Ic \&? 679Synonym for help. 680.El 681.Sh SEE ALSO 682.Xr ftp 1 , 683.Xr ls 1 , 684.Xr scp 1 , 685.Xr ssh 1 , 686.Xr ssh-add 1 , 687.Xr ssh-keygen 1 , 688.Xr ssh_config 5 , 689.Xr glob 7 , 690.Xr sftp-server 8 , 691.Xr sshd 8 692.Rs 693.%A T. Ylonen 694.%A S. Lehtinen 695.%T "SSH File Transfer Protocol" 696.%N draft-ietf-secsh-filexfer-00.txt 697.%D January 2001 698.%O work in progress material 699.Re 700