1.\" $OpenBSD: sftp.1,v 1.142 2022/09/19 21:39:16 djm 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: September 19 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_command 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_command 171Connect directly to a local sftp server 172(rather than via 173.Xr ssh 1 ) . 174A command and arguments may be specified, for example 175.Qq /path/sftp-server -el debug3 . 176This option may be useful in debugging the client and server. 177.It Fl F Ar ssh_config 178Specifies an alternative 179per-user configuration file for 180.Xr ssh 1 . 181This option is directly passed to 182.Xr ssh 1 . 183.It Fl f 184Requests that files be flushed to disk immediately after transfer. 185When uploading files, this feature is only enabled if the server 186implements the "fsync@openssh.com" extension. 187.It Fl i Ar identity_file 188Selects the file from which the identity (private key) for public key 189authentication is read. 190This option is directly passed to 191.Xr ssh 1 . 192.It Fl J Ar destination 193Connect to the target host by first making an 194.Nm 195connection to the jump host described by 196.Ar destination 197and then establishing a TCP forwarding to the ultimate destination from 198there. 199Multiple jump hops may be specified separated by comma characters. 200This is a shortcut to specify a 201.Cm ProxyJump 202configuration directive. 203This option is directly passed to 204.Xr ssh 1 . 205.It Fl l Ar limit 206Limits the used bandwidth, specified in Kbit/s. 207.It Fl N 208Disables quiet mode, e.g. to override the implicit quiet mode set by the 209.Fl b 210flag. 211.It Fl o Ar ssh_option 212Can be used to pass options to 213.Nm ssh 214in the format used in 215.Xr ssh_config 5 . 216This is useful for specifying options 217for which there is no separate 218.Nm sftp 219command-line flag. 220For example, to specify an alternate port use: 221.Ic sftp -oPort=24 . 222For full details of the options listed below, and their possible values, see 223.Xr ssh_config 5 . 224.Pp 225.Bl -tag -width Ds -offset indent -compact 226.It AddressFamily 227.It BatchMode 228.It BindAddress 229.It BindInterface 230.It CanonicalDomains 231.It CanonicalizeFallbackLocal 232.It CanonicalizeHostname 233.It CanonicalizeMaxDots 234.It CanonicalizePermittedCNAMEs 235.It CASignatureAlgorithms 236.It CertificateFile 237.It CheckHostIP 238.It Ciphers 239.It Compression 240.It ConnectionAttempts 241.It ConnectTimeout 242.It ControlMaster 243.It ControlPath 244.It ControlPersist 245.It GlobalKnownHostsFile 246.It GSSAPIAuthentication 247.It GSSAPIDelegateCredentials 248.It HashKnownHosts 249.It Host 250.It HostbasedAcceptedAlgorithms 251.It HostbasedAuthentication 252.It HostKeyAlgorithms 253.It HostKeyAlias 254.It Hostname 255.It IdentitiesOnly 256.It IdentityAgent 257.It IdentityFile 258.It IPQoS 259.It KbdInteractiveAuthentication 260.It KbdInteractiveDevices 261.It KexAlgorithms 262.It KnownHostsCommand 263.It LogLevel 264.It MACs 265.It NoHostAuthenticationForLocalhost 266.It NumberOfPasswordPrompts 267.It PasswordAuthentication 268.It PKCS11Provider 269.It Port 270.It PreferredAuthentications 271.It ProxyCommand 272.It ProxyJump 273.It PubkeyAcceptedAlgorithms 274.It PubkeyAuthentication 275.It RekeyLimit 276.It RequiredRSASize 277.It SendEnv 278.It ServerAliveInterval 279.It ServerAliveCountMax 280.It SetEnv 281.It StrictHostKeyChecking 282.It TCPKeepAlive 283.It UpdateHostKeys 284.It User 285.It UserKnownHostsFile 286.It VerifyHostKeyDNS 287.El 288.It Fl P Ar port 289Specifies the port to connect to on the remote host. 290.It Fl p 291Preserves modification times, access times, and modes from the 292original files transferred. 293.It Fl q 294Quiet mode: disables the progress meter as well as warning and 295diagnostic messages from 296.Xr ssh 1 . 297.It Fl R Ar num_requests 298Specify how many requests may be outstanding at any one time. 299Increasing this may slightly improve file transfer speed 300but will increase memory usage. 301The default is 64 outstanding requests. 302.It Fl r 303Recursively copy entire directories when uploading and downloading. 304Note that 305.Nm 306does not follow symbolic links encountered in the tree traversal. 307.It Fl S Ar program 308Name of the 309.Ar program 310to use for the encrypted connection. 311The program must understand 312.Xr ssh 1 313options. 314.It Fl s Ar subsystem | sftp_server 315Specifies the SSH2 subsystem or the path for an sftp server 316on the remote host. 317A path is useful when the remote 318.Xr sshd 8 319does not have an sftp subsystem configured. 320.It Fl v 321Raise logging level. 322This option is also passed to ssh. 323.El 324.Sh INTERACTIVE COMMANDS 325Once in interactive mode, 326.Nm 327understands a set of commands similar to those of 328.Xr ftp 1 . 329Commands are case insensitive. 330Pathnames that contain spaces must be enclosed in quotes. 331Any special characters contained within pathnames that are recognized by 332.Xr glob 3 333must be escaped with backslashes 334.Pq Sq \e . 335.Bl -tag -width Ds 336.It Ic bye 337Quit 338.Nm sftp . 339.It Ic cd Op Ar path 340Change remote directory to 341.Ar path . 342If 343.Ar path 344is not specified, then change directory to the one the session started in. 345.It Xo Ic chgrp 346.Op Fl h 347.Ar grp 348.Ar path 349.Xc 350Change group of file 351.Ar path 352to 353.Ar grp . 354.Ar path 355may contain 356.Xr glob 7 357characters and may match multiple files. 358.Ar grp 359must be a numeric GID. 360.Pp 361If the 362.Fl h 363flag is specified, then symlinks will not be followed. 364Note that this is only supported by servers that implement 365the "lsetstat@openssh.com" extension. 366.It Xo Ic chmod 367.Op Fl h 368.Ar mode 369.Ar path 370.Xc 371Change permissions of file 372.Ar path 373to 374.Ar mode . 375.Ar path 376may contain 377.Xr glob 7 378characters and may match multiple files. 379.Pp 380If the 381.Fl h 382flag is specified, then symlinks will not be followed. 383Note that this is only supported by servers that implement 384the "lsetstat@openssh.com" extension. 385.It Xo Ic chown 386.Op Fl h 387.Ar own 388.Ar path 389.Xc 390Change owner of file 391.Ar path 392to 393.Ar own . 394.Ar path 395may contain 396.Xr glob 7 397characters and may match multiple files. 398.Ar own 399must be a numeric UID. 400.Pp 401If the 402.Fl h 403flag is specified, then symlinks will not be followed. 404Note that this is only supported by servers that implement 405the "lsetstat@openssh.com" extension. 406.It Ic copy Ar oldpath Ar newpath 407Copy remote file from 408.Ar oldpath 409to 410.Ar newpath . 411.Pp 412Note that this is only supported by servers that implement the "copy-data" 413extension. 414.It Ic cp Ar oldpath Ar newpath 415Alias to 416.Ic copy 417command. 418.It Xo Ic df 419.Op Fl hi 420.Op Ar path 421.Xc 422Display usage information for the filesystem holding the current directory 423(or 424.Ar path 425if specified). 426If the 427.Fl h 428flag is specified, the capacity information will be displayed using 429"human-readable" suffixes. 430The 431.Fl i 432flag requests display of inode information in addition to capacity information. 433This command is only supported on servers that implement the 434.Dq statvfs@openssh.com 435extension. 436.It Ic exit 437Quit 438.Nm sftp . 439.It Xo Ic get 440.Op Fl afpR 441.Ar remote-path 442.Op Ar local-path 443.Xc 444Retrieve the 445.Ar remote-path 446and store it on the local machine. 447If the local 448path name is not specified, it is given the same name it has on the 449remote machine. 450.Ar remote-path 451may contain 452.Xr glob 7 453characters and may match multiple files. 454If it does and 455.Ar local-path 456is specified, then 457.Ar local-path 458must specify a directory. 459.Pp 460If the 461.Fl a 462flag is specified, then attempt to resume partial transfers of existing files. 463Note that resumption assumes that any partial copy of the local file matches 464the remote copy. 465If the remote file contents differ from the partial local copy then the 466resultant file is likely to be corrupt. 467.Pp 468If the 469.Fl f 470flag is specified, then 471.Xr fsync 2 472will be called after the file transfer has completed to flush the file 473to disk. 474.Pp 475If the 476.Fl p 477.\" undocumented redundant alias 478.\" or 479.\" .Fl P 480flag is specified, then full file permissions and access times are 481copied too. 482.Pp 483If the 484.Fl R 485.\" undocumented redundant alias 486.\" or 487.\" .Fl r 488flag is specified then directories will be copied recursively. 489Note that 490.Nm 491does not follow symbolic links when performing recursive transfers. 492.It Ic help 493Display help text. 494.It Ic lcd Op Ar path 495Change local directory to 496.Ar path . 497If 498.Ar path 499is not specified, then change directory to the local user's home directory. 500.It Ic lls Op Ar ls-options Op Ar path 501Display local directory listing of either 502.Ar path 503or current directory if 504.Ar path 505is not specified. 506.Ar ls-options 507may contain any flags supported by the local system's 508.Xr ls 1 509command. 510.Ar path 511may contain 512.Xr glob 7 513characters and may match multiple files. 514.It Ic lmkdir Ar path 515Create local directory specified by 516.Ar path . 517.It Xo Ic ln 518.Op Fl s 519.Ar oldpath 520.Ar newpath 521.Xc 522Create a link from 523.Ar oldpath 524to 525.Ar newpath . 526If the 527.Fl s 528flag is specified the created link is a symbolic link, otherwise it is 529a hard link. 530.It Ic lpwd 531Print local working directory. 532.It Xo Ic ls 533.Op Fl 1afhlnrSt 534.Op Ar path 535.Xc 536Display a remote directory listing of either 537.Ar path 538or the current directory if 539.Ar path 540is not specified. 541.Ar path 542may contain 543.Xr glob 7 544characters and may match multiple files. 545.Pp 546The following flags are recognized and alter the behaviour of 547.Ic ls 548accordingly: 549.Bl -tag -width Ds 550.It Fl 1 551Produce single columnar output. 552.It Fl a 553List files beginning with a dot 554.Pq Sq \&. . 555.It Fl f 556Do not sort the listing. 557The default sort order is lexicographical. 558.It Fl h 559When used with a long format option, use unit suffixes: Byte, Kilobyte, 560Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce 561the number of digits to four or fewer using powers of 2 for sizes (K=1024, 562M=1048576, etc.). 563.It Fl l 564Display additional details including permissions 565and ownership information. 566.It Fl n 567Produce a long listing with user and group information presented 568numerically. 569.It Fl r 570Reverse the sort order of the listing. 571.It Fl S 572Sort the listing by file size. 573.It Fl t 574Sort the listing by last modification time. 575.El 576.It Ic lumask Ar umask 577Set local umask to 578.Ar umask . 579.It Ic mkdir Ar path 580Create remote directory specified by 581.Ar path . 582.It Ic progress 583Toggle display of progress meter. 584.It Xo Ic put 585.Op Fl afpR 586.Ar local-path 587.Op Ar remote-path 588.Xc 589Upload 590.Ar local-path 591and store it on the remote machine. 592If the remote path name is not specified, it is given the same name it has 593on the local machine. 594.Ar local-path 595may contain 596.Xr glob 7 597characters and may match multiple files. 598If it does and 599.Ar remote-path 600is specified, then 601.Ar remote-path 602must specify a directory. 603.Pp 604If the 605.Fl a 606flag is specified, then attempt to resume partial 607transfers of existing files. 608Note that resumption assumes that any partial copy of the remote file 609matches the local copy. 610If the local file contents differ from the remote local copy then 611the resultant file is likely to be corrupt. 612.Pp 613If the 614.Fl f 615flag is specified, then a request will be sent to the server to call 616.Xr fsync 2 617after the file has been transferred. 618Note that this is only supported by servers that implement 619the "fsync@openssh.com" extension. 620.Pp 621If the 622.Fl p 623.\" undocumented redundant alias 624.\" or 625.\" .Fl P 626flag is specified, then full file permissions and access times are 627copied too. 628.Pp 629If the 630.Fl R 631.\" undocumented redundant alias 632.\" or 633.\" .Fl r 634flag is specified then directories will be copied recursively. 635Note that 636.Nm 637does not follow symbolic links when performing recursive transfers. 638.It Ic pwd 639Display remote working directory. 640.It Ic quit 641Quit 642.Nm sftp . 643.It Xo Ic reget 644.Op Fl fpR 645.Ar remote-path 646.Op Ar local-path 647.Xc 648Resume download of 649.Ar remote-path . 650Equivalent to 651.Ic get 652with the 653.Fl a 654flag set. 655.It Xo Ic reput 656.Op Fl fpR 657.Ar local-path 658.Op Ar remote-path 659.Xc 660Resume upload of 661.Ar local-path . 662Equivalent to 663.Ic put 664with the 665.Fl a 666flag set. 667.It Ic rename Ar oldpath newpath 668Rename remote file from 669.Ar oldpath 670to 671.Ar newpath . 672.It Ic rm Ar path 673Delete remote file specified by 674.Ar path . 675.It Ic rmdir Ar path 676Remove remote directory specified by 677.Ar path . 678.It Ic symlink Ar oldpath newpath 679Create a symbolic link from 680.Ar oldpath 681to 682.Ar newpath . 683.It Ic version 684Display the 685.Nm 686protocol version. 687.It Ic \&! Ns Ar command 688Execute 689.Ar command 690in local shell. 691.It Ic \&! 692Escape to local shell. 693.It Ic \&? 694Synonym for help. 695.El 696.Sh SEE ALSO 697.Xr ftp 1 , 698.Xr ls 1 , 699.Xr scp 1 , 700.Xr ssh 1 , 701.Xr ssh-add 1 , 702.Xr ssh-keygen 1 , 703.Xr ssh_config 5 , 704.Xr glob 7 , 705.Xr sftp-server 8 , 706.Xr sshd 8 707.Rs 708.%A T. Ylonen 709.%A S. Lehtinen 710.%T "SSH File Transfer Protocol" 711.%N draft-ietf-secsh-filexfer-00.txt 712.%D January 2001 713.%O work in progress material 714.Re 715