1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=US-ASCII">
<title>Using the command-line connection tool Plink</title>
<link rel="previous" href="Chapter6.html">
<link rel="ToC" href="index.html">
<link rel="up" href="index.html">
<link rel="index" href="IndexPage.html">
<link rel="next" href="Chapter8.html">
</head>
<body>
<p><a href="Chapter6.html">Previous</a> | <a href="index.html">Contents</a> | <a href="IndexPage.html">Index</a> | <a href="Chapter8.html">Next</a></p>
<ul>
<li><a href="#plink">Chapter 7: Using the command-line connection tool Plink</a>
<ul>
<li><a href="#plink-starting">7.1 Starting Plink</a></li>
<li><a href="#plink-usage">7.2 Using Plink</a>
<ul>
<li><a href="#plink-usage-interactive">7.2.1 Using Plink for interactive logins</a></li>
<li><a href="#plink-usage-batch">7.2.2 Using Plink for automated connections</a></li>
<li><a href="#plink-options">7.2.3 Plink command line options</a></li>
</ul></li>
<li><a href="#plink-batch">7.3 Using Plink in batch files and scripts</a></li>
<li><a href="#plink-git">7.4 Using Plink with Git</a></li>
<li><a href="#plink-cvs">7.5 Using Plink with CVS</a></li>
<li><a href="#plink-wincvs">7.6 Using Plink with WinCVS</a></li>
</ul></li>
</ul>
<h1><a name="plink"></a><a name="C7"></a>Chapter 7: Using the command-line connection tool <a name="i0"></a>Plink</h1>
<p>
<a name="i1"></a>Plink is a command-line connection tool similar to UNIX <code>ssh</code>. It is mostly used for <a name="i2"></a>automated operations, such as making CVS access a repository on a remote server.
</p>
<p>
Plink is probably not what you want if you want to run an <a name="i3"></a>interactive session in a console window.
</p>
<h2><a name="plink-starting"></a><a name="S7.1"></a>7.1 Starting Plink</h2>
<p>
Plink is a command line application. This means that you cannot just double-click on its icon to run it and instead you have to bring up a <a name="i4"></a>console window. In Windows 95, 98, and ME, this is called an ‘MS-DOS Prompt’, and in Windows NT, 2000, and XP, it is called a ‘Command Prompt’. It should be available from the Programs section of your Start Menu.
</p>
<p>
In order to use Plink, the file <code>plink.exe</code> will need either to be on your <a name="i5"></a><code>PATH</code> or in your current directory. To add the directory containing Plink to your <code>PATH</code> environment variable, type into the console window:
</p>
<pre><code>set PATH=C:\path\to\putty\directory;%PATH%
</code></pre>
<p>
This will only work for the lifetime of that particular console window. To set your <code>PATH</code> more permanently on Windows NT, 2000, and XP, use the Environment tab of the System Control Panel. On Windows 95, 98, and ME, you will need to edit your <a name="i6"></a><code>AUTOEXEC.BAT</code> to include a <code>set</code> command like the one above.
</p>
<h2><a name="plink-usage"></a><a name="S7.2"></a>7.2 Using Plink</h2>
<p>
This section describes the basics of how to use Plink for interactive logins and for automated processes.
</p>
<p>
Once you've got a console window to type into, you can type <code>plink --help</code> to bring up a usage message. This tells you the version of Plink you're using, and gives you a brief summary of how to use Plink:
</p>
<pre><code>C:\>plink --help
Plink: command-line connection utility
Release 0.83
Usage: plink [options] [user@]host [command]
("host" can also be a PuTTY saved session name)
Options:
-V print version information and exit
-pgpfp print PGP key fingerprints and exit
-v show verbose messages
-load sessname Load settings from saved session
-ssh -telnet -rlogin -raw -serial
force use of a particular protocol
-ssh-connection
force use of the bare ssh-connection protocol
-P port connect to specified port
-l user connect with specified username
-batch disable all interactive prompts
-proxycmd command
use 'command' as local proxy
-sercfg configuration-string (e.g. 19200,8,n,1,X)
Specify the serial configuration (serial only)
The following options only apply to SSH connections:
-pwfile file login with password read from specified file
-D [listen-IP:]listen-port
Dynamic SOCKS-based port forwarding
-L [listen-IP:]listen-port:host:port
Forward local port to remote address
-R [listen-IP:]listen-port:host:port
Forward remote port to local address
-X -x enable / disable X11 forwarding
-A -a enable / disable agent forwarding
-t -T enable / disable pty allocation
-1 -2 force use of particular SSH protocol version
-4 -6 force use of IPv4 or IPv6
-C enable compression
-i key private key file for user authentication
-noagent disable use of Pageant
-agent enable use of Pageant
-no-trivial-auth
disconnect if SSH authentication succeeds trivially
-noshare disable use of connection sharing
-share enable use of connection sharing
-hostkey keyid
manually specify a host key (may be repeated)
-sanitise-stderr, -sanitise-stdout, -no-sanitise-stderr, -no-sanitise-stdout
do/don't strip control chars from standard output/error
-no-antispoof omit anti-spoofing prompt after authentication
-m file read remote command(s) from file
-s remote command is an SSH subsystem (SSH-2 only)
-N don't start a shell/command (SSH-2 only)
-nc host:port
open tunnel in place of session (SSH-2 only)
-sshlog file
-sshrawlog file
log protocol details to a file
-logoverwrite
-logappend
control what happens when a log file already exists
-shareexists
test whether a connection-sharing upstream exists
</code></pre>
<p>
Once this works, you are ready to use Plink.
</p>
<h3><a name="plink-usage-interactive"></a><a name="S7.2.1"></a>7.2.1 Using Plink for interactive logins</h3>
<p>
To make a simple interactive connection to a remote server, just type <code>plink</code> and then the host name:
</p>
<pre><code>C:\>plink login.example.com
Debian GNU/Linux 2.2 flunky.example.com
flunky login:
</code></pre>
<p>
You should then be able to log in as normal and run a session. The output sent by the server will be written straight to your command prompt window, which will most likely not interpret terminal <a name="i7"></a>control codes in the way the server expects it to. So if you run any full-screen applications, for example, you can expect to see strange characters appearing in your window. Interactive connections like this are not the main point of Plink.
</p>
<p>
In order to connect with a different protocol, you can give the command line options <code>-ssh</code>, <code>-ssh-connection</code>, <code>-telnet</code>, <code>-rlogin</code>, or <code>-raw</code>. To make an SSH connection, for example:
</p>
<pre><code>C:\>plink -ssh login.example.com
login as:
</code></pre>
<p>
If you have already set up a PuTTY saved session, then instead of supplying a host name, you can give the saved session name. This allows you to use public-key authentication, specify a user name, and use most of the other features of PuTTY:
</p>
<pre><code>C:\>plink my-ssh-session
Sent username "fred"
Authenticating with public key "fred@winbox"
Last login: Thu Dec 6 19:25:33 2001 from :0.0
fred@flunky:~$
</code></pre>
<p>
(You can also use the <code>-load</code> command-line option to load a saved session; see <a href="Chapter3.html#using-cmdline-load">section 3.11.3.1</a>. If you use <code>-load</code>, the saved session exists, and it specifies a hostname, you cannot also specify a <code>host</code> or <code>user@host</code> argument - it will be treated as part of the remote command.)
</p>
<h3><a name="plink-usage-batch"></a><a name="S7.2.2"></a>7.2.2 Using Plink for automated connections</h3>
<p>
More typically Plink is used with the SSH protocol, to enable you to talk directly to a program running on the server. To do this you have to ensure Plink is <em>using</em> the SSH protocol. You can do this in several ways:
</p>
<ul><li>
Use the <code>-ssh</code> option as described in <a href="#plink-usage-interactive">section 7.2.1</a>.
</li>
<li>
Set up a PuTTY saved session that describes the server you are connecting to, and that also specifies the protocol as SSH.
</li>
<li>
Set the Windows environment variable <a name="i8"></a><code>PLINK_PROTOCOL</code> to the word <code>ssh</code>.
</li>
</ul>
<p>
Usually Plink is not invoked directly by a user, but run automatically by another process. Therefore you typically do not want Plink to prompt you for a user name or a password.
</p>
<p>
Next, you are likely to need to avoid the various interactive prompts Plink can produce. You might be prompted to verify the host key of the server you're connecting to, to enter a user name, or to enter a password.
</p>
<p>
To avoid being prompted for the server host key when using Plink for an automated connection, you can first make a <em>manual</em> connection (using either of PuTTY or Plink) to the same server, verify the host key (see <a href="Chapter2.html#gs-hostkey">section 2.2</a> for more information), and select ‘Accept’ to add the host key to the Registry. After that, Plink commands connecting to that server should not give a host key prompt unless the host key changes. Alternatively, you can specify the appropriate host key(s) on Plink's command line every time you use it; see <a href="Chapter3.html#using-cmdline-hostkey">section 3.11.3.22</a>.
</p>
<p>
To avoid being prompted for a user name, you can:
</p>
<ul><li>
Use the <code>-l</code> option to specify a user name on the command line. For example, <code>plink login.example.com -l fred</code>.
</li>
<li>
Set up a PuTTY saved session that describes the server you are connecting to, and that also specifies the username to log in as (see <a href="Chapter4.html#config-username">section 4.15.1</a>).
</li>
</ul>
<p>
To avoid being prompted for a password, you should almost certainly set up <a name="i9"></a>public-key authentication. (See <a href="Chapter8.html#pubkey">chapter 8</a> for a general introduction to public-key authentication.) Again, you can do this in two ways:
</p>
<ul><li>
Set up a PuTTY saved session that describes the server you are connecting to, and that also specifies a private key file (see <a href="Chapter4.html#config-ssh-privkey">section 4.22.1</a>). For this to work without prompting, your private key will need to have no passphrase.
</li>
<li>
Store the private key in Pageant. See <a href="Chapter9.html#pageant">chapter 9</a> for further information.
</li>
</ul>
<p>
Once you have done all this, you should be able to run a remote command on the SSH server machine and have it execute automatically with no prompting:
</p>
<pre><code>C:\>plink login.example.com -l fred echo hello, world
hello, world
C:\>
</code></pre>
<p>
Or, if you have set up a saved session with all the connection details:
</p>
<pre><code>C:\>plink mysession echo hello, world
hello, world
C:\>
</code></pre>
<p>
Then you can set up other programs to run this Plink command and talk to it as if it were a process on the server machine.
</p>
<h3><a name="plink-options"></a><a name="S7.2.3"></a>7.2.3 Plink command line options</h3>
<p>
Plink accepts all the general command line options supported by the PuTTY tools. See <a href="Chapter3.html#using-general-opts">section 3.11.3</a> for a description of these options.
</p>
<p>
Plink also supports some of its own options. The following sections describe Plink's specific command-line options.
</p>
<h4><a name="plink-option-batch"></a><a name="S7.2.3.1"></a>7.2.3.1 <a name="i10"></a><code>-batch</code>: disable all interactive prompts</h4>
<p>
If you use the <code>-batch</code> option, Plink will never give an interactive prompt while establishing the connection. If the server's host key is invalid, for example (see <a href="Chapter2.html#gs-hostkey">section 2.2</a>), then the connection will simply be abandoned instead of asking you what to do next.
</p>
<p>
This may help Plink's behaviour when it is used in automated scripts: using <code>-batch</code>, if something goes wrong at connection time, the batch job will fail rather than hang.
</p>
<p>
If another program is invoking Plink on your behalf, then you might need to arrange that that program passes <code>-batch</code> to Plink. See <a href="#plink-git">section 7.4</a> for an example involving Git.
</p>
<h4><a name="plink-option-s"></a><a name="S7.2.3.2"></a>7.2.3.2 <a name="i11"></a><code>-s</code>: remote command is SSH subsystem</h4>
<p>
If you specify the <code>-s</code> option, Plink passes the specified command as the name of an SSH ‘<a name="i12"></a>subsystem’ rather than an ordinary command line.
</p>
<p>
(This option is only meaningful with the SSH-2 protocol.)
</p>
<h4><a name="plink-option-share"></a><a name="S7.2.3.3"></a>7.2.3.3 <a name="i13"></a><code>-share</code>: Test and try to share an existing connection.</h4>
<p>
This option tries to detect if an existing connection can be shared (See <a href="Chapter4.html#config-ssh-sharing">section 4.17.5</a> for more information about SSH connection sharing.) and reuses that connection.
</p>
<p>
A Plink invocation of the form:
</p>
<pre><code>plink -share <em><session></em>
</code></pre>
<p>
will test whether there is currently a viable ‘upstream’ for the session in question, which can be specified using any syntax you'd normally use with Plink to make an actual connection (a host/port number, a bare saved session name, <code>-load</code>, etc). If no ‘upstream’ viable session is found and <code>-share</code> is specified, this connection will be become the ‘upstream’ connection for subsequent connection sharing tries.
</p>
<p>
(This option is only meaningful with the SSH-2 protocol.)
</p>
<h4><a name="plink-option-shareexists"></a><a name="S7.2.3.4"></a>7.2.3.4 <a name="i14"></a><code>-shareexists</code>: test for connection-sharing upstream</h4>
<p>
This option does not make a new connection; instead it allows testing for the presence of an existing connection that can be shared. (See <a href="Chapter4.html#config-ssh-sharing">section 4.17.5</a> for more information about SSH connection sharing.)
</p>
<p>
A Plink invocation of the form:
</p>
<pre><code>plink -shareexists <em><session></em>
</code></pre>
<p>
will test whether there is currently a viable ‘upstream’ for the session in question, which can be specified using any syntax you'd normally use with Plink to make an actual connection (a host/port number, a bare saved session name, <code>-load</code>, etc). It returns a zero exit status if a usable ‘upstream’ exists, nonzero otherwise.
</p>
<p>
(This option is only meaningful with the SSH-2 protocol.)
</p>
<h4><a name="plink-option-sanitise"></a><a name="S7.2.3.5"></a>7.2.3.5 <a name="i15"></a><a name="i16"></a><a name="i17"></a><a name="i18"></a><code>-sanitise-</code><em>stream</em>: control output sanitisation</h4>
<p>
In some situations, Plink applies a sanitisation pass to the output received from the server, to strip out control characters such as backspace and the escape character.
</p>
<p>
The idea of this is to prevent remote processes from sending confusing escape sequences through the standard error channel when Plink is being used as a transport for something like <code>git</code> or CVS. If the server actually wants to send an error message, it will probably be plain text; if the server abuses that channel to try to write over unexpected parts of your terminal display, Plink will try to stop it.
</p>
<p>
By default, this only happens for output channels which are sent to a Windows console device, or a Unix terminal device. (Any output stream going somewhere else is likely to be needed by an 8-bit protocol and must not be tampered with at all.) It also stops happening if you tell Plink to allocate a remote pseudo-terminal (see <a href="Chapter3.html#using-cmdline-pty">section 3.11.3.12</a> and <a href="Chapter4.html#config-ssh-pty">section 4.24.1</a>), on the basis that in that situation you often <em>want</em> escape sequences from the server to go to your terminal.
</p>
<p>
But in case Plink guesses wrong about whether you want this sanitisation, you can override it in either direction, using one of these options:
</p>
<dl><dt>
<code>-sanitise-stderr</code>
</dt>
<dd>
Sanitise server data written to Plink's standard error channel, regardless of terminals and consoles and remote ptys.
</dd>
<dt>
<code>-no-sanitise-stderr</code>
</dt>
<dd>
Do not sanitise server data written to Plink's standard error channel.
</dd>
<dt>
<code>-sanitise-stdout</code>
</dt>
<dd>
Sanitise server data written to Plink's standard output channel.
</dd>
<dt>
<code>-no-sanitise-stdout</code>
</dt>
<dd>
Do not sanitise server data written to Plink's standard output channel.
</dd>
</dl>
<h4><a name="plink-option-antispoof"></a><a name="S7.2.3.6"></a>7.2.3.6 <a name="i19"></a>-no-antispoof: turn off authentication spoofing protection prompt</h4>
<p>
In SSH, some possible server authentication methods require user input (for example, password authentication, or entering a private key passphrase), and others do not (e.g. a private key held in Pageant).
</p>
<p>
If you use Plink to run an interactive login session, and if Plink authenticates without needing any user interaction, and if the server is malicious or compromised, it could try to trick you into giving it authentication data that should not go to the server (such as your private key passphrase), by sending what <em>looks</em> like one of Plink's local prompts, as if Plink had not already authenticated.
</p>
<p>
To protect against this, Plink's default policy is to finish the authentication phase with a final trivial prompt looking like this:
</p>
<pre><code>Access granted. Press Return to begin session.
</code></pre>
<p>
so that if you saw anything that looked like an authentication prompt <em>after</em> that line, you would know it was not from Plink.
</p>
<p>
That extra interactive step is inconvenient. So Plink will turn it off in as many situations as it can:
</p>
<ul><li>
If Plink's standard input is not pointing at a console or terminal device – for example, if you're using Plink as a transport for some automated application like version control – then you <em>can't</em> type passphrases into the server anyway. In that situation, Plink won't try to protect you from the server trying to fool you into doing so.
</li>
<li>
If Plink is in batch mode (see <a href="#plink-usage-batch">section 7.2.2</a>), then it <em>never</em> does any interactive authentication. So anything looking like an interactive authentication prompt is automatically suspect, and so Plink omits the anti-spoofing prompt.
</li>
</ul>
<p>
But if you still find the protective prompt inconvenient, and you trust the server not to try a trick like this, you can turn it off using the ‘<code>-no-antispoof</code>’ option.
</p>
<h2><a name="plink-batch"></a><a name="S7.3"></a>7.3 Using Plink in <a name="i20"></a>batch files and <a name="i21"></a>scripts</h2>
<p>
Once you have set up Plink to be able to log in to a remote server without any interactive prompting (see <a href="#plink-usage-batch">section 7.2.2</a>), you can use it for lots of scripting and batch purposes. For example, to start a backup on a remote machine, you might use a command like:
</p>
<pre><code>plink root@myserver /etc/backups/do-backup.sh
</code></pre>
<p>
Or perhaps you want to fetch all system log lines relating to a particular web area:
</p>
<pre><code>plink mysession grep /~fred/ /var/log/httpd/access.log > fredlog
</code></pre>
<p>
Any non-interactive command you could usefully run on the server command line, you can run in a batch file using Plink in this way.
</p>
<h2><a name="plink-git"></a><a name="S7.4"></a>7.4 Using Plink with <a name="i22"></a>Git</h2>
<p>
To use Plink for Git operations performed over SSH, you can set the environment variable <a name="i23"></a><code>GIT_SSH_COMMAND</code> to point to Plink.
</p>
<p>
For example, if you've run PuTTY's full Windows installer and it has installed Plink in the default location, you might do this:
</p>
<pre><code>set GIT_SSH_COMMAND="C:\Program Files\PuTTY\plink.exe"
</code></pre>
<p>
or if you've put Plink somewhere else then you can do a similar thing with a different path.
</p>
<p>
This environment variable accepts a whole command line, not just an executable file name. So you can add Plink options to the end of it if you like. For example, if you're using Git in a batch-mode context, where your Git jobs are running unattended and nobody is available to answer interactive prompts, you might also append the ‘<code>-batch</code>’ option (<a href="#plink-option-batch">section 7.2.3.1</a>):
</p>
<pre><code>set GIT_SSH_COMMAND="C:\Program Files\PuTTY\plink.exe" -batch
</code></pre>
<p>
and then if Plink unexpectedly prints a prompt of some kind (for example, because the SSH server's host key has changed), your batch job will terminate with an error message, instead of stopping and waiting for user input that will never arrive.
</p>
<p>
(However, you don't <em>always</em> want to do this with Git. If you're using Git interactively, you might <em>want</em> Plink to stop for interactive prompts – for example, to let you enter a password for the SSH server.)
</p>
<h2><a name="plink-cvs"></a><a name="S7.5"></a>7.5 Using Plink with <a name="i24"></a>CVS</h2>
<p>
To use Plink with CVS, you need to set the environment variable <a name="i25"></a><code>CVS_RSH</code> to point to Plink:
</p>
<pre><code>set CVS_RSH=\path\to\plink.exe
</code></pre>
<p>
You also need to arrange to be able to connect to a remote host without any interactive prompts, as described in <a href="#plink-usage-batch">section 7.2.2</a>.
</p>
<p>
You should then be able to run CVS as follows:
</p>
<pre><code>cvs -d :ext:user@sessionname:/path/to/repository co module
</code></pre>
<p>
If you specified a username in your saved session, you don't even need to specify the ‘user’ part of this, and you can just say:
</p>
<pre><code>cvs -d :ext:sessionname:/path/to/repository co module
</code></pre>
<h2><a name="plink-wincvs"></a><a name="S7.6"></a>7.6 Using Plink with <a name="i26"></a>WinCVS</h2>
<p>
Plink can also be used with WinCVS. Firstly, arrange for Plink to be able to connect to a remote host non-interactively, as described in <a href="#plink-usage-batch">section 7.2.2</a>.
</p>
<p>
Then, in WinCVS, bring up the ‘Preferences’ dialogue box from the <em>Admin</em> menu, and switch to the ‘Ports’ tab. Tick the box there labelled ‘Check for an alternate <code>rsh</code> name’ and in the text entry field to the right enter the full path to <code>plink.exe</code>. Select ‘OK’ on the ‘Preferences’ dialogue box.
</p>
<p>
Next, select ‘Command Line’ from the WinCVS ‘Admin’ menu, and type a CVS command as in <a href="#plink-cvs">section 7.5</a>, for example:
</p>
<pre><code>cvs -d :ext:user@hostname:/path/to/repository co module
</code></pre>
<p>
or (if you're using a saved session):
</p>
<pre><code>cvs -d :ext:user@sessionname:/path/to/repository co module
</code></pre>
<p>
Select the folder you want to check out to with the ‘Change Folder’ button, and click ‘OK’ to check out your module. Once you've got modules checked out, WinCVS will happily invoke plink from the GUI for CVS operations.
</p>
<hr><p>If you want to provide feedback on this manual or on the PuTTY tools themselves, see the <a href="https://www.chiark.greenend.org.uk/~sgtatham/putty/feedback.html">Feedback page</a>.</p><address>
[PuTTY release 0.83]</address></body>
</html>
|
