X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/768ada0c5125b2a51e219df8181bbbb5e8459c9e..39a938f7a5e16b4be9bee493251238710fbff396:/doc/pscp.but diff --git a/doc/pscp.but b/doc/pscp.but index bb97bb6b..e5f1778c 100644 --- a/doc/pscp.but +++ b/doc/pscp.but @@ -1,33 +1,36 @@ -\versionid $Id: pscp.but,v 1.2 2001/01/27 16:26:55 owen Exp $ +\define{versionidpscp} \versionid $Id$ -\#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). - -\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. +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 -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. -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: -\c set PATH C:\path\to\putty\directory;%PATH% +\c set PATH=C:\path\to\putty\directory;%PATH% -\# FIXME: or the Environment panel in NT, or something else in Win9x... +This will only work for the lifetime of that particular console +window. To set your \c{PATH} more permanently on Windows NT, use the +Environment tab of the System Control Panel. On Windows 95, 98, and +ME, you will need to edit your \c{AUTOEXEC.BAT} to include a \c{set} +command like the one above. \H{pscp-usage} PSCP Usage @@ -38,17 +41,27 @@ 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 +\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.) @@ -57,41 +70,132 @@ 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\\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} + +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{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. +\S2{pscp-usage-basics-source} \c{source} -\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. +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{*}). -\b \c{source} One or more source files. Wildcards are allowed. +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. -\# FIXME: describe wildcard syntax +\S2{pscp-usage-basics-target} \c{target} -\b \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 -\# 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 -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. -\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: -\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 @@ -100,37 +204,93 @@ 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. -\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 +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-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. This makes it more +consistent across platforms, more suitable for scripting and +automation, and avoids security issues with wilcard 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 -\S2{pscp-usage-options-v}\c{-v} show verbose messages +\S{pscp-pubkey} Using public key authentication with PSCP -The \c{-v} option to PSCP makes it print extra information about the -file transfer. For example: +Like PuTTY, PSCP can authenticate using a public key instead of a +password. There are three ways you can do this. -\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 +Firstly, PSCP can use PuTTY saved sessions in place of hostnames +(see \k{pscp-usage-basics-host}). So you would do this: -This information may be useful for debugging problems with PSCP. +\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}). -\S2{pscp-usage-options-P}\c{-P port} connect to specified port +\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. -\# Defaults: Saved Session, or 22 +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. -\S2{pscp-usage-options-pw}\c{-pw passw} login with specified password +Thirdly, PSCP will attempt to authenticate using Pageant if Pageant +is running (see \k{pageant}). So you would do this: -\# Default is to ask. (May not be appropriate when running PSCP from -\# batch scripts etc.) -\# But should be using RSA key authentication (qv.) and possibly -\# Pageant (qv.) anyway. +\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}.