682 lines
16 KiB
Groff
682 lines
16 KiB
Groff
.\" $OpenBSD: sftp.1,v 1.128 2019/11/30 07:07:59 jmc 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: November 30 2019 $
|
|
.Dt SFTP 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sftp
|
|
.Nd OpenSSH secure file transfer
|
|
.Sh SYNOPSIS
|
|
.Nm sftp
|
|
.Op Fl 46aCfpqrv
|
|
.Op Fl B Ar buffer_size
|
|
.Op Fl b Ar batchfile
|
|
.Op Fl c Ar cipher
|
|
.Op Fl D Ar sftp_server_path
|
|
.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
|
|
.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
|
|
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 , 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_path
|
|
Connect directly to a local sftp server
|
|
(rather than via
|
|
.Xr ssh 1 ) .
|
|
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 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 AddressFamily
|
|
.It BatchMode
|
|
.It BindAddress
|
|
.It BindInterface
|
|
.It CanonicalDomains
|
|
.It CanonicalizeFallbackLocal
|
|
.It CanonicalizeHostname
|
|
.It CanonicalizeMaxDots
|
|
.It CanonicalizePermittedCNAMEs
|
|
.It CASignatureAlgorithms
|
|
.It CertificateFile
|
|
.It ChallengeResponseAuthentication
|
|
.It CheckHostIP
|
|
.It Ciphers
|
|
.It Compression
|
|
.It ConnectionAttempts
|
|
.It ConnectTimeout
|
|
.It ControlMaster
|
|
.It ControlPath
|
|
.It ControlPersist
|
|
.It GlobalKnownHostsFile
|
|
.It GSSAPIAuthentication
|
|
.It GSSAPIDelegateCredentials
|
|
.It HashKnownHosts
|
|
.It Host
|
|
.It HostbasedAuthentication
|
|
.It HostbasedKeyTypes
|
|
.It HostKeyAlgorithms
|
|
.It HostKeyAlias
|
|
.It Hostname
|
|
.It IdentitiesOnly
|
|
.It IdentityAgent
|
|
.It IdentityFile
|
|
.It IPQoS
|
|
.It KbdInteractiveAuthentication
|
|
.It KbdInteractiveDevices
|
|
.It KexAlgorithms
|
|
.It LogLevel
|
|
.It MACs
|
|
.It NoHostAuthenticationForLocalhost
|
|
.It NumberOfPasswordPrompts
|
|
.It PasswordAuthentication
|
|
.It PKCS11Provider
|
|
.It Port
|
|
.It PreferredAuthentications
|
|
.It ProxyCommand
|
|
.It ProxyJump
|
|
.It PubkeyAcceptedKeyTypes
|
|
.It PubkeyAuthentication
|
|
.It RekeyLimit
|
|
.It SendEnv
|
|
.It ServerAliveInterval
|
|
.It ServerAliveCountMax
|
|
.It SetEnv
|
|
.It StrictHostKeyChecking
|
|
.It TCPKeepAlive
|
|
.It UpdateHostKeys
|
|
.It User
|
|
.It UserKnownHostsFile
|
|
.It VerifyHostKeyDNS
|
|
.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.
|
|
.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 .
|
|
If the
|
|
.Fl h
|
|
flag is specified, then symlinks will not be followed.
|
|
.Ar path
|
|
may contain
|
|
.Xr glob 7
|
|
characters and may match multiple files.
|
|
.Ar grp
|
|
must be a numeric GID.
|
|
.It Xo Ic chmod
|
|
.Op Fl h
|
|
.Ar mode
|
|
.Ar path
|
|
.Xc
|
|
Change permissions of file
|
|
.Ar path
|
|
to
|
|
.Ar mode .
|
|
If the
|
|
.Fl h
|
|
flag is specified, then symlinks will not be followed.
|
|
.Ar path
|
|
may contain
|
|
.Xr glob 7
|
|
characters and may match multiple files.
|
|
.It Xo Ic chown
|
|
.Op Fl h
|
|
.Ar own
|
|
.Ar path
|
|
.Xc
|
|
Change owner of file
|
|
.Ar path
|
|
to
|
|
.Ar own .
|
|
If the
|
|
.Fl h
|
|
flag is specified, then symlinks will not be followed.
|
|
.Ar path
|
|
may contain
|
|
.Xr glob 7
|
|
characters and may match multiple files.
|
|
.Ar own
|
|
must be a numeric UID.
|
|
.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 Ar 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 Ar 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
|