Uploads turn out to be much easier than downloads, so here's faster

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

diff --git a/doc/pscp.but b/doc/pscp.but
index f31b8d5..1a322f6 100644 (file)
--- a/doc/pscp.but
+++ b/doc/pscp.but
@@ -1,4 +1,4 @@
-\versionid $Id: pscp.but,v 1.13 2001/08/28 09:53:51 simon Exp $
+\versionid $Id: pscp.but,v 1.22 2002/09/11 17:30:36 jacob Exp $

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


@@ -7,6 +7,10 @@
 \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


@@ -37,17 +41,24 @@ use PSCP:
 
 \c Z:\owendadmin>pscp
 \c PuTTY Secure Copy client
 
 \c Z:\owendadmin>pscp
 \c PuTTY Secure Copy client

-\c Release 0.50
+\c Release 0.53

 \c Usage: pscp [options] [user@]host:source target
 \c Usage: pscp [options] [user@]host:source target

-\c       pscp [options] source [source...] [user@]host:target
-\c       pscp [options] -ls user@host:filespec
+\c        pscp [options] source [source...] [user@]host:target
+\c        pscp [options] -ls user@host:filespec

 \c Options:
 \c   -p        preserve file attributes
 \c   -q        quiet, don't show statistics
 \c   -r        copy directories recursively
 \c   -v        show verbose messages
 \c Options:
 \c   -p        preserve file attributes
 \c   -q        quiet, don't show statistics
 \c   -r        copy directories recursively
 \c   -v        show verbose messages

+\c   -load sessname  Load settings from saved session

 \c   -P port   connect to specified port
 \c   -P port   connect to specified port

+\c   -l user   connect with specified username

 \c   -pw passw login with specified password
 \c   -pw passw login with specified password

+\c   -1 -2     force use of particular SSH protocol version
+\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)

 
 (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.)


@@ -160,6 +171,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


@@ -190,43 +209,19 @@ 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
+\S2{pscp-usage-options-batch}\c{-batch} avoid interactive prompts

 
 

-This information may be useful for debugging problems with PSCP.
+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.

 
 

-\S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port}
+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.

 
 

-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.
-
-\S2{pscp-usage-options-pw}\c{-pw passw} login with specified \i{password}
-
-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.
-
-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}.
-
-\S{pscp-pubkey} Return value
+\S{pscp-retval} Return value

 
 PSCP returns an \cw{ERRORLEVEL} of zero (success) only if the files
 were correctly transferred. You can test for this in a batch file,
 
 PSCP returns an \cw{ERRORLEVEL} of zero (success) only if the files
 were correctly transferred. You can test for this in a batch file,


@@ -238,21 +233,25 @@ using code such as this:
 \S{pscp-pubkey} Using public key authentication with PSCP
 
 Like PuTTY, PSCP can authenticate using a public key instead of a
 \S{pscp-pubkey} Using public key authentication with PSCP
 
 Like PuTTY, PSCP can authenticate using a public key instead of a

-password. There are two ways you can do this.
+password. There are three ways you can do this.

 
 Firstly, PSCP can use PuTTY saved sessions in place of hostnames
 (see \k{pscp-usage-basics-host}). So you would do this:
 
 \b Run PuTTY, and create a PuTTY saved session (see
 \k{config-saving}) which specifies your private key file (see
 
 Firstly, PSCP can use PuTTY saved sessions in place of hostnames
 (see \k{pscp-usage-basics-host}). So you would do this:
 
 \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
 \c{sessionname} is replaced by the name of your saved session.
 
 
 \b In PSCP, you can now use the name of the session instead of a
 hostname: type \c{pscp sessionname:file localfile}, where
 \c{sessionname} is replaced by the name of your saved session.
 

-Secondly, PSCP will attempt to authenticate using Pageant if Pageant
+Secondly, you can supply the name of a private key file on the command
+line, with the \c{-i} option. See \k{using-cmdline-identity} for more
+information.
+
+Thirdly, PSCP will attempt to authenticate using Pageant if Pageant

 is running (see \k{pageant}). So you would do this:
 
 \b Ensure Pageant is running, and has your private key stored in it.
 is running (see \k{pageant}). So you would do this:
 
 \b Ensure Pageant is running, and has your private key stored in it.