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

   1 \versionid $Id: pscp.but,v 1.3 2001/01/27 17:49:18 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 \S2{pscp-usage-options-v}\c{-v} show verbose messages
 106
 107 The \c{-v} option to PSCP makes it print extra information about the
 108 file transfer.  For example:
 109
 110 \c Logging in as "fred".
 111 \c fred@example.com's password:
 112 \c Sending command: scp -v -f mibs.tar
 113 \c Connected to example.com
 114 \c Sending file modes: C0644 1320960 mibs.tar
 115 \c mibs.tar                  |       1290 kB |  67.9 kB/s | ETA: 00:00:00 | 100%
 116 \c Remote exit status 0
 117 \c Closing connection
 118
 119 This information may be useful for debugging problems with PSCP.
 120
 121 \S2{pscp-usage-options-P}\c{-P port} connect to specified port
 122
 123 If the \c{host} you specify is a saved session, PSCP uses any port
 124 number specified in that saved session.  If not, PSCP uses the port
 125 specified for SSH in \e{Default Settings}, or the default SSH port,
 126 22. \#{Is this actually true?  Can you actually specify a different
 127 default port for a protocol in Default Settings?}
 128
 129 \S2{pscp-usage-options-pw}\c{-pw passw} login with specified password
 130
 131 If a password is required to connect to the \c{host}, PSCP will
 132 interactively prompt you for it.  However, this may not always be
 133 appropriate.  If you are running PSCP as part of some automated job,
 134 it will not be possible to enter a password by hand.  The \c{-p}
 135 option to PSCP lets you specify the password to use on the command
 136 line.
 137
 138 Since specifying passwords in scripts is a bad idea for security
 139 reasons, you might want instead to consider using public-key
 140 authentication.  PSCP will attempt to authenticate with any public key
 141 specified in a saved session's configuration before asking for a
 142 password.
 143
 144 \H{pscp-ixplorer} Secure iXplorer
 145
 146 Lars Gunnarson has written a graphical interface for PSCP.  You can
 147 get it from his web site, at
 148 \W{http://www.i-tree.org/}{www.i-tree.org}.