-.\" $OpenBSD: sftp.1,v 1.14 2001/04/09 00:42:05 stevesk Exp $
+.\" $OpenBSD: sftp.1,v 1.29 2002/02/06 14:22:42 markus Exp $
.\"
.\" Copyright (c) 2001 Damien Miller. All rights reserved.
.\"
.Nd Secure file transfer program
.Sh SYNOPSIS
.Nm sftp
-.Op Fl vC
+.Op Fl vC1
.Op Fl b Ar batchfile
.Op Fl o Ar ssh_option
-.Op Ar hostname | user@hostname
+.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 S Ar program
+.Ar host
+.Nm sftp
+.Op [\fIuser\fR@]\fIhost\fR[:\fIfile\fR [\fIfile\fR]]
+.Nm sftp
+.Op [\fIuser\fR@]\fIhost\fR[:\fIdir\fR[\fI/\fR]]
.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 last usage format allows the sftp client to start in a remote directory.
+.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl b Ar batchfile
Since it lacks user interaction it should be used in conjunction with
non-interactive authentication.
.Nm
-will abort if any of the following
-commands fail:
+will abort if any of the following
+commands fail:
.Ic get , put , rename , ln , rm , mkdir , chdir , lchdir
and
.Ic lmkdir .
-.It Fl C
-Enables compression (via ssh's
-.Fl C
-flag)
.It Fl o Ar ssh_option
-Specify an option to be directly passed to
-.Xr ssh 1 .
+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
+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.
+.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 S Ar program
+Name of the
+.Ar program
+to use for the encrypted connection.
+The program must understand
+.Xr ssh 1
+options.
+.It Fl 1
+Specify the use of protocol version 1.
.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.
.Bl -tag -width Ds
+.It Ic bye
+Quit sftp.
.It Ic cd Ar path
-Change remote directory to
+Change remote directory to
.Ar path .
.It Ic lcd Ar path
-Change local directory to
+Change local 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 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 .
.It Ic chown Ar own Ar path
-Change owner of file
+Change owner of file
.Ar path
to
.Ar own .
.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. If the
.Fl P
flag is specified, then the file's full permission and access time are
copied too.
.It Ic help
Display help text.
.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
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 .
.Ar path
is not specified.
.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
.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. If the
.Fl P
flag is specified, then the file's full permission and access time are
copied too.
Delete remote file 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
+Execute
.Ar command
in local shell.
.It Ic !
.Sh AUTHORS
Damien Miller <djm@mindrot.org>
.Sh SEE ALSO
+.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 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