-\versionid $Id: pscp.but,v 1.9 2001/02/04 15:49:49 owen Exp $
+\versionid $Id: pscp.but,v 1.25 2004/02/22 14:48:48 jacob 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).
-
\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
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%
+\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
\c Z:\owendadmin>pscp
\c PuTTY Secure Copy client
-\c Release 0.50
+\c Release 0.54
\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 -load sessname Load settings from saved session
\c -P port connect to specified port
+\c -l user connect with specified username
\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.)
\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}
\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
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
+\S2{pscp-usage-options-batch}\c{-batch} avoid interactive prompts
+
+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.
+
+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-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,
+using code such as this:
+
+\c pscp file*.* user@hostname:
+\c if errorlevel 1 echo There was an error
-The \c{-v} option to PSCP makes it print extra information about the
-file transfer. For example:
+\S{pscp-pubkey} Using public key authentication with PSCP
-\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
+Like PuTTY, PSCP can authenticate using a public key instead of a
+password. There are three ways you can do this.
-This information may be useful for debugging problems with PSCP.
+Firstly, PSCP can use PuTTY saved sessions in place of hostnames
+(see \k{pscp-usage-basics-host}). So you would do this:
-\S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port}
+\b Run PuTTY, and create a PuTTY saved session (see
+\k{config-saving}) which specifies your private key file (see
+\k{config-ssh-privkey}). You will probably also want to specify a
+username to log in as (see \k{config-username}).
-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.
+\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.
-\S2{pscp-usage-options-pw}\c{-pw passw} login with specified \i{password}
+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.
-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.
+Thirdly, PSCP will attempt to authenticate using Pageant if Pageant
+is running (see \k{pageant}). So you would do 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{pubkey}). PSCP will attempt to authenticate
-with any key specified in a saved session's configuration or with a
-key stored in Pageant (see \k{pageant}) before asking for a password.
+\b Ensure Pageant is running, and has your private key stored in it.
-\H{pscp-ixplorer} \i{Secure iXplorer}
+\b Specify a user and host name to PSCP as normal. PSCP will
+automatically detect Pageant and try to use the keys within it.
-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}.
+For more general information on public-key authentication, see
+\k{pubkey}.
projects / u / mdw / putty / blobdiff