-.\" $OpenBSD: sftp.1,v 1.14 2001/04/09 00:42:05 stevesk Exp $
+.\" $OpenBSD: sftp.1,v 1.61 2005/03/01 17:19:35 jmc Exp $
.\"
.\" Copyright (c) 2001 Damien Miller. All rights reserved.
.\"
.Os
.Sh NAME
.Nm sftp
-.Nd Secure file transfer program
+.Nd secure file transfer program
.Sh SYNOPSIS
.Nm sftp
-.Op Fl vC
+.Bk -words
+.Op Fl 1Cv
+.Op Fl B Ar buffer_size
.Op Fl b Ar batchfile
+.Op Fl F Ar ssh_config
.Op Fl o Ar ssh_option
-.Op Ar hostname | user@hostname
+.Op Fl P Ar sftp_server_path
+.Op Fl R Ar num_requests
+.Op Fl S Ar program
+.Op Fl s Ar subsystem | sftp_server
+.Ar host
+.Ek
+.Nm sftp
+.Oo Oo Ar user Ns @ Oc Ns
+.Ar host Ns Oo : Ns Ar file Oo
+.Ar file Oc Oc Oc
+.Nm sftp
+.Oo Oo Ar user Ns @ Oc Ns
+.Ar host Ns Oo : Ns Ar dir Ns
+.Oo Ar / Oc Oc Oc
+.Nm sftp
+.Fl b Ar batchfile
+.Oo Ar user Ns @ Oc Ns Ar host
.Sh DESCRIPTION
.Nm
is an interactive file transfer program, similar to
compression.
.Nm
connects and logs into the specified
-.Ar hostname ,
+.Ar host ,
then enters an interactive command mode.
.Pp
+The second usage format will retrieve files automatically if a non-interactive
+authentication method is used; otherwise it will do so after
+successful interactive authentication.
+.Pp
+The third usage format allows
+.Nm
+to start in a remote directory.
+.Pp
+The final usage format allows for automated sessions using the
+.Fl b
+option.
+In such cases, it is usually necessary to configure public key authentication
+to obviate the need to enter a password at connection time (see
+.Xr sshd 8
+and
+.Xr ssh-keygen 1
+for details).
The options are as follows:
.Bl -tag -width Ds
+.It Fl 1
+Specify the use of protocol version 1.
+.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
.Em stdin .
Since it lacks user interaction it should be used in conjunction with
non-interactive authentication.
+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 , rename , ln , rm , mkdir , chdir , lchdir
+will abort if any of the following
+commands fail:
+.Ic get , put , rename , ln ,
+.Ic rm , mkdir , chdir , ls ,
+.Ic lchdir , chmod , chown , chgrp , lpwd
and
.Ic lmkdir .
+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* ) .
.It Fl C
-Enables compression (via ssh's
+Enables compression (via ssh's
.Fl C
-flag)
-.It Fl o Ar ssh_option
-Specify an option to be directly passed to
+flag).
+.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 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 ChallengeResponseAuthentication
+.It CheckHostIP
+.It Cipher
+.It Ciphers
+.It Compression
+.It CompressionLevel
+.It ConnectionAttempts
+.It ConnectTimeout
+.It ControlMaster
+.It ControlPath
+.It GlobalKnownHostsFile
+.It GSSAPIAuthentication
+.It GSSAPIDelegateCredentials
+.It HashKnownHosts
+.It Host
+.It HostbasedAuthentication
+.It HostKeyAlgorithms
+.It HostKeyAlias
+.It HostName
+.It IdentityFile
+.It IdentitiesOnly
+.It KbdInteractiveDevices
+.It LogLevel
+.It MACs
+.It NoHostAuthenticationForLocalhost
+.It NumberOfPasswordPrompts
+.It PasswordAuthentication
+.It Port
+.It PreferredAuthentications
+.It Protocol
+.It ProxyCommand
+.It PubkeyAuthentication
+.It RhostsRSAAuthentication
+.It RSAAuthentication
+.It SendEnv
+.It ServerAliveInterval
+.It ServerAliveCountMax
+.It SmartcardDevice
+.It StrictHostKeyChecking
+.It TCPKeepAlive
+.It UsePrivilegedPort
+.It User
+.It UserKnownHostsFile
+.It VerifyHostKeyDNS
+.El
+.It Fl P 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 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 16 outstanding requests.
+.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 for using
+.Nm
+over protocol version 1, or 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.
+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
+understands a set of commands similar to those of
.Xr ftp 1 .
-Commands are case insensitive and pathnames may be enclosed in quotes if they
-contain spaces.
+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 Ar path
-Change remote directory to
-.Ar path .
-.It Ic lcd Ar path
-Change local directory to
+Change remote directory to
.Ar path .
.It Ic chgrp Ar grp Ar path
-Change group of file
+Change group of file
.Ar path
to
.Ar grp .
+.Ar path
+may contain
+.Xr glob 3
+characters and may match multiple files.
.Ar grp
must be a numeric GID.
.It Ic chmod Ar mode Ar path
-Change permissions of file
+Change permissions of file
.Ar path
to
.Ar mode .
+.Ar path
+may contain
+.Xr glob 3
+characters and may match multiple files.
.It Ic chown Ar own Ar path
-Change owner of file
+Change owner of file
.Ar path
to
.Ar own .
+.Ar path
+may contain
+.Xr glob 3
+characters and may match multiple files.
.Ar own
must be a numeric UID.
.It Ic exit
-Quit sftp.
+Quit
+.Nm sftp .
.It Xo Ic get
-.Op Ar flags
+.Op Fl P
.Ar remote-path
.Op Ar local-path
.Xc
.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. If the
+path name is not specified, it is given the same name it has on the
+remote machine.
+.Ar remote-path
+may contain
+.Xr glob 3
+characters and may match multiple files.
+If it does and
+.Ar local-path
+is specified, then
+.Ar local-path
+must specify a directory.
+If the
.Fl P
-flag is specified, then the file's full permission and access time are
+flag is specified, then full file permissions and access times are
copied too.
.It Ic help
Display help text.
+.It Ic lcd Ar path
+Change local directory to
+.Ar path .
.It Ic lls Op Ar ls-options Op Ar path
-Display local directory listing of either
+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 3
+characters and may match multiple files.
.It Ic lmkdir Ar path
Create local directory specified by
.Ar path .
.It Ic ln Ar oldpath Ar newpath
-Create a symbolic link from
+Create a symbolic link from
.Ar oldpath
to
.Ar newpath .
.It Ic lpwd
Print local working directory.
-.It Ic ls Op Ar path
-Display remote directory listing of either
+.It Xo Ic ls
+.Op Fl 1aflnrSt
+.Op Ar path
+.Xc
+Display a remote directory listing of either
.Ar path
-or current directory if
+or the current directory if
.Ar path
is not specified.
+.Ar path
+may contain
+.Xr glob 3
+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 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
+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 Ar flags
+.Op Fl P
.Ar local-path
-.Op 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. If the
+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 3
+characters and may match multiple files.
+If it does and
+.Ar remote-path
+is specified, then
+.Ar remote-path
+must specify a directory.
+If the
.Fl P
flag is specified, then the file's full permission and access time are
copied too.
.It Ic pwd
Display remote working directory.
.It Ic quit
-Quit sftp.
+Quit
+.Nm sftp .
.It Ic rename Ar oldpath Ar newpath
Rename remote file from
.Ar oldpath
to
.Ar newpath .
-.It Ic rmdir Ar path
-Remove remote directory specified by
-.Ar path .
.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
+Create a symbolic link from
.Ar oldpath
to
.Ar newpath .
-.It Ic ! Ar command
-Execute
+.It Ic version
+Display the
+.Nm
+protocol version.
+.It Ic \&! Ar command
+Execute
.Ar command
in local shell.
-.It Ic !
+.It Ic \&!
Escape to local shell.
-.It Ic ?
+.It Ic \&?
Synonym for help.
.El
-.Sh AUTHORS
-Damien Miller <djm@mindrot.org>
.Sh SEE ALSO
+.Xr ftp 1 ,
+.Xr ls 1 ,
+.Xr scp 1 ,
.Xr ssh 1 ,
-.Xr sftp-server 8 ,
.Xr ssh-add 1 ,
.Xr ssh-keygen 1 ,
-.Xr sshd 8 ,
-.Xr scp 1
-
+.Xr glob 3 ,
+.Xr ssh_config 5 ,
+.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