X-Git-Url: http://andersk.mit.edu/gitweb/openssh.git/blobdiff_plain/f3c7c61373d79f23a88ffa48a4937138128113c9..5498741cc14208f105eb8341046536b21a0c31db:/sftp.1 diff --git a/sftp.1 b/sftp.1 index 22915133..faf05262 100644 --- a/sftp.1 +++ b/sftp.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sftp.1,v 1.9 2001/03/02 18:54:31 deraadt Exp $ +.\" $OpenBSD: sftp.1,v 1.64 2007/05/31 19:20:16 jmc Exp $ .\" .\" Copyright (c) 2001 Damien Miller. All rights reserved. .\" @@ -22,17 +22,37 @@ .\" (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 Febuary 4, 2001 +.Dd $Mdocdate$ .Dt SFTP 1 .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 @@ -44,58 +64,219 @@ It may also use many features of ssh, such as public key authentication and 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 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 v -Raise logging level. This option is also passed to ssh. +.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 +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 +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 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 +.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. .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 help -Display help text. +.It Ic exit +Quit +.Nm sftp . .It Xo Ic get -.Op Ar flags +.Op Fl P .Ar remote-path .Op Ar local-path .Xc @@ -103,78 +284,170 @@ 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. 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 +.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 exit -Quit sftp. .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 ! Ar command -Execute +.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 \&! 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 .Sh SEE ALSO +.Xr ftp 1 , +.Xr ls 1 , +.Xr scp 1 , .Xr ssh 1 , .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