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