39a938f7 |
1 | \define{versionidpscp} \versionid $Id$ |
768ada0c |
2 | |
ded53fce |
3 | \#FIXME: Need examples |
768ada0c |
4 | |
e5b0d077 |
5 | \C{pscp} Using PSCP to transfer files securely |
6 | |
ffd64114 |
7 | \i{PSCP}, the PuTTY Secure Copy client, is a tool for transferring files |
768ada0c |
8 | securely between computers using an SSH connection. |
9 | |
9a313f60 |
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 | |
768ada0c |
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 |
ffd64114 |
18 | \i{console window}. With Windows 95, 98, and ME, this is called an |
768ada0c |
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 | |
ffd64114 |
23 | To start PSCP it will need either to be on your \i{\c{PATH}} or in your |
768ada0c |
24 | current directory. To add the directory containing PSCP to your |
25 | \c{PATH} environment variable, type into the console window: |
26 | |
8452efbc |
27 | \c set PATH=C:\path\to\putty\directory;%PATH% |
768ada0c |
28 | |
e35b2951 |
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. |
768ada0c |
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 |
c9a13be6 |
44 | \c Release 0.XX |
768ada0c |
45 | \c Usage: pscp [options] [user@]host:source target |
e2a197cf |
46 | \c pscp [options] source [source...] [user@]host:target |
db77dfb8 |
47 | \c pscp [options] -ls [user@]host:filespec |
768ada0c |
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 |
e2a197cf |
53 | \c -load sessname Load settings from saved session |
768ada0c |
54 | \c -P port connect to specified port |
e2a197cf |
55 | \c -l user connect with specified username |
768ada0c |
56 | \c -pw passw login with specified password |
e2a197cf |
57 | \c -1 -2 force use of particular SSH protocol version |
05581745 |
58 | \c -4 -6 force use of IPv4 or IPv6 |
e2a197cf |
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) |
c9a13be6 |
63 | \c -V print version information |
728f4f4c |
64 | \c -sftp force use of SFTP protocol |
6e310bc2 |
65 | \c -scp force use of SCP protocol |
768ada0c |
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 | |
ded53fce |
74 | \c pscp [options] [user@]host:source target |
75 | |
0b06900c |
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: |
ded53fce |
78 | |
79 | \c pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt |
768ada0c |
80 | |
81 | To send (a) file(s) to a remote server: |
82 | |
ded53fce |
83 | \c pscp [options] source [source...] [user@]host:target |
84 | |
35cffede |
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: |
ded53fce |
88 | |
35cffede |
89 | \c pscp c:\documents\foo.txt fred@example.com:/tmp/foo |
768ada0c |
90 | |
a4196579 |
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 |
35cffede |
98 | files) you may see a warning saying something like \q{warning: |
99 | remote host tried to write to a file called 'terminal.c' when we |
100 | requested a file called '*.c'. If this is a wildcard, consider |
101 | upgrading to SSH 2 or using the '-unsafe' option. Renaming of this |
102 | file has been disallowed}. |
a4196579 |
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 |
728f4f4c |
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}.) |
a4196579 |
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). |
132 | |
ffd64114 |
133 | \S2{pscp-usage-basics-user} \c{user} |
134 | |
135 | The login name on the remote server. If this is omitted, and \c{host} |
136 | is a PuTTY saved session, PSCP will use any username specified by that |
137 | saved session. Otherwise, PSCP will attempt to use the local Windows |
138 | username. |
139 | |
140 | \S2{pscp-usage-basics-host} \c{host} |
141 | |
142 | The name of the remote server, or the name of an existing PuTTY saved |
143 | session. In the latter case, the session's settings for hostname, port |
144 | number, cipher type and username will be used. |
768ada0c |
145 | |
ffd64114 |
146 | \S2{pscp-usage-basics-source} \c{source} |
768ada0c |
147 | |
ffd64114 |
148 | One or more source files. \i{Wildcards} are allowed. The syntax of |
149 | wildcards depends on the system to which they apply, so if you are |
150 | copying \e{from} a Windows system \e{to} a UNIX system, you should use |
116934a6 |
151 | Windows wildcard syntax (e.g. \c{*.*}), but if you are copying \e{from} |
ffd64114 |
152 | a UNIX system \e{to} a Windows system, you would use the wildcard |
153 | syntax allowed by your UNIX shell (e.g. \c{*}). |
768ada0c |
154 | |
ded53fce |
155 | If the source is a remote server and you do not specify a full |
156 | pathname (in UNIX, a pathname beginning with a \c{/} (slash) |
157 | character), what you specify as a source will be interpreted relative |
158 | to your home directory on the remote server. |
159 | |
ffd64114 |
160 | \S2{pscp-usage-basics-target} \c{target} |
768ada0c |
161 | |
ded53fce |
162 | The filename or directory to put the file(s). When copying from a |
163 | remote server to a local host, you may wish simply to place the |
164 | file(s) in the current directory. To do this, you should specify a |
165 | target of \c{.}. For example: |
166 | |
167 | \c pscp fred@example.com:/home/tom/.emacs . |
168 | |
169 | ...would copy \c{/home/tom/.emacs} on the remote server to the current |
170 | directory. |
171 | |
172 | As with the \c{source} parameter, if the target is on a remote server |
173 | and is not a full path name, it is interpreted relative to your home |
174 | directory on the remote server. |
768ada0c |
175 | |
176 | \S{pscp-usage-options} Options |
177 | |
e117a742 |
178 | PSCP accepts all the general command line options supported by the |
179 | PuTTY tools, except the ones which make no sense in a file transfer |
180 | utility. See \k{using-general-opts} for a description of these |
181 | options. (The ones not supported by PSCP are clearly marked.) |
182 | |
183 | PSCP also supports some of its own options. The following sections |
184 | describe PSCP's specific command-line options. |
185 | |
ffd64114 |
186 | These are the command line options that PSCP accepts. |
768ada0c |
187 | |
188 | \S2{pscp-usage-options-p}\c{-p} preserve file attributes |
189 | |
ffd64114 |
190 | By default, files copied with PSCP are \i{timestamp}ed with the date and |
768ada0c |
191 | time they were copied. The \c{-p} option preserves the original |
192 | timestamp on copied files. |
193 | |
ffd64114 |
194 | \S2{pscp-usage-options-q}\c{-q} quiet, don't show \i{statistics} |
768ada0c |
195 | |
196 | By default, PSCP displays a meter displaying the progress of the |
197 | current transfer: |
198 | |
35cffede |
199 | \c mibs.tar | 168 kB | 84.0 kB/s | ETA: 00:00:13 | 13% |
768ada0c |
200 | |
201 | The fields in this display are (from left to right), filename, size |
202 | (in kilobytes) of file transferred so far, estimate of how fast the |
203 | file is being transferred (in kilobytes per second), estimated time |
204 | that the transfer will be complete, and percentage of the file so far |
205 | transferred. The \c{-q} option to PSCP suppresses the printing of |
206 | these statistics. |
207 | |
ffd64114 |
208 | \S2{pscp-usage-options-r}\c{-r} copies directories \i{recursive}ly |
768ada0c |
209 | |
b3fa9b5e |
210 | By default, PSCP will only copy files. Any directories you specify to |
211 | copy will be skipped, as will their contents. The \c{-r} option tells |
212 | PSCP to descend into any directories you specify, and to copy them and |
213 | their contents. This allows you to use PSCP to transfer whole |
214 | directory structures between machines. |
215 | |
ff2ae367 |
216 | \S2{pscp-usage-options-batch}\c{-batch} avoid interactive prompts |
217 | |
218 | If you use the \c{-batch} option, PSCP will never give an |
219 | interactive prompt while establishing the connection. If the |
220 | server's host key is invalid, for example (see \k{gs-hostkey}), then |
221 | the connection will simply be abandoned instead of asking you what |
222 | to do next. |
223 | |
224 | This may help PSCP's behaviour when it is used in automated |
225 | scripts: using \c{-batch}, if something goes wrong at connection |
226 | time, the batch job will fail rather than hang. |
227 | |
728f4f4c |
228 | \S2{pscp-usage-options-backend}\c{-sftp}, \c{-scp} force use of |
229 | particular protocol |
230 | |
231 | As mentioned in \k{pscp-usage-basics}, there are two different file |
232 | transfer protocols in use with SSH. Despite its name, PSCP (like many |
233 | other ostensible \cw{scp} clients) can use either of these protocols. |
234 | |
235 | The older SCP protocol does not have a written specification and |
236 | leaves a lot of detail to the server platform. Wildcards are expanded |
237 | on the server. The simple design means that any wildcard specification |
238 | supported by the server platform (such as brace expansion) can be |
239 | used, but also leads to interoperability issues such as with filename |
240 | quoting (for instance, where filenames contain spaces), and also the |
241 | security issue described in \k{pscp-usage-basics}. |
242 | |
243 | The newer SFTP protocol, which is usually associated with SSH 2 |
244 | servers, is specified in a more platform independent way, and leaves |
9d210cac |
245 | issues such as wildcard syntax up to the client. (PuTTY's SFTP |
246 | wildcard syntax is described in \k{psftp-wildcards}.) This makes it |
247 | more consistent across platforms, more suitable for scripting and |
248 | automation, and avoids security issues with wildcard matching. |
728f4f4c |
249 | |
250 | Normally PSCP will attempt to use the SFTP protocol, and only fall |
251 | back to the SCP protocol if SFTP is not available on the server. |
252 | |
253 | The \c{-scp} option forces PSCP to use the SCP protocol or quit. |
254 | |
255 | The \c{-sftp} option forces PSCP to use the SFTP protocol or quit. |
256 | When this option is specified, PSCP looks harder for an SFTP server, |
257 | which may allow use of SFTP with SSH 1 depending on server setup. |
258 | |
4cbe74f4 |
259 | \S{pscp-retval} Return value |
a4196579 |
260 | |
261 | PSCP returns an \cw{ERRORLEVEL} of zero (success) only if the files |
262 | were correctly transferred. You can test for this in a batch file, |
263 | using code such as this: |
264 | |
265 | \c pscp file*.* user@hostname: |
266 | \c if errorlevel 1 echo There was an error |
267 | |
6da38567 |
268 | \S{pscp-pubkey} Using public key authentication with PSCP |
269 | |
270 | Like PuTTY, PSCP can authenticate using a public key instead of a |
e2a197cf |
271 | password. There are three ways you can do this. |
6da38567 |
272 | |
273 | Firstly, PSCP can use PuTTY saved sessions in place of hostnames |
274 | (see \k{pscp-usage-basics-host}). So you would do this: |
275 | |
276 | \b Run PuTTY, and create a PuTTY saved session (see |
277 | \k{config-saving}) which specifies your private key file (see |
add788fc |
278 | \k{config-ssh-privkey}). You will probably also want to specify a |
279 | username to log in as (see \k{config-username}). |
6da38567 |
280 | |
281 | \b In PSCP, you can now use the name of the session instead of a |
edcbf00a |
282 | hostname: type \c{pscp sessionname:file localfile}, where |
283 | \c{sessionname} is replaced by the name of your saved session. |
6da38567 |
284 | |
e2a197cf |
285 | Secondly, you can supply the name of a private key file on the command |
286 | line, with the \c{-i} option. See \k{using-cmdline-identity} for more |
287 | information. |
288 | |
289 | Thirdly, PSCP will attempt to authenticate using Pageant if Pageant |
6da38567 |
290 | is running (see \k{pageant}). So you would do this: |
291 | |
292 | \b Ensure Pageant is running, and has your private key stored in it. |
293 | |
294 | \b Specify a user and host name to PSCP as normal. PSCP will |
295 | automatically detect Pageant and try to use the keys within it. |
296 | |
297 | For more general information on public-key authentication, see |
298 | \k{pubkey}. |