\versionid $Id: pscp.but,v 1.4 2001/01/28 14:27:08 owen Exp $

\#FIXME: Need examples, index entries, links

\C{pscp} Using PSCP to transfer files securely

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

\H{pscp-intro} Introduction to PSCP

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

\H{pscp-starting} Starting PSCP

PSCP is a command line application.  This means that you cannot just
double-click on its icon to run it and instead you have to bring up a
console window.  With Windows 95, 98, and ME, this is called an
\q{MS-DOS Prompt} and with Windows NT and 2000 it is called a
\q{Command Prompt}.  It should be available from the Programs section
of your Start Menu.

To start PSCP it will need either to be on your \c{PATH} or in your
current directory.  To add the directory containing PSCP to your
\c{PATH} environment variable, type into the console window:

\c set PATH C:\path\to\putty\directory;%PATH%

\# FIXME: or the Environment panel in NT, or something else in Win9x...

\H{pscp-usage} PSCP Usage

Once you've got a console window to type into, you can just type
\c{pscp} on its own to bring up a usage message.  This tells you the
version of PSCP you're using, and gives you a brief summary of how to
use PSCP:

\c Z:\owendadmin>pscp
\c PuTTY Secure Copy client
\c Release 0.50
\c Usage: pscp [options] [user@]host:source target
\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   -P port   connect to specified port
\c   -pw passw login with specified password

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

\S{pscp-usage-basics} The basics

To receive (a) file(s) from a remote server: 

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

To send (a) file(s) to a remote server: 

\c{pscp [options] source [source...] [user@]host:target}

\b \c{user} The login name on the remote server. If this is omitted, scp
will try to use the default login from the PuTTY saved session.

\b \c{host} The name of the remote server, or the name of an existing PuTTY
saved session. In the latter case, the session's settings for
hostname, port number, cipher type and username will be used.  

\b \c{source} One or more source files. Wildcards are allowed.  

\# FIXME: describe wildcard syntax

\b \c{target} The filename or directory to put the file(s).  

\S{pscp-usage-options} Options

\# Document each command line option.

\S2{pscp-usage-options-p}\c{-p} preserve file attributes

By default, files copied with PSCP are timestamped with the date and
time they were copied.  The \c{-p} option preserves the original
timestamp on copied files.

\S2{pscp-usage-options-q}\c{-q} quiet, don't show statistics

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%

The fields in this display are (from left to right), filename, size
(in kilobytes) of file transferred so far, estimate of how fast the
file is being transferred (in kilobytes per second), estimated time
that the transfer will be complete, and percentage of the file so far
transferred.  The \c{-q} option to PSCP suppresses the printing of
these statistics.

\S2{pscp-usage-options-r}\c{-r} copies directories recursively

By default, PSCP will only copy files.  Any directories you specify to
copy will be skipped, as will their contents.  The \c{-r} option tells
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.

\S2{pscp-usage-options-v}\c{-v} show 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 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 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{pubkey}).  PSCP will attempt to authenticate
with any public key specified in a saved session's configuration
before asking for a password.

\H{pscp-ixplorer} Secure iXplorer

Lars Gunnarson has written a graphical interface for PSCP.  You can
get it from his web site, at
\W{http://www.i-tree.org/}{www.i-tree.org}.