X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/b3fa9b5ee0c6a8ecc97dcc654d66dcc92cc1dc87..9954aaa37368a233dc614d610ca68c2ce5a7e8cd:/doc/pscp.but diff --git a/doc/pscp.but b/doc/pscp.but index 657b12cd..627dd8f2 100644 --- a/doc/pscp.but +++ b/doc/pscp.but @@ -1,33 +1,35 @@ -\versionid $Id: pscp.but,v 1.4 2001/01/28 14:27:08 owen Exp $ +\versionid $Id: pscp.but,v 1.12 2001/07/01 09:21:01 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). -\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. \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 @@ -57,36 +59,77 @@ 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 + +\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{*}). -\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. +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. -\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. +\S2{pscp-usage-basics-target} \c{target} -\b \c{source} One or more source files. Wildcards are allowed. +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: -\# FIXME: describe wildcard syntax +\c pscp fred@example.com:/home/tom/.emacs . -\b \c{target} The filename or directory to put the file(s). +...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. +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: @@ -100,7 +143,7 @@ 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 @@ -108,7 +151,7 @@ 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 verbose messages +\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: @@ -124,14 +167,14 @@ file transfer. For example: This information may be useful for debugging problems with PSCP. -\S2{pscp-usage-options-P}\c{-P port} connect to specified port +\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 password +\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 @@ -142,11 +185,37 @@ 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 public key specified in a saved session's configuration -before asking for a password. +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} Secure iXplorer +\H{pscp-ixplorer} \i{Secure iXplorer} Lars Gunnarson has written a graphical interface for PSCP. You can get it from his web site, at