X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/e5b0d077dd2623867702f2e76afb776856eb77b4..9954aaa37368a233dc614d610ca68c2ce5a7e8cd:/doc/pscp.but diff --git a/doc/pscp.but b/doc/pscp.but index 57003d0d..627dd8f2 100644 --- a/doc/pscp.but +++ b/doc/pscp.but @@ -1,6 +1,222 @@ +\versionid $Id: pscp.but,v 1.12 2001/07/01 09:21:01 simon Exp $ + +\#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). -\# Link to iXplorer. +\i{PSCP}, the PuTTY Secure Copy client, is a tool for transferring files +securely between computers using an SSH connection. + +\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 +\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 \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% + +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 + +Once you've got a console window to type into, you can just type +\c{pscp} on its own to bring up a usage message. This tells you the +version of PSCP you're using, and gives you a brief summary of how to +use PSCP: + +\c Z:\owendadmin>pscp +\c PuTTY Secure Copy client +\c Release 0.50 +\c Usage: pscp [options] [user@]host:source target +\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 -P port connect to specified port +\c -pw passw login with specified password + +(PSCP's interface is much like the Unix \c{scp} command, if you're +familiar with that.) + +\S{pscp-usage-basics} The basics + +To receive (a) file(s) from a remote server: + +\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 + +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 + +\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. + +\S2{pscp-usage-basics-source} \c{source} + +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{*}). + +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). 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 + +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 \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 \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% + +The fields in this display are (from left to right), filename, size +(in kilobytes) of file transferred so far, estimate of how fast the +file is being transferred (in kilobytes per second), estimated time +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 \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-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-P}\c{-P port} connect to specified \i{port} + +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. + +\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} 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-auth}). 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} + +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}.