sftp.1 (18055B)
- .\" $OpenBSD: sftp.1,v 1.144 2024/12/06 15:12:56 djm Exp $
- .\"
- .\" Copyright (c) 2001 Damien Miller. All rights reserved.
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
- .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
- .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
- .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
- .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
- .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- .\"
- .Dd $Mdocdate: December 6 2024 $
- .Dt SFTP 1
- .Os
- .Sh NAME
- .Nm sftp
- .Nd OpenSSH secure file transfer
- .Sh SYNOPSIS
- .Nm sftp
- .Op Fl 46AaCfNpqrv
- .Op Fl B Ar buffer_size
- .Op Fl b Ar batchfile
- .Op Fl c Ar cipher
- .Op Fl D Ar sftp_server_command
- .Op Fl F Ar ssh_config
- .Op Fl i Ar identity_file
- .Op Fl J Ar destination
- .Op Fl l Ar limit
- .Op Fl o Ar ssh_option
- .Op Fl P Ar port
- .Op Fl R Ar num_requests
- .Op Fl S Ar program
- .Op Fl s Ar subsystem | sftp_server
- .Op Fl X Ar sftp_option
- .Ar destination
- .Sh DESCRIPTION
- .Nm
- is a file transfer program, similar to
- .Xr ftp 1 ,
- which performs all operations over an encrypted
- .Xr ssh 1
- transport.
- It may also use many features of ssh, such as public key authentication and
- compression.
- .Pp
- The
- .Ar destination
- may be specified either as
- .Sm off
- .Oo user @ Oc host Op : path
- .Sm on
- or as a URI in the form
- .Sm off
- .No sftp:// Oo user @ Oc host Oo : port Oc Op / path .
- .Sm on
- .Pp
- If the
- .Ar destination
- includes a
- .Ar path
- and it is not a directory,
- .Nm
- will retrieve files automatically if a non-interactive
- authentication method is used; otherwise it will do so after
- successful interactive authentication.
- .Pp
- If no
- .Ar path
- is specified, or if the
- .Ar path
- is a directory,
- .Nm
- will log in to the specified
- .Ar host
- and enter interactive command mode, changing to the remote directory
- if one was specified.
- An optional trailing slash can be used to force the
- .Ar path
- to be interpreted as a directory.
- .Pp
- Since the destination formats use colon characters to delimit host
- names from path names or port numbers, IPv6 addresses must be
- enclosed in square brackets to avoid ambiguity.
- .Pp
- The options are as follows:
- .Bl -tag -width Ds
- .It Fl 4
- Forces
- .Nm
- to use IPv4 addresses only.
- .It Fl 6
- Forces
- .Nm
- to use IPv6 addresses only.
- .It Fl A
- Allows forwarding of
- .Xr ssh-agent 1
- to the remote system.
- The default is not to forward an authentication agent.
- .It Fl a
- Attempt to continue interrupted transfers rather than overwriting
- existing partial or complete copies of files.
- If the partial contents differ from those being transferred,
- then the resultant file is likely to be corrupt.
- .It Fl B Ar buffer_size
- Specify the size of the buffer that
- .Nm
- uses when transferring files.
- Larger buffers require fewer round trips at the cost of higher
- memory consumption.
- The default is 32768 bytes.
- .It Fl b Ar batchfile
- Batch mode reads a series of commands from an input
- .Ar batchfile
- instead of
- .Em stdin .
- Since it lacks user interaction, it should be used in conjunction with
- non-interactive authentication to obviate the need to enter a password
- at connection time (see
- .Xr sshd 8
- and
- .Xr ssh-keygen 1
- for details).
- .Pp
- A
- .Ar batchfile
- of
- .Sq \-
- may be used to indicate standard input.
- .Nm
- will abort if any of the following
- commands fail:
- .Ic get , put , reget , reput , rename , ln ,
- .Ic rm , mkdir , chdir , ls ,
- .Ic lchdir , copy , cp , chmod , chown ,
- .Ic chgrp , lpwd , df , symlink ,
- and
- .Ic lmkdir .
- .Pp
- Termination on error can be suppressed on a command by command basis by
- prefixing the command with a
- .Sq \-
- character (for example,
- .Ic -rm /tmp/blah* ) .
- Echo of the command may be suppressed by prefixing the command with a
- .Sq @
- character.
- These two prefixes may be combined in any order, for example
- .Ic -@ls /bsd .
- .It Fl C
- Enables compression (via ssh's
- .Fl C
- flag).
- .It Fl c Ar cipher
- Selects the cipher to use for encrypting the data transfers.
- This option is directly passed to
- .Xr ssh 1 .
- .It Fl D Ar sftp_server_command
- Connect directly to a local sftp server
- (rather than via
- .Xr ssh 1 ) .
- A command and arguments may be specified, for example
- .Qq /path/sftp-server -el debug3 .
- This option may be useful in debugging the client and server.
- .It Fl F Ar ssh_config
- Specifies an alternative
- per-user configuration file for
- .Xr ssh 1 .
- This option is directly passed to
- .Xr ssh 1 .
- .It Fl f
- Requests that files be flushed to disk immediately after transfer.
- When uploading files, this feature is only enabled if the server
- implements the "fsync@openssh.com" extension.
- .It Fl i Ar identity_file
- Selects the file from which the identity (private key) for public key
- authentication is read.
- This option is directly passed to
- .Xr ssh 1 .
- .It Fl J Ar destination
- Connect to the target host by first making an
- .Nm
- connection to the jump host described by
- .Ar destination
- and then establishing a TCP forwarding to the ultimate destination from
- there.
- Multiple jump hops may be specified separated by comma characters.
- This is a shortcut to specify a
- .Cm ProxyJump
- configuration directive.
- This option is directly passed to
- .Xr ssh 1 .
- .It Fl l Ar limit
- Limits the used bandwidth, specified in Kbit/s.
- .It Fl N
- Disables quiet mode, e.g. to override the implicit quiet mode set by the
- .Fl b
- flag.
- .It Fl o Ar ssh_option
- Can be used to pass options to
- .Nm ssh
- in the format used in
- .Xr ssh_config 5 .
- This is useful for specifying options
- for which there is no separate
- .Nm sftp
- command-line flag.
- For example, to specify an alternate port use:
- .Ic sftp -oPort=24 .
- For full details of the options listed below, and their possible values, see
- .Xr ssh_config 5 .
- .Pp
- .Bl -tag -width Ds -offset indent -compact
- .It AddKeysToAgent
- .It AddressFamily
- .It BatchMode
- .It BindAddress
- .It BindInterface
- .It CASignatureAlgorithms
- .It CanonicalDomains
- .It CanonicalizeFallbackLocal
- .It CanonicalizeHostname
- .It CanonicalizeMaxDots
- .It CanonicalizePermittedCNAMEs
- .It CertificateFile
- .It ChannelTimeout
- .It CheckHostIP
- .It Ciphers
- .It ClearAllForwardings
- .It Compression
- .It ConnectTimeout
- .It ConnectionAttempts
- .It ControlMaster
- .It ControlPath
- .It ControlPersist
- .It DynamicForward
- .It EnableEscapeCommandline
- .It EnableSSHKeysign
- .It EscapeChar
- .It ExitOnForwardFailure
- .It FingerprintHash
- .It ForkAfterAuthentication
- .It ForwardAgent
- .It ForwardX11
- .It ForwardX11Timeout
- .It ForwardX11Trusted
- .It GSSAPIAuthentication
- .It GSSAPIDelegateCredentials
- .It GatewayPorts
- .It GlobalKnownHostsFile
- .It HashKnownHosts
- .It Host
- .It HostKeyAlgorithms
- .It HostKeyAlias
- .It HostbasedAcceptedAlgorithms
- .It HostbasedAuthentication
- .It Hostname
- .It IPQoS
- .It IdentitiesOnly
- .It IdentityAgent
- .It IdentityFile
- .It IgnoreUnknown
- .It Include
- .It KbdInteractiveAuthentication
- .It KbdInteractiveDevices
- .It KexAlgorithms
- .It KnownHostsCommand
- .It LocalCommand
- .It LocalForward
- .It LogLevel
- .It LogVerbose
- .It MACs
- .It NoHostAuthenticationForLocalhost
- .It NumberOfPasswordPrompts
- .It ObscureKeystrokeTiming
- .It PKCS11Provider
- .It PasswordAuthentication
- .It PermitLocalCommand
- .It PermitRemoteOpen
- .It Port
- .It PreferredAuthentications
- .It ProxyCommand
- .It ProxyJump
- .It ProxyUseFdpass
- .It PubkeyAcceptedAlgorithms
- .It PubkeyAuthentication
- .It RekeyLimit
- .It RemoteCommand
- .It RemoteForward
- .It RequestTTY
- .It RequiredRSASize
- .It RevokedHostKeys
- .It SecurityKeyProvider
- .It SendEnv
- .It ServerAliveCountMax
- .It ServerAliveInterval
- .It SessionType
- .It SetEnv
- .It StdinNull
- .It StreamLocalBindMask
- .It StreamLocalBindUnlink
- .It StrictHostKeyChecking
- .It SyslogFacility
- .It TCPKeepAlive
- .It Tag
- .It Tunnel
- .It TunnelDevice
- .It UpdateHostKeys
- .It User
- .It UserKnownHostsFile
- .It VerifyHostKeyDNS
- .It VisualHostKey
- .It XAuthLocation
- .El
- .It Fl P Ar port
- Specifies the port to connect to on the remote host.
- .It Fl p
- Preserves modification times, access times, and modes from the
- original files transferred.
- .It Fl q
- Quiet mode: disables the progress meter as well as warning and
- diagnostic messages from
- .Xr ssh 1 .
- .It Fl R Ar num_requests
- Specify how many requests may be outstanding at any one time.
- Increasing this may slightly improve file transfer speed
- but will increase memory usage.
- The default is 64 outstanding requests.
- .It Fl r
- Recursively copy entire directories when uploading and downloading.
- Note that
- .Nm
- does not follow symbolic links encountered in the tree traversal.
- .It Fl S Ar program
- Name of the
- .Ar program
- to use for the encrypted connection.
- The program must understand
- .Xr ssh 1
- options.
- .It Fl s Ar subsystem | sftp_server
- Specifies the SSH2 subsystem or the path for an sftp server
- on the remote host.
- A path is useful when the remote
- .Xr sshd 8
- does not have an sftp subsystem configured.
- .It Fl v
- Raise logging level.
- This option is also passed to ssh.
- .It Fl X Ar sftp_option
- Specify an option that controls aspects of SFTP protocol behaviour.
- The valid options are:
- .Bl -tag -width Ds
- .It Cm nrequests Ns = Ns Ar value
- Controls how many concurrent SFTP read or write requests may be in progress
- at any point in time during a download or upload.
- By default 64 requests may be active concurrently.
- .It Cm buffer Ns = Ns Ar value
- Controls the maximum buffer size for a single SFTP read/write operation used
- during download or upload.
- By default a 32KB buffer is used.
- .El
- .El
- .Sh INTERACTIVE COMMANDS
- Once in interactive mode,
- .Nm
- understands a set of commands similar to those of
- .Xr ftp 1 .
- Commands are case insensitive.
- Pathnames that contain spaces must be enclosed in quotes.
- Any special characters contained within pathnames that are recognized by
- .Xr glob 3
- must be escaped with backslashes
- .Pq Sq \e .
- .Bl -tag -width Ds
- .It Ic bye
- Quit
- .Nm sftp .
- .It Ic cd Op Ar path
- Change remote directory to
- .Ar path .
- If
- .Ar path
- is not specified, then change directory to the one the session started in.
- .It Xo Ic chgrp
- .Op Fl h
- .Ar grp
- .Ar path
- .Xc
- Change group of file
- .Ar path
- to
- .Ar grp .
- .Ar path
- may contain
- .Xr glob 7
- characters and may match multiple files.
- .Ar grp
- must be a numeric GID.
- .Pp
- If the
- .Fl h
- flag is specified, then symlinks will not be followed.
- Note that this is only supported by servers that implement
- the "lsetstat@openssh.com" extension.
- .It Xo Ic chmod
- .Op Fl h
- .Ar mode
- .Ar path
- .Xc
- Change permissions of file
- .Ar path
- to
- .Ar mode .
- .Ar path
- may contain
- .Xr glob 7
- characters and may match multiple files.
- .Pp
- If the
- .Fl h
- flag is specified, then symlinks will not be followed.
- Note that this is only supported by servers that implement
- the "lsetstat@openssh.com" extension.
- .It Xo Ic chown
- .Op Fl h
- .Ar own
- .Ar path
- .Xc
- Change owner of file
- .Ar path
- to
- .Ar own .
- .Ar path
- may contain
- .Xr glob 7
- characters and may match multiple files.
- .Ar own
- must be a numeric UID.
- .Pp
- If the
- .Fl h
- flag is specified, then symlinks will not be followed.
- Note that this is only supported by servers that implement
- the "lsetstat@openssh.com" extension.
- .It Ic copy Ar oldpath Ar newpath
- Copy remote file from
- .Ar oldpath
- to
- .Ar newpath .
- .Pp
- Note that this is only supported by servers that implement the "copy-data"
- extension.
- .It Ic cp Ar oldpath Ar newpath
- Alias to
- .Ic copy
- command.
- .It Xo Ic df
- .Op Fl hi
- .Op Ar path
- .Xc
- Display usage information for the filesystem holding the current directory
- (or
- .Ar path
- if specified).
- If the
- .Fl h
- flag is specified, the capacity information will be displayed using
- "human-readable" suffixes.
- The
- .Fl i
- flag requests display of inode information in addition to capacity information.
- This command is only supported on servers that implement the
- .Dq statvfs@openssh.com
- extension.
- .It Ic exit
- Quit
- .Nm sftp .
- .It Xo Ic get
- .Op Fl afpR
- .Ar remote-path
- .Op Ar local-path
- .Xc
- Retrieve the
- .Ar remote-path
- and store it on the local machine.
- If the local
- path name is not specified, it is given the same name it has on the
- remote machine.
- .Ar remote-path
- may contain
- .Xr glob 7
- characters and may match multiple files.
- If it does and
- .Ar local-path
- is specified, then
- .Ar local-path
- must specify a directory.
- .Pp
- If the
- .Fl a
- flag is specified, then attempt to resume partial transfers of existing files.
- Note that resumption assumes that any partial copy of the local file matches
- the remote copy.
- If the remote file contents differ from the partial local copy then the
- resultant file is likely to be corrupt.
- .Pp
- If the
- .Fl f
- flag is specified, then
- .Xr fsync 2
- will be called after the file transfer has completed to flush the file
- to disk.
- .Pp
- If the
- .Fl p
- .\" undocumented redundant alias
- .\" or
- .\" .Fl P
- flag is specified, then full file permissions and access times are
- copied too.
- .Pp
- If the
- .Fl R
- .\" undocumented redundant alias
- .\" or
- .\" .Fl r
- flag is specified then directories will be copied recursively.
- Note that
- .Nm
- does not follow symbolic links when performing recursive transfers.
- .It Ic help
- Display help text.
- .It Ic lcd Op Ar path
- Change local directory to
- .Ar path .
- If
- .Ar path
- is not specified, then change directory to the local user's home directory.
- .It Ic lls Op Ar ls-options Op Ar path
- Display local directory listing of either
- .Ar path
- or current directory if
- .Ar path
- is not specified.
- .Ar ls-options
- may contain any flags supported by the local system's
- .Xr ls 1
- command.
- .Ar path
- may contain
- .Xr glob 7
- characters and may match multiple files.
- .It Ic lmkdir Ar path
- Create local directory specified by
- .Ar path .
- .It Xo Ic ln
- .Op Fl s
- .Ar oldpath
- .Ar newpath
- .Xc
- Create a link from
- .Ar oldpath
- to
- .Ar newpath .
- If the
- .Fl s
- flag is specified the created link is a symbolic link, otherwise it is
- a hard link.
- .It Ic lpwd
- Print local working directory.
- .It Xo Ic ls
- .Op Fl 1afhlnrSt
- .Op Ar path
- .Xc
- Display a remote directory listing of either
- .Ar path
- or the current directory if
- .Ar path
- is not specified.
- .Ar path
- may contain
- .Xr glob 7
- characters and may match multiple files.
- .Pp
- The following flags are recognized and alter the behaviour of
- .Ic ls
- accordingly:
- .Bl -tag -width Ds
- .It Fl 1
- Produce single columnar output.
- .It Fl a
- List files beginning with a dot
- .Pq Sq \&. .
- .It Fl f
- Do not sort the listing.
- The default sort order is lexicographical.
- .It Fl h
- When used with a long format option, use unit suffixes: Byte, Kilobyte,
- Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce
- the number of digits to four or fewer using powers of 2 for sizes (K=1024,
- M=1048576, etc.).
- .It Fl l
- Display additional details including permissions
- and ownership information.
- .It Fl n
- Produce a long listing with user and group information presented
- numerically.
- .It Fl r
- Reverse the sort order of the listing.
- .It Fl S
- Sort the listing by file size.
- .It Fl t
- Sort the listing by last modification time.
- .El
- .It Ic lumask Ar umask
- Set local umask to
- .Ar umask .
- .It Ic mkdir Ar path
- Create remote directory specified by
- .Ar path .
- .It Ic progress
- Toggle display of progress meter.
- .It Xo Ic put
- .Op Fl afpR
- .Ar local-path
- .Op Ar remote-path
- .Xc
- Upload
- .Ar local-path
- and store it on the remote machine.
- If the remote path name is not specified, it is given the same name it has
- on the local machine.
- .Ar local-path
- may contain
- .Xr glob 7
- characters and may match multiple files.
- If it does and
- .Ar remote-path
- is specified, then
- .Ar remote-path
- must specify a directory.
- .Pp
- If the
- .Fl a
- flag is specified, then attempt to resume partial
- transfers of existing files.
- Note that resumption assumes that any partial copy of the remote file
- matches the local copy.
- If the local file contents differ from the remote local copy then
- the resultant file is likely to be corrupt.
- .Pp
- If the
- .Fl f
- flag is specified, then a request will be sent to the server to call
- .Xr fsync 2
- after the file has been transferred.
- Note that this is only supported by servers that implement
- the "fsync@openssh.com" extension.
- .Pp
- If the
- .Fl p
- .\" undocumented redundant alias
- .\" or
- .\" .Fl P
- flag is specified, then full file permissions and access times are
- copied too.
- .Pp
- If the
- .Fl R
- .\" undocumented redundant alias
- .\" or
- .\" .Fl r
- flag is specified then directories will be copied recursively.
- Note that
- .Nm
- does not follow symbolic links when performing recursive transfers.
- .It Ic pwd
- Display remote working directory.
- .It Ic quit
- Quit
- .Nm sftp .
- .It Xo Ic reget
- .Op Fl fpR
- .Ar remote-path
- .Op Ar local-path
- .Xc
- Resume download of
- .Ar remote-path .
- Equivalent to
- .Ic get
- with the
- .Fl a
- flag set.
- .It Xo Ic reput
- .Op Fl fpR
- .Ar local-path
- .Op Ar remote-path
- .Xc
- Resume upload of
- .Ar local-path .
- Equivalent to
- .Ic put
- with the
- .Fl a
- flag set.
- .It Ic rename Ar oldpath newpath
- Rename remote file from
- .Ar oldpath
- to
- .Ar newpath .
- .It Ic rm Ar path
- Delete remote file specified by
- .Ar path .
- .It Ic rmdir Ar path
- Remove remote directory specified by
- .Ar path .
- .It Ic symlink Ar oldpath newpath
- Create a symbolic link from
- .Ar oldpath
- to
- .Ar newpath .
- .It Ic version
- Display the
- .Nm
- protocol version.
- .It Ic \&! Ns Ar command
- Execute
- .Ar command
- in local shell.
- .It Ic \&!
- Escape to local shell.
- .It Ic \&?
- Synonym for help.
- .El
- .Sh SEE ALSO
- .Xr ftp 1 ,
- .Xr ls 1 ,
- .Xr scp 1 ,
- .Xr ssh 1 ,
- .Xr ssh-add 1 ,
- .Xr ssh-keygen 1 ,
- .Xr ssh_config 5 ,
- .Xr glob 7 ,
- .Xr sftp-server 8 ,
- .Xr sshd 8
- .Rs
- .%A T. Ylonen
- .%A S. Lehtinen
- .%T "SSH File Transfer Protocol"
- .%N draft-ietf-secsh-filexfer-00.txt
- .%D January 2001
- .%O work in progress material
- .Re