-\versionid $Id: pscp.but,v 1.22 2002/09/11 17:30:36 jacob Exp $
+\define{versionidpscp} \versionid $Id$
\#FIXME: Need examples
\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
+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
\c Z:\owendadmin>pscp
\c PuTTY Secure Copy client
-\c Release 0.53
+\c Release 0.XX
\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] -ls [user@]host:filespec
\c Options:
+\c -V print version information and exit
+\c -pgpfp print PGP key fingerprints and exit
\c -p preserve file attributes
\c -q quiet, don't show statistics
\c -r copy directories recursively
\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 -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 -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.)
\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:
+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\csh-whynot.txt fred@example.com:/tmp/csh-whynot
+\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 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.
+files) you may see a warning saying something like \q{warning:
+remote host tried to write to a file called \cq{terminal.c} when we
+requested a file called \cq{*.c}. If this is a wildcard, consider
+upgrading to SSH-2 or using the \cq{-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
cannot reliably verify that the filenames sent back match the
pattern.
-PSCP will attempt to use the newer SFTP protocol (part of SSH 2)
+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 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
+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
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).
+server machine be cracked by malicious people). Alternatively, do
+any such download in a newly created empty directory. (Even in
+\q{unsafe} mode, PSCP will still protect you against the server
+trying to get out of that directory using pathnames including
+\cq{..}.)
\S2{pscp-usage-basics-user} \c{user}
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
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
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}.