X-Git-Url: http://andersk.mit.edu/gitweb/openssh.git/blobdiff_plain/edeeab1e2e57692b3956eadf341d23ae5be549c7..HEAD:/sftp.1 diff --git a/sftp.1 b/sftp.1 index 093ebb91..dab73f6b 100644 --- a/sftp.1 +++ b/sftp.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sftp.1,v 1.15 2001/04/12 23:17:54 mouring Exp $ +.\" $OpenBSD: sftp.1,v 1.82 2010/01/13 12:48:34 jmc Exp $ .\" .\" Copyright (c) 2001 Damien Miller. All rights reserved. .\" @@ -22,22 +22,39 @@ .\" (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$ .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 1246Cpqrv +.Op Fl B Ar buffer_size .Op Fl b Ar batchfile +.Op Fl c Ar cipher +.Op Fl D Ar sftp_server_path +.Op Fl F Ar ssh_config +.Op Fl i Ar identity_file .Op Fl o Ar ssh_option -.Op Ar host +.Op Fl P Ar port +.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 Ar user Ns @ Oc Ns +.Ar host Ns Op : Ns Ar .Nm sftp -.Op [\fIuser\fR@]\fIhost\fR[:\fIdir\fR[\fI/\fR]] +.Oo Ar user Ns @ Oc Ns +.Ar host Ns Oo : Ns Ar dir Ns +.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 @@ -49,17 +66,47 @@ 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 fetch files automaticly if a non-interactive -authentication is used, else it do so after an interactive authenication -is used. +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 2 +Specify the use of protocol version 2. +.It Fl 4 +Forces +.Nm +to use IPv4 addresses only. +.It Fl 6 +Forces +.Nm +to use IPv6 addresses only. +.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 @@ -67,59 +114,223 @@ 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 , rm , mkdir , chdir , lchdir +will abort if any of the following +commands fail: +.Ic get , put , rename , ln , +.Ic rm , mkdir , chdir , ls , +.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 +.Sq \- +character (for example, +.Ic -rm /tmp/blah* ) . .It Fl C -Enables compression (via ssh's +Enables compression (via ssh's .Fl C -flag) +flag). +.It Fl c Ar cipher +Selects the cipher to use for encrypting the data transfers. +This option is directly passed to +.Xr ssh 1 . +.It Fl D 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 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 i Ar identity_file +Selects the file from which the identity (private key) for public key +authentication is read. +This option is directly passed to +.Xr ssh 1 . .It Fl o Ar ssh_option -Specify an option to be directly passed to +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 port +Specifies the port to connect to on the remote host. +.It Fl p +Preserves modification times, access times, and modes from the +original files transferred. +.It Fl q +Quiet mode: disables the progress meter as well as warning and +diagnostic messages from .Xr ssh 1 . +.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 64 outstanding requests. +.It Fl r +Recursively copy entire directories when uploading and downloading. +Note that +.Nm +does not follow symbolic links encountered in the tree traversal. +.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. +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 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 Ppr .Ar remote-path .Op Ar local-path .Xc @@ -127,89 +338,195 @@ 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. +.Pp +If either the .Fl P -flag is specified, then the file's full permission and access time are +or +.Fl p +flag is specified, then full file permissions and access times are copied too. +.Pp +If the +.Fl r +flag is specified then directories will be copied recursively. +Note that +.Nm +does not follow symbolic links when performing recursive transfers. .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 +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 1afhlnrSt +.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 h +When used with a long format option, use unit suffixes: Byte, Kilobyte, +Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in order to reduce +the number of digits to four or fewer using powers of 2 for sizes (K=1024, +M=1048576, etc.). +.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 Ppr .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. +.Pp +If ether the .Fl P -flag is specified, then the file's full permission and access time are +or +.Fl p +flag is specified, then full file permissions and access times are copied too. +.Pp +If the +.Fl r +flag is specified then directories will be copied recursively. +Note that +.Nm +does not follow symbolic links when performing recursive transfers. .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 +Create a symbolic link from .Ar oldpath to .Ar newpath . -.It Ic ! Ar command -Execute +.It Ic version +Display the +.Nm +protocol version. +.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 .Sh SEE ALSO +.Xr ftp 1 , +.Xr ls 1 , +.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 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