]>
Commit | Line | Data |
---|---|---|
1c1af145 | 1 | \define{versionidusing} \versionid $Id$ |
2 | ||
3 | \C{using} Using PuTTY | |
4 | ||
5 | This chapter provides a general introduction to some more advanced | |
6 | features of PuTTY. For extreme detail and reference purposes, | |
7 | \k{config} is likely to contain more information. | |
8 | ||
9 | \H{using-session} During your session | |
10 | ||
11 | A lot of PuTTY's complexity and features are in the configuration | |
12 | panel. Once you have worked your way through that and started | |
13 | a session, things should be reasonably simple after that. | |
14 | Nevertheless, there are a few more useful features available. | |
15 | ||
16 | \S{using-selection} Copying and pasting text | |
17 | ||
18 | \I{copy and paste}Often in a PuTTY session you will find text on | |
19 | your terminal screen which you want to type in again. Like most | |
20 | other terminal emulators, PuTTY allows you to copy and paste the | |
21 | text rather than having to type it again. Also, copy and paste uses | |
22 | the \I{Windows clipboard}Windows \i{clipboard}, so that you can | |
23 | paste (for example) URLs into a web browser, or paste from a word | |
24 | processor or spreadsheet into your terminal session. | |
25 | ||
26 | PuTTY's copy and paste works entirely with the \i{mouse}. In order | |
27 | to copy text to the clipboard, you just click the \i{left mouse | |
28 | button} in the \i{terminal window}, and drag to \I{selecting text}select | |
29 | text. When you let go of the button, the text is \e{automatically} | |
30 | copied to the clipboard. You do not need to press Ctrl-C or | |
31 | Ctrl-Ins; in fact, if you do press Ctrl-C, PuTTY will send a Ctrl-C | |
32 | character down your session to the server where it will probably | |
33 | cause a process to be interrupted. | |
34 | ||
35 | Pasting is done using the right button (or the middle mouse button, | |
36 | if you have a \i{three-button mouse} and have set it up; see | |
37 | \k{config-mouse}). (Pressing \i{Shift-Ins}, or selecting \q{Paste} | |
38 | from the \I{right mouse button, with Ctrl}Ctrl+right-click | |
39 | \i{context menu}, have the same effect.) When | |
40 | you click the \i{right mouse button}, PuTTY will read whatever is in | |
41 | the Windows clipboard and paste it into your session, \e{exactly} as | |
42 | if it had been typed at the keyboard. (Therefore, be careful of | |
43 | pasting formatted text into an editor that does automatic indenting; | |
44 | you may find that the spaces pasted from the clipboard plus the | |
45 | spaces added by the editor add up to too many spaces and ruin the | |
46 | formatting. There is nothing PuTTY can do about this.) | |
47 | ||
48 | If you \i{double-click} the left mouse button, PuTTY will | |
49 | \I{selecting words}select a whole word. If you double-click, hold | |
50 | down the second click, and drag the mouse, PuTTY will select a | |
51 | sequence of whole words. (You can adjust precisely what PuTTY | |
52 | considers to be part of a word; see \k{config-charclasses}.) | |
53 | If you \e{triple}-click, or \i{triple-click} and drag, then | |
54 | PuTTY will \I{selecting lines}select a whole line or sequence of lines. | |
55 | ||
56 | If you want to select a \I{rectangular selection}rectangular region | |
57 | instead of selecting to the end of each line, you can do this by | |
58 | holding down Alt when you make your selection. You can also | |
59 | configure rectangular selection to be the default, and then holding | |
60 | down Alt gives the normal behaviour instead: see | |
61 | \k{config-rectselect} for details. | |
62 | ||
63 | (In some Unix environments, Alt+drag is intercepted by the window | |
64 | manager. Shift+Alt+drag should work for rectangular selection as | |
65 | well, so you could try that instead.) | |
66 | ||
67 | If you have a \i{middle mouse button}, then you can use it to | |
68 | \I{adjusting a selection}adjust an existing selection if you | |
69 | selected something slightly wrong. (If you have configured the | |
70 | middle mouse button to paste, then the right mouse button does this | |
71 | instead.) Click the button on the screen, and you can pick up the | |
72 | nearest end of the selection and drag it to somewhere else. | |
73 | ||
74 | It's possible for the server to ask to \I{mouse reporting}handle mouse | |
75 | clicks in the PuTTY window itself. If this happens, the \i{mouse pointer} | |
76 | will turn into an arrow, and using the mouse to copy and paste will only | |
77 | work if you hold down Shift. See \k{config-features-mouse} and | |
78 | \k{config-mouseshift} for details of this feature and how to configure | |
79 | it. | |
80 | ||
81 | \S{using-scrollback} \I{scrollback}Scrolling the screen back | |
82 | ||
83 | PuTTY keeps track of text that has scrolled up off the top of the | |
84 | terminal. So if something appears on the screen that you want to | |
85 | read, but it scrolls too fast and it's gone by the time you try to | |
86 | look for it, you can use the \i{scrollbar} on the right side of the | |
87 | window to look back up the session \i{history} and find it again. | |
88 | ||
89 | As well as using the scrollbar, you can also page the scrollback up | |
90 | and down by pressing \i{Shift-PgUp} and \i{Shift-PgDn}. You can | |
91 | scroll a line at a time using \i{Ctrl-PgUp} and \i{Ctrl-PgDn}. These | |
92 | are still available if you configure the scrollbar to be invisible. | |
93 | ||
94 | By default the last 200 lines scrolled off the top are | |
95 | preserved for you to look at. You can increase (or decrease) this | |
96 | value using the configuration box; see \k{config-scrollback}. | |
97 | ||
98 | \S{using-sysmenu} The \ii{System menu} | |
99 | ||
100 | If you click the left mouse button on the icon in the top left | |
101 | corner of PuTTY's terminal window, or click the right mouse button | |
102 | on the title bar, you will see the standard Windows system menu | |
103 | containing items like Minimise, Move, Size and Close. | |
104 | ||
105 | PuTTY's system menu contains extra program features in addition to | |
106 | the Windows standard options. These extra menu commands are | |
107 | described below. | |
108 | ||
109 | (These options are also available in a \i{context menu} brought up | |
110 | by holding Ctrl and clicking with the right mouse button anywhere | |
111 | in the \i{PuTTY window}.) | |
112 | ||
113 | \S2{using-eventlog} The PuTTY \i{Event Log} | |
114 | ||
115 | If you choose \q{Event Log} from the system menu, a small window | |
116 | will pop up in which PuTTY logs significant events during the | |
117 | connection. Most of the events in the log will probably take place | |
118 | during session startup, but a few can occur at any point in the | |
119 | session, and one or two occur right at the end. | |
120 | ||
121 | You can use the mouse to select one or more lines of the Event Log, | |
122 | and hit the Copy button to copy them to the \i{clipboard}. If you | |
123 | are reporting a bug, it's often useful to paste the contents of the | |
124 | Event Log into your bug report. | |
125 | ||
126 | \S2{using-specials} \ii{Special commands} | |
127 | ||
128 | Depending on the protocol used for the current session, there may be | |
129 | a submenu of \q{special commands}. These are protocol-specific | |
130 | tokens, such as a \q{break} signal, that can be sent down a | |
131 | connection in addition to normal data. Their precise effect is usually | |
132 | up to the server. Currently only Telnet, SSH, and serial connections | |
133 | have special commands. | |
134 | ||
135 | The \q{break} signal can also be invoked from the keyboard with | |
136 | \i{Ctrl-Break}. | |
137 | ||
138 | The following \I{Telnet special commands}special commands are | |
139 | available in Telnet: | |
140 | ||
141 | \b \I{Are You There, Telnet special command}Are You There | |
142 | ||
143 | \b \I{Break, Telnet special command}Break | |
144 | ||
145 | \b \I{Synch, Telnet special command}Synch | |
146 | ||
147 | \b \I{Erase Character, Telnet special command}Erase Character | |
148 | ||
149 | \lcont{ | |
150 | PuTTY can also be configured to send this when the Backspace key is | |
151 | pressed; see \k{config-telnetkey}. | |
152 | } | |
153 | ||
154 | \b \I{Erase Line, Telnet special command}Erase Line | |
155 | ||
156 | \b \I{Go Ahead, Telnet special command}Go Ahead | |
157 | ||
158 | \b \I{No Operation, Telnet special command}No Operation | |
159 | ||
160 | \lcont{ | |
161 | Should have no effect. | |
162 | } | |
163 | ||
164 | \b \I{Abort Process, Telnet special command}Abort Process | |
165 | ||
166 | \b \I{Abort Output, Telnet special command}Abort Output | |
167 | ||
168 | \b \I{Interrupt Process, Telnet special command}Interrupt Process | |
169 | ||
170 | \lcont{ | |
171 | PuTTY can also be configured to send this when Ctrl-C is typed; see | |
172 | \k{config-telnetkey}. | |
173 | } | |
174 | ||
175 | \b \I{Suspend Process, Telnet special command}Suspend Process | |
176 | ||
177 | \lcont{ | |
178 | PuTTY can also be configured to send this when Ctrl-Z is typed; see | |
179 | \k{config-telnetkey}. | |
180 | } | |
181 | ||
182 | \b \I{End Of Record, Telnet special command}End Of Record | |
183 | ||
184 | \b \I{End Of File, Telnet special command}End Of File | |
185 | ||
186 | In an SSH connection, the following \I{SSH special commands}special | |
187 | commands are available: | |
188 | ||
189 | \b \I{IGNORE message, SSH special command}\I{No-op, in SSH}\ii{IGNORE message} | |
190 | ||
191 | \lcont{ | |
192 | Should have no effect. | |
193 | } | |
194 | ||
195 | \b \I{Repeat key exchange, SSH special command}Repeat key exchange | |
196 | ||
197 | \lcont{ | |
198 | Only available in SSH-2. Forces a \i{repeat key exchange} immediately (and | |
199 | resets associated timers and counters). For more information about | |
200 | repeat key exchanges, see \k{config-ssh-kex-rekey}. | |
201 | } | |
202 | ||
203 | \b \I{Break, SSH special command}Break | |
204 | ||
205 | \lcont{ | |
206 | Only available in SSH-2, and only during a session. Optional | |
207 | extension; may not be supported by server. PuTTY requests the server's | |
208 | default break length. | |
209 | } | |
210 | ||
211 | \b \I{Signal, SSH special command}Signals (SIGINT, SIGTERM etc) | |
212 | ||
213 | \lcont{ | |
214 | Only available in SSH-2, and only during a session. Sends various | |
215 | POSIX signals. Not honoured by all servers. | |
216 | } | |
217 | ||
218 | With a serial connection, the only available special command is | |
219 | \I{Break, serial special command}\q{Break}. | |
220 | ||
221 | \S2{using-newsession} Starting new sessions | |
222 | ||
223 | PuTTY's system menu provides some shortcut ways to start new | |
224 | sessions: | |
225 | ||
226 | \b Selecting \i{\q{New Session}} will start a completely new | |
227 | instance of PuTTY, and bring up the configuration box as normal. | |
228 | ||
229 | \b Selecting \i{\q{Duplicate Session}} will start a session in a | |
230 | new window with precisely the same options as your current one - | |
231 | connecting to the same host using the same protocol, with all the | |
232 | same terminal settings and everything. | |
233 | ||
234 | \b In an inactive window, selecting \i{\q{Restart Session}} will | |
235 | do the same as \q{Duplicate Session}, but in the current window. | |
236 | ||
237 | \b The \i{\q{Saved Sessions} submenu} gives you quick access to any | |
238 | sets of stored session details you have previously saved. See | |
239 | \k{config-saving} for details of how to create saved sessions. | |
240 | ||
241 | \S2{using-changesettings} \I{settings, changing}Changing your | |
242 | session settings | |
243 | ||
244 | If you select \i{\q{Change Settings}} from the system menu, PuTTY will | |
245 | display a cut-down version of its initial configuration box. This | |
246 | allows you to adjust most properties of your current session. You | |
247 | can change the terminal size, the font, the actions of various | |
248 | keypresses, the colours, and so on. | |
249 | ||
250 | Some of the options that are available in the main configuration box | |
251 | are not shown in the cut-down Change Settings box. These are usually | |
252 | options which don't make sense to change in the middle of a session | |
253 | (for example, you can't switch from SSH to Telnet in mid-session). | |
254 | ||
255 | You can save the current settings to a saved session for future use | |
256 | from this dialog box. See \k{config-saving} for more on saved | |
257 | sessions. | |
258 | ||
259 | \S2{using-copyall} \i{Copy All to Clipboard} | |
260 | ||
261 | This system menu option provides a convenient way to copy the whole | |
262 | contents of the terminal screen (up to the last nonempty line) and | |
263 | scrollback to the \i{clipboard} in one go. | |
264 | ||
265 | \S2{reset-terminal} \I{scrollback, clearing}Clearing and | |
266 | \I{terminal, resetting}resetting the terminal | |
267 | ||
268 | The \i{\q{Clear Scrollback}} option on the system menu tells PuTTY | |
269 | to discard all the lines of text that have been kept after they | |
270 | scrolled off the top of the screen. This might be useful, for | |
271 | example, if you displayed sensitive information and wanted to make | |
272 | sure nobody could look over your shoulder and see it. (Note that | |
273 | this only prevents a casual user from using the scrollbar to view | |
274 | the information; the text is not guaranteed not to still be in | |
275 | PuTTY's memory.) | |
276 | ||
277 | The \i{\q{Reset Terminal}} option causes a full reset of the | |
278 | \i{terminal emulation}. A VT-series terminal is a complex piece of | |
279 | software and can easily get into a state where all the text printed | |
280 | becomes unreadable. (This can happen, for example, if you | |
281 | accidentally output a binary file to your terminal.) If this | |
282 | happens, selecting Reset Terminal should sort it out. | |
283 | ||
284 | \S2{using-fullscreen} \ii{Full screen} mode | |
285 | ||
286 | If you find the title bar on a maximised window to be ugly or | |
287 | distracting, you can select Full Screen mode to maximise PuTTY | |
288 | \q{even more}. When you select this, PuTTY will expand to fill the | |
289 | whole screen and its borders, title bar and scrollbar will | |
290 | disappear. (You can configure the scrollbar not to disappear in | |
291 | full-screen mode if you want to keep it; see \k{config-scrollback}.) | |
292 | ||
293 | When you are in full-screen mode, you can still access the \i{system | |
294 | menu} if you click the left mouse button in the \e{extreme} top left | |
295 | corner of the screen. | |
296 | ||
297 | \H{using-logging} Creating a \i{log file} of your \I{session | |
298 | log}session | |
299 | ||
300 | For some purposes you may find you want to log everything that | |
301 | appears on your screen. You can do this using the \q{Logging} | |
302 | panel in the configuration box. | |
303 | ||
304 | To begin a session log, select \q{Change Settings} from the system | |
305 | menu and go to the Logging panel. Enter a log file name, and select | |
306 | a logging mode. (You can log all session output including the | |
307 | terminal \i{control sequence}s, or you can just log the printable text. | |
308 | It depends what you want the log for.) Click \q{Apply} and your log | |
309 | will be started. Later on, you can go back to the Logging panel and | |
310 | select \q{Logging turned off completely} to stop logging; then PuTTY | |
311 | will close the log file and you can safely read it. | |
312 | ||
313 | See \k{config-logging} for more details and options. | |
314 | ||
315 | \H{using-translation} Altering your \i{character set} configuration | |
316 | ||
317 | If you find that special characters (\i{accented characters}, for | |
318 | example, or \i{line-drawing characters}) are not being displayed | |
319 | correctly in your PuTTY session, it may be that PuTTY is interpreting | |
320 | the characters sent by the server according to the wrong \e{character | |
321 | set}. There are a lot of different character sets available, so it's | |
322 | entirely possible for this to happen. | |
323 | ||
324 | If you click \q{Change Settings} and look at the \q{Translation} | |
325 | panel, you should see a large number of character sets which you can | |
326 | select, and other related options. Now all you need is to find out | |
327 | which of them you want! (See \k{config-translation} for more | |
328 | information.) | |
329 | ||
330 | \H{using-x-forwarding} Using \i{X11 forwarding} in SSH | |
331 | ||
332 | The SSH protocol has the ability to securely forward X Window System | |
333 | applications over your encrypted SSH connection, so that you can run | |
334 | an application on the SSH server machine and have it put its windows | |
335 | up on your local machine without sending any X network traffic in | |
336 | the clear. | |
337 | ||
338 | In order to use this feature, you will need an X display server for | |
339 | your Windows machine, such as Cygwin/X, X-Win32, or Exceed. This will probably | |
340 | install itself as display number 0 on your local machine; if it | |
341 | doesn't, the manual for the \i{X server} should tell you what it | |
342 | does do. | |
343 | ||
344 | You should then tick the \q{Enable X11 forwarding} box in the | |
345 | X11 panel (see \k{config-ssh-x11}) before starting your SSH | |
346 | session. The \i{\q{X display location}} box is blank by default, which | |
347 | means that PuTTY will try to use a sensible default such as \c{:0}, | |
348 | which is the usual display location where your X server will be | |
349 | installed. If that needs changing, then change it. | |
350 | ||
351 | Now you should be able to log in to the SSH server as normal. To | |
352 | check that X forwarding has been successfully negotiated during | |
353 | connection startup, you can check the PuTTY Event Log (see | |
354 | \k{using-eventlog}). It should say something like this: | |
355 | ||
356 | \c 2001-12-05 17:22:01 Requesting X11 forwarding | |
357 | \c 2001-12-05 17:22:02 X11 forwarding enabled | |
358 | ||
359 | If the remote system is Unix or Unix-like, you should also be able | |
360 | to see that the \i{\c{DISPLAY} environment variable} has been set to | |
361 | point at display 10 or above on the SSH server machine itself: | |
362 | ||
363 | \c fred@unixbox:~$ echo $DISPLAY | |
364 | \c unixbox:10.0 | |
365 | ||
366 | If this works, you should then be able to run X applications in the | |
367 | remote session and have them display their windows on your PC. | |
368 | ||
369 | For more options relating to X11 forwarding, see \k{config-ssh-x11}. | |
370 | ||
371 | \H{using-port-forwarding} Using \i{port forwarding} in SSH | |
372 | ||
373 | The SSH protocol has the ability to forward arbitrary \i{network | |
374 | connection}s over your encrypted SSH connection, to avoid the network | |
375 | traffic being sent in clear. For example, you could use this to | |
376 | connect from your home computer to a \i{POP-3} server on a remote | |
377 | machine without your POP-3 password being visible to network | |
378 | sniffers. | |
379 | ||
380 | In order to use port forwarding to \I{local port forwarding}connect | |
381 | from your local machine to a port on a remote server, you need to: | |
382 | ||
383 | \b Choose a \i{port number} on your local machine where PuTTY should | |
384 | listen for incoming connections. There are likely to be plenty of | |
385 | unused port numbers above 3000. (You can also use a local loopback | |
386 | address here; see below for more details.) | |
387 | ||
388 | \b Now, before you start your SSH connection, go to the Tunnels | |
389 | panel (see \k{config-ssh-portfwd}). Make sure the \q{Local} radio | |
390 | button is set. Enter the local port number into the \q{Source port} | |
391 | box. Enter the destination host name and port number into the | |
392 | \q{Destination} box, separated by a colon (for example, | |
393 | \c{popserver.example.com:110} to connect to a POP-3 server). | |
394 | ||
395 | \b Now click the \q{Add} button. The details of your port forwarding | |
396 | should appear in the list box. | |
397 | ||
398 | Now start your session and log in. (Port forwarding will not be | |
399 | enabled until after you have logged in; otherwise it would be easy | |
400 | to perform completely anonymous network attacks, and gain access to | |
401 | anyone's virtual private network.) To check that PuTTY has set up | |
402 | the port forwarding correctly, you can look at the PuTTY Event Log | |
403 | (see \k{using-eventlog}). It should say something like this: | |
404 | ||
405 | \c 2001-12-05 17:22:10 Local port 3110 forwarding to | |
406 | \c popserver.example.com:110 | |
407 | ||
408 | Now if you connect to the source port number on your local PC, you | |
409 | should find that it answers you exactly as if it were the service | |
410 | running on the destination machine. So in this example, you could | |
411 | then configure an e-mail client to use \c{localhost:3110} as a POP-3 | |
412 | server instead of \c{popserver.example.com:110}. (Of course, the | |
413 | forwarding will stop happening when your PuTTY session closes down.) | |
414 | ||
415 | You can also forward ports in the other direction: arrange for a | |
416 | particular port number on the \e{server} machine to be \I{remote | |
417 | port forwarding}forwarded back to your PC as a connection to a | |
418 | service on your PC or near it. | |
419 | To do this, just select the \q{Remote} radio button instead of the | |
420 | \q{Local} one. The \q{Source port} box will now specify a port | |
421 | number on the \e{server} (note that most servers will not allow you | |
422 | to use \I{privileged port}port numbers under 1024 for this purpose). | |
423 | ||
424 | An alternative way to forward local connections to remote hosts is | |
425 | to use \I{dynamic port forwarding}dynamic SOCKS proxying. In this | |
426 | mode, PuTTY acts as a SOCKS server, which SOCKS-aware programs can | |
427 | connect to and open forwarded connections to the destination of their | |
428 | choice, so this can be an alternative to long lists of static | |
429 | forwardings. To use this mode, you will need to select the \q{Dynamic} | |
430 | radio button instead of \q{Local}, and then you should not enter | |
431 | anything into the \q{Destination} box (it will be ignored). PuTTY will | |
432 | then listen for SOCKS connections on the port you have specified. | |
433 | Most \i{web browsers} can be configured to connect to this SOCKS proxy | |
434 | service; also, you can forward other PuTTY connections through it by | |
435 | setting up the Proxy control panel (see \k{config-proxy} for details). | |
436 | ||
437 | The source port for a forwarded connection usually does not accept | |
438 | connections from any machine except the \I{localhost}SSH client or | |
439 | server machine itself (for local and remote forwardings respectively). | |
440 | There are controls in the Tunnels panel to change this: | |
441 | ||
442 | \b The \q{Local ports accept connections from other hosts} option | |
443 | allows you to set up local-to-remote port forwardings (including | |
444 | dynamic port forwardings) in such a way that machines other than | |
445 | your client PC can connect to the forwarded port. | |
446 | ||
447 | \b The \q{Remote ports do the same} option does the same thing for | |
448 | remote-to-local port forwardings (so that machines other than the | |
449 | SSH server machine can connect to the forwarded port.) Note that | |
450 | this feature is only available in the SSH-2 protocol, and not all | |
451 | SSH-2 servers honour it (in \i{OpenSSH}, for example, it's usually | |
452 | disabled by default). | |
453 | ||
454 | You can also specify an \i{IP address} to \I{listen address}listen | |
455 | on. Typically a Windows machine can be asked to listen on any single | |
456 | IP address in the \cw{127.*.*.*} range, and all of these are | |
457 | \i{loopback address}es available only to the local machine. So if | |
458 | you forward (for example) \c{127.0.0.5:79} to a remote machine's | |
459 | \i\cw{finger} port, then you should be able to run commands such as | |
460 | \c{finger fred@127.0.0.5}. | |
461 | This can be useful if the program connecting to the forwarded port | |
462 | doesn't allow you to change the port number it uses. This feature is | |
463 | available for local-to-remote forwarded ports; SSH-1 is unable to | |
464 | support it for remote-to-local ports, while SSH-2 can support it in | |
465 | theory but servers will not necessarily cooperate. | |
466 | ||
467 | (Note that if you're using Windows XP Service Pack 2, you may need | |
468 | to obtain a fix from Microsoft in order to use addresses like | |
469 | \cw{127.0.0.5} - see \k{faq-alternate-localhost}.) | |
470 | ||
471 | For more options relating to port forwarding, see | |
472 | \k{config-ssh-portfwd}. | |
473 | ||
474 | If the connection you are forwarding over SSH is itself a second SSH | |
475 | connection made by another copy of PuTTY, you might find the | |
476 | \q{logical host name} configuration option useful to warn PuTTY of | |
477 | which host key it should be expecting. See \k{config-loghost} for | |
478 | details of this. | |
479 | ||
480 | \H{using-rawprot} Making \i{raw TCP connections} | |
481 | ||
482 | A lot of \I{debugging Internet protocols}Internet protocols are | |
483 | composed of commands and responses in plain text. For example, | |
484 | \i{SMTP} (the protocol used to transfer e-mail), \i{NNTP} (the | |
485 | protocol used to transfer Usenet news), and \i{HTTP} (the protocol | |
486 | used to serve Web pages) all consist of commands in readable plain | |
487 | text. | |
488 | ||
489 | Sometimes it can be useful to connect directly to one of these | |
490 | services and speak the protocol \q{by hand}, by typing protocol | |
491 | commands and watching the responses. On Unix machines, you can do | |
492 | this using the system's \c{telnet} command to connect to the right | |
493 | port number. For example, \c{telnet mailserver.example.com 25} might | |
494 | enable you to talk directly to the SMTP service running on a mail | |
495 | server. | |
496 | ||
497 | Although the Unix \c{telnet} program provides this functionality, | |
498 | the protocol being used is not really Telnet. Really there is no | |
499 | actual protocol at all; the bytes sent down the connection are | |
500 | exactly the ones you type, and the bytes shown on the screen are | |
501 | exactly the ones sent by the server. Unix \c{telnet} will attempt to | |
502 | detect or guess whether the service it is talking to is a real | |
503 | Telnet service or not; PuTTY prefers to be told for certain. | |
504 | ||
505 | In order to make a debugging connection to a service of this type, | |
506 | you simply select the fourth protocol name, \I{\q{Raw} | |
507 | protocol}\q{Raw}, from the \q{Protocol} buttons in the \q{Session} | |
508 | configuration panel. (See \k{config-hostname}.) You can then enter a | |
509 | host name and a port number, and make the connection. | |
510 | ||
511 | \H{using-serial} Connecting to a local serial line | |
512 | ||
513 | PuTTY can connect directly to a local serial line as an alternative | |
514 | to making a network connection. In this mode, text typed into the | |
515 | PuTTY window will be sent straight out of your computer's serial | |
516 | port, and data received through that port will be displayed in the | |
517 | PuTTY window. You might use this mode, for example, if your serial | |
518 | port is connected to another computer which has a serial connection. | |
519 | ||
520 | To make a connection of this type, simply select \q{Serial} from the | |
521 | \q{Connection type} radio buttons on the \q{Session} configuration | |
522 | panel (see \k{config-hostname}). The \q{Host Name} and \q{Port} | |
523 | boxes will transform into \q{Serial line} and \q{Speed}, allowing | |
524 | you to specify which serial line to use (if your computer has more | |
525 | than one) and what speed (baud rate) to use when transferring data. | |
526 | For further configuration options (data bits, stop bits, parity, | |
527 | flow control), you can use the \q{Serial} configuration panel (see | |
528 | \k{config-serial}). | |
529 | ||
530 | After you start up PuTTY in serial mode, you might find that you | |
531 | have to make the first move, by sending some data out of the serial | |
532 | line in order to notify the device at the other end that someone is | |
533 | there for it to talk to. This probably depends on the device. If you | |
534 | start up a PuTTY serial session and nothing appears in the window, | |
535 | try pressing Return a few times and see if that helps. | |
536 | ||
537 | A serial line provides no well defined means for one end of the | |
538 | connection to notify the other that the connection is finished. | |
539 | Therefore, PuTTY in serial mode will remain connected until you | |
540 | close the window using the close button. | |
541 | ||
542 | \H{using-cmdline} The PuTTY command line | |
543 | ||
544 | PuTTY can be made to do various things without user intervention by | |
545 | supplying \i{command-line arguments} (e.g., from a \i{command prompt | |
546 | window}, or a \i{Windows shortcut}). | |
547 | ||
548 | \S{using-cmdline-session} Starting a session from the command line | |
549 | ||
550 | \I\c{-ssh}\I\c{-telnet}\I\c{-rlogin}\I\c{-raw}\I\c{-serial}These | |
551 | options allow you to bypass the configuration window and launch | |
552 | straight into a session. | |
553 | ||
554 | To start a connection to a server called \c{host}: | |
555 | ||
556 | \c putty.exe [-ssh | -telnet | -rlogin | -raw] [user@]host | |
557 | ||
558 | If this syntax is used, settings are taken from the \i{Default Settings} | |
559 | (see \k{config-saving}); \c{user} overrides these settings if | |
560 | supplied. Also, you can specify a protocol, which will override the | |
561 | default protocol (see \k{using-cmdline-protocol}). | |
562 | ||
563 | For telnet sessions, the following alternative syntax is supported | |
564 | (this makes PuTTY suitable for use as a URL handler for \i{telnet | |
565 | URLs} in \i{web browsers}): | |
566 | ||
567 | \c putty.exe telnet://host[:port]/ | |
568 | ||
569 | To start a connection to a serial port, e.g. COM1: | |
570 | ||
571 | \c putty.exe -serial com1 | |
572 | ||
573 | In order to start an existing saved session called \c{sessionname}, | |
574 | use the \c{-load} option (described in \k{using-cmdline-load}). | |
575 | ||
576 | \c putty.exe -load "session name" | |
577 | ||
578 | \S{using-cleanup} \i\c{-cleanup} | |
579 | ||
580 | \cfg{winhelp-topic}{options.cleanup} | |
581 | ||
582 | If invoked with the \c{-cleanup} option, rather than running as | |
583 | normal, PuTTY will remove its \I{removing registry entries}registry | |
584 | entries and \i{random seed file} from the local machine (after | |
585 | confirming with the user). | |
586 | ||
587 | Note that on \i{multi-user systems}, \c{-cleanup} only removes | |
588 | registry entries and files associated with the currently logged-in | |
589 | user. | |
590 | ||
591 | \S{using-general-opts} Standard command-line options | |
592 | ||
593 | PuTTY and its associated tools support a range of command-line | |
594 | options, most of which are consistent across all the tools. This | |
595 | section lists the available options in all tools. Options which are | |
596 | specific to a particular tool are covered in the chapter about that | |
597 | tool. | |
598 | ||
599 | \S2{using-cmdline-load} \i\c{-load}: load a saved session | |
600 | ||
601 | \I{saved sessions, loading from command line}The \c{-load} option | |
602 | causes PuTTY to load configuration details out of a saved session. | |
603 | If these details include a host name, then this option is all you | |
604 | need to make PuTTY start a session. | |
605 | ||
606 | You need double quotes around the session name if it contains spaces. | |
607 | ||
608 | If you want to create a \i{Windows shortcut} to start a PuTTY saved | |
609 | session, this is the option you should use: your shortcut should | |
610 | call something like | |
611 | ||
612 | \c d:\path\to\putty.exe -load "my session" | |
613 | ||
614 | (Note that PuTTY itself supports an alternative form of this option, | |
615 | for backwards compatibility. If you execute \i\c{putty @sessionname} | |
616 | it will have the same effect as \c{putty -load "sessionname"}. With | |
617 | the \c{@} form, no double quotes are required, and the \c{@} sign | |
618 | must be the very first thing on the command line. This form of the | |
619 | option is deprecated.) | |
620 | ||
621 | \S2{using-cmdline-protocol} Selecting a protocol: \c{-ssh}, | |
622 | \c{-telnet}, \c{-rlogin}, \c{-raw} \c{-serial} | |
623 | ||
624 | To choose which protocol you want to connect with, you can use one | |
625 | of these options: | |
626 | ||
627 | \b \i\c{-ssh} selects the SSH protocol. | |
628 | ||
629 | \b \i\c{-telnet} selects the Telnet protocol. | |
630 | ||
631 | \b \i\c{-rlogin} selects the Rlogin protocol. | |
632 | ||
633 | \b \i\c{-raw} selects the raw protocol. | |
634 | ||
635 | \b \i\c{-serial} selects a serial connection. | |
636 | ||
637 | These options are not available in the file transfer tools PSCP and | |
638 | PSFTP (which only work with the SSH protocol). | |
639 | ||
640 | These options are equivalent to the \i{protocol selection} buttons | |
641 | in the Session panel of the PuTTY configuration box (see | |
642 | \k{config-hostname}). | |
643 | ||
644 | \S2{using-cmdline-v} \i\c{-v}: increase verbosity | |
645 | ||
646 | \I{verbose mode}Most of the PuTTY tools can be made to tell you more | |
647 | about what they are doing by supplying the \c{-v} option. If you are | |
648 | having trouble when making a connection, or you're simply curious, | |
649 | you can turn this switch on and hope to find out more about what is | |
650 | happening. | |
651 | ||
652 | \S2{using-cmdline-l} \i\c{-l}: specify a \i{login name} | |
653 | ||
654 | You can specify the user name to log in as on the remote server | |
655 | using the \c{-l} option. For example, \c{plink login.example.com -l | |
656 | fred}. | |
657 | ||
658 | These options are equivalent to the username selection box in the | |
659 | Connection panel of the PuTTY configuration box (see | |
660 | \k{config-username}). | |
661 | ||
662 | \S2{using-cmdline-portfwd} \I{-L-upper}\c{-L}, \I{-R-upper}\c{-R} | |
663 | and \I{-D-upper}\c{-D}: set up \i{port forwardings} | |
664 | ||
665 | As well as setting up port forwardings in the PuTTY configuration | |
666 | (see \k{config-ssh-portfwd}), you can also set up forwardings on the | |
667 | command line. The command-line options work just like the ones in | |
668 | Unix \c{ssh} programs. | |
669 | ||
670 | To \I{local port forwarding}forward a local port (say 5110) to a | |
671 | remote destination (say \cw{popserver.example.com} port 110), you | |
672 | can write something like one of these: | |
673 | ||
674 | \c putty -L 5110:popserver.example.com:110 -load mysession | |
675 | \c plink mysession -L 5110:popserver.example.com:110 | |
676 | ||
677 | To forward a \I{remote port forwarding}remote port to a local | |
678 | destination, just use the \c{-R} option instead of \c{-L}: | |
679 | ||
680 | \c putty -R 5023:mytelnetserver.myhouse.org:23 -load mysession | |
681 | \c plink mysession -R 5023:mytelnetserver.myhouse.org:23 | |
682 | ||
683 | To \I{listen address}specify an IP address for the listening end of the | |
684 | tunnel, prepend it to the argument: | |
685 | ||
686 | \c plink -L 127.0.0.5:23:localhost:23 myhost | |
687 | ||
688 | To set up \I{dynamic port forwarding}SOCKS-based dynamic port | |
689 | forwarding on a local port, use the \c{-D} option. For this one you | |
690 | only have to pass the port number: | |
691 | ||
692 | \c putty -D 4096 -load mysession | |
693 | ||
694 | For general information on port forwarding, see | |
695 | \k{using-port-forwarding}. | |
696 | ||
697 | These options are not available in the file transfer tools PSCP and | |
698 | PSFTP. | |
699 | ||
700 | \S2{using-cmdline-m} \i\c{-m}: \I{reading commands from a file}read | |
701 | a remote command or script from a file | |
702 | ||
703 | The \i\c{-m} option performs a similar function to the \q{\ii{Remote | |
704 | command}} box in the SSH panel of the PuTTY configuration box (see | |
705 | \k{config-command}). However, the \c{-m} option expects to be given | |
706 | a local file name, and it will read a command from that file. | |
707 | ||
708 | With some servers (particularly Unix systems), you can even put | |
709 | multiple lines in this file and execute more than one command in | |
710 | sequence, or a whole shell script; but this is arguably an abuse, and | |
711 | cannot be expected to work on all servers. In particular, it is known | |
712 | \e{not} to work with certain \q{embedded} servers, such as \i{Cisco} | |
713 | routers. | |
714 | ||
715 | This option is not available in the file transfer tools PSCP and | |
716 | PSFTP. | |
717 | ||
718 | \S2{using-cmdline-p} \I{-P-upper}\c{-P}: specify a \i{port number} | |
719 | ||
720 | The \c{-P} option is used to specify the port number to connect to. If | |
721 | you have a Telnet server running on port 9696 of a machine instead of | |
722 | port 23, for example: | |
723 | ||
724 | \c putty -telnet -P 9696 host.name | |
725 | \c plink -telnet -P 9696 host.name | |
726 | ||
727 | (Note that this option is more useful in Plink than in PuTTY, | |
728 | because in PuTTY you can write \c{putty -telnet host.name 9696} in | |
729 | any case.) | |
730 | ||
731 | This option is equivalent to the port number control in the Session | |
732 | panel of the PuTTY configuration box (see \k{config-hostname}). | |
733 | ||
734 | \S2{using-cmdline-pw} \i\c{-pw}: specify a \i{password} | |
735 | ||
736 | A simple way to automate a remote login is to supply your password | |
737 | on the command line. This is \e{not recommended} for reasons of | |
738 | security. If you possibly can, we recommend you set up public-key | |
739 | authentication instead. See \k{pubkey} for details. | |
740 | ||
741 | Note that the \c{-pw} option only works when you are using the SSH | |
742 | protocol. Due to fundamental limitations of Telnet and Rlogin, these | |
743 | protocols do not support automated password authentication. | |
744 | ||
745 | \S2{using-cmdline-agentauth} \i\c{-agent} and \i\c{-noagent}: | |
746 | control use of Pageant for authentication | |
747 | ||
748 | The \c{-agent} option turns on SSH authentication using Pageant, and | |
749 | \c{-noagent} turns it off. These options are only meaningful if you | |
750 | are using SSH. | |
751 | ||
752 | See \k{pageant} for general information on \i{Pageant}. | |
753 | ||
754 | These options are equivalent to the agent authentication checkbox in | |
755 | the Auth panel of the PuTTY configuration box (see | |
756 | \k{config-ssh-tryagent}). | |
757 | ||
758 | \S2{using-cmdline-agent} \I{-A-upper}\c{-A} and \i\c{-a}: control \i{agent | |
759 | forwarding} | |
760 | ||
761 | The \c{-A} option turns on SSH agent forwarding, and \c{-a} turns it | |
762 | off. These options are only meaningful if you are using SSH. | |
763 | ||
764 | See \k{pageant} for general information on \i{Pageant}, and | |
765 | \k{pageant-forward} for information on agent forwarding. Note that | |
766 | there is a security risk involved with enabling this option; see | |
767 | \k{pageant-security} for details. | |
768 | ||
769 | These options are equivalent to the agent forwarding checkbox in the | |
770 | Auth panel of the PuTTY configuration box (see \k{config-ssh-agentfwd}). | |
771 | ||
772 | These options are not available in the file transfer tools PSCP and | |
773 | PSFTP. | |
774 | ||
775 | \S2{using-cmdline-x11} \I{-X-upper}\c{-X} and \i\c{-x}: control \i{X11 | |
776 | forwarding} | |
777 | ||
778 | The \c{-X} option turns on X11 forwarding in SSH, and \c{-x} turns | |
779 | it off. These options are only meaningful if you are using SSH. | |
780 | ||
781 | For information on X11 forwarding, see \k{using-x-forwarding}. | |
782 | ||
783 | These options are equivalent to the X11 forwarding checkbox in the | |
784 | X11 panel of the PuTTY configuration box (see \k{config-ssh-x11}). | |
785 | ||
786 | These options are not available in the file transfer tools PSCP and | |
787 | PSFTP. | |
788 | ||
789 | \S2{using-cmdline-pty} \i\c{-t} and \I{-T-upper}\c{-T}: control | |
790 | \i{pseudo-terminal allocation} | |
791 | ||
792 | The \c{-t} option ensures PuTTY attempts to allocate a | |
793 | pseudo-terminal at the server, and \c{-T} stops it from allocating | |
794 | one. These options are only meaningful if you are using SSH. | |
795 | ||
796 | These options are equivalent to the \q{Don't allocate a | |
797 | pseudo-terminal} checkbox in the SSH panel of the PuTTY | |
798 | configuration box (see \k{config-ssh-pty}). | |
799 | ||
800 | These options are not available in the file transfer tools PSCP and | |
801 | PSFTP. | |
802 | ||
803 | \S2{using-cmdline-noshell} \I{-N-upper}\c{-N}: suppress starting a | |
804 | \I{suppressing remote shell}shell or command | |
805 | ||
806 | The \c{-N} option prevents PuTTY from attempting to start a shell or | |
807 | command on the remote server. You might want to use this option if | |
808 | you are only using the SSH connection for port forwarding, and your | |
809 | user account on the server does not have the ability to run a shell. | |
810 | ||
811 | This feature is only available in SSH protocol version 2 (since the | |
812 | version 1 protocol assumes you will always want to run a shell). | |
813 | ||
814 | This option is equivalent to the \q{Don't start a shell or command | |
815 | at all} checkbox in the SSH panel of the PuTTY configuration box | |
816 | (see \k{config-ssh-noshell}). | |
817 | ||
818 | This option is not available in the file transfer tools PSCP and | |
819 | PSFTP. | |
820 | ||
821 | \S2{using-cmdline-ncmode} \I{-nc}\c{-nc}: make a \i{remote network | |
822 | connection} in place of a remote shell or command | |
823 | ||
824 | The \c{-nc} option prevents Plink (or PuTTY) from attempting to | |
825 | start a shell or command on the remote server. Instead, it will | |
826 | instruct the remote server to open a network connection to a host | |
827 | name and port number specified by you, and treat that network | |
828 | connection as if it were the main session. | |
829 | ||
830 | You specify a host and port as an argument to the \c{-nc} option, | |
831 | with a colon separating the host name from the port number, like | |
832 | this: | |
833 | ||
834 | \c plink host1.example.com -nc host2.example.com:1234 | |
835 | ||
836 | You might want to use this feature if you needed to make an SSH | |
837 | connection to a target host which you can only reach by going | |
838 | through a proxy host, and rather than using port forwarding you | |
839 | prefer to use the local proxy feature (see \k{config-proxy-type} for | |
840 | more about local proxies). In this situation you might select | |
841 | \q{Local} proxy type, set your local proxy command to be \cq{plink | |
842 | %proxyhost -nc %host:%port}, enter the target host name on the | |
843 | Session panel, and enter the directly reachable proxy host name on | |
844 | the Proxy panel. | |
845 | ||
846 | This feature is only available in SSH protocol version 2 (since the | |
847 | version 1 protocol assumes you will always want to run a shell). It | |
848 | is not available in the file transfer tools PSCP and PSFTP. It is | |
849 | available in PuTTY itself, although it is unlikely to be very useful | |
850 | in any tool other than Plink. Also, \c{-nc} uses the same server | |
851 | functionality as port forwarding, so it will not work if your server | |
852 | administrator has disabled port forwarding. | |
853 | ||
854 | (The option is named \c{-nc} after the Unix program | |
855 | \W{http://www.vulnwatch.org/netcat/}\c{nc}, short for \q{netcat}. | |
856 | The command \cq{plink host1 -nc host2:port} is very similar in | |
857 | functionality to \cq{plink host1 nc host2 port}, which invokes | |
858 | \c{nc} on the server and tells it to connect to the specified | |
859 | destination. However, Plink's built-in \c{-nc} option does not | |
860 | depend on the \c{nc} program being installed on the server.) | |
861 | ||
862 | \S2{using-cmdline-compress} \I{-C-upper}\c{-C}: enable \i{compression} | |
863 | ||
864 | The \c{-C} option enables compression of the data sent across the | |
865 | network. This option is only meaningful if you are using SSH. | |
866 | ||
867 | This option is equivalent to the \q{Enable compression} checkbox in | |
868 | the SSH panel of the PuTTY configuration box (see | |
869 | \k{config-ssh-comp}). | |
870 | ||
871 | \S2{using-cmdline-sshprot} \i\c{-1} and \i\c{-2}: specify an \i{SSH | |
872 | protocol version} | |
873 | ||
874 | The \c{-1} and \c{-2} options force PuTTY to use version \I{SSH-1}1 | |
875 | or version \I{SSH-2}2 of the SSH protocol. These options are only | |
876 | meaningful if you are using SSH. | |
877 | ||
878 | These options are equivalent to selecting your preferred SSH | |
879 | protocol version as \q{1 only} or \q{2 only} in the SSH panel of the | |
880 | PuTTY configuration box (see \k{config-ssh-prot}). | |
881 | ||
882 | \S2{using-cmdline-ipversion} \i\c{-4} and \i\c{-6}: specify an | |
883 | \i{Internet protocol version} | |
884 | ||
885 | The \c{-4} and \c{-6} options force PuTTY to use the older Internet | |
886 | protocol \i{IPv4} or the newer \i{IPv6} for most outgoing | |
887 | connections. | |
888 | ||
889 | These options are equivalent to selecting your preferred Internet | |
890 | protocol version as \q{IPv4} or \q{IPv6} in the Connection panel of | |
891 | the PuTTY configuration box (see \k{config-address-family}). | |
892 | ||
893 | \S2{using-cmdline-identity} \i\c{-i}: specify an SSH \i{private key} | |
894 | ||
895 | The \c{-i} option allows you to specify the name of a private key | |
896 | file in \c{*.\i{PPK}} format which PuTTY will use to authenticate with the | |
897 | server. This option is only meaningful if you are using SSH. | |
898 | ||
899 | For general information on \i{public-key authentication}, see | |
900 | \k{pubkey}. | |
901 | ||
902 | This option is equivalent to the \q{Private key file for | |
903 | authentication} box in the Auth panel of the PuTTY configuration box | |
904 | (see \k{config-ssh-privkey}). | |
905 | ||
906 | \S2{using-cmdline-loghost} \i\c{-loghost}: specify a \i{logical host | |
907 | name} | |
908 | ||
909 | This option overrides PuTTY's normal SSH host key caching policy by | |
910 | telling it the name of the host you expect your connection to end up | |
911 | at (in cases where this differs from the location PuTTY thinks it's | |
912 | connecting to). It can be a plain host name, or a host name followed | |
913 | by a colon and a port number. See \k{config-loghost} for more detail | |
914 | on this. | |
915 | ||
916 | \S2{using-cmdline-pgpfp} \i\c{-pgpfp}: display \i{PGP key fingerprint}s | |
917 | ||
918 | This option causes the PuTTY tools not to run as normal, but instead | |
919 | to display the fingerprints of the PuTTY PGP Master Keys, in order to | |
920 | aid with \i{verifying new versions}. See \k{pgpkeys} for more information. | |
921 | ||
922 | \S2{using-cmdline-sercfg} \i\c{-sercfg}: specify serial port | |
923 | \i{configuration} | |
924 | ||
925 | This option specifies the configuration parameters for the serial | |
926 | port (baud rate, stop bits etc). Its argument is interpreted as a | |
927 | comma-separated list of configuration options, which can be as | |
928 | follows: | |
929 | ||
930 | \b Any single digit from 5 to 9 sets the number of data bits. | |
931 | ||
932 | \b \cq{1}, \cq{1.5} or \cq{2} sets the number of stop bits. | |
933 | ||
934 | \b Any other numeric string is interpreted as a baud rate. | |
935 | ||
936 | \b A single lower-case letter specifies the parity: \cq{n} for none, | |
937 | \cq{o} for odd, \cq{e} for even, \cq{m} for mark and \cq{s} for space. | |
938 | ||
939 | \b A single upper-case letter specifies the flow control: \cq{N} for | |
940 | none, \cq{X} for XON/XOFF, \cq{R} for RTS/CTS and \cq{D} for | |
941 | DSR/DTR. | |
942 | ||
943 | For example, \cq{-sercfg 19200,8,n,1,N} denotes a baud rate of | |
944 | 19200, 8 data bits, no parity, 1 stop bit and no flow control. |