mdw@git.distorted.org.uk Git - sgt/putty/blob - doc/pscp.but

   1 \versionid $Id: pscp.but,v 1.12 2001/07/01 09:21:01 simon Exp $
   2
   3 \#FIXME: Need examples
   4
   5 \C{pscp} Using PSCP to transfer files securely
   6
   7 \# Explain PSCP: the command line, the modes of use (local->remote
   8 \# and remote->local, recursive, wildcards).
   9
  10 \i{PSCP}, the PuTTY Secure Copy client, is a tool for transferring files
  11 securely between computers using an SSH connection.
  12
  13 \H{pscp-starting} Starting PSCP
  14
  15 PSCP is a command line application.  This means that you cannot just
  16 double-click on its icon to run it and instead you have to bring up a
  17 \i{console window}.  With Windows 95, 98, and ME, this is called an
  18 \q{MS-DOS Prompt} and with Windows NT and 2000 it is called a
  19 \q{Command Prompt}.  It should be available from the Programs section
  20 of your Start Menu.
  21
  22 To start PSCP it will need either to be on your \i{\c{PATH}} or in your
  23 current directory.  To add the directory containing PSCP to your
  24 \c{PATH} environment variable, type into the console window:
  25
  26 \c set PATH=C:\path\to\putty\directory;%PATH%
  27
  28 This will only work for the lifetime of that particular console
  29 window.  To set your \c{PATH} more permanently on Windows NT, use the
  30 Environment tab of the System Control Panel.  On Windows 95, 98, and
  31 ME, you will need to edit your \c{AUTOEXEC.BAT} to include a \c{set}
  32 command like the one above.
  33
  34 \H{pscp-usage} PSCP Usage
  35
  36 Once you've got a console window to type into, you can just type
  37 \c{pscp} on its own to bring up a usage message.  This tells you the
  38 version of PSCP you're using, and gives you a brief summary of how to
  39 use PSCP:
  40
  41 \c Z:\owendadmin>pscp
  42 \c PuTTY Secure Copy client
  43 \c Release 0.50
  44 \c Usage: pscp [options] [user@]host:source target
  45 \c       pscp [options] source [source...] [user@]host:target
  46 \c       pscp [options] -ls user@host:filespec
  47 \c Options:
  48 \c   -p        preserve file attributes
  49 \c   -q        quiet, don't show statistics
  50 \c   -r        copy directories recursively
  51 \c   -v        show verbose messages
  52 \c   -P port   connect to specified port
  53 \c   -pw passw login with specified password
  54
  55 (PSCP's interface is much like the Unix \c{scp} command, if you're
  56 familiar with that.)
  57
  58 \S{pscp-usage-basics} The basics
  59
  60 To receive (a) file(s) from a remote server:
  61
  62 \c pscp [options] [user@]host:source target
  63
  64 So to copy the file \c{/etc/hosts} from the server \c{example.com} as
  65 user \c{fred} to the file \c{c:\\temp\\example-hosts.txt}, you would type:
  66
  67 \c pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt
  68
  69 To send (a) file(s) to a remote server:
  70
  71 \c pscp [options] source [source...] [user@]host:target
  72
  73 So to copy the local file \c{c:\\documents\\csh-whynot.txt} to the
  74 server \c{example.com} as user \c{fred} to the file
  75 \c{/tmp/csh-whynot} you would type:
  76
  77 \c pscp c:\documents\csh-whynot.txt fred@example.com:/tmp/csh-whynot
  78
  79 \S2{pscp-usage-basics-user} \c{user}
  80
  81 The login name on the remote server. If this is omitted, and \c{host}
  82 is a PuTTY saved session, PSCP will use any username specified by that
  83 saved session.  Otherwise, PSCP will attempt to use the local Windows
  84 username.
  85
  86 \S2{pscp-usage-basics-host} \c{host}
  87
  88 The name of the remote server, or the name of an existing PuTTY saved
  89 session. In the latter case, the session's settings for hostname, port
  90 number, cipher type and username will be used.
  91
  92 \S2{pscp-usage-basics-source} \c{source}
  93
  94 One or more source files. \i{Wildcards} are allowed.  The syntax of
  95 wildcards depends on the system to which they apply, so if you are
  96 copying \e{from} a Windows system \e{to} a UNIX system, you should use
  97 Windows wildcard syntax (e.g. \c{*.*}), but if you are copying \e{from}
  98 a UNIX system \e{to} a Windows system, you would use the wildcard
  99 syntax allowed by your UNIX shell (e.g. \c{*}).
 100
 101 If the source is a remote server and you do not specify a full
 102 pathname (in UNIX, a pathname beginning with a \c{/} (slash)
 103 character), what you specify as a source will be interpreted relative
 104 to your home directory on the remote server.
 105
 106 \S2{pscp-usage-basics-target} \c{target}
 107
 108 The filename or directory to put the file(s).  When copying from a
 109 remote server to a local host, you may wish simply to place the
 110 file(s) in the current directory.  To do this, you should specify a
 111 target of \c{.}.  For example:
 112
 113 \c pscp fred@example.com:/home/tom/.emacs .
 114
 115 ...would copy \c{/home/tom/.emacs} on the remote server to the current
 116 directory.
 117
 118 As with the \c{source} parameter, if the target is on a remote server
 119 and is not a full path name, it is interpreted relative to your home
 120 directory on the remote server.
 121
 122 \S{pscp-usage-options} Options
 123
 124 These are the command line options that PSCP accepts.
 125
 126 \S2{pscp-usage-options-p}\c{-p} preserve file attributes
 127
 128 By default, files copied with PSCP are \i{timestamp}ed with the date and
 129 time they were copied.  The \c{-p} option preserves the original
 130 timestamp on copied files.
 131
 132 \S2{pscp-usage-options-q}\c{-q} quiet, don't show \i{statistics}
 133
 134 By default, PSCP displays a meter displaying the progress of the
 135 current transfer:
 136
 137 \c mibs.tar                  |        168 kB |  84.0 kB/s | ETA: 00:00:13 |  13%
 138
 139 The fields in this display are (from left to right), filename, size
 140 (in kilobytes) of file transferred so far, estimate of how fast the
 141 file is being transferred (in kilobytes per second), estimated time
 142 that the transfer will be complete, and percentage of the file so far
 143 transferred.  The \c{-q} option to PSCP suppresses the printing of
 144 these statistics.
 145
 146 \S2{pscp-usage-options-r}\c{-r} copies directories \i{recursive}ly
 147
 148 By default, PSCP will only copy files.  Any directories you specify to
 149 copy will be skipped, as will their contents.  The \c{-r} option tells
 150 PSCP to descend into any directories you specify, and to copy them and
 151 their contents.  This allows you to use PSCP to transfer whole
 152 directory structures between machines.
 153
 154 \S2{pscp-usage-options-v}\c{-v} show \i{verbose} messages
 155
 156 The \c{-v} option to PSCP makes it print extra information about the
 157 file transfer.  For example:
 158
 159 \c Logging in as "fred".
 160 \c fred@example.com's password:
 161 \c Sending command: scp -v -f mibs.tar
 162 \c Connected to example.com
 163 \c Sending file modes: C0644 1320960 mibs.tar
 164 \c mibs.tar                  |       1290 kB |  67.9 kB/s | ETA: 00:00:00 | 100%
 165 \c Remote exit status 0
 166 \c Closing connection
 167
 168 This information may be useful for debugging problems with PSCP.
 169
 170 \S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port}
 171
 172 If the \c{host} you specify is a saved session, PSCP uses any port
 173 number specified in that saved session.  If not, PSCP uses the default
 174 SSH port, 22.  The \c{-P} option allows you specify the port number to
 175 connect to for PSCP's SSH connection.
 176
 177 \S2{pscp-usage-options-pw}\c{-pw passw} login with specified \i{password}
 178
 179 If a password is required to connect to the \c{host}, PSCP will
 180 interactively prompt you for it.  However, this may not always be
 181 appropriate.  If you are running PSCP as part of some automated job,
 182 it will not be possible to enter a password by hand.  The \c{-pw}
 183 option to PSCP lets you specify the password to use on the command
 184 line.
 185
 186 Since specifying passwords in scripts is a bad idea for security
 187 reasons, you might want instead to consider using public-key
 188 authentication; see \k{pscp-pubkey}.
 189
 190 \S{pscp-pubkey} Using public key authentication with PSCP
 191
 192 Like PuTTY, PSCP can authenticate using a public key instead of a
 193 password. There are two ways you can do this.
 194
 195 Firstly, PSCP can use PuTTY saved sessions in place of hostnames
 196 (see \k{pscp-usage-basics-host}). So you would do this:
 197
 198 \b Run PuTTY, and create a PuTTY saved session (see
 199 \k{config-saving}) which specifies your private key file (see
 200 \k{config-auth}). You will probably also want to specify a username
 201 to log in as (see \k{config-username}).
 202
 203 \b In PSCP, you can now use the name of the session instead of a
 204 hostname: type \c{pscp sessionname:file localfile}, where
 205 \c{sessionname} is replaced by the name of your saved session.
 206
 207 Secondly, PSCP will attempt to authenticate using Pageant if Pageant
 208 is running (see \k{pageant}). So you would do this:
 209
 210 \b Ensure Pageant is running, and has your private key stored in it.
 211
 212 \b Specify a user and host name to PSCP as normal. PSCP will
 213 automatically detect Pageant and try to use the keys within it.
 214
 215 For more general information on public-key authentication, see
 216 \k{pubkey}.
 217
 218 \H{pscp-ixplorer} \i{Secure iXplorer}
 219
 220 Lars Gunnarson has written a graphical interface for PSCP.  You can
 221 get it from his web site, at
 222 \W{http://www.i-tree.org/}{www.i-tree.org}.