1.\" $OpenBSD: sftp.1,v 1.141 2022/06/27 21:41:55 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: June 27 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 SendEnv 277.It ServerAliveInterval 278.It ServerAliveCountMax 279.It SetEnv 280.It StrictHostKeyChecking 281.It TCPKeepAlive 282.It UpdateHostKeys 283.It User 284.It UserKnownHostsFile 285.It VerifyHostKeyDNS 286.El 287.It Fl P Ar port 288Specifies the port to connect to on the remote host. 289.It Fl p 290Preserves modification times, access times, and modes from the 291original files transferred. 292.It Fl q 293Quiet mode: disables the progress meter as well as warning and 294diagnostic messages from 295.Xr ssh 1 . 296.It Fl R Ar num_requests 297Specify how many requests may be outstanding at any one time. 298Increasing this may slightly improve file transfer speed 299but will increase memory usage. 300The default is 64 outstanding requests. 301.It Fl r 302Recursively copy entire directories when uploading and downloading. 303Note that 304.Nm 305does not follow symbolic links encountered in the tree traversal. 306.It Fl S Ar program 307Name of the 308.Ar program 309to use for the encrypted connection. 310The program must understand 311.Xr ssh 1 312options. 313.It Fl s Ar subsystem | sftp_server 314Specifies the SSH2 subsystem or the path for an sftp server 315on the remote host. 316A path is useful when the remote 317.Xr sshd 8 318does not have an sftp subsystem configured. 319.It Fl v 320Raise logging level. 321This option is also passed to ssh. 322.El 323.Sh INTERACTIVE COMMANDS 324Once in interactive mode, 325.Nm 326understands a set of commands similar to those of 327.Xr ftp 1 . 328Commands are case insensitive. 329Pathnames that contain spaces must be enclosed in quotes. 330Any special characters contained within pathnames that are recognized by 331.Xr glob 3 332must be escaped with backslashes 333.Pq Sq \e . 334.Bl -tag -width Ds 335.It Ic bye 336Quit 337.Nm sftp . 338.It Ic cd Op Ar path 339Change remote directory to 340.Ar path . 341If 342.Ar path 343is not specified, then change directory to the one the session started in. 344.It Xo Ic chgrp 345.Op Fl h 346.Ar grp 347.Ar path 348.Xc 349Change group of file 350.Ar path 351to 352.Ar grp . 353.Ar path 354may contain 355.Xr glob 7 356characters and may match multiple files. 357.Ar grp 358must be a numeric GID. 359.Pp 360If the 361.Fl h 362flag is specified, then symlinks will not be followed. 363Note that this is only supported by servers that implement 364the "lsetstat@openssh.com" extension. 365.It Xo Ic chmod 366.Op Fl h 367.Ar mode 368.Ar path 369.Xc 370Change permissions of file 371.Ar path 372to 373.Ar mode . 374.Ar path 375may contain 376.Xr glob 7 377characters and may match multiple files. 378.Pp 379If the 380.Fl h 381flag is specified, then symlinks will not be followed. 382Note that this is only supported by servers that implement 383the "lsetstat@openssh.com" extension. 384.It Xo Ic chown 385.Op Fl h 386.Ar own 387.Ar path 388.Xc 389Change owner of file 390.Ar path 391to 392.Ar own . 393.Ar path 394may contain 395.Xr glob 7 396characters and may match multiple files. 397.Ar own 398must be a numeric UID. 399.Pp 400If the 401.Fl h 402flag is specified, then symlinks will not be followed. 403Note that this is only supported by servers that implement 404the "lsetstat@openssh.com" extension. 405.It Ic copy Ar oldpath Ar newpath 406Copy remote file from 407.Ar oldpath 408to 409.Ar newpath . 410.Pp 411Note that this is only supported by servers that implement the "copy-data" 412extension. 413.It Ic cp Ar oldpath Ar newpath 414Alias to 415.Ic copy 416command. 417.It Xo Ic df 418.Op Fl hi 419.Op Ar path 420.Xc 421Display usage information for the filesystem holding the current directory 422(or 423.Ar path 424if specified). 425If the 426.Fl h 427flag is specified, the capacity information will be displayed using 428"human-readable" suffixes. 429The 430.Fl i 431flag requests display of inode information in addition to capacity information. 432This command is only supported on servers that implement the 433.Dq statvfs@openssh.com 434extension. 435.It Ic exit 436Quit 437.Nm sftp . 438.It Xo Ic get 439.Op Fl afpR 440.Ar remote-path 441.Op Ar local-path 442.Xc 443Retrieve the 444.Ar remote-path 445and store it on the local machine. 446If the local 447path name is not specified, it is given the same name it has on the 448remote machine. 449.Ar remote-path 450may contain 451.Xr glob 7 452characters and may match multiple files. 453If it does and 454.Ar local-path 455is specified, then 456.Ar local-path 457must specify a directory. 458.Pp 459If the 460.Fl a 461flag is specified, then attempt to resume partial transfers of existing files. 462Note that resumption assumes that any partial copy of the local file matches 463the remote copy. 464If the remote file contents differ from the partial local copy then the 465resultant file is likely to be corrupt. 466.Pp 467If the 468.Fl f 469flag is specified, then 470.Xr fsync 2 471will be called after the file transfer has completed to flush the file 472to disk. 473.Pp 474If the 475.Fl p 476.\" undocumented redundant alias 477.\" or 478.\" .Fl P 479flag is specified, then full file permissions and access times are 480copied too. 481.Pp 482If the 483.Fl R 484.\" undocumented redundant alias 485.\" or 486.\" .Fl r 487flag is specified then directories will be copied recursively. 488Note that 489.Nm 490does not follow symbolic links when performing recursive transfers. 491.It Ic help 492Display help text. 493.It Ic lcd Op Ar path 494Change local directory to 495.Ar path . 496If 497.Ar path 498is not specified, then change directory to the local user's home directory. 499.It Ic lls Op Ar ls-options Op Ar path 500Display local directory listing of either 501.Ar path 502or current directory if 503.Ar path 504is not specified. 505.Ar ls-options 506may contain any flags supported by the local system's 507.Xr ls 1 508command. 509.Ar path 510may contain 511.Xr glob 7 512characters and may match multiple files. 513.It Ic lmkdir Ar path 514Create local directory specified by 515.Ar path . 516.It Xo Ic ln 517.Op Fl s 518.Ar oldpath 519.Ar newpath 520.Xc 521Create a link from 522.Ar oldpath 523to 524.Ar newpath . 525If the 526.Fl s 527flag is specified the created link is a symbolic link, otherwise it is 528a hard link. 529.It Ic lpwd 530Print local working directory. 531.It Xo Ic ls 532.Op Fl 1afhlnrSt 533.Op Ar path 534.Xc 535Display a remote directory listing of either 536.Ar path 537or the current directory if 538.Ar path 539is not specified. 540.Ar path 541may contain 542.Xr glob 7 543characters and may match multiple files. 544.Pp 545The following flags are recognized and alter the behaviour of 546.Ic ls 547accordingly: 548.Bl -tag -width Ds 549.It Fl 1 550Produce single columnar output. 551.It Fl a 552List files beginning with a dot 553.Pq Sq \&. . 554.It Fl f 555Do not sort the listing. 556The default sort order is lexicographical. 557.It Fl h 558When used with a long format option, use unit suffixes: Byte, Kilobyte, 559Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce 560the number of digits to four or fewer using powers of 2 for sizes (K=1024, 561M=1048576, etc.). 562.It Fl l 563Display additional details including permissions 564and ownership information. 565.It Fl n 566Produce a long listing with user and group information presented 567numerically. 568.It Fl r 569Reverse the sort order of the listing. 570.It Fl S 571Sort the listing by file size. 572.It Fl t 573Sort the listing by last modification time. 574.El 575.It Ic lumask Ar umask 576Set local umask to 577.Ar umask . 578.It Ic mkdir Ar path 579Create remote directory specified by 580.Ar path . 581.It Ic progress 582Toggle display of progress meter. 583.It Xo Ic put 584.Op Fl afpR 585.Ar local-path 586.Op Ar remote-path 587.Xc 588Upload 589.Ar local-path 590and store it on the remote machine. 591If the remote path name is not specified, it is given the same name it has 592on the local machine. 593.Ar local-path 594may contain 595.Xr glob 7 596characters and may match multiple files. 597If it does and 598.Ar remote-path 599is specified, then 600.Ar remote-path 601must specify a directory. 602.Pp 603If the 604.Fl a 605flag is specified, then attempt to resume partial 606transfers of existing files. 607Note that resumption assumes that any partial copy of the remote file 608matches the local copy. 609If the local file contents differ from the remote local copy then 610the resultant file is likely to be corrupt. 611.Pp 612If the 613.Fl f 614flag is specified, then a request will be sent to the server to call 615.Xr fsync 2 616after the file has been transferred. 617Note that this is only supported by servers that implement 618the "fsync@openssh.com" extension. 619.Pp 620If the 621.Fl p 622.\" undocumented redundant alias 623.\" or 624.\" .Fl P 625flag is specified, then full file permissions and access times are 626copied too. 627.Pp 628If the 629.Fl R 630.\" undocumented redundant alias 631.\" or 632.\" .Fl r 633flag is specified then directories will be copied recursively. 634Note that 635.Nm 636does not follow symbolic links when performing recursive transfers. 637.It Ic pwd 638Display remote working directory. 639.It Ic quit 640Quit 641.Nm sftp . 642.It Xo Ic reget 643.Op Fl fpR 644.Ar remote-path 645.Op Ar local-path 646.Xc 647Resume download of 648.Ar remote-path . 649Equivalent to 650.Ic get 651with the 652.Fl a 653flag set. 654.It Xo Ic reput 655.Op Fl fpR 656.Ar local-path 657.Op Ar remote-path 658.Xc 659Resume upload of 660.Ar local-path . 661Equivalent to 662.Ic put 663with the 664.Fl a 665flag set. 666.It Ic rename Ar oldpath newpath 667Rename remote file from 668.Ar oldpath 669to 670.Ar newpath . 671.It Ic rm Ar path 672Delete remote file specified by 673.Ar path . 674.It Ic rmdir Ar path 675Remove remote directory specified by 676.Ar path . 677.It Ic symlink Ar oldpath newpath 678Create a symbolic link from 679.Ar oldpath 680to 681.Ar newpath . 682.It Ic version 683Display the 684.Nm 685protocol version. 686.It Ic \&! Ns Ar command 687Execute 688.Ar command 689in local shell. 690.It Ic \&! 691Escape to local shell. 692.It Ic \&? 693Synonym for help. 694.El 695.Sh SEE ALSO 696.Xr ftp 1 , 697.Xr ls 1 , 698.Xr scp 1 , 699.Xr ssh 1 , 700.Xr ssh-add 1 , 701.Xr ssh-keygen 1 , 702.Xr ssh_config 5 , 703.Xr glob 7 , 704.Xr sftp-server 8 , 705.Xr sshd 8 706.Rs 707.%A T. Ylonen 708.%A S. Lehtinen 709.%T "SSH File Transfer Protocol" 710.%N draft-ietf-secsh-filexfer-00.txt 711.%D January 2001 712.%O work in progress material 713.Re 714