-.\" $OpenBSD: sftp.1,v 1.26 2001/09/17 20:38:09 stevesk Exp $
+.\" $OpenBSD: sftp.1,v 1.41 2003/03/28 10:11:43 jmc Exp $
.\"
.\" Copyright (c) 2001 Damien Miller. All rights reserved.
.\"
.Nd Secure file transfer program
.Sh SYNOPSIS
.Nm sftp
-.Op Fl 1Cv
+.Bk -words
+.Op Fl vC1
.Op Fl b Ar batchfile
-.Op Fl F Ar ssh_config
.Op Fl o Ar ssh_option
.Op Fl s Ar subsystem | sftp_server
+.Op Fl B Ar buffer_size
+.Op Fl F Ar ssh_config
+.Op Fl P Ar sftp_server path
+.Op Fl R Ar num_requests
.Op Fl S Ar program
.Ar host
+.Ek
.Nm sftp
-.Op [\fIuser\fR@]\fIhost\fR[:\fIfile\fR [\fIfile\fR]]
+.Oo Oo Ar user Ns No @ Oc Ns
+.Ar host Ns Oo : Ns Ar file Oo
+.Ar file Oc Oc Oc
.Nm sftp
-.Op [\fIuser\fR@]\fIhost\fR[:\fIdir\fR[\fI/\fR]]
+.Oo Oo Ar user Ns No @ Oc Ns
+.Ar host Ns Oo : Ns Ar dir Ns
+.Oo Ar / Oc Oc Oc
.Sh DESCRIPTION
.Nm
is an interactive file transfer program, similar to
.Pp
The options are as follows:
.Bl -tag -width Ds
-.It Fl 1
-Specify the use of protocol version 1.
.It Fl b Ar batchfile
Batch mode reads a series of commands from an input
.Ar batchfile
.Nm
will abort if any of the following
commands fail:
-.Ic get , put , rename , ln , rm , mkdir , chdir , lchdir
+.Ic get , put , rename , ln ,
+.Ic rm , mkdir , chdir , ls ,
+.Ic lchdir , chmod , chown , chgrp , lpwd
and
.Ic lmkdir .
-.It Fl C
-Enables compression (via ssh's
-.Fl C
-flag).
-.It Fl F Ar ssh_config
-Specifies an alternative
-per-user configuration file for
-.Nm ssh .
-This option is directly passed to
-.Xr ssh 1 .
+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 the
-.Xr ssh 1
-configuration file. This is useful for specifying options
+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
+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
+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.
+.It Fl C
+Enables compression (via ssh's
+.Fl C
+flag).
+.It Fl F Ar ssh_config
+Specifies an alternative
+per-user configuration file for
+.Nm ssh .
+This option is directly passed to
+.Xr ssh 1 .
+.It Fl P Ar sftp_server path
+Connect directly to a local
+.Nm sftp-server
+(rather than via
+.Nm ssh )
+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
The program must understand
.Xr ssh 1
options.
-.It Fl v
-Raise logging level. This option is also passed to ssh.
+.It Fl 1
+Specify the use of protocol version 1.
.El
.Sh INTERACTIVE COMMANDS
Once in interactive mode,
.Ar newpath .
.It Ic lpwd
Print local working directory.
-.It Ic ls Op Ar path
+.It Xo Ic ls
+.Op Ar flags
+.Op Ar path
+.Xc
Display remote directory listing of either
.Ar path
or current directory if
.Ar path
-is not specified.
+is not specified. If the
+.Fl l
+flag is specified, then display additional details including permissions
+and ownership information.
.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 Ar flags
.Ar local-path
-.Op Ar local-path
+.Op Ar remote-path
.Xc
Upload
.Ar local-path
.Ar oldpath
to
.Ar newpath .
+.It Ic version
+Display the
+.Nm
+protocol version.
.It Ic ! Ar command
Execute
.Ar command
.Xr ssh 1 ,
.Xr ssh-add 1 ,
.Xr ssh-keygen 1 ,
+.Xr ssh_config 5 ,
.Xr sftp-server 8 ,
.Xr sshd 8
.Rs