1 \C{config} Configuring PuTTY
3 This chapter describes all the configuration options in PuTTY.
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.
9 \H{config-session} The Session panel
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.
15 \S{config-hostname} The host name section
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.
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.
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, an
26 rlogin connection or an SSH connection. \#{ FIXME: link to sections on
29 \b The \e{Port} box lets you specify which port number on the server
30 to connect to. If you select Telnet, Rlogin, or SSH, this box will be
31 filled in automatically to the usual value, and you will only need to
32 change it if you have an unusual server. If you select Raw mode, you
33 will almost certainly need to fill in the \e{Port} box.
35 \S{config-saving} Loading and storing saved sessions
37 The next part of the Session configuration panel allows you to save
38 your preferred PuTTY options so they will appear automatically the
39 next time you start PuTTY. It also allows you to create \e{saved
40 sessions}, which contain a full set of configuration options plus a
41 host name and protocol. A saved session contains all the information
42 PuTTY needs to start exactly the session you want.
44 \b To save your default settings: first set up the settings the way
45 you want them saved. Then come back to the Session panel. Select the
46 \q{Default Settings} entry in the saved sessions list, with a single
47 click. Then press the \e{Save} button.
49 \b To save a session: first go through the rest of the configuration
50 box setting up all the options you want. Then come back to the
51 Session panel. Enter a name for the saved session in the \e{Saved
52 Sessions} input box. (The server name is often a good choice for a
53 saved session name.) Then press the \e{Save} button. Your saved
54 session name should now appear in the list box.
56 \b To reload a saved session: single-click to select the session
57 name in the list box, and then press the \e{Load} button. Your saved
58 settings should all appear in the configuration panel.
60 \b To modify a saved session: first load it as described above. Then
61 make the changes you want. Come back to the Session panel,
62 single-click to select the session name in the list box, and press
63 the \e{Save} button. The new settings will be saved over the top of
66 \b To start a saved session immediately: double-click on the session
69 \b To delete a saved session: single-click to select the session
70 name in the list box, and then press the \e{Delete} button.
72 Each saved session is independent of the Default Settings
73 configuration. If you change your preferences and update Default
74 Settings, you must also update every saved session separately.
76 \S{config-closeonexit} \q{Close Window on Exit}
78 Finally in the Session panel, there is a check box labelled \q{Close
79 Window on Exit}. If this is turned on, the PuTTY session window will
80 disappear as soon as the session inside it terminates. Otherwise,
81 the window will remain on the desktop until you close it yourself,
82 so you can still read and copy text out of it.
84 \H{config-terminal} The Terminal panel
86 The Terminal configuration panel allows you to control the behaviour
87 of PuTTY's terminal emulation.
89 \S{config-autowrap} \q{Auto wrap mode initially on}
91 Auto wrap mode controls what happens when text printed in a PuTTY
92 window reaches the right-hand edge of the window.
94 With auto wrap mode on, if a long line of text reaches the
95 right-hand edge, it will wrap over on to the next line so you can
96 still see all the text. With auto wrap mode off, the cursor will
97 stay at the right-hand edge of the screen, and all the characters in
98 the line will be printed on top of each other.
100 If you are running a full-screen application and you occasionally
101 find the screen scrolling up when it looks as if it shouldn't, you
102 could try turning this option off.
104 Auto wrap mode can be turned on and off by control sequences sent by
105 the server. This configuration option only controls the \e{default}
106 state. If you modify this option in mid-session using \e{Change
107 Settings}, you will need to reset the terminal \#{ FIXME } before
108 the change takes effect.
110 \S{config-decom} \q{DEC Origin Mode initially on}
112 DEC Origin Mode is a minor option which controls how PuTTY
113 interprets cursor-position control sequences sent by the server.
115 The server can send a control sequence that restricts the scrolling
116 region of the display. For example, in an editor, the server might
117 reserve a line at the top of the screen and a line at the bottom,
118 and might send a control sequence that causes scrolling operations
119 to affect only the remaining lines.
121 With DEC Origin Mode on, cursor coordinates are counted from the top
122 of the scrolling region. With it turned off, cursor coordinates are
123 counted from the top of the whole screen regardless of the scrolling
126 It is unlikely you would need to change this option, but if you find
127 a full-screen application is displaying pieces of text in what looks
128 like the wrong part of the screen, you could try turning DEC Origin
129 Mode on to see whether that helps.
131 DEC Origin Mode can be turned on and off by control sequences sent by
132 the server. This configuration option only controls the \e{default}
133 state. If you modify this option in mid-session using \e{Change
134 Settings}, you will need to reset the terminal \#{ FIXME } before
135 the change takes effect.
137 \S{config-crlf} \q{Implicit CR in every LF}
139 Most servers send two control characters, CR and LF, to start a new
140 line of the screen. The CR character makes the cursor return to the
141 left-hand side of the screen. The LF character makes the cursor move
142 one line down (and might make the screen scroll).
144 Some servers only send LF, and expect the terminal to move the
145 cursor over to the left automatically. If you come across a server
146 that does this, you will see a stepped effect on the screen, like
149 \c First line of text
153 If this happens to you, try enabling the \q{Implicit CR in every LF}
154 option, and things might go back to normal:
156 \c First line of text
160 \S{config-beep} \q{Beep enabled}
162 This option lets you turn off beeps in PuTTY. If your server is
163 beeping too much or attracting unwelcome attention, you can turn the
166 \S{config-erase} \q{Use background colour to erase screen}
168 Not all terminals agree on what colour to turn the screen when the
169 server sends a \q{clear screen} sequence. Some terminals believe the
170 screen should always be cleared to the \e{default} background
171 colour. Others believe the screen should be cleared to whatever the
172 server has selected as a background colour.
174 There exist applications that expect both kinds of behaviour.
175 Therefore, PuTTY can be configured to do either.
177 With this option disabled, screen clearing is always done in the
178 default background colour. With this option enabled, it is done in
179 the \e{current} background colour.
181 \S{config-blink} \q{Enable blinking text}
183 The server can ask PuTTY to display text that blinks on and off.
184 This is very distracting, so PuTTY allows you to turn blinking text
187 \S{config-localterm} \q{Use local terminal line discipline}
189 Normally, every character you type into the PuTTY window is sent
190 straight to the server.
192 If you enable local terminal line discipline, this changes. PuTTY
193 will let you edit a whole line at a time locally, and the line will
194 only be sent to the server when you press Return. If you make a
195 mistake, you can use the Backspace key to correct it before you
196 press Return, and the server will never see the mistake.
198 Since it would be hard to edit a line locally without being able to
199 see it, local terminal line discipline also makes PuTTY echo what
200 you type. This makes it ideal for use in raw mode \#{ FIXME } or
201 when connecting to MUDs or talkers.
203 \S{config-logging} Controlling session logging
205 PuTTY has the ability to log the output from your session into a
206 file. You might want this if you were saving a particular piece of
207 output to mail to somebody, for example in a bug report.
209 You can choose between:
211 \b not logging anything (the default)
213 \b logging only the printable characters in a session (ignoring
214 control sequences to change colours or clear the screen)
216 \b logging everything sent to the terminal by the server.
218 You can turn logging on and off in mid-session using \e{Change
221 \H{config-keyboard} The Keyboard panel
223 The Keyboard configuration panel allows you to control the behaviour
224 of the keyboard in PuTTY.
226 \S{config-backspace} Changing the action of the Backspace key
228 Some terminals believe that the Backspace key should send the same
229 thing to the server as Control-H (ASCII code 8). Other terminals
230 believe that the Backspace key should send ASCII code 127 (usually
231 known as Control-?) so that it can be distinguished from Control-H.
232 This option allows you to choose which code PuTTY generates when you
235 If you are connecting to a Unix system, you will probably find that
236 the Unix \c{stty} command lets you configure which the server
237 expects to see, so you might not need to change which one PuTTY
238 generates. On other systems, the server's expectation might be fixed
239 and you might have no choice but to configure PuTTY.
241 If you do have the choice, we recommend configuring PuTTY to
242 generate Control-? and configuring the server to expect it, because
243 that allows applications such as \c{emacs} to use Control-H for
246 \S{config-homeend} Changing the action of the Home and End keys
248 The Unix terminal emulator \c{rxvt} disagrees with the rest of the
249 world about what character sequences should be sent to the server by
250 the Home and End keys.
252 \c{xterm}, and other terminals, send \c{ESC [1~} for the Home key,
253 and \c{ESC [4~} for the End key. \c{rxvt} sends \c{ESC [H} for the
254 Home key and \c{ESC [Ow} for the End key.
256 If you find an application on which the Home and End keys aren't
257 working, you could try switching this option to see if it helps.
259 \S{config-funkeys} Changing the action of the function keys and keypad
261 This option affects the function keys (F1 to F12) and the top row of
264 \b In the default mode, labelled \c{ESC [n~}, the function keys
265 generate sequences like \c{ESC [11~}, \c{ESC [12~} and so on. This
266 matches the general behaviour of Digital's terminals.
268 \b In Linux mode, F6 to F12 behave just like the default mode, but
269 F1 to F5 generate \c{ESC [[A} through to \c{ESC [[E}. This mimics the
270 Linux virtual console.
272 \b In Xterm R6 mode, F5 to F12 behave like the default mode, but F1
273 to F4 generate \c{ESC OP} through to \c{ESC OS}, which are the
274 sequences produced by the top row of the \e{keypad} on Digital's
277 \b In VT400 mode, all the function keys behave like the default
278 mode, but the actual top row of the numeric keypad generates \c{ESC
279 OP} through to \c{ESC OS}.
281 \b In VT100+ mode, the function keys generate \c{ESC OP} through to
284 \b In SCO mode, the function keys F1 to F12 generate \c{ESC [M}
285 through to \c{ESC [X}. Together with shift, they generate \c{ESC [Y}
286 through to \c{ESC [j}. With control they generate \c{ESC [k} through
287 to \c{ESC [v}, and with shift and control together they generate
288 \c{ESC [w} through to \c{ESC [\{}.
290 If you don't know what any of this means, you probably don't need to
293 \S{config-appcursor} Controlling Application Cursor Keys mode
295 Application Cursor Keys mode is a way for the server to change the
296 control sequences sent by the arrow keys. In normal mode, the arrow
297 keys send \c{ESC [A} through to \c{ESC [D}. In application mode,
298 they send \c{ESC OA} through to \c{ESC OD}.
300 Application Cursor Keys mode can be turned on and off by the server,
301 depending on the application. PuTTY allows you to configure the
302 initial state, and also allows you to disable application mode
305 \S{config-appkeypad} Controlling Application Keypad mode
307 Application Keypad mode is a way for the server to change the
308 behaviour of the numeric keypad.
310 In normal mode, the keypad behaves like a normal Windows keypad:
311 with NumLock on, the number keys generate numbers, and with NumLock
312 off they act like the arrow keys and Home, End etc.
314 In application mode, all the keypad keys send special control
315 sequences, \e{including} Num Lock. Num Lock stops behaving like Num
316 Lock and becomes another function key.
318 Depending on which version of Windows you run, you may find the Num
319 Lock light still flashes on and off every time you press Num Lock,
320 even when application mode is active and Num Lock is acting like a
321 function key. This is unavoidable.
323 Application keypad mode can be turned on and off by the server,
324 depending on the application. PuTTY allows you to configure the
325 initial state, and also allows you to disable application mode
328 \S{config-nethack} Using NetHack keypad mode
330 PuTTY has a special mode for playing NetHack. You can enable it by
331 selecting \q{NetHack} in the \q{Initial state of numeric keypad}
334 In this mode, the numeric keypad keys 1-9 generate the NetHack
335 movement commands (\cw{hjklyubn}). The 5 key generates the \c{.}
336 command (do nothing).
338 Better still, pressing Shift with the keypad keys generates the
339 capital forms of the commands (\cw{HJKLYUBN}), which tells NetHack
340 to keep moving you in the same direction until you encounter
341 something interesting.
343 For some reason, this feature only works properly when Num Lock is
344 on. We don't know why.
346 \S{config-compose} Enabling a DEC-like Compose key
348 DEC terminals have a Compose key, which provides an easy-to-remember
349 way of typing accented characters. You press Compose and then type
350 two more characters. The two characters are \q{combined} to produce
351 an accented character. The choices of character are designed to be
352 easy to remember; for example, composing \q{e} and \q{`} produces
353 the \q{\u00e8{e-grave}} character.
355 If you enable the \q{Application and AltGr act as Compose key}
356 option, the Windows Application key and the AltGr key will both have
359 \H{config-bell} The Bell panel
361 The Bell configuration panel allows you to control how PuTTY should
362 respond to a terminal bell.
364 \S{config-bellstyle} Set the style of bell
366 When a terminal bell occurs, PuTTY can do one of the following things:
368 \b Nothing. The bell is disabled. Taskbar bell indication still
371 \b Play Windows Default Sound. The Windows Default Sound (which can
372 be configured from the Sounds control panel) will be played.
374 \b Play a custom sound file. Select a \c{.wav} sound file using the
375 \e{Custom sound file to play as a bell} text box, or browse for the
376 file to play using the \e{Browse...} button.
378 \b Flash the terminal window as a visual bell. No sound will be
381 In addition, the PuTTY window's title bar and its entry in the taskbar
382 can be configured to flash or invert to indicate that a terminal bell
385 \S{config-belloverload} Control the bell overload behaviour
387 Sometimes mistakes, for example trying to \c{cat} a binary file on a
388 Unix machine, can lead to a large number of terminal bells being
389 received by PuTTY. It might take a long time for PuTTY to catch up
390 with reacting to these bells, and the noise or flashing could be very
391 irritating for the user.
393 PuTTY's bell overload handling is designed to avoid this problem. If
394 turned on using the \e{Bell is temporarily disabled when over-used}
395 tick box, the bell will be disabled if it occurs more than a specified
396 number of times in a specified number of seconds. When no bells have
397 occurred for a number of seconds, PuTTY re-enables the bell.
399 \H{config-window} The Window panel
401 The Window configuration panel allows you to control aspects of the
402 PuTTY window and its behaviour.
404 \S{config-winsize} Setting the size of the PuTTY window
406 The \e{Rows} and \e{Columns} boxes let you set the PuTTY window to a
407 precise size. Of course you can also drag the window to a new size
408 while a session is running.
410 If you are running an application which is unable to deal with
411 changes in window size, you might want to enable the \q{Lock window
412 size against resizing} option, which prevents the user from
413 accidentally changing the size of the window.
415 \S{config-scrollback} Controlling scrollback
417 Text that scrolls off the top of the PuTTY terminal window is kept
418 for reference. The scrollbar on the right of the window lets you
419 view the scrolled-off text. You can also page through the scrollback
420 using the keyboard, by pressing Shift-PgUp and Shift-PgDn.
422 The \q{Lines of scrollback} box lets you configure how many lines of
423 text PuTTY keeps. The \q{Display scrollbar} option allows you to
424 hide the scrollbar (although you can still view the scrollback using
425 Shift-PgUp and Shift-PgDn).
427 If you are viewing part of the scrollback when the server sends more
428 text to PuTTY, the screen will revert to showing the current
429 terminal contents. You can disable this behaviour by turning off
430 \q{Reset scrollback on display activity}. You can also make the
431 screen revert when you press a key, by turning on \q{Reset
432 scrollback on keypress}.
434 \S{config-warnonclose} \q{Warn before closing window}
436 If you press the Close button in a PuTTY window that contains a
437 running session, PuTTY will put up a warning window asking if you
438 really meant to close the window. A window whose session has already
439 terminated can always be closed without a warning.
441 If you want to be able to close a window quickly, you can disable
442 the \q{Warn before closing window} option.
444 \S{config-altf4} \q{Window closes on ALT-F4}
446 By default, pressing ALT-F4 causes the window to close (or a warning
447 box to appear; see \k{config-warnonclose}). If you disable the
448 \q{Window closes on ALT-F4} option, then pressing ALT-F4 will simply
449 send a key sequence to the server.
451 \S{config-altspace} \q{System menu appears on ALT-Space}
453 If this option is enabled, then pressing ALT-Space will bring up the
454 PuTTY window's menu, like clicking on the top left corner. If it is
455 disabled, then pressing ALT-Space will just send \c{ESC SPACE} to
458 \S{config-altonly} \q{System menu appears on Alt alone}
460 If this option is enabled, then pressing and releasing ALT will
461 bring up the PuTTY window's menu, like clicking on the top left
462 corner. If it is disabled, then pressing and releasing ALT will have
465 \S{config-alwaysontop} \q{Ensure window is always on top}
467 If this option is enabled, the PuTTY window will stay on top of all
470 \H{config-appearance} The Appearance panel
472 The Appearance configuration panel allows you to control aspects of
475 \S{config-cursor} Controlling the appearance of the cursor
477 The \q{Cursor appearance} option lets you configure the cursor to be
478 a block, an underline, or a vertical line. A block cursor becomes an
479 empty box when the window loses focus; an underline or a vertical
482 The \q{Cursor blinks} option makes the cursor blink on and off. This
483 works in any of the cursor modes.
485 \S{config-font} Controlling the font used in the terminal window
489 \S{config-title} Controlling the window title
491 \H{config-translation} The Translation panel
493 The Translation configuration panel allows you to control the
494 translation between the character set understood by the server and
495 the character set understood by PuTTY.
497 \S{config-linedraw} Line drawing characters
499 \S{config-outputtrans} Character set translation of output data
501 \S{config-inputtrans} Character set translation of input data
503 \H{config-selection} The Selection panel
505 The Selection panel allows you to control the way copy and paste
506 work in the PuTTY window.
508 \S{config-mouse} Changing the actions of the mouse buttons
510 \S{config-charclasses} Configuring word-by-word selection
512 \H{config-colours} The Colours panel
514 The Colours panel allows you to control PuTTY's use of colour.
516 \S{config-boldcolour} \q{Bolded text is a different colour}
518 \S{config-logpalette} \q{Attempt to use logical palettes}
520 \S{config-colourcfg} Adjusting the colours in the terminal window
522 \H{config-connection} The Connection panel
524 The Connection panel allows you to configure options that apply to
525 more than one type of connection.
527 \S{config-termtype} \q{Terminal-type string}
529 \S{config-username} \q{Auto-login username}
531 \S{config-keepalive} Using keepalives to prevent disconnection
533 If you find your sessions are closing unexpectedly (\q{Connection
534 reset by peer}) after they have been idle for a while, you might
535 want to try using this option.
537 Some network routers and firewalls need keep track of all
538 connections through them. Usually, these firewalls will assume a
539 connection is dead if no data is transferred in either direction
540 after a certain time interval. This can cause PuTTY sessions to be
541 unexpectedly closed by the firewall if no traffic is seen in the
542 session for some time.
544 The keepalive option (\q{Seconds between keepalives}) allows you to
545 configure PuTTY to send data through the session at regular
546 intervals, in a way that does not disrupt the actual terminal
547 session. If you find your firewall is cutting idle connections off,
548 you can try entering a non-zero value in this field. The value is
549 measured in seconds; so, for example, if your firewall cuts
550 connections off after ten minutes then you might want to enter 300
551 seconds (5 minutes) in the box.
553 Note that keepalives are not always helpful. They help if you have a
554 firewall which drops your connection after an idle period; but if
555 the network between you and the server suffers from breaks in
556 connectivity then keepalives can actually make things worse. If a
557 session is idle, and connectivity is temporarily lost between the
558 endpoints, but the connectivity is restored before either side tries
559 to send anything, then there will be no problem - neither endpoint
560 will notice that anything was wrong. However, if one side does send
561 something during the break, it will repeatedly try to re-send, and
562 eventually give up and abandon the connection. Then when
563 connectivity is restored, the other side will find that the first
564 side doesn't believe there is an open connection any more.
565 Keepalives can make this sort of problem worse, because they
566 increase the probability that PuTTY will attempt to send data during
567 a break in connectivity. Therefore, you might find they help
568 connection loss, or you might find they make it worse, depending on
569 what \e{kind} of network problems you have between you and the
572 Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
573 protocols offer no way of implementing them.
575 \H{config-telnet} The Telnet panel
577 The Telnet panel allows you to configure options that only apply to
580 \S{config-termspeed} \q{Terminal-speed string}
582 \S{config-environ} Setting environment variables on the server
584 \S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
586 \H{config-ssh} The SSH panel
588 The SSH panel allows you to configure options that only apply to
591 \S{config-command} Executing a specific command on the server
593 \S{config-auth} SSH authentication options
595 \S{config-protocol} SSH protocol options
597 \H{config-file} Storing configuration in a file
599 PuTTY does not currently support storing its configuration in a file
600 instead of the Registry. However, you can work around this with a
601 couple of batch files.
603 You will need a file called (say) \c{PUTTY.BAT} which imports the
604 contents of a file into the Registry, then runs PuTTY, exports the
605 contents of the Registry back into the file, and deletes the
606 Registry entries. This can all be done using the Regedit command
607 line options, so it's all automatic. Here is what you need in
611 \c regedit /s putty.reg
612 \c regedit /s puttyrnd.reg
613 \c start /w putty.exe
614 \c regedit /e puttynew.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
615 \c copy puttynew.reg putty.reg
617 \c regedit /s puttydel.reg
619 This batch file needs two auxiliary files: \c{PUTTYRND.REG} which
620 sets up an initial safe location for the \c{PUTTY.RND} random seed
621 file, and \c{PUTTYDEL.REG} which destroys everything in the Registry
622 once it's been successfully saved back to the file.
624 Here is \c{PUTTYDEL.REG}:
628 \c [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
630 Here is an example \c{PUTTYRND.REG} file:
634 \c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
635 \c "RandSeedFile"="a:\putty.rnd"
637 You should replace \c{a:\\putty.rnd} with the location where you
638 want to store your random number data. If the aim is to carry around
639 PuTTY and its settings on one floppy, you probably want to store it