=================================================================== RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/ssh/sftp.1,v retrieving revision 1.40 retrieving revision 1.40.2.3 diff -u -r1.40 -r1.40.2.3 --- src/usr.bin/ssh/sftp.1 2003/01/10 08:19:07 1.40 +++ src/usr.bin/ssh/sftp.1 2004/03/04 18:18:16 1.40.2.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sftp.1,v 1.40 2003/01/10 08:19:07 fgsch Exp $ +.\" $OpenBSD: sftp.1,v 1.40.2.3 2004/03/04 18:18:16 brad Exp $ .\" .\" Copyright (c) 2001 Damien Miller. All rights reserved. .\" @@ -27,23 +27,32 @@ .Os .Sh NAME .Nm sftp -.Nd Secure file transfer program +.Nd secure file transfer program .Sh SYNOPSIS .Nm sftp -.Op Fl vC1 -.Op Fl b Ar batchfile -.Op Fl o Ar ssh_option -.Op Fl s Ar subsystem | sftp_server +.Bk -words +.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 -.Op [\fIuser\fR@]\fIhost\fR[:\fIfile\fR [\fIfile\fR]] +.Oo Oo Ar user Ns @ 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 @ 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 @@ -62,10 +71,28 @@ 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 the sftp client 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 @@ -73,44 +100,24 @@ .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 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 -.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. +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 .Fl C @@ -118,19 +125,76 @@ .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 ConnectionTimeout +.It GlobalKnownHostsFile +.It GSSAPIAuthentication +.It GSSAPIDelegateCredentials +.It Host +.It HostbasedAuthentication +.It HostKeyAlgorithms +.It HostKeyAlias +.It HostName +.It IdentityFile +.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 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 16 outstanding requests. .It Fl S Ar program Name of the .Ar program @@ -138,8 +202,17 @@ 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, @@ -148,15 +221,13 @@ .Xr ftp 1 . Commands are case insensitive and pathnames may be enclosed in quotes if they contain spaces. -.Bl -tag -width Ds +.Bl -tag -width "lmdir path" .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 @@ -177,7 +248,8 @@ .Ar own must be a numeric UID. .It Ic exit -Quit sftp. +Quit +.Nm sftp . .It Xo Ic get .Op Ar flags .Ar remote-path @@ -188,12 +260,16 @@ 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. +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 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 @@ -218,7 +294,8 @@ .Ar path or current directory if .Ar path -is not specified. If the +is not specified. +If the .Fl l flag is specified, then display additional details including permissions and ownership information. @@ -237,26 +314,29 @@ .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. .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 @@ -266,18 +346,17 @@ Display the .Nm protocol version. -.It Ic ! Ar command +.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 scp 1 , .Xr ssh 1 , .Xr ssh-add 1 ,