Integrate unfix.org's IPv6 patches up to level 10, with rather a lot

[u/mdw/putty] / doc / pscp.but

diff --git a/doc/pscp.but b/doc/pscp.but
index c4ccc64..4485b9b 100644 (file)
--- a/doc/pscp.but
+++ b/doc/pscp.but
@@ -1,4 +1,4 @@
-\versionid $Id: pscp.but,v 1.26 2004/04/24 12:25:08 jacob Exp $
+\define{versionidpscp} \versionid $Id$

 
 \#FIXME: Need examples
 
 
 \#FIXME: Need examples
 


@@ -55,11 +55,14 @@ use PSCP:
 \c   -l user   connect with specified username
 \c   -pw passw login with specified password
 \c   -1 -2     force use of particular SSH protocol version
 \c   -l user   connect with specified username
 \c   -pw passw login with specified password
 \c   -1 -2     force use of particular SSH protocol version

+\c   -4 -6     force use of IPv4 or IPv6

 \c   -C        enable compression
 \c   -i key    private key file for authentication
 \c   -batch    disable all interactive prompts
 \c   -unsafe   allow server-side wildcards (DANGEROUS)
 \c   -V        print version information
 \c   -C        enable compression
 \c   -i key    private key file for authentication
 \c   -batch    disable all interactive prompts
 \c   -unsafe   allow server-side wildcards (DANGEROUS)
 \c   -V        print version information

+\c   -sftp     force use of SFTP protocol
+\c   -scp      force use of SCP protocol

 
 (PSCP's interface is much like the Unix \c{scp} command, if you're
 familiar with that.)
 
 (PSCP's interface is much like the Unix \c{scp} command, if you're
 familiar with that.)


@@ -79,11 +82,11 @@ To send (a) file(s) to a remote server:
 
 \c pscp [options] source [source...] [user@]host:target
 
 
 \c pscp [options] source [source...] [user@]host:target
 

-So to copy the local file \c{c:\\documents\\csh-whynot.txt} to the
-server \c{example.com} as user \c{fred} to the file
-\c{/tmp/csh-whynot} you would type:
+So to copy the local file \c{c:\\documents\\foo.txt} to the server
+\c{example.com} as user \c{fred} to the file \c{/tmp/foo} you would
+type:

 
 

-\c pscp c:\documents\csh-whynot.txt fred@example.com:/tmp/csh-whynot
+\c pscp c:\documents\foo.txt fred@example.com:/tmp/foo

 
 You can use wildcards to transfer multiple files in either
 direction, like this:
 
 You can use wildcards to transfer multiple files in either
 direction, like this:


@@ -92,12 +95,11 @@ direction, like this:
 \c pscp fred@example.com:source/*.c c:\source
 
 However, in the second case (using a wildcard for multiple remote
 \c pscp fred@example.com:source/*.c c:\source
 
 However, in the second case (using a wildcard for multiple remote

-files) you may see a warning like this:
-
-\c warning: remote host tried to write to a file called 'terminal.c'
-\c          when we requested a file called '*.c'.
-\c          If this is a wildcard, consider upgrading to SSH 2 or using
-\c          the '-unsafe' option. Renaming of this file has been disallowed.
+files) you may see a warning saying something like \q{warning:
+remote host tried to write to a file called 'terminal.c' when we
+requested a file called '*.c'. If this is a wildcard, consider
+upgrading to SSH 2 or using the '-unsafe' option. Renaming of this
+file has been disallowed}.

 
 This is due to a fundamental insecurity in the old-style SCP
 protocol: the client sends the wildcard string (\c{*.c}) to the
 
 This is due to a fundamental insecurity in the old-style SCP
 protocol: the client sends the wildcard string (\c{*.c}) to the


@@ -113,7 +115,8 @@ pattern.
 PSCP will attempt to use the newer SFTP protocol (part of SSH 2)
 where possible, which does not suffer from this security flaw. If
 you are talking to an SSH 2 server which supports SFTP, you will
 PSCP will attempt to use the newer SFTP protocol (part of SSH 2)
 where possible, which does not suffer from this security flaw. If
 you are talking to an SSH 2 server which supports SFTP, you will

-never see this warning.
+never see this warning. (You can force use of the SFTP protocol,
+if available, with \c{-sftp} - see \k{pscp-usage-options-backend}.)

 
 If you really need to use a server-side wildcard with an SSH 1
 server, you can use the \c{-unsafe} command line option with PSCP:
 
 If you really need to use a server-side wildcard with an SSH 1
 server, you can use the \c{-unsafe} command line option with PSCP:


@@ -193,7 +196,7 @@ timestamp on copied files.
 By default, PSCP displays a meter displaying the progress of the
 current transfer:
 
 By default, PSCP displays a meter displaying the progress of the
 current transfer:
 

-\c mibs.tar                  |        168 kB |  84.0 kB/s | ETA: 00:00:13 |  13%
+\c mibs.tar          |   168 kB |  84.0 kB/s | ETA: 00:00:13 |  13%

 
 The fields in this display are (from left to right), filename, size
 (in kilobytes) of file transferred so far, estimate of how fast the
 
 The fields in this display are (from left to right), filename, size
 (in kilobytes) of file transferred so far, estimate of how fast the


@@ -222,6 +225,37 @@ This may help PSCP's behaviour when it is used in automated
 scripts: using \c{-batch}, if something goes wrong at connection
 time, the batch job will fail rather than hang.
 
 scripts: using \c{-batch}, if something goes wrong at connection
 time, the batch job will fail rather than hang.
 

+\S2{pscp-usage-options-backend}\c{-sftp}, \c{-scp} force use of
+particular protocol
+
+As mentioned in \k{pscp-usage-basics}, there are two different file
+transfer protocols in use with SSH. Despite its name, PSCP (like many
+other ostensible \cw{scp} clients) can use either of these protocols.
+
+The older SCP protocol does not have a written specification and
+leaves a lot of detail to the server platform. Wildcards are expanded
+on the server. The simple design means that any wildcard specification
+supported by the server platform (such as brace expansion) can be
+used, but also leads to interoperability issues such as with filename
+quoting (for instance, where filenames contain spaces), and also the
+security issue described in \k{pscp-usage-basics}.
+
+The newer SFTP protocol, which is usually associated with SSH 2
+servers, is specified in a more platform independent way, and leaves
+issues such as wildcard syntax up to the client. (PuTTY's SFTP
+wildcard syntax is described in \k{psftp-wildcards}.) This makes it
+more consistent across platforms, more suitable for scripting and
+automation, and avoids security issues with wildcard matching.
+
+Normally PSCP will attempt to use the SFTP protocol, and only fall
+back to the SCP protocol if SFTP is not available on the server.
+
+The \c{-scp} option forces PSCP to use the SCP protocol or quit.
+
+The \c{-sftp} option forces PSCP to use the SFTP protocol or quit.
+When this option is specified, PSCP looks harder for an SFTP server,
+which may allow use of SFTP with SSH 1 depending on server setup.
+

 \S{pscp-retval} Return value
 
 PSCP returns an \cw{ERRORLEVEL} of zero (success) only if the files
 \S{pscp-retval} Return value
 
 PSCP returns an \cw{ERRORLEVEL} of zero (success) only if the files