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