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,
26 or an SSH connection. \#{ FIXME: link to sections on these? }
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.
34 \S{config-saving} Loading and storing saved sessions
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.
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.
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.
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.
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
65 \b To start a saved session immediately: double-click on the session
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.
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.
75 \S{config-closeonexit} \q{Close Window on Exit}
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.
83 \H{config-terminal} The Terminal panel
85 The Terminal configuration panel allows you to control the behaviour
86 of PuTTY's terminal emulation.
88 \S{config-autowrap} \q{Auto wrap mode initially on}
90 Auto wrap mode controls what happens when text printed in a PuTTY
91 window reaches the right-hand edge of the window.
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.
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.
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.
109 \S{config-decom} \q{DEC Origin Mode initially on}
111 DEC Origin Mode is a minor option which controls how PuTTY
112 interprets cursor-position control sequences sent by the server.
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.
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
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.
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.
136 \S{config-crlf} \q{Implicit CR in every LF}
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).
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
148 \c First line of text
152 If this happens to you, try enabling the \q{Implicit CR in every LF}
153 option, and things might go back to normal:
155 \c First line of text
159 \S{config-beep} \q{Beep enabled}
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
165 \S{config-erase} \q{Use background colour to erase screen}
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.
173 There exist applications that expect both kinds of behaviour.
174 Therefore, PuTTY can be configured to do either.
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.
180 \S{config-blink} \q{Enable blinking text}
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
186 \S{config-localterm} \q{Use local terminal line discipline}
188 Normally, every character you type into the PuTTY window is sent
189 straight to the server.
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.
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.
202 \S{config-logging} Controlling session logging
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.
208 You can choose between:
210 \b not logging anything (the default)
212 \b logging only the printable characters in a session (ignoring
213 control sequences to change colours or clear the screen)
215 \b logging everything sent to the terminal by the server.
217 You can turn logging on and off in mid-session using \e{Change
220 \H{config-keyboard} The Keyboard panel
222 The Keyboard configuration panel allows you to control the behaviour
223 of the keyboard in PuTTY.
225 \S{config-backspace} Changing the action of the Backspace key
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
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.
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
245 \S{config-homeend} Changing the action of the Home and End keys
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.
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.
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.
258 \S{config-funkeys} Changing the action of the function keys and keypad
260 This option affects the function keys (F1 to F12) and the top row of
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.
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.
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
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}.
280 If you don't know what any of this means, you probably don't need to
283 \S{config-appcursor} Controlling Application Cursor Keys mode
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}.
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
295 \S{config-appkeypad} Controlling Application Keypad mode
297 Application Keypad mode is a way for the server to change the
298 behaviour of the numeric keypad.
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.
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.
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.
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
318 \S{config-nethack} Using NetHack keypad mode
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}
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).
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.
333 For some reason, this feature only works properly when Num Lock is
334 on. We don't know why.
336 \S{config-compose} Enabling a DEC-like Compose key
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.
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
349 \H{config-window} The Window panel
351 The Window configuration panel allows you to control aspects of the
352 PuTTY window and its behaviour.
354 \S{config-winsize} Setting the size of the PuTTY window
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.
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.
365 \S{config-scrollback} Controlling scrollback
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.
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).
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}.
384 \S{config-warnonclose} \q{Warn before closing window}
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.
391 If you want to be able to close a window quickly, you can disable
392 the \q{Warn before closing window} option.
394 \S{config-altf4} \q{Window closes on ALT-F4}
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.
401 \S{config-altspace} \q{System menu appears on ALT-Space}
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
408 \S{config-altonly} \q{System menu appears on Alt alone}
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
415 \S{config-alwaysontop} \q{Ensure window is always on top}
417 If this option is enabled, the PuTTY window will stay on top of all
420 \H{config-appearance} The Appearance panel
422 The Appearance configuration panel allows you to control aspects of
425 \S{config-cursor} Controlling the appearance of the cursor
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
432 The \q{Cursor blinks} option makes the cursor blink on and off. This
433 works in any of the cursor modes.
435 \S{config-font} Controlling the font used in the terminal window
439 \S{config-title} Controlling the window title
441 \H{config-translation} The Translation panel
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.
447 \S{config-linedraw} Line drawing characters
449 \S{config-outputtrans} Character set translation of output data
451 \S{config-inputtrans} Character set translation of input data
453 \H{config-selection} The Selection panel
455 The Selection panel allows you to control the way copy and paste
456 work in the PuTTY window.
458 \S{config-mouse} Changing the actions of the mouse buttons
460 \S{config-charclasses} Configuring word-by-word selection
462 \H{config-colours} The Colours panel
464 The Colours panel allows you to control PuTTY's use of colour.
466 \S{config-boldcolour} \q{Bolded text is a different colour}
468 \S{config-logpalette} \q{Attempt to use logical palettes}
470 \S{config-colourcfg} Adjusting the colours in the terminal window
472 \H{config-connection} The Connection panel
474 The Connection panel allows you to configure options that apply to
475 more than one type of connection.
477 \S{config-termtype} \q{Terminal-type string}
479 \S{config-username} \q{Auto-login username}
481 \S{config-keepalive} Using keepalives to prevent disconnection
483 \H{config-telnet} The Telnet panel
485 The Telnet panel allows you to configure options that only apply to
488 \S{config-termspeed} \q{Terminal-speed string}
490 \S{config-environ} Setting environment variables on the server
492 \S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
494 \H{config-ssh} The SSH panel
496 The SSH panel allows you to configure options that only apply to
499 \S{config-command} Executing a specific command on the server
501 \S{config-auth} SSH authentication options
503 \S{config-protocol} SSH protocol options