X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/a41965794a63cac0a98650e40a2c0c3076b91cbf..a5dd84675905dfc4274cf45424e6f3a9e385e1a7:/doc/pscp.but diff --git a/doc/pscp.but b/doc/pscp.but index f31b8d5b..c4ccc644 100644 --- a/doc/pscp.but +++ b/doc/pscp.but @@ -1,4 +1,4 @@ -\versionid $Id: pscp.but,v 1.13 2001/08/28 09:53:51 simon Exp $ +\versionid $Id: pscp.but,v 1.26 2004/04/24 12:25:08 jacob Exp $ \#FIXME: Need examples @@ -7,6 +7,10 @@ \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 @@ -37,17 +41,25 @@ use PSCP: \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 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) +\c -V print version information (PSCP's interface is much like the Unix \c{scp} command, if you're familiar with that.) @@ -160,6 +172,14 @@ directory on the remote server. \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 @@ -190,43 +210,19 @@ 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-batch}\c{-batch} avoid interactive prompts -\S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port} +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. -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. +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-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} Return value +\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, @@ -238,21 +234,25 @@ using code such as this: \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. +password. There are three 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}). +\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 +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. + +Thirdly, 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. @@ -262,9 +262,3 @@ 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}.