e5b0d077 |
1 | \C{config} Configuring PuTTY |
2 | |
55ba634a |
3 | This chapter describes all the configuration options in PuTTY. |
4 | |
5 | PuTTY is configured using the control panel that comes up before you |
6 | start a session. Some options can also be changed in the middle of a |
7 | session, by selecting \e{Change Settings} from the window menu. |
8 | |
9 | \H{config-session} The Session panel |
10 | |
11 | The Session configuration panel contains the basic options you need |
12 | to specify in order to open a session at all, and also allows you to |
13 | save your settings to be reloaded later. |
14 | |
15 | \S{config-hostname} The host name section |
16 | |
17 | The top box on the Session panel, labelled \q{Specify your |
18 | connection by host name}, contains the details that need to be |
19 | filled in before PuTTY can open a session at all. |
20 | |
21 | \b The \e{Host Name} box is where you type the name, or the IP |
22 | address, of the server you want to connect to. |
23 | |
24 | \b The \e{Protocol} radio buttons let you choose what type of |
25 | connection you want to make: a raw connection, a Telnet connection, |
26 | or an SSH connection. \#{ FIXME: link to sections on these? } |
27 | |
28 | \b The \e{Port} box lets you specify which port number on the server |
29 | to connect to. If you select Telnet or SSH, this box will be filled |
30 | in automatically to the usual value, and you will only need to |
31 | change it if you have an unusual server. If you select Raw mode, you |
32 | will almost certainly need to fill in the \e{Port} box. |
33 | |
34 | \S{config-saving} Loading and storing saved sessions |
35 | |
36 | The next part of the Session configuration panel allows you to save |
37 | your preferred PuTTY options so they will appear automatically the |
38 | next time you start PuTTY. It also allows you to create \e{saved |
39 | sessions}, which contain a full set of configuration options plus a |
40 | host name and protocol. A saved session contains all the information |
41 | PuTTY needs to start exactly the session you want. |
42 | |
43 | \b To save your default settings: first set up the settings the way |
44 | you want them saved. Then come back to the Session panel. Select the |
45 | \q{Default Settings} entry in the saved sessions list, with a single |
46 | click. Then press the \e{Save} button. |
47 | |
48 | \b To save a session: first go through the rest of the configuration |
49 | box setting up all the options you want. Then come back to the |
50 | Session panel. Enter a name for the saved session in the \e{Saved |
51 | Sessions} input box. (The server name is often a good choice for a |
52 | saved session name.) Then press the \e{Save} button. Your saved |
53 | session name should now appear in the list box. |
54 | |
55 | \b To reload a saved session: single-click to select the session |
56 | name in the list box, and then press the \e{Load} button. Your saved |
57 | settings should all appear in the configuration panel. |
58 | |
59 | \b To modify a saved session: first load it as described above. Then |
60 | make the changes you want. Come back to the Session panel, |
61 | single-click to select the session name in the list box, and press |
62 | the \e{Save} button. The new settings will be saved over the top of |
63 | the old ones. |
64 | |
65 | \b To start a saved session immediately: double-click on the session |
66 | name in the list box. |
67 | |
68 | \b To delete a saved session: single-click to select the session |
69 | name in the list box, and then press the \e{Delete} button. |
70 | |
71 | Each saved session is independent of the Default Settings |
72 | configuration. If you change your preferences and update Default |
73 | Settings, you must also update every saved session separately. |
74 | |
75 | \S{config-closeonexit} \q{Close Window on Exit} |
76 | |
77 | Finally in the Session panel, there is a check box labelled \q{Close |
78 | Window on Exit}. If this is turned on, the PuTTY session window will |
79 | disappear as soon as the session inside it terminates. Otherwise, |
80 | the window will remain on the desktop until you close it yourself, |
81 | so you can still read and copy text out of it. |
82 | |
83 | \H{config-terminal} The Terminal panel |
84 | |
85 | The Terminal configuration panel allows you to control the behaviour |
86 | of PuTTY's terminal emulation. |
87 | |
88 | \S{config-autowrap} \q{Auto wrap mode initially on} |
89 | |
90 | Auto wrap mode controls what happens when text printed in a PuTTY |
91 | window reaches the right-hand edge of the window. |
92 | |
93 | With auto wrap mode on, if a long line of text reaches the |
94 | right-hand edge, it will wrap over on to the next line so you can |
95 | still see all the text. With auto wrap mode off, the cursor will |
96 | stay at the right-hand edge of the screen, and all the characters in |
97 | the line will be printed on top of each other. |
98 | |
99 | If you are running a full-screen application and you occasionally |
100 | find the screen scrolling up when it looks as if it shouldn't, you |
101 | could try turning this option off. |
102 | |
103 | Auto wrap mode can be turned on and off by control sequences sent by |
104 | the server. This configuration option only controls the \e{default} |
105 | state. If you modify this option in mid-session using \e{Change |
106 | Settings}, you will need to reset the terminal \#{ FIXME } before |
107 | the change takes effect. |
108 | |
109 | \S{config-decom} \q{DEC Origin Mode initially on} |
110 | |
111 | DEC Origin Mode is a minor option which controls how PuTTY |
112 | interprets cursor-position control sequences sent by the server. |
113 | |
114 | The server can send a control sequence that restricts the scrolling |
115 | region of the display. For example, in an editor, the server might |
116 | reserve a line at the top of the screen and a line at the bottom, |
117 | and might send a control sequence that causes scrolling operations |
118 | to affect only the remaining lines. |
119 | |
120 | With DEC Origin Mode on, cursor coordinates are counted from the top |
121 | of the scrolling region. With it turned off, cursor coordinates are |
122 | counted from the top of the whole screen regardless of the scrolling |
123 | region. |
124 | |
125 | It is unlikely you would need to change this option, but if you find |
126 | a full-screen application is displaying pieces of text in what looks |
127 | like the wrong part of the screen, you could try turning DEC Origin |
128 | Mode on to see whether that helps. |
129 | |
130 | DEC Origin Mode can be turned on and off by control sequences sent by |
131 | the server. This configuration option only controls the \e{default} |
132 | state. If you modify this option in mid-session using \e{Change |
133 | Settings}, you will need to reset the terminal \#{ FIXME } before |
134 | the change takes effect. |
135 | |
136 | \S{config-crlf} \q{Implicit CR in every LF} |
137 | |
138 | Most servers send two control characters, CR and LF, to start a new |
139 | line of the screen. The CR character makes the cursor return to the |
140 | left-hand side of the screen. The LF character makes the cursor move |
141 | one line down (and might make the screen scroll). |
142 | |
143 | Some servers only send LF, and expect the terminal to move the |
144 | cursor over to the left automatically. If you come across a server |
145 | that does this, you will see a stepped effect on the screen, like |
146 | this: |
147 | |
148 | \c First line of text |
149 | \c Second line |
150 | \c Third line |
151 | |
152 | If this happens to you, try enabling the \q{Implicit CR in every LF} |
153 | option, and things might go back to normal: |
154 | |
155 | \c First line of text |
156 | \c Second line |
157 | \c Third line |
158 | |
159 | \S{config-beep} \q{Beep enabled} |
160 | |
161 | This option lets you turn off beeps in PuTTY. If your server is |
162 | beeping too much or attracting unwelcome attention, you can turn the |
163 | beeps off. |
164 | |
165 | \S{config-erase} \q{Use background colour to erase screen} |
166 | |
167 | Not all terminals agree on what colour to turn the screen when the |
168 | server sends a \q{clear screen} sequence. Some terminals believe the |
169 | screen should always be cleared to the \e{default} background |
170 | colour. Others believe the screen should be cleared to whatever the |
171 | server has selected as a background colour. |
172 | |
173 | There exist applications that expect both kinds of behaviour. |
174 | Therefore, PuTTY can be configured to do either. |
175 | |
176 | With this option disabled, screen clearing is always done in the |
177 | default background colour. With this option enabled, it is done in |
178 | the \e{current} background colour. |
179 | |
180 | \S{config-blink} \q{Enable blinking text} |
181 | |
182 | The server can ask PuTTY to display text that blinks on and off. |
183 | This is very distracting, so PuTTY allows you to turn blinking text |
184 | off completely. |
185 | |
186 | \S{config-localterm} \q{Use local terminal line discipline} |
187 | |
188 | Normally, every character you type into the PuTTY window is sent |
189 | straight to the server. |
190 | |
191 | If you enable local terminal line discipline, this changes. PuTTY |
192 | will let you edit a whole line at a time locally, and the line will |
193 | only be sent to the server when you press Return. If you make a |
194 | mistake, you can use the Backspace key to correct it before you |
195 | press Return, and the server will never see the mistake. |
196 | |
197 | Since it would be hard to edit a line locally without being able to |
198 | see it, local terminal line discipline also makes PuTTY echo what |
199 | you type. This makes it ideal for use in raw mode \#{ FIXME } or |
200 | when connecting to MUDs or talkers. |
201 | |
202 | \S{config-logging} Controlling session logging |
203 | |
204 | PuTTY has the ability to log the output from your session into a |
205 | file. You might want this if you were saving a particular piece of |
206 | output to mail to somebody, for example in a bug report. |
207 | |
208 | You can choose between: |
209 | |
210 | \b not logging anything (the default) |
211 | |
212 | \b logging only the printable characters in a session (ignoring |
213 | control sequences to change colours or clear the screen) |
214 | |
215 | \b logging everything sent to the terminal by the server. |
216 | |
217 | You can turn logging on and off in mid-session using \e{Change |
218 | Settings}. |
219 | |
220 | \H{config-keyboard} The Keyboard panel |
221 | |
1630bb61 |
222 | The Keyboard configuration panel allows you to control the behaviour |
223 | of the keyboard in PuTTY. |
224 | |
55ba634a |
225 | \S{config-backspace} Changing the action of the Backspace key |
226 | |
1630bb61 |
227 | Some terminals believe that the Backspace key should send the same |
228 | thing to the server as Control-H (ASCII code 8). Other terminals |
229 | believe that the Backspace key should send ASCII code 127 (usually |
230 | known as Control-?) so that it can be distinguished from Control-H. |
231 | This option allows you to choose which code PuTTY generates when you |
232 | press Backspace. |
233 | |
234 | If you are connecting to a Unix system, you will probably find that |
235 | the Unix \c{stty} command lets you configure which the server |
236 | expects to see, so you might not need to change which one PuTTY |
237 | generates. On other systems, the server's expectation might be fixed |
238 | and you might have no choice but to configure PuTTY. |
239 | |
240 | If you do have the choice, we recommend configuring PuTTY to |
241 | generate Control-? and configuring the server to expect it, because |
242 | that allows applications such as \c{emacs} to use Control-H for |
243 | help. |
244 | |
55ba634a |
245 | \S{config-homeend} Changing the action of the Home and End keys |
246 | |
1630bb61 |
247 | The Unix terminal emulator \c{rxvt} disagrees with the rest of the |
248 | world about what character sequences should be sent to the server by |
249 | the Home and End keys. |
250 | |
251 | \c{xterm}, and other terminals, send \c{ESC [1~} for the Home key, |
252 | and \c{ESC [4~} for the End key. \c{rxvt} sends \c{ESC [H} for the |
253 | Home key and \c{ESC [Ow} for the End key. |
254 | |
255 | If you find an application on which the Home and End keys aren't |
256 | working, you could try switching this option to see if it helps. |
257 | |
55ba634a |
258 | \S{config-funkeys} Changing the action of the function keys and keypad |
259 | |
1630bb61 |
260 | This option affects the function keys (F1 to F12) and the top row of |
261 | the numeric keypad. |
262 | |
263 | \b In the default mode, labelled \c{ESC [n~}, the function keys |
264 | generate sequences like \c{ESC [11~}, \c{ESC [12~} and so on. This |
265 | matches the general behaviour of Digital's terminals. |
266 | |
267 | \b In Linux mode, F6 to F12 behave just like the default mode, but |
268 | F1 to F5 generate \c{ESC [[A} through to \c{ESC [[E}. This mimics the |
269 | Linux virtual console. |
270 | |
271 | \b In Xterm R6 mode, F5 to F12 behave like the default mode, but F1 |
272 | to F4 generate \c{ESC OP} through to \c{ESC OS}, which are the |
273 | sequences produced by the top row of the \e{keypad} on Digital's |
274 | terminals. |
275 | |
276 | \b In VT400 mode, all the function keys behave like the default |
277 | mode, but the actual top row of the numeric keypad generates \c{ESC |
278 | OP} through to \c{ESC OS}. |
279 | |
280 | If you don't know what any of this means, you probably don't need to |
281 | fiddle with it. |
282 | |
55ba634a |
283 | \S{config-appcursor} Controlling Application Cursor Keys mode |
284 | |
1630bb61 |
285 | Application Cursor Keys mode is a way for the server to change the |
286 | control sequences sent by the arrow keys. In normal mode, the arrow |
287 | keys send \c{ESC [A} through to \c{ESC [D}. In application mode, |
288 | they send \c{ESC OA} through to \c{ESC OD}. |
289 | |
290 | Application Cursor Keys mode can be turned on and off by the server, |
291 | depending on the application. PuTTY allows you to configure the |
292 | initial state, and also allows you to disable application mode |
293 | completely. |
294 | |
55ba634a |
295 | \S{config-appkeypad} Controlling Application Keypad mode |
296 | |
1630bb61 |
297 | Application Keypad mode is a way for the server to change the |
298 | behaviour of the numeric keypad. |
299 | |
300 | In normal mode, the keypad behaves like a normal Windows keypad: |
301 | with NumLock on, the number keys generate numbers, and with NumLock |
302 | off they act like the arrow keys and Home, End etc. |
303 | |
304 | In application mode, all the keypad keys send special control |
305 | sequences, \e{including} Num Lock. Num Lock stops behaving like Num |
306 | Lock and becomes another function key. |
307 | |
308 | Depending on which version of Windows you run, you may find the Num |
309 | Lock light still flashes on and off every time you press Num Lock, |
310 | even when application mode is active and Num Lock is acting like a |
311 | function key. This is unavoidable. |
312 | |
313 | Application keypad mode can be turned on and off by the server, |
314 | depending on the application. PuTTY allows you to configure the |
315 | initial state, and also allows you to disable application mode |
316 | completely. |
317 | |
55ba634a |
318 | \S{config-nethack} Using NetHack keypad mode |
319 | |
1630bb61 |
320 | PuTTY has a special mode for playing NetHack. You can enable it by |
321 | selecting \q{NetHack} in the \q{Initial state of numeric keypad} |
322 | control. |
323 | |
324 | In this mode, the numeric keypad keys 1-9 generate the NetHack |
325 | movement commands (\cw{hjklyubn}). The 5 key generates the \c{.} |
326 | command (do nothing). |
327 | |
328 | Better still, pressing Shift with the keypad keys generates the |
329 | capital forms of the commands (\cw{HJKLYUBN}), which tells NetHack |
330 | to keep moving you in the same direction until you encounter |
331 | something interesting. |
332 | |
333 | For some reason, this feature only works properly when Num Lock is |
334 | on. We don't know why. |
335 | |
55ba634a |
336 | \S{config-compose} Enabling a DEC-like Compose key |
337 | |
1630bb61 |
338 | DEC terminals have a Compose key, which provides an easy-to-remember |
339 | way of typing accented characters. You press Compose and then type |
340 | two more characters. The two characters are \q{combined} to produce |
341 | an accented character. The choices of character are designed to be |
342 | easy to remember; for example, composing \q{e} and \q{`} produces |
343 | the \q{\u00e8{e-grave}} character. |
344 | |
345 | If you enable the \q{Application and AltGr act as Compose key} |
346 | option, the Windows Application key and the AltGr key will both have |
347 | this behaviour. |
348 | |
55ba634a |
349 | \H{config-window} The Window panel |
350 | |
1630bb61 |
351 | The Window configuration panel allows you to control aspects of the |
352 | PuTTY window and its behaviour. |
353 | |
55ba634a |
354 | \S{config-winsize} Setting the size of the PuTTY window |
355 | |
1630bb61 |
356 | The \e{Rows} and \e{Columns} boxes let you set the PuTTY window to a |
357 | precise size. Of course you can also drag the window to a new size |
358 | while a session is running. |
359 | |
360 | If you are running an application which is unable to deal with |
361 | changes in window size, you might want to enable the \q{Lock window |
362 | size against resizing} option, which prevents the user from |
363 | accidentally changing the size of the window. |
364 | |
55ba634a |
365 | \S{config-scrollback} Controlling scrollback |
366 | |
1630bb61 |
367 | Text that scrolls off the top of the PuTTY terminal window is kept |
368 | for reference. The scrollbar on the right of the window lets you |
369 | view the scrolled-off text. You can also page through the scrollback |
370 | using the keyboard, by pressing Shift-PgUp and Shift-PgDn. |
371 | |
372 | The \q{Lines of scrollback} box lets you configure how many lines of |
373 | text PuTTY keeps. The \q{Display scrollbar} option allows you to |
374 | hide the scrollbar (although you can still view the scrollback using |
375 | Shift-PgUp and Shift-PgDn). |
376 | |
377 | If you are viewing part of the scrollback when the server sends more |
378 | text to PuTTY, the screen will revert to showing the current |
379 | terminal contents. You can disable this behaviour by turning off |
380 | \q{Reset scrollback on display activity}. You can also make the |
381 | screen revert when you press a key, by turning on \q{Reset |
382 | scrollback on keypress}. |
383 | |
55ba634a |
384 | \S{config-warnonclose} \q{Warn before closing window} |
385 | |
1630bb61 |
386 | If you press the Close button in a PuTTY window that contains a |
387 | running session, PuTTY will put up a warning window asking if you |
388 | really meant to close the window. A window whose session has already |
389 | terminated can always be closed without a warning. |
390 | |
391 | If you want to be able to close a window quickly, you can disable |
392 | the \q{Warn before closing window} option. |
393 | |
55ba634a |
394 | \S{config-altf4} \q{Window closes on ALT-F4} |
395 | |
1630bb61 |
396 | By default, pressing ALT-F4 causes the window to close (or a warning |
397 | box to appear; see \k{config-warnonclose}). If you disable the |
398 | \q{Window closes on ALT-F4} option, then pressing ALT-F4 will simply |
399 | send a key sequence to the server. |
400 | |
55ba634a |
401 | \S{config-altspace} \q{System menu appears on ALT-Space} |
402 | |
1630bb61 |
403 | If this option is enabled, then pressing ALT-Space will bring up the |
404 | PuTTY window's menu, like clicking on the top left corner. If it is |
405 | disabled, then pressing ALT-Space will just send \c{ESC SPACE} to |
406 | the server. |
407 | |
55ba634a |
408 | \S{config-altonly} \q{System menu appears on Alt alone} |
409 | |
1630bb61 |
410 | If this option is enabled, then pressing and releasing ALT will |
411 | bring up the PuTTY window's menu, like clicking on the top left |
412 | corner. If it is disabled, then pressing and releasing ALT will have |
413 | no effect. |
414 | |
55ba634a |
415 | \S{config-alwaysontop} \q{Ensure window is always on top} |
416 | |
1630bb61 |
417 | If this option is enabled, the PuTTY window will stay on top of all |
418 | other windows. |
419 | |
55ba634a |
420 | \H{config-appearance} The Appearance panel |
421 | |
1630bb61 |
422 | The Appearance configuration panel allows you to control aspects of |
423 | PuTTY's appearance. |
424 | |
55ba634a |
425 | \S{config-cursor} Controlling the appearance of the cursor |
426 | |
26c8f51a |
427 | The \q{Cursor appearance} option lets you configure the cursor to be |
428 | a block, an underline, or a vertical line. A block cursor becomes an |
429 | empty box when the window loses focus; an underline or a vertical |
430 | line becomes dotted. |
431 | |
432 | The \q{Cursor blinks} option makes the cursor blink on and off. This |
433 | works in any of the cursor modes. |
55ba634a |
434 | |
435 | \S{config-font} Controlling the font used in the terminal window |
436 | |
26c8f51a |
437 | |
438 | |
55ba634a |
439 | \S{config-title} Controlling the window title |
440 | |
441 | \H{config-translation} The Translation panel |
442 | |
1630bb61 |
443 | The Translation configuration panel allows you to control the |
444 | translation between the character set understood by the server and |
445 | the character set understood by PuTTY. |
446 | |
55ba634a |
447 | \S{config-linedraw} Line drawing characters |
448 | |
449 | \S{config-outputtrans} Character set translation of output data |
450 | |
451 | \S{config-inputtrans} Character set translation of input data |
452 | |
453 | \H{config-selection} The Selection panel |
454 | |
1630bb61 |
455 | The Selection panel allows you to control the way copy and paste |
456 | work in the PuTTY window. |
457 | |
55ba634a |
458 | \S{config-mouse} Changing the actions of the mouse buttons |
459 | |
460 | \S{config-charclasses} Configuring word-by-word selection |
461 | |
462 | \H{config-colours} The Colours panel |
463 | |
1630bb61 |
464 | The Colours panel allows you to control PuTTY's use of colour. |
465 | |
55ba634a |
466 | \S{config-boldcolour} \q{Bolded text is a different colour} |
467 | |
468 | \S{config-logpalette} \q{Attempt to use logical palettes} |
469 | |
470 | \S{config-colourcfg} Adjusting the colours in the terminal window |
471 | |
472 | \H{config-connection} The Connection panel |
473 | |
1630bb61 |
474 | The Connection panel allows you to configure options that apply to |
475 | more than one type of connection. |
476 | |
55ba634a |
477 | \S{config-termtype} \q{Terminal-type string} |
478 | |
479 | \S{config-username} \q{Auto-login username} |
480 | |
481 | \S{config-keepalive} Using keepalives to prevent disconnection |
482 | |
483 | \H{config-telnet} The Telnet panel |
484 | |
1630bb61 |
485 | The Telnet panel allows you to configure options that only apply to |
486 | Telnet sessions. |
487 | |
55ba634a |
488 | \S{config-termspeed} \q{Terminal-speed string} |
489 | |
490 | \S{config-environ} Setting environment variables on the server |
491 | |
492 | \S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity} |
493 | |
494 | \H{config-ssh} The SSH panel |
495 | |
1630bb61 |
496 | The SSH panel allows you to configure options that only apply to |
497 | SSH sessions. |
498 | |
55ba634a |
499 | \S{config-command} Executing a specific command on the server |
500 | |
501 | \S{config-auth} SSH authentication options |
502 | |
503 | \S{config-protocol} SSH protocol options |
37c6fce1 |
504 | |
505 | \H{config-file} Storing configuration in a file |
506 | |
507 | PuTTY does not currently support storing its configuration in a file |
508 | instead of the Registry. However, you can work around this with a |
509 | couple of batch files. |
510 | |
511 | You will need a file called (say) \c{PUTTY.BAT} which imports the |
512 | contents of a file into the Registry, then runs PuTTY, exports the |
513 | contents of the Registry back into the file, and deletes the |
514 | Registry entries. This can all be done using the Regedit command |
515 | line options, so it's all automatic. Here is what you need in |
516 | \c{PUTTY.BAT}: |
517 | |
518 | \c @ECHO OFF |
519 | \c regedit /s putty.reg |
520 | \c regedit /s puttyrnd.reg |
521 | \c start /w putty.exe |
522 | \c regedit /e puttynew.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY |
523 | \c copy puttynew.reg putty.reg |
524 | \c del puttynew.reg |
525 | \c regedit /s puttydel.reg |
526 | |
527 | This batch file needs two auxiliary files: \c{PUTTYRND.REG} which |
528 | sets up an initial safe location for the \c{PUTTY.RND} random seed |
529 | file, and \c{PUTTYDEL.REG} which destroys everything in the Registry |
530 | once it's been successfully saved back to the file. |
531 | |
532 | Here is \c{PUTTYDEL.REG}: |
533 | |
534 | \c REGEDIT4 |
535 | \c |
536 | \c [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY] |
537 | |
538 | Here is an example \c{PUTTYRND.REG} file: |
539 | |
540 | \c REGEDIT4 |
541 | \c |
542 | \c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY] |
543 | \c "RandSeedFile"="a:\putty.rnd" |
544 | |
545 | You should replace \c{a:\\putty.rnd} with the location where you |
546 | want to store your random number data. If the aim is to carry around |
547 | PuTTY and its settings on one floppy, you probably want to store it |
548 | on the floppy. |