1 \define{versionidpscp} \versionid $Id$
5 \C{pscp} Using \i{PSCP} to transfer files securely
7 \i{PSCP}, the PuTTY Secure Copy client, is a tool for \i{transferring files}
8 securely between computers using an SSH connection.
10 If you have an SSH-2 server, you might prefer PSFTP (see \k{psftp})
11 for interactive use. PSFTP does not in general work with SSH-1
14 \H{pscp-starting} Starting PSCP
16 PSCP is a command line application. This means that you cannot just
17 double-click on its icon to run it and instead you have to bring up a
18 \i{console window}. With Windows 95, 98, and ME, this is called an
19 \q{MS-DOS Prompt} and with Windows NT, 2000, and XP, it is called a
20 \q{Command Prompt}. It should be available from the Programs section
21 of your \i{Start Menu}.
23 To start PSCP it will need either to be on your \i{\c{PATH}} or in your
24 current directory. To add the directory containing PSCP to your
25 \c{PATH} environment variable, type into the console window:
27 \c set PATH=C:\path\to\putty\directory;%PATH%
29 This will only work for the lifetime of that particular console
30 window. To set your \c{PATH} more permanently on Windows NT, 2000,
31 and XP, use the Environment tab of the System Control Panel. On
32 Windows 95, 98, and ME, you will need to edit your \i\c{AUTOEXEC.BAT}
33 to include a \c{set} command like the one above.
35 \H{pscp-usage} PSCP Usage
37 Once you've got a console window to type into, you can just type
38 \c{pscp} on its own to bring up a usage message. This tells you the
39 version of PSCP you're using, and gives you a brief summary of how to
43 \c PuTTY Secure Copy client
45 \c Usage: pscp [options] [user@]host:source target
46 \c pscp [options] source [source...] [user@]host:target
47 \c pscp [options] -ls [user@]host:filespec
49 \c -V print version information and exit
50 \c -pgpfp print PGP key fingerprints and exit
51 \c -p preserve file attributes
52 \c -q quiet, don't show statistics
53 \c -r copy directories recursively
54 \c -v show verbose messages
55 \c -load sessname Load settings from saved session
56 \c -P port connect to specified port
57 \c -l user connect with specified username
58 \c -pw passw login with specified password
59 \c -1 -2 force use of particular SSH protocol version
60 \c -4 -6 force use of IPv4 or IPv6
61 \c -C enable compression
62 \c -i key private key file for authentication
63 \c -noagent disable use of Pageant
64 \c -agent enable use of Pageant
65 \c -batch disable all interactive prompts
66 \c -unsafe allow server-side wildcards (DANGEROUS)
67 \c -sftp force use of SFTP protocol
68 \c -scp force use of SCP protocol
70 (PSCP's interface is much like the Unix \c{scp} command, if you're
73 \S{pscp-usage-basics} The basics
75 To \I{receiving files}receive (a) file(s) from a remote server:
77 \c pscp [options] [user@]host:source target
79 So to copy the file \c{/etc/hosts} from the server \c{example.com} as
80 user \c{fred} to the file \c{c:\\temp\\example-hosts.txt}, you would type:
82 \c pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt
84 To \I{sending files}send (a) file(s) to a remote server:
86 \c pscp [options] source [source...] [user@]host:target
88 So to copy the local file \c{c:\\documents\\foo.txt} to the server
89 \c{example.com} as user \c{fred} to the file \c{/tmp/foo} you would
92 \c pscp c:\documents\foo.txt fred@example.com:/tmp/foo
94 You can use \i{wildcards} to transfer multiple files in either
97 \c pscp c:\documents\*.doc fred@example.com:docfiles
98 \c pscp fred@example.com:source/*.c c:\source
100 However, in the second case (using a wildcard for multiple remote
101 files) you may see a warning saying something like \q{warning:
102 remote host tried to write to a file called \cq{terminal.c} when we
103 requested a file called \cq{*.c}. If this is a wildcard, consider
104 upgrading to SSH-2 or using the \cq{-unsafe} option. Renaming of
105 this file has been disallowed}.
107 This is due to a \I{security risk}fundamental insecurity in the old-style
108 \i{SCP protocol}: the client sends the wildcard string (\c{*.c}) to the
109 server, and the server sends back a sequence of file names that
110 match the wildcard pattern. However, there is nothing to stop the
111 server sending back a \e{different} pattern and writing over one of
112 your other files: if you request \c{*.c}, the server might send back
113 the file name \c{AUTOEXEC.BAT} and install a virus for you. Since
114 the wildcard matching rules are decided by the server, the client
115 cannot reliably verify that the filenames sent back match the
118 PSCP will attempt to use the newer \i{SFTP} protocol (part of SSH-2)
119 where possible, which does not suffer from this security flaw. If
120 you are talking to an SSH-2 server which supports SFTP, you will
121 never see this warning. (You can force use of the SFTP protocol,
122 if available, with \c{-sftp} - see \k{pscp-usage-options-backend}.)
124 If you really need to use a server-side wildcard with an SSH-1
125 server, you can use the \i\c{-unsafe} command line option with PSCP:
127 \c pscp -unsafe fred@example.com:source/*.c c:\source
129 This will suppress the warning message and the file transfer will
130 happen. However, you should be aware that by using this option you
131 are giving the server the ability to write to \e{any} file in the
132 target directory, so you should only use this option if you trust
133 the server administrator not to be malicious (and not to let the
134 server machine be cracked by malicious people). Alternatively, do
135 any such download in a newly created empty directory. (Even in
136 \q{unsafe} mode, PSCP will still protect you against the server
137 trying to get out of that directory using pathnames including
140 \S2{pscp-usage-basics-user} \c{user}
142 The \i{login name} on the remote server. If this is omitted, and \c{host}
143 is a PuTTY saved session, PSCP will use any username specified by that
144 saved session. Otherwise, PSCP will attempt to use the local Windows
147 \S2{pscp-usage-basics-host} \I{hostname}\c{host}
149 The name of the remote server, or the name of an existing PuTTY saved
150 session. In the latter case, the session's settings for hostname, port
151 number, cipher type and username will be used.
153 \S2{pscp-usage-basics-source} \c{source}
155 One or more source files. \ii{Wildcards} are allowed. The syntax of
156 wildcards depends on the system to which they apply, so if you are
157 copying \e{from} a Windows system \e{to} a UNIX system, you should use
158 Windows wildcard syntax (e.g. \c{*.*}), but if you are copying \e{from}
159 a UNIX system \e{to} a Windows system, you would use the wildcard
160 syntax allowed by your UNIX shell (e.g. \c{*}).
162 If the source is a remote server and you do not specify a full
163 pathname (in UNIX, a pathname beginning with a \c{/} (slash)
164 character), what you specify as a source will be interpreted relative
165 to your \i{home directory} on the remote server.
167 \S2{pscp-usage-basics-target} \c{target}
169 The filename or directory to put the file(s). When copying from a
170 remote server to a local host, you may wish simply to place the
171 file(s) in the current directory. To do this, you should specify a
172 target of \c{.}. For example:
174 \c pscp fred@example.com:/home/tom/.emacs .
176 ...would copy \c{/home/tom/.emacs} on the remote server to the current
179 As with the \c{source} parameter, if the target is on a remote server
180 and is not a full path name, it is interpreted relative to your home
181 directory on the remote server.
183 \S{pscp-usage-options} Options
185 PSCP accepts all the general command line options supported by the
186 PuTTY tools, except the ones which make no sense in a file transfer
187 utility. See \k{using-general-opts} for a description of these
188 options. (The ones not supported by PSCP are clearly marked.)
190 PSCP also supports some of its own options. The following sections
191 describe PSCP's specific command-line options.
193 \S2{pscp-usage-options-ls}\I{-ls-PSCP}\c{-ls} \I{listing files}list remote files
195 If the \c{-ls} option is given, no files are transferred; instead,
196 remote files are listed. Only a hostname specification and
197 optional remote file specification need be given. For example:
199 \c pscp -ls fred@example.com:dir1
201 The SCP protocol does not contain within itself a means of listing
202 files. If SCP is in use, this option therefore assumes that the
203 server responds appropriately to the command \c{ls\_-la};
204 this may not work with all servers.
206 If SFTP is in use, this option should work with all servers.
208 \S2{pscp-usage-options-p}\I{-p-PSCP}\c{-p} \i{preserve file attributes}
210 By default, files copied with PSCP are \i{timestamp}ed with the date and
211 time they were copied. The \c{-p} option preserves the original
212 timestamp on copied files.
214 \S2{pscp-usage-options-q}\I{-q-PSCP}\c{-q} quiet, don't show \i{statistics}
216 By default, PSCP displays a meter displaying the progress of the
219 \c mibs.tar | 168 kB | 84.0 kB/s | ETA: 00:00:13 | 13%
221 The fields in this display are (from left to right), filename, size
222 (in kilobytes) of file transferred so far, estimate of how fast the
223 file is being transferred (in kilobytes per second), estimated time
224 that the transfer will be complete, and percentage of the file so far
225 transferred. The \c{-q} option to PSCP suppresses the printing of
228 \S2{pscp-usage-options-r}\I{-r-PSCP}\c{-r} copies directories \i{recursive}ly
230 By default, PSCP will only copy files. Any directories you specify to
231 copy will be skipped, as will their contents. The \c{-r} option tells
232 PSCP to descend into any directories you specify, and to copy them and
233 their contents. This allows you to use PSCP to transfer whole
234 directory structures between machines.
236 \S2{pscp-usage-options-batch}\I{-batch-PSCP}\c{-batch} avoid interactive prompts
238 If you use the \c{-batch} option, PSCP will never give an
239 interactive prompt while establishing the connection. If the
240 server's host key is invalid, for example (see \k{gs-hostkey}), then
241 the connection will simply be abandoned instead of asking you what
244 This may help PSCP's behaviour when it is used in automated
245 scripts: using \c{-batch}, if something goes wrong at connection
246 time, the batch job will fail rather than hang.
248 \S2{pscp-usage-options-backend}\i\c{-sftp}, \i\c{-scp} force use of
251 As mentioned in \k{pscp-usage-basics}, there are two different file
252 transfer protocols in use with SSH. Despite its name, PSCP (like many
253 other ostensible \cw{scp} clients) can use either of these protocols.
255 The older \i{SCP protocol} does not have a written specification and
256 leaves a lot of detail to the server platform. \ii{Wildcards} are expanded
257 on the server. The simple design means that any wildcard specification
258 supported by the server platform (such as brace expansion) can be
259 used, but also leads to interoperability issues such as with filename
260 quoting (for instance, where filenames contain spaces), and also the
261 security issue described in \k{pscp-usage-basics}.
263 The newer \i{SFTP} protocol, which is usually associated with SSH-2
264 servers, is specified in a more platform independent way, and leaves
265 issues such as wildcard syntax up to the client. (PuTTY's SFTP
266 wildcard syntax is described in \k{psftp-wildcards}.) This makes it
267 more consistent across platforms, more suitable for scripting and
268 automation, and avoids security issues with wildcard matching.
270 Normally PSCP will attempt to use the SFTP protocol, and only fall
271 back to the SCP protocol if SFTP is not available on the server.
273 The \c{-scp} option forces PSCP to use the SCP protocol or quit.
275 The \c{-sftp} option forces PSCP to use the SFTP protocol or quit.
276 When this option is specified, PSCP looks harder for an SFTP server,
277 which may allow use of SFTP with SSH-1 depending on server setup.
279 \S{pscp-retval} \ii{Return value}
281 PSCP returns an \i\cw{ERRORLEVEL} of zero (success) only if the files
282 were correctly transferred. You can test for this in a \i{batch file},
283 using code such as this:
285 \c pscp file*.* user@hostname:
286 \c if errorlevel 1 echo There was an error
288 \S{pscp-pubkey} Using \i{public key authentication} with PSCP
290 Like PuTTY, PSCP can authenticate using a public key instead of a
291 password. There are three ways you can do this.
293 Firstly, PSCP can use PuTTY saved sessions in place of hostnames
294 (see \k{pscp-usage-basics-host}). So you would do this:
296 \b Run PuTTY, and create a PuTTY saved session (see
297 \k{config-saving}) which specifies your private key file (see
298 \k{config-ssh-privkey}). You will probably also want to specify a
299 username to log in as (see \k{config-username}).
301 \b In PSCP, you can now use the name of the session instead of a
302 hostname: type \c{pscp sessionname:file localfile}, where
303 \c{sessionname} is replaced by the name of your saved session.
305 Secondly, you can supply the name of a private key file on the command
306 line, with the \c{-i} option. See \k{using-cmdline-identity} for more
309 Thirdly, PSCP will attempt to authenticate using Pageant if Pageant
310 is running (see \k{pageant}). So you would do this:
312 \b Ensure Pageant is running, and has your private key stored in it.
314 \b Specify a user and host name to PSCP as normal. PSCP will
315 automatically detect Pageant and try to use the keys within it.
317 For more general information on public-key authentication, see