+\versionid $Id: pscp.but,v 1.12 2001/07/01 09:21:01 simon Exp $
+
+\#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).
-\# Link to iXplorer.
+\i{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
+\i{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 \i{\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%
+
+This will only work for the lifetime of that particular console
+window. To set your \c{PATH} more permanently on Windows NT, use the
+Environment tab of the System Control Panel. On Windows 95, 98, and
+ME, you will need to edit your \c{AUTOEXEC.BAT} to include a \c{set}
+command like the one above.
+
+\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
+
+So to copy the file \c{/etc/hosts} from the server \c{example.com} as
+user \c{fred} to the file \c{c:\\temp\\example-hosts.txt}, you would type:
+
+\c pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt
+
+To send (a) file(s) to a remote server:
+
+\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:
+
+\c pscp c:\documents\csh-whynot.txt fred@example.com:/tmp/csh-whynot
+
+\S2{pscp-usage-basics-user} \c{user}
+
+The login name on the remote server. If this is omitted, and \c{host}
+is a PuTTY saved session, PSCP will use any username specified by that
+saved session. Otherwise, PSCP will attempt to use the local Windows
+username.
+
+\S2{pscp-usage-basics-host} \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.
+
+\S2{pscp-usage-basics-source} \c{source}
+
+One or more source files. \i{Wildcards} are allowed. The syntax of
+wildcards depends on the system to which they apply, so if you are
+copying \e{from} a Windows system \e{to} a UNIX system, you should use
+Windows wildcard syntax (e.g. \c{*.*}), but if you are copying \e{from}
+a UNIX system \e{to} a Windows system, you would use the wildcard
+syntax allowed by your UNIX shell (e.g. \c{*}).
+
+If the source is a remote server and you do not specify a full
+pathname (in UNIX, a pathname beginning with a \c{/} (slash)
+character), what you specify as a source will be interpreted relative
+to your home directory on the remote server.
+
+\S2{pscp-usage-basics-target} \c{target}
+
+The filename or directory to put the file(s). When copying from a
+remote server to a local host, you may wish simply to place the
+file(s) in the current directory. To do this, you should specify a
+target of \c{.}. For example:
+
+\c pscp fred@example.com:/home/tom/.emacs .
+
+...would copy \c{/home/tom/.emacs} on the remote server to the current
+directory.
+
+As with the \c{source} parameter, if the target is on a remote server
+and is not a full path name, it is interpreted relative to your home
+directory on the remote server.
+
+\S{pscp-usage-options} Options
+
+These are the command line options that PSCP accepts.
+
+\S2{pscp-usage-options-p}\c{-p} preserve file attributes
+
+By default, files copied with PSCP are \i{timestamp}ed 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 \i{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 \i{recursive}ly
+
+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 \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}
+
+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} 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.
+
+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}).
+
+\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
+is running (see \k{pageant}). So you would do this:
+
+\b Ensure Pageant is running, and has your private key stored in it.
+
+\b Specify a user and host name to PSCP as normal. PSCP will
+automatically detect Pageant and try to use the keys within it.
+
+For more general information on public-key authentication, see
+\k{pubkey}.
+
+\H{pscp-ixplorer} \i{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}.
projects / u / mdw / putty / blobdiff