1 \versionid $Id: pscp.but,v 1.12 2001/07/01 09:21:01 simon Exp $
5 \C{pscp} Using PSCP to transfer files securely
7 \# Explain PSCP: the command line, the modes of use (local->remote
8 \# and remote->local, recursive, wildcards).
10 \i{PSCP}, the PuTTY Secure Copy client, is a tool for transferring files
11 securely between computers using an SSH connection.
13 \H{pscp-starting} Starting PSCP
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
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:
26 \c set PATH=C:\path\to\putty\directory;%PATH%
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.
34 \H{pscp-usage} PSCP Usage
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
42 \c PuTTY Secure Copy client
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
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
55 (PSCP's interface is much like the Unix \c{scp} command, if you're
58 \S{pscp-usage-basics} The basics
60 To receive (a) file(s) from a remote server:
62 \c pscp [options] [user@]host:source target
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:
67 \c pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt
69 To send (a) file(s) to a remote server:
71 \c pscp [options] source [source...] [user@]host:target
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:
77 \c pscp c:\documents\csh-whynot.txt fred@example.com:/tmp/csh-whynot
79 \S2{pscp-usage-basics-user} \c{user}
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
86 \S2{pscp-usage-basics-host} \c{host}
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.
92 \S2{pscp-usage-basics-source} \c{source}
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{*}).
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.
106 \S2{pscp-usage-basics-target} \c{target}
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:
113 \c pscp fred@example.com:/home/tom/.emacs .
115 ...would copy \c{/home/tom/.emacs} on the remote server to the current
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.
122 \S{pscp-usage-options} Options
124 These are the command line options that PSCP accepts.
126 \S2{pscp-usage-options-p}\c{-p} preserve file attributes
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.
132 \S2{pscp-usage-options-q}\c{-q} quiet, don't show \i{statistics}
134 By default, PSCP displays a meter displaying the progress of the
137 \c mibs.tar | 168 kB | 84.0 kB/s | ETA: 00:00:13 | 13%
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
146 \S2{pscp-usage-options-r}\c{-r} copies directories \i{recursive}ly
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.
154 \S2{pscp-usage-options-v}\c{-v} show \i{verbose} messages
156 The \c{-v} option to PSCP makes it print extra information about the
157 file transfer. For example:
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
168 This information may be useful for debugging problems with PSCP.
170 \S2{pscp-usage-options-P}\c{-P port} connect to specified \i{port}
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.
177 \S2{pscp-usage-options-pw}\c{-pw passw} login with specified \i{password}
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
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}.
190 \S{pscp-pubkey} Using public key authentication with PSCP
192 Like PuTTY, PSCP can authenticate using a public key instead of a
193 password. There are two ways you can do this.
195 Firstly, PSCP can use PuTTY saved sessions in place of hostnames
196 (see \k{pscp-usage-basics-host}). So you would do this:
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}).
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.
207 Secondly, PSCP will attempt to authenticate using Pageant if Pageant
208 is running (see \k{pageant}). So you would do this:
210 \b Ensure Pageant is running, and has your private key stored in it.
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.
215 For more general information on public-key authentication, see
218 \H{pscp-ixplorer} \i{Secure iXplorer}
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}.