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

   1 \versionid $Id: pscp.but,v 1.4 2001/01/28 14:27:08 owen Exp $
   2
   3 \#FIXME: Need examples, index entries, links
   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 \H{pscp-intro} Introduction to PSCP
  11
  12 PSCP, the PuTTY Secure Copy client, is a tool for transferring files
  13 securely between computers using an SSH connection.
  14
  15 \H{pscp-starting} Starting PSCP
  16
  17 PSCP is a command line application.  This means that you cannot just
  18 double-click on its icon to run it and instead you have to bring up a
  19 console window.  With Windows 95, 98, and ME, this is called an
  20 \q{MS-DOS Prompt} and with Windows NT and 2000 it is called a
  21 \q{Command Prompt}.  It should be available from the Programs section
  22 of your Start Menu.
  23
  24 To start PSCP it will need either to be on your \c{PATH} or in your
  25 current directory.  To add the directory containing PSCP to your
  26 \c{PATH} environment variable, type into the console window:
  27
  28 \c set PATH C:\path\to\putty\directory;%PATH%
  29
  30 \# FIXME: or the Environment panel in NT, or something else in Win9x...
  31
  32 \H{pscp-usage} PSCP Usage
  33
  34 Once you've got a console window to type into, you can just type
  35 \c{pscp} on its own to bring up a usage message.  This tells you the
  36 version of PSCP you're using, and gives you a brief summary of how to
  37 use PSCP:
  38
  39 \c Z:\owendadmin>pscp
  40 \c PuTTY Secure Copy client
  41 \c Release 0.50
  42 \c Usage: pscp [options] [user@]host:source target
  43 \c       pscp [options] source [source...] [user@]host:target
  44 \c       pscp [options] -ls user@host:filespec
  45 \c Options:
  46 \c   -p        preserve file attributes
  47 \c   -q        quiet, don't show statistics
  48 \c   -r        copy directories recursively
  49 \c   -v        show verbose messages
  50 \c   -P port   connect to specified port
  51 \c   -pw passw login with specified password
  52
  53 (PSCP's interface is much like the Unix \c{scp} command, if you're
  54 familiar with that.)
  55
  56 \S{pscp-usage-basics} The basics
  57
  58 To receive (a) file(s) from a remote server:
  59
  60 \c{pscp [options] [user@]host:source target}
  61
  62 To send (a) file(s) to a remote server:
  63
  64 \c{pscp [options] source [source...] [user@]host:target}
  65
  66 \b \c{user} The login name on the remote server. If this is omitted, scp
  67 will try to use the default login from the PuTTY saved session.
  68
  69 \b \c{host} The name of the remote server, or the name of an existing PuTTY
  70 saved session. In the latter case, the session's settings for
  71 hostname, port number, cipher type and username will be used.
  72
  73 \b \c{source} One or more source files. Wildcards are allowed.
  74
  75 \# FIXME: describe wildcard syntax
  76
  77 \b \c{target} The filename or directory to put the file(s).
  78
  79 \S{pscp-usage-options} Options
  80
  81 \# Document each command line option.
  82
  83 \S2{pscp-usage-options-p}\c{-p} preserve file attributes
  84
  85 By default, files copied with PSCP are timestamped with the date and
  86 time they were copied.  The \c{-p} option preserves the original
  87 timestamp on copied files.
  88
  89 \S2{pscp-usage-options-q}\c{-q} quiet, don't show statistics
  90
  91 By default, PSCP displays a meter displaying the progress of the
  92 current transfer:
  93
  94 \c mibs.tar                  |        168 kB |  84.0 kB/s | ETA: 00:00:13 |  13%
  95
  96 The fields in this display are (from left to right), filename, size
  97 (in kilobytes) of file transferred so far, estimate of how fast the
  98 file is being transferred (in kilobytes per second), estimated time
  99 that the transfer will be complete, and percentage of the file so far
 100 transferred.  The \c{-q} option to PSCP suppresses the printing of
 101 these statistics.
 102
 103 \S2{pscp-usage-options-r}\c{-r} copies directories recursively
 104
 105 By default, PSCP will only copy files.  Any directories you specify to
 106 copy will be skipped, as will their contents.  The \c{-r} option tells
 107 PSCP to descend into any directories you specify, and to copy them and
 108 their contents.  This allows you to use PSCP to transfer whole
 109 directory structures between machines.
 110
 111 \S2{pscp-usage-options-v}\c{-v} show verbose messages
 112
 113 The \c{-v} option to PSCP makes it print extra information about the
 114 file transfer.  For example:
 115
 116 \c Logging in as "fred".
 117 \c fred@example.com's password:
 118 \c Sending command: scp -v -f mibs.tar
 119 \c Connected to example.com
 120 \c Sending file modes: C0644 1320960 mibs.tar
 121 \c mibs.tar                  |       1290 kB |  67.9 kB/s | ETA: 00:00:00 | 100%
 122 \c Remote exit status 0
 123 \c Closing connection
 124
 125 This information may be useful for debugging problems with PSCP.
 126
 127 \S2{pscp-usage-options-P}\c{-P port} connect to specified port
 128
 129 If the \c{host} you specify is a saved session, PSCP uses any port
 130 number specified in that saved session.  If not, PSCP uses the default
 131 SSH port, 22.  The \c{-P} option allows you specify the port number to
 132 connect to for PSCP's SSH connection.
 133
 134 \S2{pscp-usage-options-pw}\c{-pw passw} login with specified password
 135
 136 If a password is required to connect to the \c{host}, PSCP will
 137 interactively prompt you for it.  However, this may not always be
 138 appropriate.  If you are running PSCP as part of some automated job,
 139 it will not be possible to enter a password by hand.  The \c{-pw}
 140 option to PSCP lets you specify the password to use on the command
 141 line.
 142
 143 Since specifying passwords in scripts is a bad idea for security
 144 reasons, you might want instead to consider using public-key
 145 authentication (see \k{pubkey}).  PSCP will attempt to authenticate
 146 with any public key specified in a saved session's configuration
 147 before asking for a password.
 148
 149 \H{pscp-ixplorer} Secure iXplorer
 150
 151 Lars Gunnarson has written a graphical interface for PSCP.  You can
 152 get it from his web site, at
 153 \W{http://www.i-tree.org/}{www.i-tree.org}.