Integrate unfix.org's IPv6 patches up to level 10, with rather a lot
[u/mdw/putty] / doc / pscp.but
index 8304d45..4485b9b 100644 (file)
@@ -1,31 +1,30 @@
-\versionid $Id: pscp.but,v 1.5 2001/01/28 14:38:23 owen Exp $
+\define{versionidpscp} \versionid $Id$
 
 
-\#FIXME: Need examples, index entries, links
+\#FIXME: Need examples
 
 \C{pscp} Using PSCP to transfer files securely
 
 
 \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
+\i{PSCP}, the PuTTY Secure Copy client, is a tool for transferring files
 securely between computers using an SSH connection.
 
 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
 double-click on its icon to run it and instead you have to bring up a
 \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
+\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.
 
 \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
+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:
 
 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
 
 This will only work for the lifetime of that particular console
 window.  To set your \c{PATH} more permanently on Windows NT, use the
@@ -42,17 +41,28 @@ 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.XX
 \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   -4 -6     force use of IPv4 or IPv6
+\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)
+\c   -V        print version information
+\c   -sftp     force use of SFTP protocol
+\c   -scp      force use of SCP protocol
 
 (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.)
@@ -61,41 +71,132 @@ familiar with that.)
 
 To receive (a) file(s) from a remote server: 
 
 
 To receive (a) file(s) from a remote server: 
 
-\c{pscp [options] [user@]host:source target}
+\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: 
 
 
 To send (a) file(s) to a remote server: 
 
-\c{pscp [options] source [source...] [user@]host:target}
+\c pscp [options] source [source...] [user@]host:target
+
+So to copy the local file \c{c:\\documents\\foo.txt} to the server
+\c{example.com} as user \c{fred} to the file \c{/tmp/foo} you would
+type:
+
+\c pscp c:\documents\foo.txt fred@example.com:/tmp/foo
+
+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 saying something like \q{warning:
+remote host tried to write to a file called 'terminal.c' when we
+requested a file called '*.c'. If this is a wildcard, consider
+upgrading to SSH 2 or using 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. (You can force use of the SFTP protocol,
+if available, with \c{-sftp} - see \k{pscp-usage-options-backend}.)
+
+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}
+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}
 
 
-\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.
+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{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}
 
 
-\b \c{source} One or more source files. Wildcards are allowed.  
+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{*}).
 
 
-\# FIXME: describe wildcard syntax
+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.
 
 
-\b \c{target} The filename or directory to put the file(s).  
+\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
 
 
 \S{pscp-usage-options} Options
 
-\# Document each command line option.
+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
 
 
 \S2{pscp-usage-options-p}\c{-p} preserve file attributes
 
-By default, files copied with PSCP are timestamped with the date and
+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.
 
 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
+\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:
 
 
 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%
+\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
 
 The fields in this display are (from left to right), filename, size
 (in kilobytes) of file transferred so far, estimate of how fast the
@@ -104,7 +205,7 @@ 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.
 
 transferred.  The \c{-q} option to PSCP suppresses the printing of
 these statistics.
 
-\S2{pscp-usage-options-r}\c{-r} copies directories recursively
+\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
 
 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
@@ -112,46 +213,86 @@ 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 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.
+
+\S2{pscp-usage-options-backend}\c{-sftp}, \c{-scp} force use of
+particular protocol
+
+As mentioned in \k{pscp-usage-basics}, there are two different file
+transfer protocols in use with SSH. Despite its name, PSCP (like many
+other ostensible \cw{scp} clients) can use either of these protocols.
+
+The older SCP protocol does not have a written specification and
+leaves a lot of detail to the server platform. Wildcards are expanded
+on the server. The simple design means that any wildcard specification
+supported by the server platform (such as brace expansion) can be
+used, but also leads to interoperability issues such as with filename
+quoting (for instance, where filenames contain spaces), and also the
+security issue described in \k{pscp-usage-basics}.
+
+The newer SFTP protocol, which is usually associated with SSH 2
+servers, is specified in a more platform independent way, and leaves
+issues such as wildcard syntax up to the client. (PuTTY's SFTP
+wildcard syntax is described in \k{psftp-wildcards}.) This makes it
+more consistent across platforms, more suitable for scripting and
+automation, and avoids security issues with wildcard matching.
+
+Normally PSCP will attempt to use the SFTP protocol, and only fall
+back to the SCP protocol if SFTP is not available on the server.
+
+The \c{-scp} option forces PSCP to use the SCP protocol or quit.
+
+The \c{-sftp} option forces PSCP to use the SFTP protocol or quit.
+When this option is specified, PSCP looks harder for an SFTP server,
+which may allow use of SFTP with SSH 1 depending on server setup.
+
+\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 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 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 public key specified in a saved session's configuration
-before asking for a password.
+\b Ensure Pageant is running, and has your private key stored in it.
 
 
-\H{pscp-ixplorer} 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}.