Document all the new command-line stuff.

[PuTTY.git] / doc / pscp.but

diff --git a/doc/pscp.but b/doc/pscp.but
index 26bb8790e64ae4ca1161f966a73ca67390ed7d29..ad0144c7504a32559401d25d1e346ae0bab31fb7 100644 (file)
--- a/doc/pscp.but
+++ b/doc/pscp.but
@@ -1,4 +1,4 @@
-\versionid $Id: pscp.but,v 1.14 2001/09/22 15:36:44 simon Exp $
+\versionid $Id: pscp.but,v 1.21 2002/08/07 19:20:06 simon 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


@@ -160,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


@@ -190,43 +202,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
-
-This information may be useful for debugging problems with PSCP.
-
-\S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port}
-
-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}
+\S2{pscp-usage-options-batch}\c{-batch} avoid interactive prompts

 
 

-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.
+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.

 
 

-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}.
+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.

 
 

-\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,


@@ -245,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


@@ -267,6 +255,4 @@ For more general information on public-key authentication, see
 
 Lars Gunnarson has written a graphical interface for PSCP.  You can
 get it from his web site, at
 
 Lars Gunnarson has written a graphical interface for PSCP.  You can
 get it from his web site, at

-\W{http://members.surfeu.at/lgunnars/daplay/}{members.surfeu.at}.
-\# \W{http://www.i-tree.org/}{www.i-tree.org}.
-\# update this if the original site ever returns.
+\W{http://www.i-tree.org/}{www.i-tree.org}.