Introduce the Bugs control panel, for overriding PuTTY's server

[sgt/putty] / doc / pscp.but

diff --git a/doc/pscp.but b/doc/pscp.but
index 627dd8f..ad0144c 100644 (file)
--- a/doc/pscp.but
+++ b/doc/pscp.but
@@ -1,15 +1,16 @@
-\versionid $Id: pscp.but,v 1.12 2001/07/01 09:21:01 simon Exp $
+\versionid $Id: pscp.but,v 1.21 2002/08/07 19:20:06 simon Exp $

 
 \#FIXME: Need examples
 
 \C{pscp} Using PSCP to transfer files securely
 
 
 \#FIXME: Need examples
 
 \C{pscp} Using PSCP to transfer files securely
 

-\# Explain PSCP: the command line, the modes of use (local->remote
-\# and remote->local, recursive, wildcards).
-

 \i{PSCP}, the PuTTY Secure Copy client, is a tool for transferring files
 securely between computers using an SSH connection.
 
 \i{PSCP}, the PuTTY Secure Copy client, is a tool for transferring files
 securely between computers using an SSH connection.
 

+If you have an SSH 2 server, you might prefer PSFTP (see \k{psftp})
+for interactive use. PSFTP does not in general work with SSH 1
+servers, however.
+

 \H{pscp-starting} Starting PSCP
 
 PSCP is a command line application.  This means that you cannot just
 \H{pscp-starting} Starting PSCP
 
 PSCP is a command line application.  This means that you cannot just


@@ -76,6 +77,48 @@ server \c{example.com} as user \c{fred} to the file
 
 \c pscp c:\documents\csh-whynot.txt fred@example.com:/tmp/csh-whynot
 
 
 \c pscp c:\documents\csh-whynot.txt fred@example.com:/tmp/csh-whynot
 

+You can use wildcards to transfer multiple files in either
+direction, like this:
+
+\c pscp c:\documents\*.doc fred@example.com:docfiles
+\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.
+
+This is due to a fundamental insecurity in the old-style SCP
+protocol: the client sends the wildcard string (\c{*.c}) to the
+server, and the server sends back a sequence of file names that
+match the wildcard pattern. However, there is nothing to stop the
+server sending back a \e{different} pattern and writing over one of
+your other files: if you request \c{*.c}, the server might send back
+the file name \c{AUTOEXEC.BAT} and install a virus for you. Since
+the wildcard matching rules are decided by the server, the client
+cannot reliably verify that the filenames sent back match the
+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
+never see this warning.
+
+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:
+
+\c pscp -unsafe fred@example.com:source/*.c c:\source
+
+This will suppress the warning message and the file transfer will
+happen. However, you should be aware that by using this option you
+are giving the server the ability to write to \e{any} file in the
+target directory, so you should only use this option if you trust
+the server administrator not to be malicious (and not to let the
+server machine be cracked by malicious people).
+

 \S2{pscp-usage-basics-user} \c{user}
 
 The login name on the remote server. If this is omitted, and \c{host}
 \S2{pscp-usage-basics-user} \c{user}
 
 The login name on the remote server. If this is omitted, and \c{host}


@@ -121,6 +164,14 @@ directory on the remote server.
 
 \S{pscp-usage-options} Options
 
 
 \S{pscp-usage-options} Options
 

+PSCP accepts all the general command line options supported by the
+PuTTY tools, except the ones which make no sense in a file transfer
+utility. See \k{using-general-opts} for a description of these
+options. (The ones not supported by PSCP are clearly marked.)
+
+PSCP also supports some of its own options. The following sections
+describe PSCP's specific command-line options.
+

 These are the command line options that PSCP accepts.
 
 \S2{pscp-usage-options-p}\c{-p} preserve file attributes
 These are the command line options that PSCP accepts.
 
 \S2{pscp-usage-options-p}\c{-p} preserve file attributes


@@ -151,41 +202,26 @@ PSCP to descend into any directories you specify, and to copy them and
 their contents.  This allows you to use PSCP to transfer whole
 directory structures between machines.
 
 their contents.  This allows you to use PSCP to transfer whole
 directory structures between machines.
 

-\S2{pscp-usage-options-v}\c{-v} show \i{verbose} messages
-
-The \c{-v} option to PSCP makes it print extra information about the
-file transfer.  For example:
-
-\c Logging in as "fred".
-\c fred@example.com's password:
-\c Sending command: scp -v -f mibs.tar
-\c Connected to example.com
-\c Sending file modes: C0644 1320960 mibs.tar
-\c mibs.tar                  |       1290 kB |  67.9 kB/s | ETA: 00:00:00 | 100%
-\c Remote exit status 0
-\c Closing connection
-
-This information may be useful for debugging problems with PSCP.
+\S2{pscp-usage-options-batch}\c{-batch} avoid interactive prompts

 
 

-\S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port}
+If you use the \c{-batch} option, PSCP will never give an
+interactive prompt while establishing the connection. If the
+server's host key is invalid, for example (see \k{gs-hostkey}), then
+the connection will simply be abandoned instead of asking you what
+to do next.

 
 

-If the \c{host} you specify is a saved session, PSCP uses any port
-number specified in that saved session.  If not, PSCP uses the default
-SSH port, 22.  The \c{-P} option allows you specify the port number to 
-connect to for PSCP's SSH connection.
+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.

 
 

-\S2{pscp-usage-options-pw}\c{-pw passw} login with specified \i{password}
+\S{pscp-retval} Return value

 
 

-If a password is required to connect to the \c{host}, PSCP will
-interactively prompt you for it.  However, this may not always be
-appropriate.  If you are running PSCP as part of some automated job,
-it will not be possible to enter a password by hand.  The \c{-pw}
-option to PSCP lets you specify the password to use on the command
-line.
+PSCP returns an \cw{ERRORLEVEL} of zero (success) only if the files
+were correctly transferred. You can test for this in a batch file,
+using code such as this:

 
 

-Since specifying passwords in scripts is a bad idea for security
-reasons, you might want instead to consider using public-key
-authentication; see \k{pscp-pubkey}.
+\c pscp file*.* user@hostname:
+\c if errorlevel 1 echo There was an error

 
 \S{pscp-pubkey} Using public key authentication with PSCP
 
 
 \S{pscp-pubkey} Using public key authentication with PSCP
 


@@ -197,8 +233,8 @@ Firstly, PSCP can use PuTTY saved sessions in place of hostnames
 
 \b Run PuTTY, and create a PuTTY saved session (see
 \k{config-saving}) which specifies your private key file (see
 
 \b Run PuTTY, and create a PuTTY saved session (see
 \k{config-saving}) which specifies your private key file (see

-\k{config-auth}). You will probably also want to specify a username
-to log in as (see \k{config-username}).
+\k{config-ssh-privkey}). You will probably also want to specify a
+username to log in as (see \k{config-username}).

 
 \b In PSCP, you can now use the name of the session instead of a
 hostname: type \c{pscp sessionname:file localfile}, where
 
 \b In PSCP, you can now use the name of the session instead of a
 hostname: type \c{pscp sessionname:file localfile}, where