X-Git-Url: http://andersk.mit.edu/gitweb/gssapi-openssh.git/blobdiff_plain/6a9b319871ee85eeada2a0511e9436d0bfa6aab8..91d9cdd3ca06d1809bc05a285dafdea2954850b2:/openssh/sftp.1

diff --git a/openssh/sftp.1 b/openssh/sftp.1
index 02d2c27..37ccb3a 100644
--- a/openssh/sftp.1
+++ b/openssh/sftp.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: sftp.1,v 1.41 2003/03/28 10:11:43 jmc Exp $
+.\" $OpenBSD: sftp.1,v 1.69 2008/12/09 15:35:00 sobrado Exp $
 .\"
 .\" Copyright (c) 2001 Damien Miller.  All rights reserved.
 .\"
@@ -22,34 +22,36 @@
 .\" (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 February 4, 2001
+.Dd $Mdocdate: December 9 2008 $
 .Dt SFTP 1
 .Os
 .Sh NAME
 .Nm sftp
-.Nd Secure file transfer program
+.Nd secure file transfer program
 .Sh SYNOPSIS
 .Nm sftp
 .Bk -words
-.Op Fl vC1
-.Op Fl b Ar batchfile
-.Op Fl o Ar ssh_option
-.Op Fl s Ar subsystem | sftp_server
+.Op Fl 1Cv
 .Op Fl B Ar buffer_size
+.Op Fl b Ar batchfile
 .Op Fl F Ar ssh_config
-.Op Fl P Ar sftp_server path
+.Op Fl o Ar ssh_option
+.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 No @ Oc Ns
-.Ar host Ns Oo : Ns Ar file Oo
-.Ar file Oc Oc Oc
+.Oo Ar user Ns @ Oc Ns
+.Ar host Ns Op : Ns Ar
 .Nm sftp
-.Oo Oo Ar user Ns No @ Oc Ns
+.Oo Ar user Ns @ Oc Ns
 .Ar host Ns Oo : Ns Ar dir Ns
-.Oo Ar / Oc Oc Oc
+.Op Ar / 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
@@ -68,10 +70,30 @@ 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 last usage format allows the sftp client to start in a remote directory.
+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 necessary to configure 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).
 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
@@ -79,44 +101,25 @@ instead of
 .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 ,
 .Ic rm , mkdir , chdir , ls ,
-.Ic lchdir , chmod , chown , chgrp , lpwd
+.Ic lchdir , chmod , chown ,
+.Ic chgrp , lpwd , df ,
 and
 .Ic lmkdir .
 Termination on error can be suppressed on a command by command basis by
 prefixing the command with a
-.Ic '-'
-character (For example,
-.Ic -rm /tmp/blah*
-).
-.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 .
-.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 sftp over
-protocol version 1, or when the remote
-.Nm sshd
-does not have an sftp subsystem configured.
-.It Fl v
-Raise logging level. This option is also passed to ssh.
-.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.
+.Sq \-
+character (for example,
+.Ic -rm /tmp/blah* ) .
 .It Fl C
 Enables compression (via ssh's
 .Fl C
@@ -124,19 +127,83 @@ flag).
 .It Fl F Ar ssh_config
 Specifies an alternative
 per-user configuration file for
-.Nm ssh .
+.Xr ssh 1 .
 This option is directly passed to
 .Xr ssh 1 .
-.It Fl P Ar sftp_server path
-Connect directly to a local
-.Nm sftp-server
+.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 RekeyLimit
+.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
-.Nm ssh )
+.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.
+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 S Ar program
 Name of the
 .Ar program
@@ -144,30 +211,45 @@ to use for the encrypted connection.
 The program must understand
 .Xr ssh 1
 options.
-.It Fl 1
-Specify the use of protocol version 1.
+.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.
 .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 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 sftp.
+Quit
+.Nm sftp .
 .It Ic cd Ar path
 Change remote directory to
 .Ar path .
-.It Ic lcd Ar path
-Change local directory to
-.Ar path .
 .It Ic chgrp Ar grp Ar path
 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
@@ -175,17 +257,44 @@ 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
 .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 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 sftp.
+Quit
+.Nm sftp .
 .It Xo Ic get
-.Op Ar flags
+.Op Fl P
 .Ar remote-path
 .Op Ar local-path
 .Xc
@@ -194,18 +303,39 @@ Retrieve the
 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
+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
 .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 .
@@ -217,17 +347,44 @@ to
 .It Ic lpwd
 Print local working directory.
 .It Xo Ic ls
-.Op Ar flags
+.Op Fl 1aflnrSt
 .Op Ar path
 .Xc
-Display remote directory listing of either
+Display a remote directory listing of either
 .Ar path
-or current directory if
+or the current directory if
 .Ar path
-is not specified. If the
-.Fl l
-flag is specified, then display additional details including permissions
+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
 .Ar umask .
@@ -237,32 +394,44 @@ Create remote directory specified by
 .It Ic progress
 Toggle display of progress meter.
 .It Xo Ic put
-.Op Ar flags
+.Op Fl P
 .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
 .Ar oldpath
@@ -272,22 +441,23 @@ to
 Display the
 .Nm
 protocol version.
-.It Ic ! Ar command
+.It Ic \&! Ns 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 ssh-add 1 ,
 .Xr ssh-keygen 1 ,
+.Xr glob 3 ,
 .Xr ssh_config 5 ,
 .Xr sftp-server 8 ,
 .Xr sshd 8