1 \versionid $Id: config.but,v 1.86.2.1 2004/07/29 17:56:50 simon Exp $
3 \C{config} Configuring PuTTY
5 This chapter describes all the configuration options in PuTTY.
7 PuTTY is configured using the control panel that comes up before you
8 start a session. Some options can also be changed in the middle of a
9 session, by selecting \q{Change Settings} from the window menu.
11 \H{config-session} The Session panel
13 The Session configuration panel contains the basic options you need
14 to specify in order to open a session at all, and also allows you to
15 save your settings to be reloaded later.
17 \S{config-hostname} The host name section
19 \cfg{winhelp-topic}{session.hostname}
21 The top box on the Session panel, labelled \q{Specify your
22 connection by host name}, contains the details that need to be
23 filled in before PuTTY can open a session at all.
25 \b The \q{Host Name} box is where you type the name, or the IP
26 address, of the server you want to connect to.
28 \b The \q{Protocol} radio buttons let you choose what type of
29 connection you want to make: a raw connection, a Telnet connection, an
30 rlogin connection or an SSH connection. (See \k{which-one} for a
31 summary of the differences between SSH, Telnet and rlogin.)
33 \b The \q{Port} box lets you specify which port number on the server
34 to connect to. If you select Telnet, Rlogin, or SSH, this box will
35 be filled in automatically to the usual value, and you will only
36 need to change it if you have an unusual server. If you select Raw
37 mode (see \k{using-rawprot}), you will almost certainly need to fill
40 \S{config-saving} Loading and storing saved sessions
42 \cfg{winhelp-topic}{session.saved}
44 The next part of the Session configuration panel allows you to save
45 your preferred PuTTY options so they will appear automatically the
46 next time you start PuTTY. It also allows you to create \e{saved
47 sessions}, which contain a full set of configuration options plus a
48 host name and protocol. A saved session contains all the information
49 PuTTY needs to start exactly the session you want.
51 \b To save your default settings: first set up the settings the way
52 you want them saved. Then come back to the Session panel. Select the
53 \q{Default Settings} entry in the saved sessions list, with a single
54 click. Then press the \q{Save} button.
56 Note that PuTTY does not allow you to save a host name into the
57 Default Settings entry. This ensures that when PuTTY is started up,
58 the host name box is always empty, so a user can always just type in
59 a host name and connect.
61 If there is a specific host you want to store the details of how to
62 connect to, you should create a saved session, which will be
63 separate from the Default Settings.
65 \b To save a session: first go through the rest of the configuration
66 box setting up all the options you want. Then come back to the
67 Session panel. Enter a name for the saved session in the \q{Saved
68 Sessions} input box. (The server name is often a good choice for a
69 saved session name.) Then press the \q{Save} button. Your saved
70 session name should now appear in the list box.
72 \b To reload a saved session: single-click to select the session
73 name in the list box, and then press the \q{Load} button. Your saved
74 settings should all appear in the configuration panel.
76 \b To modify a saved session: first load it as described above. Then
77 make the changes you want. Come back to the Session panel,
78 single-click to select the session name in the list box, and press
79 the \q{Save} button. The new settings will be saved over the top of
82 \b To start a saved session immediately: double-click on the session
85 \b To delete a saved session: single-click to select the session
86 name in the list box, and then press the \q{Delete} button.
88 Each saved session is independent of the Default Settings
89 configuration. If you change your preferences and update Default
90 Settings, you must also update every saved session separately.
92 Saved sessions are stored in the Registry, at the location
94 \c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\Sessions
96 If you need to store them in a file, you could try the method
97 described in \k{config-file}.
99 \S{config-closeonexit} \q{Close Window on Exit}
101 \cfg{winhelp-topic}{session.coe}
103 Finally in the Session panel, there is an option labelled \q{Close
104 Window on Exit}. This controls whether the PuTTY session window
105 disappears as soon as the session inside it terminates. If you are
106 likely to want to copy and paste text out of the session after it
107 has terminated, you should arrange this option to be off.
109 \q{Close Window On Exit} has three settings. \q{Always} means always
110 close the window on exit; \q{Never} means never close on exit
111 (always leave the window open). The third setting, and the default
112 one, is \q{Only on clean exit}. In this mode, a session which
113 terminates normally will cause its window to close, but one which is
114 aborted unexpectedly by network trouble or a confusing message from
115 the server will leave the window up.
117 \H{config-logging} The Logging panel
119 \cfg{winhelp-topic}{logging.main}
121 The Logging configuration panel allows you to save log files of your
122 PuTTY sessions, for debugging, analysis or future reference.
124 The main option is a radio-button set that specifies whether PuTTY
125 will log anything at all. The options are
127 \b \q{Logging turned off completely}. This is the default option; in
128 this mode PuTTY will not create a log file at all.
130 \b \q{Log printable output only}. In this mode, a log file will be
131 created and written to, but only printable text will be saved into
132 it. The various terminal control codes that are typically sent down
133 an interactive session alongside the printable text will be omitted.
134 This might be a useful mode if you want to read a log file in a text
135 editor and hope to be able to make sense of it.
137 \b \q{Log all session output}. In this mode, \e{everything} sent by
138 the server into your terminal session is logged. If you view the log
139 file in a text editor, therefore, you may well find it full of
140 strange control characters. This is a particularly useful mode if
141 you are experiencing problems with PuTTY's terminal handling: you
142 can record everything that went to the terminal, so that someone
143 else can replay the session later in slow motion and watch to see
146 \b \q{Log SSH packet data}. In this mode (which is only used by SSH
147 connections), the SSH message packets sent over the encrypted
148 connection are written to the log file. You might need this to debug
149 a network-level problem, or more likely to send to the PuTTY authors
150 as part of a bug report. \e{BE WARNED} that if you log in using a
151 password, the password will appear in the log file, so be sure to
152 edit it out before sending the log file to anyone else!
154 \S{config-logfilename} \q{Log file name}
156 \cfg{winhelp-topic}{logging.filename}
158 In this edit box you enter the name of the file you want to log the
159 session to. The \q{Browse} button will let you look around your file
160 system to find the right place to put the file; or if you already
161 know exactly where you want it to go, you can just type a pathname
164 There are a few special features in this box. If you use the \c{&}
165 character in the file name box, PuTTY will insert details of the
166 current session in the name of the file it actually opens. The
167 precise replacements it will do are:
169 \b \c{&Y} will be replaced by the current year, as four digits.
171 \b \c{&M} will be replaced by the current month, as two digits.
173 \b \c{&D} will be replaced by the current day of the month, as two
176 \b \c{&T} will be replaced by the current time, as six digits
177 (HHMMSS) with no punctuation.
179 \b \c{&H} will be replaced by the host name you are connecting to.
181 For example, if you enter the host name
182 \c{c:\\puttylogs\\log-&h-&y&m&d-&t.dat}, you will end up with files looking
185 \c log-server1.example.com-20010528-110859.dat
186 \c log-unixbox.somewhere.org-20010611-221001.dat
188 \S{config-logfileexists} \q{What to do if the log file already exists}
190 \cfg{winhelp-topic}{logging.exists}
192 This control allows you to specify what PuTTY should do if it tries
193 to start writing to a log file and it finds the file already exists.
194 You might want to automatically destroy the existing log file and
195 start a new one with the same name. Alternatively, you might want to
196 open the existing log file and add data to the \e{end} of it.
197 Finally (the default option), you might not want to have any
198 automatic behaviour, but to ask the user every time the problem
201 \H{config-terminal} The Terminal panel
203 The Terminal configuration panel allows you to control the behaviour
204 of PuTTY's terminal emulation.
206 \S{config-autowrap} \q{Auto wrap mode initially on}
208 \cfg{winhelp-topic}{terminal.autowrap}
210 Auto wrap mode controls what happens when text printed in a PuTTY
211 window reaches the right-hand edge of the window.
213 With auto wrap mode on, if a long line of text reaches the
214 right-hand edge, it will wrap over on to the next line so you can
215 still see all the text. With auto wrap mode off, the cursor will
216 stay at the right-hand edge of the screen, and all the characters in
217 the line will be printed on top of each other.
219 If you are running a full-screen application and you occasionally
220 find the screen scrolling up when it looks as if it shouldn't, you
221 could try turning this option off.
223 Auto wrap mode can be turned on and off by control sequences sent by
224 the server. This configuration option controls the \e{default}
225 state, which will be restored when you reset the terminal (see
226 \k{reset-terminal}). However, if you modify this option in
227 mid-session using \q{Change Settings}, it will take effect
230 \S{config-decom} \q{DEC Origin Mode initially on}
232 \cfg{winhelp-topic}{terminal.decom}
234 DEC Origin Mode is a minor option which controls how PuTTY
235 interprets cursor-position control sequences sent by the server.
237 The server can send a control sequence that restricts the scrolling
238 region of the display. For example, in an editor, the server might
239 reserve a line at the top of the screen and a line at the bottom,
240 and might send a control sequence that causes scrolling operations
241 to affect only the remaining lines.
243 With DEC Origin Mode on, cursor coordinates are counted from the top
244 of the scrolling region. With it turned off, cursor coordinates are
245 counted from the top of the whole screen regardless of the scrolling
248 It is unlikely you would need to change this option, but if you find
249 a full-screen application is displaying pieces of text in what looks
250 like the wrong part of the screen, you could try turning DEC Origin
251 Mode on to see whether that helps.
253 DEC Origin Mode can be turned on and off by control sequences sent
254 by the server. This configuration option controls the \e{default}
255 state, which will be restored when you reset the terminal (see
256 \k{reset-terminal}). However, if you modify this option in
257 mid-session using \q{Change Settings}, it will take effect
260 \S{config-crlf} \q{Implicit CR in every LF}
262 \cfg{winhelp-topic}{terminal.lfhascr}
264 Most servers send two control characters, CR and LF, to start a new
265 line of the screen. The CR character makes the cursor return to the
266 left-hand side of the screen. The LF character makes the cursor move
267 one line down (and might make the screen scroll).
269 Some servers only send LF, and expect the terminal to move the
270 cursor over to the left automatically. If you come across a server
271 that does this, you will see a stepped effect on the screen, like
274 \c First line of text
278 If this happens to you, try enabling the \q{Implicit CR in every LF}
279 option, and things might go back to normal:
281 \c First line of text
285 \S{config-erase} \q{Use background colour to erase screen}
287 \cfg{winhelp-topic}{terminal.bce}
289 Not all terminals agree on what colour to turn the screen when the
290 server sends a \q{clear screen} sequence. Some terminals believe the
291 screen should always be cleared to the \e{default} background
292 colour. Others believe the screen should be cleared to whatever the
293 server has selected as a background colour.
295 There exist applications that expect both kinds of behaviour.
296 Therefore, PuTTY can be configured to do either.
298 With this option disabled, screen clearing is always done in the
299 default background colour. With this option enabled, it is done in
300 the \e{current} background colour.
302 Background-colour erase can be turned on and off by control
303 sequences sent by the server. This configuration option controls the
304 \e{default} state, which will be restored when you reset the
305 terminal (see \k{reset-terminal}). However, if you modify this
306 option in mid-session using \q{Change Settings}, it will take effect
309 \S{config-blink} \q{Enable blinking text}
311 \cfg{winhelp-topic}{terminal.blink}
313 The server can ask PuTTY to display text that blinks on and off.
314 This is very distracting, so PuTTY allows you to turn blinking text
317 When blinking text is disabled and the server attempts to make some
318 text blink, PuTTY will instead display the text with a bolded
321 Blinking text can be turned on and off by control sequences sent by
322 the server. This configuration option controls the \e{default}
323 state, which will be restored when you reset the terminal (see
324 \k{reset-terminal}). However, if you modify this option in
325 mid-session using \q{Change Settings}, it will take effect
328 \S{config-answerback} \q{Answerback to ^E}
330 \cfg{winhelp-topic}{terminal.answerback}
332 This option controls what PuTTY will send back to the server if the
333 server sends it the ^E enquiry character. Normally it just sends
334 the string \q{PuTTY}.
336 If you accidentally write the contents of a binary file to your
337 terminal, you will probably find that it contains more than one ^E
338 character, and as a result your next command line will probably read
339 \q{PuTTYPuTTYPuTTY...} as if you had typed the answerback string
340 multiple times at the keyboard. If you set the answerback string to
341 be empty, this problem should go away, but doing so might cause
344 Note that this is \e{not} the feature of PuTTY which the server will
345 typically use to determine your terminal type. That feature is the
346 \q{Terminal-type string} in the Connection panel; see
347 \k{config-termtype} for details.
349 You can include control characters in the answerback string using
350 \c{^C} notation. (Use \c{^~} to get a literal \c{^}.)
352 \S{config-localecho} \q{Local echo}
354 \cfg{winhelp-topic}{terminal.localecho}
356 With local echo disabled, characters you type into the PuTTY window
357 are not echoed in the window \e{by PuTTY}. They are simply sent to
358 the server. (The \e{server} might choose to echo them back to you;
359 this can't be controlled from the PuTTY control panel.)
361 Some types of session need local echo, and many do not. In its
362 default mode, PuTTY will automatically attempt to deduce whether or
363 not local echo is appropriate for the session you are working in. If
364 you find it has made the wrong decision, you can use this
365 configuration option to override its choice: you can force local
366 echo to be turned on, or force it to be turned off, instead of
367 relying on the automatic detection.
369 \S{config-localedit} \q{Local line editing}
371 \cfg{winhelp-topic}{terminal.localedit}
373 Normally, every character you type into the PuTTY window is sent
374 immediately to the server the moment you type it.
376 If you enable local line editing, this changes. PuTTY will let you
377 edit a whole line at a time locally, and the line will only be sent
378 to the server when you press Return. If you make a mistake, you can
379 use the Backspace key to correct it before you press Return, and the
380 server will never see the mistake.
382 Since it is hard to edit a line locally without being able to see
383 it, local line editing is mostly used in conjunction with local echo
384 (\k{config-localecho}). This makes it ideal for use in raw mode
385 \#{FIXME} or when connecting to MUDs or talkers. (Although some more
386 advanced MUDs do occasionally turn local line editing on and turn
387 local echo off, in order to accept a password from the user.)
389 Some types of session need local line editing, and many do not. In
390 its default mode, PuTTY will automatically attempt to deduce whether
391 or not local line editing is appropriate for the session you are
392 working in. If you find it has made the wrong decision, you can use
393 this configuration option to override its choice: you can force
394 local line editing to be turned on, or force it to be turned off,
395 instead of relying on the automatic detection.
397 \S{config-printing} Remote-controlled printing
399 \cfg{winhelp-topic}{terminal.printing}
401 A lot of VT100-compatible terminals support printing under control
402 of the remote server. PuTTY supports this feature as well, but it is
403 turned off by default.
405 To enable remote-controlled printing, choose a printer from the
406 \q{Printer to send ANSI printer output to} drop-down list box. This
407 should allow you to select from all the printers you have installed
408 drivers for on your computer. Alternatively, you can type the
409 network name of a networked printer (for example,
410 \c{\\\\printserver\\printer1}) even if you haven't already
411 installed a driver for it on your own machine.
413 When the remote server attempts to print some data, PuTTY will send
414 that data to the printer \e{raw} - without translating it,
415 attempting to format it, or doing anything else to it. It is up to
416 you to ensure your remote server knows what type of printer it is
419 Since PuTTY sends data to the printer raw, it cannot offer options
420 such as portrait versus landscape, print quality, or paper tray
421 selection. All these things would be done by your PC printer driver
422 (which PuTTY bypasses); if you need them done, you will have to find
423 a way to configure your remote server to do them.
425 To disable remote printing again, choose \q{None (printing
426 disabled)} from the printer selection list. This is the default
429 \H{config-keyboard} The Keyboard panel
431 The Keyboard configuration panel allows you to control the behaviour
432 of the keyboard in PuTTY.
434 \S{config-backspace} Changing the action of the Backspace key
436 \cfg{winhelp-topic}{keyboard.backspace}
438 Some terminals believe that the Backspace key should send the same
439 thing to the server as Control-H (ASCII code 8). Other terminals
440 believe that the Backspace key should send ASCII code 127 (usually
441 known as Control-?) so that it can be distinguished from Control-H.
442 This option allows you to choose which code PuTTY generates when you
445 If you are connecting to a Unix system, you will probably find that
446 the Unix \c{stty} command lets you configure which the server
447 expects to see, so you might not need to change which one PuTTY
448 generates. On other systems, the server's expectation might be fixed
449 and you might have no choice but to configure PuTTY.
451 If you do have the choice, we recommend configuring PuTTY to
452 generate Control-? and configuring the server to expect it, because
453 that allows applications such as \c{emacs} to use Control-H for
456 \S{config-homeend} Changing the action of the Home and End keys
458 \cfg{winhelp-topic}{keyboard.homeend}
460 The Unix terminal emulator \c{rxvt} disagrees with the rest of the
461 world about what character sequences should be sent to the server by
462 the Home and End keys.
464 \c{xterm}, and other terminals, send \c{ESC [1~} for the Home key,
465 and \c{ESC [4~} for the End key. \c{rxvt} sends \c{ESC [H} for the
466 Home key and \c{ESC [Ow} for the End key.
468 If you find an application on which the Home and End keys aren't
469 working, you could try switching this option to see if it helps.
471 \S{config-funkeys} Changing the action of the function keys and keypad
473 \cfg{winhelp-topic}{keyboard.funkeys}
475 This option affects the function keys (F1 to F12) and the top row of
478 \b In the default mode, labelled \c{ESC [n~}, the function keys
479 generate sequences like \c{ESC [11~}, \c{ESC [12~} and so on. This
480 matches the general behaviour of Digital's terminals.
482 \b In Linux mode, F6 to F12 behave just like the default mode, but
483 F1 to F5 generate \c{ESC [[A} through to \c{ESC [[E}. This mimics the
484 Linux virtual console.
486 \b In Xterm R6 mode, F5 to F12 behave like the default mode, but F1
487 to F4 generate \c{ESC OP} through to \c{ESC OS}, which are the
488 sequences produced by the top row of the \e{keypad} on Digital's
491 \b In VT400 mode, all the function keys behave like the default
492 mode, but the actual top row of the numeric keypad generates \c{ESC
493 OP} through to \c{ESC OS}.
495 \b In VT100+ mode, the function keys generate \c{ESC OP} through to
498 \b In SCO mode, the function keys F1 to F12 generate \c{ESC [M}
499 through to \c{ESC [X}. Together with shift, they generate \c{ESC [Y}
500 through to \c{ESC [j}. With control they generate \c{ESC [k} through
501 to \c{ESC [v}, and with shift and control together they generate
502 \c{ESC [w} through to \c{ESC [\{}.
504 If you don't know what any of this means, you probably don't need to
507 \S{config-appcursor} Controlling Application Cursor Keys mode
509 \cfg{winhelp-topic}{keyboard.appcursor}
511 Application Cursor Keys mode is a way for the server to change the
512 control sequences sent by the arrow keys. In normal mode, the arrow
513 keys send \c{ESC [A} through to \c{ESC [D}. In application mode,
514 they send \c{ESC OA} through to \c{ESC OD}.
516 Application Cursor Keys mode can be turned on and off by the server,
517 depending on the application. PuTTY allows you to configure the
520 You can also disable application cursor keys mode completely, using
521 the \q{Features} configuration panel; see
522 \k{config-features-application}.
524 \S{config-appkeypad} Controlling Application Keypad mode
526 \cfg{winhelp-topic}{keyboard.appkeypad}
528 Application Keypad mode is a way for the server to change the
529 behaviour of the numeric keypad.
531 In normal mode, the keypad behaves like a normal Windows keypad:
532 with NumLock on, the number keys generate numbers, and with NumLock
533 off they act like the arrow keys and Home, End etc.
535 In application mode, all the keypad keys send special control
536 sequences, \e{including} Num Lock. Num Lock stops behaving like Num
537 Lock and becomes another function key.
539 Depending on which version of Windows you run, you may find the Num
540 Lock light still flashes on and off every time you press Num Lock,
541 even when application mode is active and Num Lock is acting like a
542 function key. This is unavoidable.
544 Application keypad mode can be turned on and off by the server,
545 depending on the application. PuTTY allows you to configure the
548 You can also disable application keypad mode completely, using the
549 \q{Features} configuration panel; see
550 \k{config-features-application}.
552 \S{config-nethack} Using NetHack keypad mode
554 \cfg{winhelp-topic}{keyboard.nethack}
556 PuTTY has a special mode for playing NetHack. You can enable it by
557 selecting \q{NetHack} in the \q{Initial state of numeric keypad}
560 In this mode, the numeric keypad keys 1-9 generate the NetHack
561 movement commands (\cw{hjklyubn}). The 5 key generates the \c{.}
562 command (do nothing).
564 Better still, pressing Shift with the keypad keys generates the
565 capital forms of the commands (\cw{HJKLYUBN}), which tells NetHack
566 to keep moving you in the same direction until you encounter
567 something interesting.
569 For some reason, this feature only works properly when Num Lock is
570 on. We don't know why.
572 \S{config-compose} Enabling a DEC-like Compose key
574 \cfg{winhelp-topic}{keyboard.compose}
576 DEC terminals have a Compose key, which provides an easy-to-remember
577 way of typing accented characters. You press Compose and then type
578 two more characters. The two characters are \q{combined} to produce
579 an accented character. The choices of character are designed to be
580 easy to remember; for example, composing \q{e} and \q{`} produces
581 the \q{\u00e8{e-grave}} character.
583 If your keyboard has a Windows Application key, it acts as a Compose
584 key in PuTTY. Alternatively, if you enable the \q{AltGr acts as
585 Compose key} option, the AltGr key will become a Compose key.
587 \S{config-ctrlalt} \q{Control-Alt is different from AltGr}
589 \cfg{winhelp-topic}{keyboard.ctrlalt}
591 Some old keyboards do not have an AltGr key, which can make it
592 difficult to type some characters. PuTTY can be configured to treat
593 the key combination Ctrl + Left Alt the same way as the AltGr key.
595 By default, this checkbox is checked, and the key combination Ctrl +
596 Left Alt does something completely different. PuTTY's usual handling
597 of the left Alt key is to prefix the Escape (Control-\cw{[})
598 character to whatever character sequence the rest of the keypress
599 would generate. For example, Alt-A generates Escape followed by
600 \c{a}. So Alt-Ctrl-A would generate Escape, followed by Control-A.
602 If you uncheck this box, Ctrl-Alt will become a synonym for AltGr,
603 so you can use it to type extra graphic characters if your keyboard
606 (However, Ctrl-Alt will never act as a Compose key, regardless of the
607 setting of \q{AltGr acts as Compose key} described in
610 \H{config-bell} The Bell panel
612 The Bell panel controls the terminal bell feature: the server's
613 ability to cause PuTTY to beep at you.
615 In the default configuration, when the server sends the character
616 with ASCII code 7 (Control-G), PuTTY will play the Windows Default
617 Beep sound. This is not always what you want the terminal bell
618 feature to do; the Bell panel allows you to configure alternative
621 \S{config-bellstyle} \q{Set the style of bell}
623 \cfg{winhelp-topic}{bell.style}
625 This control allows you to select various different actions to occur
628 \b Selecting \q{None} disables the bell completely. In this mode,
629 the server can send as many Control-G characters as it likes and
630 nothing at all will happen.
632 \b \q{Make default system alert sound} is the default setting. It
633 causes the Windows \q{Default Beep} sound to be played. To change
634 what this sound is, or to test it if nothing seems to be happening,
635 use the Sound configurer in the Windows Control Panel.
637 \b \q{Visual bell} is a silent alternative to a beeping computer. In
638 this mode, when the server sends a Control-G, the whole PuTTY window
639 will flash white for a fraction of a second.
641 \b \q{Beep using the PC speaker} is self-explanatory.
643 \b \q{Play a custom sound file} allows you to specify a particular
644 sound file to be used by PuTTY alone, or even by a particular
645 individual PuTTY session. This allows you to distinguish your PuTTY
646 beeps from any other beeps on the system. If you select this option,
647 you will also need to enter the name of your sound file in the edit
648 control \q{Custom sound file to play as a bell}.
650 \S{config-belltaskbar} \q{Taskbar/caption indication on bell}
652 \cfg{winhelp-topic}{bell.taskbar}
654 This feature controls what happens to the PuTTY window's entry in
655 the Windows Taskbar if a bell occurs while the window does not have
658 In the default state (\q{Disabled}) nothing unusual happens.
660 If you select \q{Steady}, then when a bell occurs and the window is
661 not in focus, the window's Taskbar entry and its title bar will
662 change colour to let you know that PuTTY session is asking for your
663 attention. The change of colour will persist until you select the
664 window, so you can leave several PuTTY windows minimised in your
665 terminal, go away from your keyboard, and be sure not to have missed
666 any important beeps when you get back.
668 \q{Flashing} is even more eye-catching: the Taskbar entry will
669 continuously flash on and off until you select the window.
671 \S{config-bellovl} \q{Control the bell overload behaviour}
673 \cfg{winhelp-topic}{bell.overload}
675 A common user error in a terminal session is to accidentally run the
676 Unix command \c{cat} (or equivalent) on an inappropriate file type,
677 such as an executable, image file, or ZIP file. This produces a huge
678 stream of non-text characters sent to the terminal, which typically
679 includes a lot of bell characters. As a result of this the terminal
680 often doesn't stop beeping for ten minutes, and everybody else in
681 the office gets annoyed.
683 To try to avoid this behaviour, or any other cause of excessive
684 beeping, PuTTY includes a bell overload management feature. In the
685 default configuration, receiving more than five bell characters in a
686 two-second period will cause the overload feature to activate. Once
687 the overload feature is active, further bells will have no effect at
688 all, so the rest of your binary file will be sent to the screen in
689 silence. After a period of five seconds during which no further
690 bells are received, the overload feature will turn itself off again
691 and bells will be re-enabled.
693 If you want this feature completely disabled, you can turn it off
694 using the checkbox \q{Bell is temporarily disabled when over-used}.
696 Alternatively, if you like the bell overload feature but don't agree
697 with the settings, you can configure the details: how many bells
698 constitute an overload, how short a time period they have to arrive
699 in to do so, and how much silent time is required before the
700 overload feature will deactivate itself.
702 Bell overload mode is always deactivated by any keypress in the
703 terminal. This means it can respond to large unexpected streams of
704 data, but does not interfere with ordinary command-line activities
705 that generate beeps (such as filename completion).
707 \H{config-features} The Features panel
709 PuTTY's terminal emulation is very highly featured, and can do a lot
710 of things under remote server control. Some of these features can
711 cause problems due to buggy or strangely configured server
714 The Features configuration panel allows you to disable some of
715 PuTTY's more advanced terminal features, in case they cause trouble.
717 \S{config-features-application} Disabling application keypad and cursor keys
719 \cfg{winhelp-topic}{features.application}
721 Application keypad mode (see \k{config-appkeypad}) and application
722 cursor keys mode (see \k{config-appcursor}) alter the behaviour of
723 the keypad and cursor keys. Some applications enable these modes but
724 then do not deal correctly with the modified keys. You can force
725 these modes to be permanently disabled no matter what the server
728 \S{config-features-mouse} Disabling \cw{xterm}-style mouse reporting
730 \cfg{winhelp-topic}{features.mouse}
732 PuTTY allows the server to send control codes that let it take over
733 the mouse and use it for purposes other than copy and paste.
734 Applications which use this feature include the text-mode web
735 browser \c{links}, the Usenet newsreader \c{trn} version 4, and the
736 file manager \c{mc} (Midnight Commander).
738 If you find this feature inconvenient, you can disable it using the
739 \q{Disable xterm-style mouse reporting} control. With this box
740 ticked, the mouse will \e{always} do copy and paste in the normal
743 Note that even if the application takes over the mouse, you can
744 still manage PuTTY's copy and paste by holding down the Shift key
745 while you select and paste, unless you have deliberately turned this
746 feature off (see \k{config-mouseshift}).
748 \S{config-features-resize} Disabling remote terminal resizing
750 \cfg{winhelp-topic}{features.resize}
752 PuTTY has the ability to change the terminal's size and position in
753 response to commands from the server. If you find PuTTY is doing
754 this unexpectedly or inconveniently, you can tell PuTTY not to
755 respond to those server commands.
757 \S{config-features-altscreen} Disabling switching to the alternate screen
759 \cfg{winhelp-topic}{features.altscreen}
761 Many terminals, including PuTTY, support an \q{alternate screen}.
762 This is the same size as the ordinary terminal screen, but separate.
763 Typically a screen-based program such as a text editor might switch
764 the terminal to the alternate screen before starting up. Then at the
765 end of the run, it switches back to the primary screen, and you see
766 the screen contents just as they were before starting the editor.
768 Some people prefer this not to happen. If you want your editor to
769 run in the same screen as the rest of your terminal activity, you
770 can disable the alternate screen feature completely.
772 \S{config-features-retitle} Disabling remote window title changing
774 \cfg{winhelp-topic}{features.retitle}
776 PuTTY has the ability to change the window title in response to
777 commands from the server. If you find PuTTY is doing this
778 unexpectedly or inconveniently, you can tell PuTTY not to respond to
779 those server commands.
781 \S{config-features-qtitle} Disabling remote window title querying
783 \cfg{winhelp-topic}{features.qtitle}
785 PuTTY can optionally provide the xterm service of allowing server
786 applications to find out the local window title. This feature is
787 disabled by default, but you can turn it on if you really want it.
789 NOTE that this feature is a \e{potential security hazard}. If a
790 malicious application can write data to your terminal (for example,
791 if you merely \c{cat} a file owned by someone else on the server
792 machine), it can change your window title (unless you have disabled
793 this as mentioned in \k{config-features-retitle}) and then use this
794 service to have the new window title sent back to the server as if
795 typed at the keyboard. This allows an attacker to fake keypresses
796 and potentially cause your server-side applications to do things you
797 didn't want. Therefore this feature is disabled by default, and we
798 recommend you do not turn it on unless you \e{really} know what you
801 \S{config-features-dbackspace} Disabling destructive backspace
803 \cfg{winhelp-topic}{features.dbackspace}
805 Normally, when PuTTY receives character 127 (^?) from the server, it
806 will perform a \q{destructive backspace}: move the cursor one space
807 left and delete the character under it. This can apparently cause
808 problems in some applications, so PuTTY provides the ability to
809 configure character 127 to perform a normal backspace (without
810 deleting a character) instead.
812 \S{config-features-charset} Disabling remote character set
815 \cfg{winhelp-topic}{features.charset}
817 PuTTY has the ability to change its character set configuration in
818 response to commands from the server. Some programs send these
819 commands unexpectedly or inconveniently. In particular, BitchX (an
820 IRC client) seems to have a habit of reconfiguring the character set
821 to something other than the user intended.
823 If you find that accented characters are not showing up the way you
824 expect them to, particularly if you're running BitchX, you could try
825 disabling the remote character set configuration commands.
827 \H{config-window} The Window panel
829 The Window configuration panel allows you to control aspects of the
832 \S{config-winsize} Setting the size of the PuTTY window
834 \cfg{winhelp-topic}{window.size}
836 The \q{Rows} and \q{Columns} boxes let you set the PuTTY window to a
837 precise size. Of course you can also drag the window to a new size
838 while a session is running.
840 \S{config-winsizelock} What to do when the window is resized
842 \cfg{winhelp-topic}{window.resize}
844 These options allow you to control what happens when the user tries
845 to resize the PuTTY window.
847 When you resize the PuTTY window, one of four things can happen:
849 \b Nothing (if you have completely disabled resizes).
851 \b The font size can stay the same and the number of rows and
852 columns in the terminal can change.
854 \b The number of rows and columns in the terminal can stay the same,
855 and the font size can change.
857 \b You can allow PuTTY to change \e{either} the terminal size or the
858 font size. In this mode it will change the terminal size most of the
859 time, but enlarge the font when you maximise the window.
861 You can control which of these happens using the \q{Lock terminal
862 size against resizing} and \q{Lock font size against resizing}
863 options. If you lock both, the window will refuse to be resized at
864 all. If you lock just the terminal size, the font size will change
865 when you resize the window. If you lock just the font size, the
866 terminal size will change when you resize the window.
868 \S{config-scrollback} Controlling scrollback
870 \cfg{winhelp-topic}{window.scrollback}
872 These options let you configure the way PuTTY keeps text after it
873 scrolls off the top of the screen (see \k{using-scrollback}).
875 The \q{Lines of scrollback} box lets you configure how many lines of
876 text PuTTY keeps. The \q{Display scrollbar} options allow you to
877 hide the scrollbar (although you can still view the scrollback using
878 the keyboard as described in \k{using-scrollback}). You can separately
879 configure whether the scrollbar is shown in full-screen mode and in
882 If you are viewing part of the scrollback when the server sends more
883 text to PuTTY, the screen will revert to showing the current
884 terminal contents. You can disable this behaviour by turning off
885 \q{Reset scrollback on display activity}. You can also make the
886 screen revert when you press a key, by turning on \q{Reset
887 scrollback on keypress}.
889 \S{config-erasetoscrollback} \q{Push erased text into scrollback}
891 \cfg{winhelp-topic}{window.erased}
893 When this option is enabled, the contents of the terminal screen
894 will be pushed into the scrollback when a server-side application
895 clears the screen, so that your scrollback will contain a better
896 record of what was on your screen in the past.
898 If the application switches to the alternate screen (see
899 \k{config-features-altscreen} for more about this), then the
900 contents of the primary screen will be visible in the scrollback
901 until the application switches back again.
903 This option is enabled by default.
905 \H{config-appearance} The Appearance panel
907 The Appearance configuration panel allows you to control aspects of
908 the appearance of PuTTY's window.
910 \S{config-cursor} Controlling the appearance of the cursor
912 \cfg{winhelp-topic}{appearance.cursor}
914 The \q{Cursor appearance} option lets you configure the cursor to be
915 a block, an underline, or a vertical line. A block cursor becomes an
916 empty box when the window loses focus; an underline or a vertical
919 The \q{Cursor blinks} option makes the cursor blink on and off. This
920 works in any of the cursor modes.
922 \S{config-font} Controlling the font used in the terminal window
924 \cfg{winhelp-topic}{appearance.font}
926 This option allows you to choose what font, in what size, the PuTTY
927 terminal window uses to display the text in the session. You will be
928 offered a choice from all the fixed-width fonts installed on the
929 system. (VT100-style terminal handling can only deal with fixed-
932 \S{config-mouseptr} \q{Hide mouse pointer when typing in window}
934 \cfg{winhelp-topic}{appearance.hidemouse}
936 If you enable this option, the mouse pointer will disappear if the
937 PuTTY window is selected and you press a key. This way, it will not
938 obscure any of the text in the window while you work in your
939 session. As soon as you move the mouse, the pointer will reappear.
941 This option is disabled by default, so the mouse pointer remains
942 visible at all times.
944 \S{config-winborder} Controlling the window border
946 \cfg{winhelp-topic}{appearance.border}
948 PuTTY allows you to configure the appearance of the window border to
951 The checkbox marked \q{Sunken-edge border} changes the appearance of
952 the window border to something more like a DOS box: the inside edge
953 of the border is highlighted as if it sank down to meet the surface
954 inside the window. This makes the border a little bit thicker as
955 well. It's hard to describe well. Try it and see if you like it.
957 You can also configure a completely blank gap between the text in
958 the window and the border, using the \q{Gap between text and window
959 edge} control. By default this is set at one pixel. You can reduce
960 it to zero, or increase it further.
962 \H{config-behaviour} The Behaviour panel
964 The Behaviour configuration panel allows you to control aspects of
965 the behaviour of PuTTY's window.
967 \S{config-title} Controlling the window title
969 \cfg{winhelp-topic}{appearance.title}
971 The \q{Window title} edit box allows you to set the title of the
972 PuTTY window. By default the window title will contain the host name
973 followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
974 If you want a different window title, this is where to set it.
976 PuTTY allows the server to send \c{xterm} control sequences which
977 modify the title of the window in mid-session (unless this is disabled -
978 see \k{config-features-retitle}); the title string set here
979 is therefore only the \e{initial} window title.
981 As well as the \e{window} title, there is also an
982 \c{xterm} sequence to modify the title of the window's \e{icon}.
983 This makes sense in a windowing system where the window becomes an
984 icon when minimised, such as Windows 3.1 or most X Window System
985 setups; but in the Windows 95-like user interface it isn't as
988 By default, PuTTY only uses the server-supplied \e{window} title, and
989 ignores the icon title entirely. If for some reason you want to see
990 both titles, check the box marked \q{Separate window and icon titles}.
991 If you do this, PuTTY's window title and Taskbar caption will
992 change into the server-supplied icon title if you minimise the PuTTY
993 window, and change back to the server-supplied window title if you
994 restore it. (If the server has not bothered to supply a window or
995 icon title, none of this will happen.)
997 \S{config-warnonclose} \q{Warn before closing window}
999 \cfg{winhelp-topic}{behaviour.closewarn}
1001 If you press the Close button in a PuTTY window that contains a
1002 running session, PuTTY will put up a warning window asking if you
1003 really meant to close the window. A window whose session has already
1004 terminated can always be closed without a warning.
1006 If you want to be able to close a window quickly, you can disable
1007 the \q{Warn before closing window} option.
1009 \S{config-altf4} \q{Window closes on ALT-F4}
1011 \cfg{winhelp-topic}{behaviour.altf4}
1013 By default, pressing ALT-F4 causes the window to close (or a warning
1014 box to appear; see \k{config-warnonclose}). If you disable the
1015 \q{Window closes on ALT-F4} option, then pressing ALT-F4 will simply
1016 send a key sequence to the server.
1018 \S{config-altspace} \q{System menu appears on ALT-Space}
1020 \cfg{winhelp-topic}{behaviour.altspace}
1022 If this option is enabled, then pressing ALT-Space will bring up the
1023 PuTTY window's menu, like clicking on the top left corner. If it is
1024 disabled, then pressing ALT-Space will just send \c{ESC SPACE} to
1027 Some accessibility programs for Windows may need this option
1028 enabling to be able to control PuTTY's window successfully. For
1029 instance, Dragon NaturallySpeaking requires it both to open the
1030 system menu via voice, and to close, minimise, maximise and restore
1033 \S{config-altonly} \q{System menu appears on Alt alone}
1035 \cfg{winhelp-topic}{behaviour.altonly}
1037 If this option is enabled, then pressing and releasing ALT will
1038 bring up the PuTTY window's menu, like clicking on the top left
1039 corner. If it is disabled, then pressing and releasing ALT will have
1042 \S{config-alwaysontop} \q{Ensure window is always on top}
1044 \cfg{winhelp-topic}{behaviour.alwaysontop}
1046 If this option is enabled, the PuTTY window will stay on top of all
1049 \S{config-fullscreen} \q{Full screen on Alt-Enter}
1051 \cfg{winhelp-topic}{behaviour.altenter}
1053 If this option is enabled, then pressing Alt-Enter will cause the
1054 PuTTY window to become full-screen. Pressing Alt-Enter again will
1055 restore the previous window size.
1057 The full-screen feature is also available from the System menu, even
1058 when it is configured not to be available on the Alt-Enter key. See
1059 \k{using-fullscreen}.
1061 \H{config-translation} The Translation panel
1063 The Translation configuration panel allows you to control the
1064 translation between the character set understood by the server and
1065 the character set understood by PuTTY.
1067 \S{config-charset} Controlling character set translation
1069 \cfg{winhelp-topic}{translation.codepage}
1071 During an interactive session, PuTTY receives a stream of 8-bit
1072 bytes from the server, and in order to display them on the screen it
1073 needs to know what character set to interpret them in.
1075 There are a lot of character sets to choose from. The \q{Received
1076 data assumed to be in which character set} option lets you select
1077 one. By default PuTTY will attempt to choose a character set that is
1078 right for your locale as reported by Windows; if it gets it wrong,
1079 you can select a different one using this control.
1081 A few notable character sets are:
1083 \b The ISO-8859 series are all standard character sets that include
1084 various accented characters appropriate for different sets of
1087 \b The Win125x series are defined by Microsoft, for similar
1088 purposes. In particular Win1252 is almost equivalent to ISO-8859-1,
1089 but contains a few extra characters such as matched quotes and the
1092 \b If you want the old IBM PC character set with block graphics and
1093 line-drawing characters, you can select \q{CP437}.
1095 \b PuTTY also supports Unicode mode, in which the data coming from
1096 the server is interpreted as being in the UTF-8 encoding of Unicode.
1097 If you select \q{UTF-8} as a character set you can use this mode.
1098 Not all server-side applications will support it.
1100 If you need support for a numeric code page which is not listed in
1101 the drop-down list, such as code page 866, then you can try entering
1102 its name manually (\c{CP866} for example) in the list box. If the
1103 underlying version of Windows has the appropriate translation table
1104 installed, PuTTY will use it.
1106 \S{config-cyr} \q{Caps Lock acts as Cyrillic switch}
1108 \cfg{winhelp-topic}{translation.cyrillic}
1110 This feature allows you to switch between a US/UK keyboard layout
1111 and a Cyrillic keyboard layout by using the Caps Lock key, if you
1112 need to type (for example) Russian and English side by side in the
1115 Currently this feature is not expected to work properly if your
1116 native keyboard layout is not US or UK.
1118 \S{config-linedraw} Controlling display of line drawing characters
1120 \cfg{winhelp-topic}{translation.linedraw}
1122 VT100-series terminals allow the server to send control sequences
1123 that shift temporarily into a separate character set for drawing
1124 lines and boxes. PuTTY has a variety of ways to support this
1125 capability. In general you should probably try lots of options until
1126 you find one that your particular font supports.
1128 \b \q{Font has XWindows encoding} is for use with fonts that have a
1129 special encoding, where the lowest 32 character positions (below the
1130 ASCII printable range) contain the line-drawing characters. This is
1131 unlikely to be the case with any standard Windows font; it will
1132 probably only apply to custom-built fonts or fonts that have been
1133 automatically converted from the X Window System.
1135 \b \q{Use font in both ANSI and OEM modes} tries to use the same
1136 font in two different character sets, to obtain a wider range of
1137 characters. This doesn't always work; some fonts claim to be a
1138 different size depending on which character set you try to use.
1140 \b \q{Use font in OEM mode only} is more reliable than that, but can
1141 miss out other characters from the main character set.
1143 \b \q{Poor man's line drawing} assumes that the font \e{cannot}
1144 generate the line and box characters at all, so it will use the
1145 \c{+}, \c{-} and \c{|} characters to draw approximations to boxes.
1146 You should use this option if none of the other options works.
1148 \b \q{Unicode mode} tries to use the box characters that are present
1149 in Unicode. For good Unicode-supporting fonts this is probably the
1150 most reliable and functional option.
1152 \S{config-linedrawpaste} Controlling copy and paste of line drawing
1155 \cfg{winhelp-topic}{selection.linedraw}
1157 By default, when you copy and paste a piece of the PuTTY screen that
1158 contains VT100 line and box drawing characters, PuTTY will paste
1159 them in the form they appear on the screen: either Unicode line
1160 drawing code points, or the \q{poor man's} line-drawing characters
1161 \c{+}, \c{-} and \c{|}. The checkbox \q{Copy and paste VT100 line
1162 drawing chars as lqqqk} disables this feature, so line-drawing
1163 characters will be pasted as the ASCII characters that were printed
1164 to produce them. This will typically mean they come out mostly as
1165 \c{q} and \c{x}, with a scattering of \c{jklmntuvw} at the corners.
1166 This might be useful if you were trying to recreate the same box
1167 layout in another program, for example.
1169 Note that this option only applies to line-drawing characters which
1170 \e{were} printed by using the VT100 mechanism. Line-drawing
1171 characters displayed using Unicode will paste as Unicode always.
1173 \H{config-selection} The Selection panel
1175 The Selection panel allows you to control the way copy and paste
1176 work in the PuTTY window.
1178 \S{config-rtfpaste} Pasting in Rich Text Format
1180 \cfg{winhelp-topic}{selection.rtf}
1182 If you enable \q{Paste to clipboard in RTF as well as plain text},
1183 PuTTY will write formatting information to the clipboard as well as
1184 the actual text you copy. Currently the only effect of this will be
1185 that if you paste into (say) a word processor, the text will appear
1186 in the word processor in the same font PuTTY was using to display
1187 it. In future it is likely that other formatting information (bold,
1188 underline, colours) will be copied as well.
1190 This option can easily be inconvenient, so by default it is
1193 \S{config-mouse} Changing the actions of the mouse buttons
1195 \cfg{winhelp-topic}{selection.buttons}
1197 PuTTY's copy and paste mechanism is by default modelled on the Unix
1198 \c{xterm} application. The X Window System uses a three-button mouse,
1199 and the convention is that the left button selects, the right button
1200 extends an existing selection, and the middle button pastes.
1202 Windows often only has two mouse buttons, so in PuTTY's default
1203 configuration (\q{Compromise}), the \e{right} button pastes, and the
1204 \e{middle} button (if you have one) extends a selection.
1206 If you have a three-button mouse and you are already used to the
1207 \c{xterm} arrangement, you can select it using the \q{Action of
1208 mouse buttons} control.
1210 Alternatively, with the \q{Windows} option selected, the middle
1211 button extends, and the right button brings up a context menu (on
1212 which one of the options is \q{Paste}). (This context menu is always
1213 available by holding down Ctrl and right-clicking, regardless of the
1214 setting of this option.)
1216 \S{config-mouseshift} \q{Shift overrides application's use of mouse}
1218 \cfg{winhelp-topic}{selection.shiftdrag}
1220 PuTTY allows the server to send control codes that let it take over
1221 the mouse and use it for purposes other than copy and paste.
1222 Applications which use this feature include the text-mode web
1223 browser \c{links}, the Usenet newsreader \c{trn} version 4, and the
1224 file manager \c{mc} (Midnight Commander).
1226 When running one of these applications, pressing the mouse buttons
1227 no longer performs copy and paste. If you do need to copy and paste,
1228 you can still do so if you hold down Shift while you do your mouse
1231 However, it is possible in theory for applications to even detect
1232 and make use of Shift + mouse clicks. We don't know of any
1233 applications that do this, but in case someone ever writes one,
1234 unchecking the \q{Shift overrides application's use of mouse}
1235 checkbox will cause Shift + mouse clicks to go to the server as well
1236 (so that mouse-driven copy and paste will be completely disabled).
1238 If you want to prevent the application from taking over the mouse at
1239 all, you can do this using the Features control panel; see
1240 \k{config-features-mouse}.
1242 \S{config-rectselect} Default selection mode
1244 \cfg{winhelp-topic}{selection.rect}
1246 As described in \k{using-selection}, PuTTY has two modes of
1247 selecting text to be copied to the clipboard. In the default mode
1248 (\q{Normal}), dragging the mouse from point A to point B selects to
1249 the end of the line containing A, all the lines in between, and from
1250 the very beginning of the line containing B. In the other mode
1251 (\q{Rectangular block}), dragging the mouse between two points
1252 defines a rectangle, and everything within that rectangle is copied.
1254 Normally, you have to hold down Alt while dragging the mouse to
1255 select a rectangular block. Using the \q{Default selection mode}
1256 control, you can set rectangular selection as the default, and then
1257 you have to hold down Alt to get the \e{normal} behaviour.
1259 \S{config-charclasses} Configuring word-by-word selection
1261 \cfg{winhelp-topic}{selection.charclasses}
1263 PuTTY will select a word at a time in the terminal window if you
1264 double-click to begin the drag. This panel allows you to control
1265 precisely what is considered to be a word.
1267 Each character is given a \e{class}, which is a small number
1268 (typically 0, 1 or 2). PuTTY considers a single word to be any
1269 number of adjacent characters in the same class. So by modifying the
1270 assignment of characters to classes, you can modify the word-by-word
1271 selection behaviour.
1273 In the default configuration, the character classes are:
1275 \b Class 0 contains white space and control characters.
1277 \b Class 1 contains most punctuation.
1279 \b Class 2 contains letters, numbers and a few pieces of punctuation
1280 (the double quote, minus sign, period, forward slash and
1283 So, for example, if you assign the \c{@} symbol into character class
1284 2, you will be able to select an e-mail address with just a double
1287 In order to adjust these assignments, you start by selecting a group
1288 of characters in the list box. Then enter a class number in the edit
1289 box below, and press the \q{Set} button.
1291 This mechanism currently only covers ASCII characters, because it
1292 isn't feasible to expand the list to cover the whole of Unicode.
1294 Character class definitions can be modified by control sequences
1295 sent by the server. This configuration option controls the
1296 \e{default} state, which will be restored when you reset the
1297 terminal (see \k{reset-terminal}). However, if you modify this
1298 option in mid-session using \q{Change Settings}, it will take effect
1301 \H{config-colours} The Colours panel
1303 The Colours panel allows you to control PuTTY's use of colour.
1305 \S{config-boldcolour} \q{Bolded text is a different colour}
1307 \cfg{winhelp-topic}{colours.bold}
1309 When the server sends a control sequence indicating that some text
1310 should be displayed in bold, PuTTY can handle this two ways. It can
1311 either change the font for a bold version, or use the same font in a
1312 brighter colour. This control lets you choose which.
1314 By default the box is checked, so non-bold text is displayed in
1315 light grey and bold text is displayed in bright white (and similarly
1316 in other colours). If you uncheck the box, bold and non-bold text
1317 will be displayed in the same colour, and instead the font will
1318 change to indicate the difference.
1320 \S{config-logpalette} \q{Attempt to use logical palettes}
1322 \cfg{winhelp-topic}{colours.logpal}
1324 Logical palettes are a mechanism by which a Windows application
1325 running on an 8-bit colour display can select precisely the colours
1326 it wants instead of going with the Windows standard defaults.
1328 If you are not getting the colours you ask for on an 8-bit display,
1329 you can try enabling this option. However, be warned that it's never
1332 \S{config-syscolour} \q{Use system colours}
1334 \cfg{winhelp-topic}{colours.system}
1336 Enabling this option will cause PuTTY to ignore the configured colours
1337 for \q{Default Background/Foreground} and \q{Cursor Colour/Text} (see
1338 \k{config-colourcfg}), instead going with the system-wide defaults.
1340 Note that non-bold and bold text will be the same colour if this
1341 option is enabled. You might want to change to indicating bold text
1342 by font changes (see \k{config-boldcolour}).
1344 \S{config-colourcfg} Adjusting the colours in the terminal window
1346 \cfg{winhelp-topic}{colours.config}
1348 The main colour control allows you to specify exactly what colours
1349 things should be displayed in. To modify one of the PuTTY colours,
1350 use the list box to select which colour you want to modify. The RGB
1351 values for that colour will appear on the right-hand side of the
1352 list box. Now, if you press the \q{Modify} button, you will be
1353 presented with a colour selector, in which you can choose a new
1354 colour to go in place of the old one.
1356 PuTTY allows you to set the cursor colour, the default foreground
1357 and background, and the precise shades of all the ANSI configurable
1358 colours (black, red, green, yellow, blue, magenta, cyan, and white).
1359 You can also modify the precise shades used for the bold versions of
1360 these colours; these are used to display bold text if you have
1361 selected \q{Bolded text is a different colour}, and can also be used
1362 if the server asks specifically to use them.
1364 \H{config-connection} The Connection panel
1366 The Connection panel allows you to configure options that apply to
1367 more than one type of connection.
1369 \S{config-termtype} \q{Terminal-type string}
1371 \cfg{winhelp-topic}{connection.termtype}
1373 Most servers you might connect to with PuTTY are designed to be
1374 connected to from lots of different types of terminal. In order to
1375 send the right control sequences to each one, the server will need
1376 to know what type of terminal it is dealing with. Therefore, each of
1377 the SSH, Telnet and Rlogin protocols allow a text string to be sent
1378 down the connection describing the terminal.
1380 PuTTY attempts to emulate the Unix \c{xterm} program, and by default
1381 it reflects this by sending \c{xterm} as a terminal-type string. If
1382 you find this is not doing what you want - perhaps the remote
1383 terminal reports \q{Unknown terminal type} - you could try setting
1384 this to something different, such as \c{vt220}.
1386 If you're not sure whether a problem is due to the terminal type
1387 setting or not, you probably need to consult the manual for your
1388 application or your server.
1390 \S{config-termspeed} \q{Terminal speeds}
1392 \cfg{winhelp-topic}{connection.termspeed}
1394 The Telnet, Rlogin, and SSH protocols allow the client to specify
1395 terminal speeds to the server.
1397 This parameter does \e{not} affect the actual speed of the connection,
1398 which is always \q{as fast as possible}; it is just a hint that is
1399 sometimes used by server software to modify its behaviour. For
1400 instance, if a slow speed is indicated, the server may switch to a
1401 less bandwidth-hungry display mode.
1403 The value is usually meaningless in a network environment, but
1404 PuTTY lets you configure it, in case you find the server is reacting
1405 badly to the default value.
1407 The format is a pair of numbers separated by a comma, for instance,
1408 \c{38400,38400}. The first number represents the output speed
1409 (\e{from} the server) in bits per second, and the second is the input
1410 speed (\e{to} the server). (Only the first is used in the Rlogin
1413 This option has no effect on Raw connections.
1415 \S{config-username} \q{Auto-login username}
1417 \cfg{winhelp-topic}{connection.username}
1419 All three of the SSH, Telnet and Rlogin protocols allow you to
1420 specify what user name you want to log in as, without having to type
1421 it explicitly every time. (Some Telnet servers don't support this.)
1423 In this box you can type that user name.
1425 \S{config-keepalive} Using keepalives to prevent disconnection
1427 \cfg{winhelp-topic}{connection.keepalive}
1429 If you find your sessions are closing unexpectedly (\q{Connection
1430 reset by peer}) after they have been idle for a while, you might
1431 want to try using this option.
1433 Some network routers and firewalls need to keep track of all
1434 connections through them. Usually, these firewalls will assume a
1435 connection is dead if no data is transferred in either direction
1436 after a certain time interval. This can cause PuTTY sessions to be
1437 unexpectedly closed by the firewall if no traffic is seen in the
1438 session for some time.
1440 The keepalive option (\q{Seconds between keepalives}) allows you to
1441 configure PuTTY to send data through the session at regular
1442 intervals, in a way that does not disrupt the actual terminal
1443 session. If you find your firewall is cutting idle connections off,
1444 you can try entering a non-zero value in this field. The value is
1445 measured in seconds; so, for example, if your firewall cuts
1446 connections off after ten minutes then you might want to enter 300
1447 seconds (5 minutes) in the box.
1449 Note that keepalives are not always helpful. They help if you have a
1450 firewall which drops your connection after an idle period; but if
1451 the network between you and the server suffers from breaks in
1452 connectivity then keepalives can actually make things worse. If a
1453 session is idle, and connectivity is temporarily lost between the
1454 endpoints, but the connectivity is restored before either side tries
1455 to send anything, then there will be no problem - neither endpoint
1456 will notice that anything was wrong. However, if one side does send
1457 something during the break, it will repeatedly try to re-send, and
1458 eventually give up and abandon the connection. Then when
1459 connectivity is restored, the other side will find that the first
1460 side doesn't believe there is an open connection any more.
1461 Keepalives can make this sort of problem worse, because they
1462 increase the probability that PuTTY will attempt to send data during
1463 a break in connectivity. Therefore, you might find they help
1464 connection loss, or you might find they make it worse, depending on
1465 what \e{kind} of network problems you have between you and the
1468 Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
1469 protocols offer no way of implementing them. (For an alternative, see
1470 \k{config-tcp-keepalives}.)
1472 Note that if you are using SSH1 and the server has a bug that makes
1473 it unable to deal with SSH1 ignore messages (see
1474 \k{config-ssh-bug-ignore1}), enabling keepalives will have no effect.
1476 \S{config-nodelay} \q{Disable Nagle's algorithm}
1478 \cfg{winhelp-topic}{connection.nodelay}
1480 Nagle's algorithm is a detail of TCP/IP implementations that tries
1481 to minimise the number of small data packets sent down a network
1482 connection. With Nagle's algorithm enabled, PuTTY's bandwidth usage
1483 will be slightly more efficient; with it disabled, you may find you
1484 get a faster response to your keystrokes when connecting to some
1487 The Nagle algorithm is disabled by default.
1489 \S{config-tcp-keepalives} \q{Enable TCP keepalives}
1491 \cfg{winhelp-topic}{connection.tcpkeepalive}
1493 \e{NOTE:} TCP keepalives should not be confused with the
1494 application-level keepalives described in \k{config-keepalive}. If in
1495 doubt, you probably want application-level keepalives; TCP keepalives
1496 are provided for completeness.
1498 The idea of TCP keepalives is similar to application-level keepalives,
1499 and the same caveats apply. The main differences are:
1501 \b TCP keepalives are available on \e{all} connection types, including
1504 \b The interval between TCP keepalives is usually much longer,
1505 typically two hours; this is set by the operating system, and cannot
1506 be configured within PuTTY.
1508 \b If the operating system does not receive a response to a keepalive,
1509 it may send out more in quick succession and if terminate the connection
1510 if no response is received.
1512 TCP keepalives may be more useful for ensuring that half-open connections
1513 are terminated than for keeping a connection alive.
1515 TCP keepalives are disabled by default.
1517 \H{config-proxy} The Proxy panel
1519 \cfg{winhelp-topic}{proxy.main}
1521 The Proxy panel allows you to configure PuTTY to use various types
1522 of proxy in order to make its network connections. The settings in
1523 this panel affect the primary network connection forming your PuTTY
1524 session, but also any extra connections made as a result of SSH port
1525 forwarding (see \k{using-port-forwarding}).
1527 \S{config-proxy-type} Setting the proxy type
1529 \cfg{winhelp-topic}{proxy.type}
1531 The \q{Proxy type} radio buttons allow you to configure what type of
1532 proxy you want PuTTY to use for its network connections. The default
1533 setting is \q{None}; in this mode no proxy is used for any
1536 \b Selecting \q{HTTP} allows you to proxy your connections through a
1537 web server supporting the HTTP \cw{CONNECT} command, as documented
1538 in \W{http://www.ietf.org/rfc/rfc2817.txt}{RFC 2817}.
1540 \b Selecting \q{SOCKS 4} or \q{SOCKS 5} allows you to proxy your
1541 connections through a SOCKS server.
1543 \b Many firewalls implement a less formal type of proxy in which a
1544 user can make a Telnet connection directly to the firewall machine
1545 and enter a command such as \c{connect myhost.com 22} to connect
1546 through to an external host. Selecting \q{Telnet} allows you to tell
1547 PuTTY to use this type of proxy.
1549 \S{config-proxy-exclude} Excluding parts of the network from proxying
1551 \cfg{winhelp-topic}{proxy.exclude}
1553 Typically you will only need to use a proxy to connect to non-local
1554 parts of your network; for example, your proxy might be required for
1555 connections outside your company's internal network. In the
1556 \q{Exclude Hosts/IPs} box you can enter ranges of IP addresses, or
1557 ranges of DNS names, for which PuTTY will avoid using the proxy and
1558 make a direct connection instead.
1560 The \q{Exclude Hosts/IPs} box may contain more than one exclusion
1561 range, separated by commas. Each range can be an IP address or a DNS
1562 name, with a \c{*} character allowing wildcards. For example:
1566 This excludes any host with a name ending in \c{.example.com} from
1571 This excludes any host with an IP address starting with 192.168.88
1574 \c 192.168.88.*,*.example.com
1576 This excludes both of the above ranges at once.
1578 Connections to the local host (the host name \c{localhost}, and any
1579 loopback IP address) are never proxied, even if the proxy exclude
1580 list does not explicitly contain them. It is very unlikely that this
1581 behaviour would ever cause problems, but if it does you can change
1582 it by enabling \q{Consider proxying local host connections}.
1584 Note that if you are doing DNS at the proxy (see
1585 \k{config-proxy-dns}), you should make sure that your proxy
1586 exclusion settings do not depend on knowing the IP address of a
1587 host. If the name is passed on to the proxy without PuTTY looking it
1588 up, it will never know the IP address and cannot check it against
1591 \S{config-proxy-dns} Name resolution when using a proxy
1593 \cfg{winhelp-topic}{proxy.dns}
1595 If you are using a proxy to access a private network, it can make a
1596 difference whether DNS name resolution is performed by PuTTY itself
1597 (on the client machine) or performed by the proxy.
1599 The \q{Do DNS name lookup at proxy end} configuration option allows
1600 you to control this. If you set it to \q{No}, PuTTY will always do
1601 its own DNS, and will always pass an IP address to the proxy. If you
1602 set it to \q{Yes}, PuTTY will always pass host names straight to the
1603 proxy without trying to look them up first.
1605 If you set this option to \q{Auto} (the default), PuTTY will do
1606 something it considers appropriate for each type of proxy. Telnet
1607 and HTTP proxies will have host names passed straight to them; SOCKS
1610 Note that if you are doing DNS at the proxy, you should make sure
1611 that your proxy exclusion settings (see \k{config-proxy-exclude}) do
1612 not depend on knowing the IP address of a host. If the name is
1613 passed on to the proxy without PuTTY looking it up, it will never
1614 know the IP address and cannot check it against your list.
1616 The original SOCKS 4 protocol does not support proxy-side DNS. There
1617 is a protocol extension (SOCKS 4A) which does support it, but not
1618 all SOCKS 4 servers provide this extension. If you enable proxy DNS
1619 and your SOCKS 4 server cannot deal with it, this might be why.
1621 \S{config-proxy-auth} Username and password
1623 \cfg{winhelp-topic}{proxy.auth}
1625 If your proxy requires authentication, you can enter a username and
1626 a password in the \q{Username} and \q{Password} boxes.
1628 Note that if you save your session, the proxy password will be
1629 saved in plain text, so anyone who can access your PuTTY
1630 configuration data will be able to discover it.
1632 Authentication is not fully supported for all forms of proxy:
1634 \b Username and password authentication is supported for HTTP
1635 proxies and SOCKS 5 proxies.
1637 \b SOCKS 4 can use the \q{Username} field, but does not support
1640 \b You can specify a way to include a username and password in the
1641 Telnet proxy command (see \k{config-proxy-command}).
1643 \S{config-proxy-command} Specifying the Telnet proxy command
1645 \cfg{winhelp-topic}{proxy.command}
1647 If you are using the Telnet proxy type, the usual command required
1648 by the firewall's Telnet server is \c{connect}, followed by a host
1649 name and a port number. If your proxy needs a different command,
1650 you can enter an alternative here.
1652 In this string, you can use \c{\\n} to represent a new-line, \c{\\r}
1653 to represent a carriage return, \c{\\t} to represent a tab
1654 character, and \c{\\x} followed by two hex digits to represent any
1655 other character. \c{\\\\} is used to encode the \c{\\} character
1658 Also, the special strings \c{%host} and \c{%port} will be replaced
1659 by the host name and port number you want to connect to. The strings
1660 \c{%user} and \c{%pass} will be replaced by the proxy username and
1661 password you specify. To get a literal \c{%} sign, enter \c{%%}.
1663 If the Telnet proxy server prompts for a username and password
1664 before commands can be sent, you can use a command such as:
1666 \c %user\n%pass\nconnect %host %port\n
1668 This will send your username and password as the first two lines to
1669 the proxy, followed by a command to connect to the desired host and
1670 port. Note that if you do not include the \c{%user} or \c{%pass}
1671 tokens in the Telnet command, then the \q{Username} and \q{Password}
1672 configuration fields will be ignored.
1674 \H{config-telnet} The Telnet panel
1676 The Telnet panel allows you to configure options that only apply to
1679 \S{config-environ} Setting environment variables on the server
1681 \cfg{winhelp-topic}{telnet.environ}
1683 The Telnet protocol provides a means for the client to pass
1684 environment variables to the server. Many Telnet servers have
1685 stopped supporting this feature due to security flaws, but PuTTY
1686 still supports it for the benefit of any servers which have found
1687 other ways around the security problems than just disabling the
1690 To add an environment variable to the list transmitted down the
1691 connection, you enter the variable name in the \q{Variable} box,
1692 enter its value in the \q{Value} box, and press the \q{Add} button.
1693 To remove one from the list, select it in the list box and press
1696 \S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
1698 \cfg{winhelp-topic}{telnet.oldenviron}
1700 The original Telnet mechanism for passing environment variables was
1701 badly specified. At the time the standard (RFC 1408) was written,
1702 BSD telnet implementations were already supporting the feature, and
1703 the intention of the standard was to describe the behaviour the BSD
1704 implementations were already using.
1706 Sadly there was a typing error in the standard when it was issued,
1707 and two vital function codes were specified the wrong way round. BSD
1708 implementations did not change, and the standard was not corrected.
1709 Therefore, it's possible you might find either BSD or RFC-compliant
1710 implementations out there. This switch allows you to choose which
1711 one PuTTY claims to be.
1713 The problem was solved by issuing a second standard, defining a new
1714 Telnet mechanism called \cw{NEW_ENVIRON}, which behaved exactly like
1715 the original \cw{OLD_ENVIRON} but was not encumbered by existing
1716 implementations. Most Telnet servers now support this, and it's
1717 unambiguous. This feature should only be needed if you have trouble
1718 passing environment variables to quite an old server.
1720 \S{config-ptelnet} Passive and active Telnet negotiation modes
1722 \cfg{winhelp-topic}{telnet.passive}
1724 In a Telnet connection, there are two types of data passed between
1725 the client and the server: actual text, and \e{negotiations} about
1726 which Telnet extra features to use.
1728 PuTTY can use two different strategies for negotiation:
1730 \b In \e{active} mode, PuTTY starts to send negotiations as soon as
1731 the connection is opened.
1733 \b In \e{passive} mode, PuTTY will wait to negotiate until it sees a
1734 negotiation from the server.
1736 The obvious disadvantage of passive mode is that if the server is
1737 also operating in a passive mode, then negotiation will never begin
1738 at all. For this reason PuTTY defaults to active mode.
1740 However, sometimes passive mode is required in order to successfully
1741 get through certain types of firewall and Telnet proxy server. If
1742 you have confusing trouble with a firewall, you could try enabling
1743 passive mode to see if it helps.
1745 \S{config-telnetkey} \q{Keyboard sends telnet Backspace and Interrupt}
1747 \cfg{winhelp-topic}{telnet.specialkeys}
1749 If this box is checked, the Backspace key on the keyboard will send
1750 the Telnet special backspace code, and Control-C will send the
1751 Telnet special interrupt code. You probably shouldn't enable this
1752 unless you know what you're doing.
1754 \S{config-telnetnl} \q{Return key sends telnet New Line instead of ^M}
1756 \cfg{winhelp-topic}{telnet.newline}
1758 Unlike most other remote login protocols, the Telnet protocol has a
1759 special \q{new line} code that is not the same as the usual line
1760 endings of Control-M or Control-J. By default, PuTTY sends the
1761 Telnet New Line code when you press Return, instead of sending
1762 Control-M as it does in most other protocols.
1764 Most Unix-style Telnet servers don't mind whether they receive
1765 Telnet New Line or Control-M; some servers do expect New Line, and
1766 some servers prefer to see ^M. If you are seeing surprising
1767 behaviour when you press Return in a Telnet session, you might try
1768 turning this option off to see if it helps.
1770 \H{config-rlogin} The Rlogin panel
1772 The Rlogin panel allows you to configure options that only apply to
1775 \S{config-rlogin-localuser} \q{Local username}
1777 \cfg{winhelp-topic}{rlogin.localuser}
1779 Rlogin allows an automated (password-free) form of login by means of
1780 a file called \c{.rhosts} on the server. You put a line in your
1781 \c{.rhosts} file saying something like \c{jbloggs@pc1.example.com},
1782 and then when you make an Rlogin connection the client transmits the
1783 username of the user running the Rlogin client. The server checks
1784 the username and hostname against \c{.rhosts}, and if they match it
1785 does not ask for a password.
1787 This only works because Unix systems contain a safeguard to stop a
1788 user from pretending to be another user in an Rlogin connection.
1789 Rlogin connections have to come from port numbers below 1024, and
1790 Unix systems prohibit this to unprivileged processes; so when the
1791 server sees a connection from a low-numbered port, it assumes the
1792 client end of the connection is held by a privileged (and therefore
1793 trusted) process, so it believes the claim of who the user is.
1795 Windows does not have this restriction: \e{any} user can initiate an
1796 outgoing connection from a low-numbered port. Hence, the Rlogin
1797 \c{.rhosts} mechanism is completely useless for securely
1798 distinguishing several different users on a Windows machine. If you
1799 have a \c{.rhosts} entry pointing at a Windows PC, you should assume
1800 that \e{anyone} using that PC can spoof your username in an Rlogin
1801 connection and access your account on the server.
1803 The \q{Local username} control allows you to specify what user name
1804 PuTTY should claim you have, in case it doesn't match your Windows
1805 user name (or in case you didn't bother to set up a Windows user
1808 \H{config-ssh} The SSH panel
1810 The SSH panel allows you to configure options that only apply to
1813 \S{config-command} Executing a specific command on the server
1815 \cfg{winhelp-topic}{ssh.command}
1817 In SSH, you don't have to run a general shell session on the server.
1818 Instead, you can choose to run a single specific command (such as a
1819 mail user agent, for example). If you want to do this, enter the
1820 command in the \q{Remote command} box.
1822 \S{config-ssh-pty} \q{Don't allocate a pseudo-terminal}
1824 \cfg{winhelp-topic}{ssh.nopty}
1826 When connecting to a Unix system, most interactive shell sessions
1827 are run in a \e{pseudo-terminal}, which allows the Unix system to
1828 pretend it's talking to a real physical terminal device but allows
1829 the SSH server to catch all the data coming from that fake device
1830 and send it back to the client.
1832 Occasionally you might find you have a need to run a session \e{not}
1833 in a pseudo-terminal. In PuTTY, this is generally only useful for
1834 very specialist purposes; although in Plink (see \k{plink}) it is
1835 the usual way of working.
1837 \S{config-ssh-comp} \q{Enable compression}
1839 \cfg{winhelp-topic}{ssh.compress}
1841 This enables data compression in the SSH connection: data sent by
1842 the server is compressed before sending, and decompressed at the
1843 client end. Likewise, data sent by PuTTY to the server is compressed
1844 first and the server decompresses it at the other end. This can help
1845 make the most of a low-bandwidth connection.
1847 \S{config-ssh-prot} \q{Preferred SSH protocol version}
1849 \cfg{winhelp-topic}{ssh.protocol}
1851 This allows you to select whether you would like to use SSH protocol
1852 version 1 or version 2. \#{FIXME: say something about this elsewhere?}
1854 PuTTY will attempt to use protocol 1 if the server you connect to
1855 does not offer protocol 2, and vice versa.
1857 If you select \q{1 only} or \q{2 only} here, PuTTY will only connect
1858 if the server you connect to offers the SSH protocol version you
1861 \S{config-ssh-encryption} Encryption algorithm selection
1863 \cfg{winhelp-topic}{ssh.ciphers}
1865 PuTTY supports a variety of different encryption algorithms, and
1866 allows you to choose which one you prefer to use. You can do this by
1867 dragging the algorithms up and down in the list box (or moving them
1868 using the Up and Down buttons) to specify a preference order. When
1869 you make an SSH connection, PuTTY will search down the list from the
1870 top until it finds an algorithm supported by the server, and then
1873 PuTTY currently supports the following algorithms:
1875 \b AES (Rijndael) - 256, 192, or 128-bit CBC (SSH-2 only)
1877 \b Blowfish - 128-bit CBC
1879 \b Triple-DES - 168-bit CBC
1881 \b Single-DES - 56-bit CBC (see below for SSH-2)
1883 If the algorithm PuTTY finds is below the \q{warn below here} line,
1884 you will see a warning box when you make the connection:
1886 \c The first cipher supported by the server
1887 \c is single-DES, which is below the configured
1888 \c warning threshold.
1889 \c Do you want to continue with this connection?
1891 This warns you that the first available encryption is not a very
1892 secure one. Typically you would put the \q{warn below here} line
1893 between the encryptions you consider secure and the ones you
1894 consider substandard. By default, PuTTY supplies a preference order
1895 intended to reflect a reasonable preference in terms of security and
1898 In SSH-2, the encryption algorithm is negotiated independently for
1899 each direction of the connection, although PuTTY does not support
1900 separate configuration of the preference orders. As a result you may
1901 get two warnings similar to the one above, possibly with different
1904 Single-DES is not recommended in the SSH 2 draft protocol
1905 standards, but one or two server implementations do support it.
1906 PuTTY can use single-DES to interoperate with
1907 these servers if you enable the \q{Enable legacy use of single-DES in
1908 SSH 2} option; by default this is disabled and PuTTY will stick to
1909 recommended ciphers.
1911 \H{config-ssh-auth} The Auth panel
1913 The Auth panel allows you to configure authentication options for
1916 \S{config-ssh-tis} \q{Attempt TIS or CryptoCard authentication}
1918 \cfg{winhelp-topic}{ssh.auth.tis}
1920 TIS and CryptoCard authentication are simple challenge/response
1921 forms of authentication available in SSH protocol version 1 only.
1922 You might use them if you were using S/Key one-time passwords, for
1923 example, or if you had a physical security token that generated
1924 responses to authentication challenges.
1926 With this switch enabled, PuTTY will attempt these forms of
1927 authentication if the server is willing to try them. You will be
1928 presented with a challenge string (which will be different every
1929 time) and must supply the correct response in order to log in. If
1930 your server supports this, you should talk to your system
1931 administrator about precisely what form these challenges and
1934 \S{config-ssh-ki} \q{Attempt keyboard-interactive authentication}
1936 \cfg{winhelp-topic}{ssh.auth.ki}
1938 The SSH 2 equivalent of TIS authentication is called
1939 \q{keyboard-interactive}. It is a flexible authentication method
1940 using an arbitrary sequence of requests and responses; so it is not
1941 only useful for challenge/response mechanisms such as S/Key, but it
1942 can also be used for (for example) asking the user for a new
1943 password when the old one has expired.
1945 PuTTY leaves this option enabled by default, but supplies a switch
1946 to turn it off in case you should have trouble with it.
1948 \S{config-ssh-agentfwd} \q{Allow agent forwarding}
1950 \cfg{winhelp-topic}{ssh.auth.agentfwd}
1952 This option allows the SSH server to open forwarded connections back
1953 to your local copy of Pageant. If you are not running Pageant, this
1954 option will do nothing.
1956 See \k{pageant} for general information on Pageant, and
1957 \k{pageant-forward} for information on agent forwarding. Note that
1958 there is a security risk involved with enabling this option; see
1959 \k{pageant-security} for details.
1961 \S{config-ssh-changeuser} \q{Allow attempted changes of username in SSH2}
1963 \cfg{winhelp-topic}{ssh.auth.changeuser}
1965 In the SSH 1 protocol, it is impossible to change username after
1966 failing to authenticate. So if you mis-type your username at the
1967 PuTTY \q{login as:} prompt, you will not be able to change it except
1968 by restarting PuTTY.
1970 The SSH 2 protocol \e{does} allow changes of username, in principle,
1971 but does not make it mandatory for SSH 2 servers to accept them. In
1972 particular, OpenSSH does not accept a change of username; once you
1973 have sent one username, it will reject attempts to try to
1974 authenticate as another user. (Depending on the version of OpenSSH,
1975 it may quietly return failure for all login attempts, or it may send
1978 For this reason, PuTTY will by default not prompt you for your
1979 username more than once, in case the server complains. If you know
1980 your server can cope with it, you can enable the \q{Allow attempted
1981 changes of username} option to modify PuTTY's behaviour.
1983 \S{config-ssh-privkey} \q{Private key file for authentication}
1985 \cfg{winhelp-topic}{ssh.auth.privkey}
1987 This box is where you enter the name of your private key file if you
1988 are using public key authentication. See \k{pubkey} for information
1989 about public key authentication in SSH.
1991 This key must be in PuTTY's native format (\c{*.PPK}).
1993 \H{config-ssh-tunnels} The Tunnels panel
1995 The Tunnels panel allows you to configure tunnelling of other
1996 connection types through an SSH connection.
1998 \S{config-ssh-x11} X11 forwarding
2000 \cfg{winhelp-topic}{ssh.tunnels.x11}
2002 If your server lets you run X Window System applications, X11
2003 forwarding allows you to securely give those applications access to
2004 a local X display on your PC.
2006 To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
2007 If your X display is not the primary display on your local machine
2008 (which it almost certainly will be unless you have deliberately
2009 arranged otherwise), you need to enter its location in the \q{X
2010 display location} box.
2012 See \k{using-x-forwarding} for more information about X11
2015 \S2{config-ssh-x11auth} Remote X11 authentication
2017 \cfg{winhelp-topic}{ssh.tunnels.x11auth}
2019 If you are using X11 forwarding, the virtual X server created on the
2020 SSH server machine will be protected by authorisation data. This
2021 data is invented, and checked, by PuTTY.
2023 The usual authorisation method used for this is called
2024 \cw{MIT-MAGIC-COOKIE-1}. This is a simple password-style protocol:
2025 the X client sends some cookie data to the server, and the server
2026 checks that it matches the real cookie. The cookie data is sent over
2027 an unencrypted X11 connection; so if you allow a client on a third
2028 machine to access the virtual X server, then the cookie will be sent
2031 PuTTY offers the alternative protocol \cw{XDM-AUTHORIZATION-1}. This
2032 is a cryptographically authenticated protocol: the data sent by the
2033 X client is different every time, and it depends on the IP address
2034 and port of the client's end of the connection and is also stamped
2035 with the current time. So an eavesdropper who captures an
2036 \cw{XDM-AUTHORIZATION-1} string cannot immediately re-use it for
2037 their own X connection.
2039 PuTTY's support for \cw{XDM-AUTHORIZATION-1} is a somewhat
2040 experimental feature, and may encounter several problems:
2042 \b Some X clients probably do not even support
2043 \cw{XDM-AUTHORIZATION-1}, so they will not know what to do with the
2044 data PuTTY has provided.
2046 \b This authentication mechanism will only work in SSH v2. In SSH
2047 v1, the SSH server does not tell the client the source address of
2048 a forwarded connection in a machine-readable format, so it's
2049 impossible to verify the \cw{XDM-AUTHORIZATION-1} data.
2051 \b You may find this feature causes problems with some SSH servers,
2052 which will not clean up \cw{XDM-AUTHORIZATION-1} data after a
2053 session, so that if you then connect to the same server using
2054 a client which only does \cw{MIT-MAGIC-COOKIE-1} and are allocated
2055 the same remote display number, you might find that out-of-date
2056 authentication data is still present on your server and your X
2059 PuTTY's default is \cw{MIT-MAGIC-COOKIE-1}. If you change it, you
2060 should be sure you know what you're doing.
2062 \S{config-ssh-portfwd} Port forwarding
2064 \cfg{winhelp-topic}{ssh.tunnels.portfwd}
2066 Port forwarding allows you to tunnel other types of network
2067 connection down an SSH session. See \k{using-port-forwarding} for a
2068 general discussion of port forwarding and how it works.
2070 The port forwarding section in the Tunnels panel shows a list of all
2071 the port forwardings that PuTTY will try to set up when it connects
2072 to the server. By default no port forwardings are set up, so this
2075 To add a port forwarding:
2077 \b Set one of the \q{Local} or \q{Remote} radio buttons, depending
2078 on whether you want to forward a local port to a remote destination
2079 (\q{Local}) or forward a remote port to a local destination
2080 (\q{Remote}). Alternatively, select \q{Dynamic} if you want PuTTY to
2081 provide a local SOCKS 4/4A/5 proxy on a local port.
2083 \b Enter a source port number into the \q{Source port} box. For
2084 local forwardings, PuTTY will listen on this port of your PC. For
2085 remote forwardings, your SSH server will listen on this port of the
2086 remote machine. Note that most servers will not allow you to listen
2087 on port numbers less than 1024.
2089 \b If you have selected \q{Local} or \q{Remote} (this step is not
2090 needed with \q{Dynamic}), enter a hostname and port number separated
2091 by a colon, in the \q{Destination} box. Connections received on the
2092 source port will be directed to this destination. For example, to
2093 connect to a POP-3 server, you might enter
2094 \c{popserver.example.com:110}.
2096 \b Click the \q{Add} button. Your forwarding details should appear
2099 To remove a port forwarding, simply select its details in the list
2100 box, and click the \q{Remove} button.
2102 In the \q{Source port} box, you can also optionally enter an IP
2103 address to listen on, by specifying (for instance) \c{127.0.0.5:79}.
2104 See \k{using-port-forwarding} for more information on how this
2105 works and its restrictions.
2107 \S{config-ssh-portfwd-localhost} Controlling the visibility of
2110 \cfg{winhelp-topic}{ssh.tunnels.portfwd.localhost}
2112 The source port for a forwarded connection usually does not accept
2113 connections from any machine except the SSH client or server machine
2114 itself (for local and remote forwardings respectively). There are
2115 controls in the Tunnels panel to change this:
2117 \b The \q{Local ports accept connections from other hosts} option
2118 allows you to set up local-to-remote port forwardings in such a way
2119 that machines other than your client PC can connect to the forwarded
2120 port. (This also applies to dynamic SOCKS forwarding.)
2122 \b The \q{Remote ports do the same} option does the same thing for
2123 remote-to-local port forwardings (so that machines other than the
2124 SSH server machine can connect to the forwarded port.) Note that
2125 this feature is only available in the SSH 2 protocol, and not all
2126 SSH 2 servers support it (OpenSSH 3.0 does not, for example).
2128 \H{config-ssh-bugs} The Bugs panel
2130 Not all SSH servers work properly. Various existing servers have
2131 bugs in them, which can make it impossible for a client to talk to
2132 them unless it knows about the bug and works around it.
2134 Since most servers announce their software version number at the
2135 beginning of the SSH connection, PuTTY will attempt to detect which
2136 bugs it can expect to see in the server and automatically enable
2137 workarounds. However, sometimes it will make mistakes; if the server
2138 has been deliberately configured to conceal its version number, or
2139 if the server is a version which PuTTY's bug database does not know
2140 about, then PuTTY will not know what bugs to expect.
2142 The Bugs panel allows you to manually configure the bugs PuTTY
2143 expects to see in the server. Each bug can be configured in three
2146 \b \q{Off}: PuTTY will assume the server does not have the bug.
2148 \b \q{On}: PuTTY will assume the server \e{does} have the bug.
2150 \b \q{Auto}: PuTTY will use the server's version number announcement
2151 to try to guess whether or not the server has the bug.
2153 \S{config-ssh-bug-ignore1} \q{Chokes on SSH1 ignore messages}
2155 \cfg{winhelp-topic}{ssh.bugs.ignore1}
2157 An ignore message (SSH_MSG_IGNORE) is a message in the SSH protocol
2158 which can be sent from the client to the server, or from the server
2159 to the client, at any time. Either side is required to ignore the
2160 message whenever it receives it. PuTTY uses ignore messages to hide
2161 the password packet in SSH1, so that a listener cannot tell the
2162 length of the user's password; it also uses ignore messages for
2163 connection keepalives (see \k{config-keepalive}).
2165 If this bug is detected, PuTTY will stop using ignore messages. This
2166 means that keepalives will stop working, and PuTTY will have to fall
2167 back to a secondary defence against SSH1 password-length
2168 eavesdropping. See \k{config-ssh-bug-plainpw1}. If this bug is
2169 enabled when talking to a correct server, the session will succeed,
2170 but keepalives will not work and the session might be more
2171 vulnerable to eavesdroppers than it could be.
2173 This is an SSH1-specific bug. No known SSH2 server fails to deal
2174 with SSH2 ignore messages.
2176 \S{config-ssh-bug-plainpw1} \q{Refuses all SSH1 password camouflage}
2178 \cfg{winhelp-topic}{ssh.bugs.plainpw1}
2180 When talking to an SSH1 server which cannot deal with ignore
2181 messages (see \k{config-ssh-bug-ignore1}), PuTTY will attempt to
2182 disguise the length of the user's password by sending additional
2183 padding \e{within} the password packet. This is technically a
2184 violation of the SSH1 specification, and so PuTTY will only do it
2185 when it cannot use standards-compliant ignore messages as
2186 camouflage. In this sense, for a server to refuse to accept a padded
2187 password packet is not really a bug, but it does make life
2188 inconvenient if the server can also not handle ignore messages.
2190 If this \q{bug} is detected, PuTTY will have no choice but to send
2191 the user's password with no form of camouflage, so that an
2192 eavesdropping user will be easily able to find out the exact length
2193 of the password. If this bug is enabled when talking to a correct
2194 server, the session will succeed, but will be more vulnerable to
2195 eavesdroppers than it could be.
2197 This is an SSH1-specific bug. SSH2 is secure against this type of
2200 \S{config-ssh-bug-rsa1} \q{Chokes on SSH1 RSA authentication}
2202 \cfg{winhelp-topic}{ssh.bugs.rsa1}
2204 Some SSH1 servers cannot deal with RSA authentication messages at
2205 all. If Pageant is running and contains any SSH1 keys, PuTTY will
2206 normally automatically try RSA authentication before falling back to
2207 passwords, so these servers will crash when they see the RSA attempt.
2209 If this bug is detected, PuTTY will go straight to password
2210 authentication. If this bug is enabled when talking to a correct
2211 server, the session will succeed, but of course RSA authentication
2214 This is an SSH1-specific bug.
2216 \S{config-ssh-bug-hmac2} \q{Miscomputes SSH2 HMAC keys}
2218 \cfg{winhelp-topic}{ssh.bugs.hmac2}
2220 Versions 2.3.0 and below of the SSH server software from
2221 \cw{ssh.com} compute the keys for their HMAC message authentication
2222 codes incorrectly. A typical symptom of this problem is that PuTTY
2223 dies unexpectedly at the beginning of the session, saying
2224 \q{Incorrect MAC received on packet}.
2226 If this bug is detected, PuTTY will compute its HMAC keys in the
2227 same way as the buggy server, so that communication will still be
2228 possible. If this bug is enabled when talking to a correct server,
2229 communication will fail.
2231 This is an SSH2-specific bug.
2233 \S{config-ssh-bug-derivekey2} \q{Miscomputes SSH2 encryption keys}
2235 \cfg{winhelp-topic}{ssh.bugs.derivekey2}
2237 Versions below 2.0.11 of the SSH server software from \cw{ssh.com}
2238 compute the keys for the session encryption incorrectly. This
2239 problem can cause various error messages, such as \q{Incoming packet
2240 was garbled on decryption}, or possibly even \q{Out of memory}.
2242 If this bug is detected, PuTTY will compute its encryption keys in
2243 the same way as the buggy server, so that communication will still
2244 be possible. If this bug is enabled when talking to a correct
2245 server, communication will fail.
2247 This is an SSH2-specific bug.
2249 \S{config-ssh-bug-sig} \q{Requires padding on SSH2 RSA signatures}
2251 \cfg{winhelp-topic}{ssh.bugs.rsapad2}
2253 Versions below 3.3 of OpenSSH require SSH2 RSA signatures to be
2254 padded with zero bytes to the same length as the RSA key modulus.
2255 The SSH2 draft specification says that an unpadded signature MUST be
2256 accepted, so this is a bug. A typical symptom of this problem is
2257 that PuTTY mysteriously fails RSA authentication once in every few
2258 hundred attempts, and falls back to passwords.
2260 If this bug is detected, PuTTY will pad its signatures in the way
2261 OpenSSH expects. If this bug is enabled when talking to a correct
2262 server, it is likely that no damage will be done, since correct
2263 servers usually still accept padded signatures because they're used
2264 to talking to OpenSSH.
2266 This is an SSH2-specific bug.
2268 \S{config-ssh-bug-dhgex} \q{Chokes on Diffie-Hellman group exchange}
2270 \cfg{winhelp-topic}{ssh.bugs.dhgex2}
2272 We have anecdotal evidence that some SSH servers claim to be able to
2273 perform Diffie-Hellman group exchange, but fail to actually do so
2274 when PuTTY tries to. If your SSH2 sessions spontaneously close
2275 immediately after opening the PuTTY window, it might be worth
2276 enabling the workaround for this bug to see if it helps.
2278 We have no hard evidence that any specific version of specific
2279 server software reliably demonstrates this bug. Therefore, PuTTY
2280 will never \e{assume} a server has this bug; if you want the
2281 workaround, you need to enable it manually.
2283 This is an SSH2-specific bug.
2285 \S{config-ssh-bug-pksessid2} \q{Misuses the session ID in PK auth}
2287 \cfg{winhelp-topic}{ssh.bugs.pksessid2}
2289 Versions below 2.3 of OpenSSH require SSH2 public-key authentication
2290 to be done slightly differently: the data to be signed by the client
2291 contains the session ID formatted in a different way. If public-key
2292 authentication mysteriously does not work but the Event Log (see
2293 \k{using-eventlog}) thinks it has successfully sent a signature, it
2294 might be worth enabling the workaround for this bug to see if it
2297 If this bug is detected, PuTTY will sign data in the way OpenSSH
2298 expects. If this bug is enabled when talking to a correct server,
2299 SSH2 public-key authentication will fail.
2301 This is an SSH2-specific bug.
2303 \H{config-file} Storing configuration in a file
2305 PuTTY does not currently support storing its configuration in a file
2306 instead of the Registry. However, you can work around this with a
2307 couple of batch files.
2309 You will need a file called (say) \c{PUTTY.BAT} which imports the
2310 contents of a file into the Registry, then runs PuTTY, exports the
2311 contents of the Registry back into the file, and deletes the
2312 Registry entries. This can all be done using the Regedit command
2313 line options, so it's all automatic. Here is what you need in
2317 \c regedit /s putty.reg
2318 \c regedit /s puttyrnd.reg
2319 \c start /w putty.exe
2320 \c regedit /ea new.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
2321 \c copy new.reg putty.reg
2323 \c regedit /s puttydel.reg
2325 This batch file needs two auxiliary files: \c{PUTTYRND.REG} which
2326 sets up an initial safe location for the \c{PUTTY.RND} random seed
2327 file, and \c{PUTTYDEL.REG} which destroys everything in the Registry
2328 once it's been successfully saved back to the file.
2330 Here is \c{PUTTYDEL.REG}:
2334 \c [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
2336 Here is an example \c{PUTTYRND.REG} file:
2340 \c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
2341 \c "RandSeedFile"="a:\\putty.rnd"
2343 You should replace \c{a:\\putty.rnd} with the location where you
2344 want to store your random number data. If the aim is to carry around
2345 PuTTY and its settings on one floppy, you probably want to store it