X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/ffd641146e9eff7ee3c1349663729477ca630f17..41d3adbbfed77605e4a397ce199c5751c35bf94b:/doc/pscp.but

diff --git a/doc/pscp.but b/doc/pscp.but
index 08be2d0b..5da247df 100644
--- a/doc/pscp.but
+++ b/doc/pscp.but
@@ -1,15 +1,16 @@
-\versionid $Id: pscp.but,v 1.6 2001/01/31 00:25:57 owen Exp $
+\versionid $Id: pscp.but,v 1.20 2001/12/31 16:15:19 simon Exp $
 
-\#FIXME: Need examples, index entries, links
+\#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
@@ -23,7 +24,7 @@ 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%
+\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
@@ -59,11 +60,64 @@ familiar with that.)
 
 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: 
 
-\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\\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
+
+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}
 
@@ -83,13 +137,30 @@ number, cipher type and username will be used.
 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 \{from} 
+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).
+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
 
@@ -157,9 +228,56 @@ 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 key specified in a saved session's configuration or with a
-key stored in Pageant (see \k{pageant}) before asking for a password.
+authentication; see \k{pscp-pubkey}.
+
+\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
+
+\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-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
+\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}