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

   1 \versionid $Id: pscp.but,v 1.6 2001/01/31 00:25:57 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 \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 To send (a) file(s) to a remote server:
  65
  66 \c{pscp [options] source [source...] [user@]host:target}
  67
  68 \S2{pscp-usage-basics-user} \c{user}
  69
  70 The login name on the remote server. If this is omitted, and \c{host}
  71 is a PuTTY saved session, PSCP will use any username specified by that
  72 saved session.  Otherwise, PSCP will attempt to use the local Windows
  73 username.
  74
  75 \S2{pscp-usage-basics-host} \c{host}
  76
  77 The name of the remote server, or the name of an existing PuTTY saved
  78 session. In the latter case, the session's settings for hostname, port
  79 number, cipher type and username will be used.
  80
  81 \S2{pscp-usage-basics-source} \c{source}
  82
  83 One or more source files. \i{Wildcards} are allowed.  The syntax of
  84 wildcards depends on the system to which they apply, so if you are
  85 copying \e{from} a Windows system \e{to} a UNIX system, you should use
  86 Windows wildcard syntax (e.g. \c{*.*}), but if you are copying \{from}
  87 a UNIX system \e{to} a Windows system, you would use the wildcard
  88 syntax allowed by your UNIX shell (e.g. \c{*}).
  89
  90 \S2{pscp-usage-basics-target} \c{target}
  91
  92 The filename or directory to put the file(s).
  93
  94 \S{pscp-usage-options} Options
  95
  96 These are the command line options that PSCP accepts.
  97
  98 \S2{pscp-usage-options-p}\c{-p} preserve file attributes
  99
 100 By default, files copied with PSCP are \i{timestamp}ed with the date and
 101 time they were copied.  The \c{-p} option preserves the original
 102 timestamp on copied files.
 103
 104 \S2{pscp-usage-options-q}\c{-q} quiet, don't show \i{statistics}
 105
 106 By default, PSCP displays a meter displaying the progress of the
 107 current transfer:
 108
 109 \c mibs.tar                  |        168 kB |  84.0 kB/s | ETA: 00:00:13 |  13%
 110
 111 The fields in this display are (from left to right), filename, size
 112 (in kilobytes) of file transferred so far, estimate of how fast the
 113 file is being transferred (in kilobytes per second), estimated time
 114 that the transfer will be complete, and percentage of the file so far
 115 transferred.  The \c{-q} option to PSCP suppresses the printing of
 116 these statistics.
 117
 118 \S2{pscp-usage-options-r}\c{-r} copies directories \i{recursive}ly
 119
 120 By default, PSCP will only copy files.  Any directories you specify to
 121 copy will be skipped, as will their contents.  The \c{-r} option tells
 122 PSCP to descend into any directories you specify, and to copy them and
 123 their contents.  This allows you to use PSCP to transfer whole
 124 directory structures between machines.
 125
 126 \S2{pscp-usage-options-v}\c{-v} show \i{verbose} messages
 127
 128 The \c{-v} option to PSCP makes it print extra information about the
 129 file transfer.  For example:
 130
 131 \c Logging in as "fred".
 132 \c fred@example.com's password:
 133 \c Sending command: scp -v -f mibs.tar
 134 \c Connected to example.com
 135 \c Sending file modes: C0644 1320960 mibs.tar
 136 \c mibs.tar                  |       1290 kB |  67.9 kB/s | ETA: 00:00:00 | 100%
 137 \c Remote exit status 0
 138 \c Closing connection
 139
 140 This information may be useful for debugging problems with PSCP.
 141
 142 \S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port}
 143
 144 If the \c{host} you specify is a saved session, PSCP uses any port
 145 number specified in that saved session.  If not, PSCP uses the default
 146 SSH port, 22.  The \c{-P} option allows you specify the port number to
 147 connect to for PSCP's SSH connection.
 148
 149 \S2{pscp-usage-options-pw}\c{-pw passw} login with specified \i{password}
 150
 151 If a password is required to connect to the \c{host}, PSCP will
 152 interactively prompt you for it.  However, this may not always be
 153 appropriate.  If you are running PSCP as part of some automated job,
 154 it will not be possible to enter a password by hand.  The \c{-pw}
 155 option to PSCP lets you specify the password to use on the command
 156 line.
 157
 158 Since specifying passwords in scripts is a bad idea for security
 159 reasons, you might want instead to consider using public-key
 160 authentication (see \k{pubkey}).  PSCP will attempt to authenticate
 161 with any key specified in a saved session's configuration or with a
 162 key stored in Pageant (see \k{pageant}) before asking for a password.
 163
 164 \H{pscp-ixplorer} \i{Secure iXplorer}
 165
 166 Lars Gunnarson has written a graphical interface for PSCP.  You can
 167 get it from his web site, at
 168 \W{http://www.i-tree.org/}{www.i-tree.org}.