1 \versionid $Id: config.but,v 1.59 2003/03/07 09:03:11 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 \S{config-closeonexit} \q{Close Window on Exit}
94 \cfg{winhelp-topic}{session.coe}
96 Finally in the Session panel, there is an option labelled \q{Close
97 Window on Exit}. This controls whether the PuTTY session window
98 disappears as soon as the session inside it terminates. If you are
99 likely to want to copy and paste text out of the session after it
100 has terminated, you should arrange this option to be off.
102 \q{Close Window On Exit} has three settings. \q{Always} means always
103 close the window on exit; \q{Never} means never close on exit
104 (always leave the window open). The third setting, and the default
105 one, is \q{Only on clean exit}. In this mode, a session which
106 terminates normally will cause its window to close, but one which is
107 aborted unexpectedly by network trouble or a confusing message from
108 the server will leave the window up.
110 \H{config-logging} The Logging panel
112 \cfg{winhelp-topic}{logging.main}
114 The Logging configuration panel allows you to save log files of your
115 PuTTY sessions, for debugging, analysis or future reference.
117 The main option is a radio-button set that specifies whether PuTTY
118 will log anything at all. The options are
120 \b \q{Logging turned off completely}. This is the default option; in
121 this mode PuTTY will not create a log file at all.
123 \b \q{Log printable output only}. In this mode, a log file will be
124 created and written to, but only printable text will be saved into
125 it. The various terminal control codes that are typically sent down
126 an interactive session alongside the printable text will be omitted.
127 This might be a useful mode if you want to read a log file in a text
128 editor and hope to be able to make sense of it.
130 \b \q{Log all session output}. In this mode, \e{everything} sent by
131 the server into your terminal session is logged. If you view the log
132 file in a text editor, therefore, you may well find it full of
133 strange control characters. This is a particularly useful mode if
134 you are experiencing problems with PuTTY's terminal handling: you
135 can record everything that went to the terminal, so that someone
136 else can replay the session later in slow motion and watch to see
139 \b \q{Log SSH packet data}. In this mode (which is only used by SSH
140 connections), the SSH message packets sent over the encrypted
141 connection are written to the log file. You might need this to debug
142 a network-level problem, or more likely to send to the PuTTY authors
143 as part of a bug report. \e{BE WARNED} that if you log in using a
144 password, the password will appear in the log file, so be sure to
145 edit it out before sending the log file to anyone else!
147 \S{config-logfilename} \q{Log file name}
149 \cfg{winhelp-topic}{logging.filename}
151 In this edit box you enter the name of the file you want to log the
152 session to. The \q{Browse} button will let you look around your file
153 system to find the right place to put the file; or if you already
154 know exactly where you want it to go, you can just type a pathname
157 There are a few special features in this box. If you use the \c{&}
158 character in the file name box, PuTTY will insert details of the
159 current session in the name of the file it actually opens. The
160 precise replacements it will do are:
162 \b \c{&Y} will be replaced by the current year, as four digits.
164 \b \c{&M} will be replaced by the current month, as two digits.
166 \b \c{&D} will be replaced by the current day of the month, as two
169 \b \c{&T} will be replaced by the current time, as six digits
170 (HHMMSS) with no punctuation.
172 \b \c{&H} will be replaced by the host name you are connecting to.
174 For example, if you enter the host name
175 \c{c:\\puttylogs\\log-&h-&y&m&d-&t.dat}, you will end up with files looking
178 \c log-server1.example.com-20010528-110859.dat
179 \c log-unixbox.somewhere.org-20010611-221001.dat
181 \S{config-logfileexists} \q{What to do if the log file already exists}
183 \cfg{winhelp-topic}{logging.exists}
185 This control allows you to specify what PuTTY should do if it tries
186 to start writing to a log file and it finds the file already exists.
187 You might want to automatically destroy the existing log file and
188 start a new one with the same name. Alternatively, you might want to
189 open the existing log file and add data to the \e{end} of it.
190 Finally (the default option), you might not want to have any
191 automatic behaviour, but to ask the user every time the problem
194 \H{config-terminal} The Terminal panel
196 The Terminal configuration panel allows you to control the behaviour
197 of PuTTY's terminal emulation.
199 \S{config-autowrap} \q{Auto wrap mode initially on}
201 \cfg{winhelp-topic}{terminal.autowrap}
203 Auto wrap mode controls what happens when text printed in a PuTTY
204 window reaches the right-hand edge of the window.
206 With auto wrap mode on, if a long line of text reaches the
207 right-hand edge, it will wrap over on to the next line so you can
208 still see all the text. With auto wrap mode off, the cursor will
209 stay at the right-hand edge of the screen, and all the characters in
210 the line will be printed on top of each other.
212 If you are running a full-screen application and you occasionally
213 find the screen scrolling up when it looks as if it shouldn't, you
214 could try turning this option off.
216 Auto wrap mode can be turned on and off by control sequences sent by
217 the server. This configuration option controls the \e{default}
218 state, which will be restored when you reset the terminal (see
219 \k{reset-terminal}). However, if you modify this option in
220 mid-session using \q{Change Settings}, it will take effect
223 \S{config-decom} \q{DEC Origin Mode initially on}
225 \cfg{winhelp-topic}{terminal.decom}
227 DEC Origin Mode is a minor option which controls how PuTTY
228 interprets cursor-position control sequences sent by the server.
230 The server can send a control sequence that restricts the scrolling
231 region of the display. For example, in an editor, the server might
232 reserve a line at the top of the screen and a line at the bottom,
233 and might send a control sequence that causes scrolling operations
234 to affect only the remaining lines.
236 With DEC Origin Mode on, cursor coordinates are counted from the top
237 of the scrolling region. With it turned off, cursor coordinates are
238 counted from the top of the whole screen regardless of the scrolling
241 It is unlikely you would need to change this option, but if you find
242 a full-screen application is displaying pieces of text in what looks
243 like the wrong part of the screen, you could try turning DEC Origin
244 Mode on to see whether that helps.
246 DEC Origin Mode can be turned on and off by control sequences sent
247 by the server. This configuration option controls the \e{default}
248 state, which will be restored when you reset the terminal (see
249 \k{reset-terminal}). However, if you modify this option in
250 mid-session using \q{Change Settings}, it will take effect
253 \S{config-crlf} \q{Implicit CR in every LF}
255 \cfg{winhelp-topic}{terminal.lfhascr}
257 Most servers send two control characters, CR and LF, to start a new
258 line of the screen. The CR character makes the cursor return to the
259 left-hand side of the screen. The LF character makes the cursor move
260 one line down (and might make the screen scroll).
262 Some servers only send LF, and expect the terminal to move the
263 cursor over to the left automatically. If you come across a server
264 that does this, you will see a stepped effect on the screen, like
267 \c First line of text
271 If this happens to you, try enabling the \q{Implicit CR in every LF}
272 option, and things might go back to normal:
274 \c First line of text
278 \S{config-erase} \q{Use background colour to erase screen}
280 \cfg{winhelp-topic}{terminal.bce}
282 Not all terminals agree on what colour to turn the screen when the
283 server sends a \q{clear screen} sequence. Some terminals believe the
284 screen should always be cleared to the \e{default} background
285 colour. Others believe the screen should be cleared to whatever the
286 server has selected as a background colour.
288 There exist applications that expect both kinds of behaviour.
289 Therefore, PuTTY can be configured to do either.
291 With this option disabled, screen clearing is always done in the
292 default background colour. With this option enabled, it is done in
293 the \e{current} background colour.
295 Background-colour erase can be turned on and off by control
296 sequences sent by the server. This configuration option controls the
297 \e{default} state, which will be restored when you reset the
298 terminal (see \k{reset-terminal}). However, if you modify this
299 option in mid-session using \q{Change Settings}, it will take effect
302 \S{config-blink} \q{Enable blinking text}
304 \cfg{winhelp-topic}{terminal.blink}
306 The server can ask PuTTY to display text that blinks on and off.
307 This is very distracting, so PuTTY allows you to turn blinking text
310 When blinking text is disabled and the server attempts to make some
311 text blink, PuTTY will instead display the text with a bolded
314 Blinking text can be turned on and off by control sequences sent by
315 the server. This configuration option controls the \e{default}
316 state, which will be restored when you reset the terminal (see
317 \k{reset-terminal}). However, if you modify this option in
318 mid-session using \q{Change Settings}, it will take effect
321 \S{config-answerback} \q{Answerback to ^E}
323 \cfg{winhelp-topic}{terminal.answerback}
325 This option controls what PuTTY will send back to the server if the
326 server sends it the ^E enquiry character. Normally it just sends
327 the string \q{PuTTY}.
329 If you accidentally write the contents of a binary file to your
330 terminal, you will probably find that it contains more than one ^E
331 character, and as a result your next command line will probably read
332 \q{PuTTYPuTTYPuTTY...} as if you had typed the answerback string
333 multiple times at the keyboard. If you set the answerback string to
334 be empty, this problem should go away, but doing so might cause
337 Note that this is \e{not} the feature of PuTTY which the server will
338 typically use to determine your terminal type. That feature is the
339 \q{Terminal-type string} in the Connection panel; see
340 \k{config-termtype} for details.
342 You can include control characters in the answerback string using
343 \c{^C} notation. (Use \c{^~} to get a literal \c{^}.)
345 \S{config-localecho} \q{Local echo}
347 \cfg{winhelp-topic}{terminal.localecho}
349 With local echo disabled, characters you type into the PuTTY window
350 are not echoed in the window \e{by PuTTY}. They are simply sent to
351 the server. (The \e{server} might choose to echo them back to you;
352 this can't be controlled from the PuTTY control panel.)
354 Some types of session need local echo, and many do not. In its
355 default mode, PuTTY will automatically attempt to deduce whether or
356 not local echo is appropriate for the session you are working in. If
357 you find it has made the wrong decision, you can use this
358 configuration option to override its choice: you can force local
359 echo to be turned on, or force it to be turned off, instead of
360 relying on the automatic detection.
362 \S{config-localedit} \q{Local line editing}
364 \cfg{winhelp-topic}{terminal.localedit}
366 Normally, every character you type into the PuTTY window is sent
367 immediately to the server the moment you type it.
369 If you enable local line editing, this changes. PuTTY will let you
370 edit a whole line at a time locally, and the line will only be sent
371 to the server when you press Return. If you make a mistake, you can
372 use the Backspace key to correct it before you press Return, and the
373 server will never see the mistake.
375 Since it is hard to edit a line locally without being able to see
376 it, local line editing is mostly used in conjunction with local echo
377 (\k{config-localecho}). This makes it ideal for use in raw mode
378 \#{FIXME} or when connecting to MUDs or talkers. (Although some more
379 advanced MUDs do occasionally turn local line editing on and turn
380 local echo off, in order to accept a password from the user.)
382 Some types of session need local line editing, and many do not. In
383 its default mode, PuTTY will automatically attempt to deduce whether
384 or not local line editing is appropriate for the session you are
385 working in. If you find it has made the wrong decision, you can use
386 this configuration option to override its choice: you can force
387 local line editing to be turned on, or force it to be turned off,
388 instead of relying on the automatic detection.
390 \S{config-printing} Remote-controlled printing
392 \cfg{winhelp-topic}{terminal.printing}
394 A lot of VT100-compatible terminals support printing under control
395 of the remote server. PuTTY supports this feature as well, but it is
396 turned off by default.
398 To enable remote-controlled printing, choose a printer from the
399 \q{Printer to send ANSI printer output to} drop-down list box. This
400 should allow you to select from all the printers you have installed
401 drivers for on your computer. Alternatively, you can type the
402 network name of a networked printer (for example,
403 \c{\\\\printserver\\printer1}) even if you haven't already
404 installed a driver for it on your own machine.
406 When the remote server attempts to print some data, PuTTY will send
407 that data to the printer \e{raw} - without translating it,
408 attempting to format it, or doing anything else to it. It is up to
409 you to ensure your remote server knows what type of printer it is
412 Since PuTTY sends data to the printer raw, it cannot offer options
413 such as portrait versus landscape, print quality, or paper tray
414 selection. All these things would be done by your PC printer driver
415 (which PuTTY bypasses); if you need them done, you will have to find
416 a way to configure your remote server to do them.
418 To disable remote printing again, choose \q{None (printing
419 disabled)} from the printer selection list. This is the default
422 \H{config-keyboard} The Keyboard panel
424 The Keyboard configuration panel allows you to control the behaviour
425 of the keyboard in PuTTY.
427 \S{config-backspace} Changing the action of the Backspace key
429 \cfg{winhelp-topic}{keyboard.backspace}
431 Some terminals believe that the Backspace key should send the same
432 thing to the server as Control-H (ASCII code 8). Other terminals
433 believe that the Backspace key should send ASCII code 127 (usually
434 known as Control-?) so that it can be distinguished from Control-H.
435 This option allows you to choose which code PuTTY generates when you
438 If you are connecting to a Unix system, you will probably find that
439 the Unix \c{stty} command lets you configure which the server
440 expects to see, so you might not need to change which one PuTTY
441 generates. On other systems, the server's expectation might be fixed
442 and you might have no choice but to configure PuTTY.
444 If you do have the choice, we recommend configuring PuTTY to
445 generate Control-? and configuring the server to expect it, because
446 that allows applications such as \c{emacs} to use Control-H for
449 \S{config-homeend} Changing the action of the Home and End keys
451 \cfg{winhelp-topic}{keyboard.homeend}
453 The Unix terminal emulator \c{rxvt} disagrees with the rest of the
454 world about what character sequences should be sent to the server by
455 the Home and End keys.
457 \c{xterm}, and other terminals, send \c{ESC [1~} for the Home key,
458 and \c{ESC [4~} for the End key. \c{rxvt} sends \c{ESC [H} for the
459 Home key and \c{ESC [Ow} for the End key.
461 If you find an application on which the Home and End keys aren't
462 working, you could try switching this option to see if it helps.
464 \S{config-funkeys} Changing the action of the function keys and keypad
466 \cfg{winhelp-topic}{keyboard.funkeys}
468 This option affects the function keys (F1 to F12) and the top row of
471 \b In the default mode, labelled \c{ESC [n~}, the function keys
472 generate sequences like \c{ESC [11~}, \c{ESC [12~} and so on. This
473 matches the general behaviour of Digital's terminals.
475 \b In Linux mode, F6 to F12 behave just like the default mode, but
476 F1 to F5 generate \c{ESC [[A} through to \c{ESC [[E}. This mimics the
477 Linux virtual console.
479 \b In Xterm R6 mode, F5 to F12 behave like the default mode, but F1
480 to F4 generate \c{ESC OP} through to \c{ESC OS}, which are the
481 sequences produced by the top row of the \e{keypad} on Digital's
484 \b In VT400 mode, all the function keys behave like the default
485 mode, but the actual top row of the numeric keypad generates \c{ESC
486 OP} through to \c{ESC OS}.
488 \b In VT100+ mode, the function keys generate \c{ESC OP} through to
491 \b In SCO mode, the function keys F1 to F12 generate \c{ESC [M}
492 through to \c{ESC [X}. Together with shift, they generate \c{ESC [Y}
493 through to \c{ESC [j}. With control they generate \c{ESC [k} through
494 to \c{ESC [v}, and with shift and control together they generate
495 \c{ESC [w} through to \c{ESC [\{}.
497 If you don't know what any of this means, you probably don't need to
500 \S{config-appcursor} Controlling Application Cursor Keys mode
502 \cfg{winhelp-topic}{keyboard.appcursor}
504 Application Cursor Keys mode is a way for the server to change the
505 control sequences sent by the arrow keys. In normal mode, the arrow
506 keys send \c{ESC [A} through to \c{ESC [D}. In application mode,
507 they send \c{ESC OA} through to \c{ESC OD}.
509 Application Cursor Keys mode can be turned on and off by the server,
510 depending on the application. PuTTY allows you to configure the
513 You can also disable application cursor keys mode completely, using
514 the \q{Features} configuration panel; see
515 \k{config-features-application}.
517 \S{config-appkeypad} Controlling Application Keypad mode
519 \cfg{winhelp-topic}{keyboard.appkeypad}
521 Application Keypad mode is a way for the server to change the
522 behaviour of the numeric keypad.
524 In normal mode, the keypad behaves like a normal Windows keypad:
525 with NumLock on, the number keys generate numbers, and with NumLock
526 off they act like the arrow keys and Home, End etc.
528 In application mode, all the keypad keys send special control
529 sequences, \e{including} Num Lock. Num Lock stops behaving like Num
530 Lock and becomes another function key.
532 Depending on which version of Windows you run, you may find the Num
533 Lock light still flashes on and off every time you press Num Lock,
534 even when application mode is active and Num Lock is acting like a
535 function key. This is unavoidable.
537 Application keypad mode can be turned on and off by the server,
538 depending on the application. PuTTY allows you to configure the
541 You can also disable application keypad mode completely, using the
542 \q{Features} configuration panel; see
543 \k{config-features-application}.
545 \S{config-nethack} Using NetHack keypad mode
547 \cfg{winhelp-topic}{keyboard.nethack}
549 PuTTY has a special mode for playing NetHack. You can enable it by
550 selecting \q{NetHack} in the \q{Initial state of numeric keypad}
553 In this mode, the numeric keypad keys 1-9 generate the NetHack
554 movement commands (\cw{hjklyubn}). The 5 key generates the \c{.}
555 command (do nothing).
557 Better still, pressing Shift with the keypad keys generates the
558 capital forms of the commands (\cw{HJKLYUBN}), which tells NetHack
559 to keep moving you in the same direction until you encounter
560 something interesting.
562 For some reason, this feature only works properly when Num Lock is
563 on. We don't know why.
565 \S{config-compose} Enabling a DEC-like Compose key
567 \cfg{winhelp-topic}{keyboard.compose}
569 DEC terminals have a Compose key, which provides an easy-to-remember
570 way of typing accented characters. You press Compose and then type
571 two more characters. The two characters are \q{combined} to produce
572 an accented character. The choices of character are designed to be
573 easy to remember; for example, composing \q{e} and \q{`} produces
574 the \q{\u00e8{e-grave}} character.
576 If your keyboard has a Windows Application key, it acts as a Compose
577 key in PuTTY. Alternatively, if you enable the \q{AltGr acts as
578 Compose key} option, the AltGr key will become a Compose key.
580 \S{config-ctrlalt} \q{Control-Alt is different from AltGr}
582 \cfg{winhelp-topic}{keyboard.ctrlalt}
584 Some old keyboards do not have an AltGr key, which can make it
585 difficult to type some characters. PuTTY can be configured to treat
586 the key combination Ctrl + Left Alt the same way as the AltGr key.
588 By default, this checkbox is checked, and the key combination Ctrl +
589 Left Alt does something completely different. PuTTY's usual handling
590 of the left Alt key is to prefix the Escape (Control-\cw{[})
591 character to whatever character sequence the rest of the keypress
592 would generate. For example, Alt-A generates Escape followed by
593 \c{a}. So Alt-Ctrl-A would generate Escape, followed by Control-A.
595 If you uncheck this box, Ctrl-Alt will become a synonym for AltGr,
596 so you can use it to type extra graphic characters if your keyboard
599 (However, Ctrl-Alt will never act as a Compose key, regardless of the
600 setting of \q{AltGr acts as Compose key} described in
603 \H{config-bell} The Bell panel
605 The Bell panel controls the terminal bell feature: the server's
606 ability to cause PuTTY to beep at you.
608 In the default configuration, when the server sends the character
609 with ASCII code 7 (Control-G), PuTTY will play the Windows Default
610 Beep sound. This is not always what you want the terminal bell
611 feature to do; the Bell panel allows you to configure alternative
614 \S{config-bellstyle} \q{Set the style of bell}
616 \cfg{winhelp-topic}{bell.style}
618 This control allows you to select various different actions to occur
621 \b Selecting \q{None} disables the bell completely. In this mode,
622 the server can send as many Control-G characters as it likes and
623 nothing at all will happen.
625 \b \q{Make default system alert sound} is the default setting. It
626 causes the Windows \q{Default Beep} sound to be played. To change
627 what this sound is, or to test it if nothing seems to be happening,
628 use the Sound configurer in the Windows Control Panel.
630 \b \q{Visual bell} is a silent alternative to a beeping computer. In
631 this mode, when the server sends a Control-G, the whole PuTTY window
632 will flash white for a fraction of a second.
634 \b \q{Play a custom sound file} allows you to specify a particular
635 sound file to be used by PuTTY alone, or even by a particular
636 individual PuTTY session. This allows you to distinguish your PuTTY
637 beeps from any other beeps on the system. If you select this option,
638 you will also need to enter the name of your sound file in the edit
639 control \q{Custom sound file to play as a bell}.
641 \S{config-belltaskbar} \q{Taskbar/caption indication on bell}
643 \cfg{winhelp-topic}{bell.taskbar}
645 This feature controls what happens to the PuTTY window's entry in
646 the Windows Taskbar if a bell occurs while the window does not have
649 In the default state (\q{Disabled}) nothing unusual happens.
651 If you select \q{Steady}, then when a bell occurs and the window is
652 not in focus, the window's Taskbar entry and its title bar will
653 change colour to let you know that PuTTY session is asking for your
654 attention. The change of colour will persist until you select the
655 window, so you can leave several PuTTY windows minimised in your
656 terminal, go away from your keyboard, and be sure not to have missed
657 any important beeps when you get back.
659 \q{Flashing} is even more eye-catching: the Taskbar entry will
660 continuously flash on and off until you select the window.
662 \S{config-bellovl} \q{Control the bell overload behaviour}
664 \cfg{winhelp-topic}{bell.overload}
666 A common user error in a terminal session is to accidentally run the
667 Unix command \c{cat} (or equivalent) on an inappropriate file type,
668 such as an executable, image file, or ZIP file. This produces a huge
669 stream of non-text characters sent to the terminal, which typically
670 includes a lot of bell characters. As a result of this the terminal
671 often doesn't stop beeping for ten minutes, and everybody else in
672 the office gets annoyed.
674 To try to avoid this behaviour, or any other cause of excessive
675 beeping, PuTTY includes a bell overload management feature. In the
676 default configuration, receiving more than five bell characters in a
677 two-second period will cause the overload feature to activate. Once
678 the overload feature is active, further bells will have no effect at
679 all, so the rest of your binary file will be sent to the screen in
680 silence. After a period of five seconds during which no further
681 bells are received, the overload feature will turn itself off again
682 and bells will be re-enabled.
684 If you want this feature completely disabled, you can turn it off
685 using the checkbox \q{Bell is temporarily disabled when over-used}.
687 Alternatively, if you like the bell overload feature but don't agree
688 with the settings, you can configure the details: how many bells
689 constitute an overload, how short a time period they have to arrive
690 in to do so, and how much silent time is required before the
691 overload feature will deactivate itself.
693 Bell overload mode is always deactivated by any keypress in the
694 terminal. This means it can respond to large unexpected streams of
695 data, but does not interfere with ordinary command-line activities
696 that generate beeps (such as filename completion).
698 \H{config-features} The Features panel
700 PuTTY's terminal emulation is very highly featured, and can do a lot
701 of things under remote server control. Some of these features can
702 cause problems due to buggy or strangely configured server
705 The Features configuration panel allows you to disable some of
706 PuTTY's more advanced terminal features, in case they cause trouble.
708 \S{config-features-application} Disabling application keypad and cursor keys
710 \cfg{winhelp-topic}{features.application}
712 Application keypad mode (see \k{config-appkeypad}) and application
713 cursor keys mode (see \k{config-appcursor}) alter the behaviour of
714 the keypad and cursor keys. Some applications enable these modes but
715 then do not deal correctly with the modified keys. You can force
716 these modes to be permanently disabled no matter what the server
719 \S{config-features-mouse} Disabling \cw{xterm}-style mouse reporting
721 \cfg{winhelp-topic}{features.mouse}
723 PuTTY allows the server to send control codes that let it take over
724 the mouse and use it for purposes other than copy and paste.
725 Applications which use this feature include the text-mode web
726 browser \c{links}, the Usenet newsreader \c{trn} version 4, and the
727 file manager \c{mc} (Midnight Commander).
729 If you find this feature inconvenient, you can disable it using the
730 \q{Disable xterm-style mouse reporting} control. With this box
731 ticked, the mouse will \e{always} do copy and paste in the normal
734 Note that even if the application takes over the mouse, you can
735 still manage PuTTY's copy and paste by holding down the Shift key
736 while you select and paste, unless you have deliberately turned this
737 feature off (see \k{config-mouseshift}).
739 \S{config-features-resize} Disabling remote terminal resizing
741 \cfg{winhelp-topic}{features.resize}
743 PuTTY has the ability to change the terminal's size and position in
744 response to commands from the server. If you find PuTTY is doing
745 this unexpectedly or inconveniently, you can tell PuTTY not to
746 respond to those server commands.
748 \S{config-features-altscreen} Disabling switching to the alternate screen
750 \cfg{winhelp-topic}{features.altscreen}
752 Many terminals, including PuTTY, support an \q{alternate screen}.
753 This is the same size as the ordinary terminal screen, but separate.
754 Typically a screen-based program such as a text editor might switch
755 the terminal to the alternate screen before starting up. Then at the
756 end of the run, it switches back to the primary screen, and you see
757 the screen contents just as they were before starting the editor.
759 Some people prefer this not to happen. If you want your editor to
760 run in the same screen as the rest of your terminal activity, you
761 can disable the alternate screen feature completely.
763 \S{config-features-retitle} Disabling remote window title changing
765 \cfg{winhelp-topic}{features.retitle}
767 PuTTY has the ability to change the window title in response to
768 commands from the server. If you find PuTTY is doing this
769 unexpectedly or inconveniently, you can tell PuTTY not to respond to
770 those server commands.
772 \S{config-features-dbackspace} Disabling destructive backspace
774 \cfg{winhelp-topic}{features.dbackspace}
776 Normally, when PuTTY receives character 127 (^?) from the server, it
777 will perform a \q{destructive backspace}: move the cursor one space
778 left and delete the character under it. This can apparently cause
779 problems in some applications, so PuTTY provides the ability to
780 configure character 127 to perform a normal backspace (without
781 deleting a character) instead.
783 \S{config-features-charset} Disabling remote character set
786 \cfg{winhelp-topic}{features.charset}
788 PuTTY has the ability to change its character set configuration in
789 response to commands from the server. Some programs send these
790 commands unexpectedly or inconveniently. In particular, BitchX (an
791 IRC client) seems to have a habit of reconfiguring the character set
792 to something other than the user intended.
794 If you find that accented characters are not showing up the way you
795 expect them to, particularly if you're running BitchX, you could try
796 disabling the remote character set configuration commands.
798 \H{config-window} The Window panel
800 The Window configuration panel allows you to control aspects of the
803 \S{config-winsize} Setting the size of the PuTTY window
805 \cfg{winhelp-topic}{window.size}
807 The \q{Rows} and \q{Columns} boxes let you set the PuTTY window to a
808 precise size. Of course you can also drag the window to a new size
809 while a session is running.
811 \S{config-winsizelock} What to do when the window is resized
813 \cfg{winhelp-topic}{window.resize}
815 These options allow you to control what happens when the user tries
816 to resize the PuTTY window.
818 When you resize the PuTTY window, one of four things can happen:
820 \b Nothing (if you have completely disabled resizes).
822 \b The font size can stay the same and the number of rows and
823 columns in the terminal can change.
825 \b The number of rows and columns in the terminal can stay the same,
826 and the font size can change.
828 \b You can allow PuTTY to change \e{either} the terminal size or the
829 font size. In this mode it will change the terminal size most of the
830 time, but enlarge the font when you maximise the window.
832 You can control which of these happens using the \q{Lock terminal
833 size against resizing} and \q{Lock font size against resizing}
834 options. If you lock both, the window will refuse to be resized at
835 all. If you lock just the terminal size, the font size will change
836 when you resize the window. If you lock just the font size, the
837 terminal size will change when you resize the window.
839 \S{config-scrollback} Controlling scrollback
841 \cfg{winhelp-topic}{window.scrollback}
843 These options let you configure the way PuTTY keeps text after it
844 scrolls off the top of the screen (see \k{using-scrollback}).
846 The \q{Lines of scrollback} box lets you configure how many lines of
847 text PuTTY keeps. The \q{Display scrollbar} options allow you to
848 hide the scrollbar (although you can still view the scrollback using
849 Shift-PgUp and Shift-PgDn). You can separately configure whether the
850 scrollbar is shown in full-screen mode and in normal modes.
852 If you are viewing part of the scrollback when the server sends more
853 text to PuTTY, the screen will revert to showing the current
854 terminal contents. You can disable this behaviour by turning off
855 \q{Reset scrollback on display activity}. You can also make the
856 screen revert when you press a key, by turning on \q{Reset
857 scrollback on keypress}.
859 \S{config-erasetoscrollback} \q{Push erased text into scrollback}
861 \cfg{winhelp-topic}{window.erased}
863 When this option is enabled, the contents of the terminal screen
864 will be pushed into the scrollback when a server-side application
865 clears the screen, so that your scrollback will contain a better
866 record of what was on your screen in the past.
868 If the application switches to the alternate screen (see
869 \k{config-features-altscreen} for more about this), then the
870 contents of the primary screen will be visible in the scrollback
871 until the application switches back again.
873 This option is enabled by default.
875 \H{config-appearance} The Appearance panel
877 The Appearance configuration panel allows you to control aspects of
878 the appearance of PuTTY's window.
880 \S{config-cursor} Controlling the appearance of the cursor
882 \cfg{winhelp-topic}{appearance.cursor}
884 The \q{Cursor appearance} option lets you configure the cursor to be
885 a block, an underline, or a vertical line. A block cursor becomes an
886 empty box when the window loses focus; an underline or a vertical
889 The \q{Cursor blinks} option makes the cursor blink on and off. This
890 works in any of the cursor modes.
892 \S{config-font} Controlling the font used in the terminal window
894 \cfg{winhelp-topic}{appearance.font}
896 This option allows you to choose what font, in what size, the PuTTY
897 terminal window uses to display the text in the session. You will be
898 offered a choice from all the fixed-width fonts installed on the
899 system. (VT100-style terminal handling can only deal with fixed-
902 \S{config-mouseptr} \q{Hide mouse pointer when typing in window}
904 \cfg{winhelp-topic}{appearance.hidemouse}
906 If you enable this option, the mouse pointer will disappear if the
907 PuTTY window is selected and you press a key. This way, it will not
908 obscure any of the text in the window while you work in your
909 session. As soon as you move the mouse, the pointer will reappear.
911 This option is disabled by default, so the mouse pointer remains
912 visible at all times.
914 \S{config-winborder} Controlling the window border
916 \cfg{winhelp-topic}{appearance.border}
918 PuTTY allows you to configure the appearance of the window border to
921 The checkbox marked \q{Sunken-edge border} changes the appearance of
922 the window border to something more like a DOS box: the inside edge
923 of the border is highlighted as if it sank down to meet the surface
924 inside the window. This makes the border a little bit thicker as
925 well. It's hard to describe well. Try it and see if you like it.
927 You can also configure a completely blank gap between the text in
928 the window and the border, using the \q{Gap between text and window
929 edge} control. By default this is set at one pixel. You can reduce
930 it to zero, or increase it further.
932 \H{config-behaviour} The Behaviour panel
934 The Behaviour configuration panel allows you to control aspects of
935 the behaviour of PuTTY's window.
937 \S{config-title} Controlling the window title
939 \cfg{winhelp-topic}{appearance.title}
941 The \q{Window title} edit box allows you to set the title of the
942 PuTTY window. By default the window title will contain the host name
943 followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
944 If you want a different window title, this is where to set it.
946 PuTTY allows the server to send \c{xterm} control sequences which
947 modify the title of the window in mid-session. There is also an
948 \c{xterm} sequence to modify the title of the window's \e{icon}.
949 This makes sense in a windowing system where the window becomes an
950 icon when minimised, such as Windows 3.1 or most X Window System
951 setups; but in the Windows 95-like user interface it isn't as
954 By default, PuTTY only uses the server-supplied \e{window} title, and
955 ignores the icon title entirely. If for some reason you want to see
956 both titles, check the box marked \q{Separate window and icon titles}.
957 If you do this, PuTTY's window title and Taskbar caption will
958 change into the server-supplied icon title if you minimise the PuTTY
959 window, and change back to the server-supplied window title if you
960 restore it. (If the server has not bothered to supply a window or
961 icon title, none of this will happen.)
963 \S{config-warnonclose} \q{Warn before closing window}
965 \cfg{winhelp-topic}{behaviour.closewarn}
967 If you press the Close button in a PuTTY window that contains a
968 running session, PuTTY will put up a warning window asking if you
969 really meant to close the window. A window whose session has already
970 terminated can always be closed without a warning.
972 If you want to be able to close a window quickly, you can disable
973 the \q{Warn before closing window} option.
975 \S{config-altf4} \q{Window closes on ALT-F4}
977 \cfg{winhelp-topic}{behaviour.altf4}
979 By default, pressing ALT-F4 causes the window to close (or a warning
980 box to appear; see \k{config-warnonclose}). If you disable the
981 \q{Window closes on ALT-F4} option, then pressing ALT-F4 will simply
982 send a key sequence to the server.
984 \S{config-altspace} \q{System menu appears on ALT-Space}
986 \cfg{winhelp-topic}{behaviour.altspace}
988 If this option is enabled, then pressing ALT-Space will bring up the
989 PuTTY window's menu, like clicking on the top left corner. If it is
990 disabled, then pressing ALT-Space will just send \c{ESC SPACE} to
993 Some accessibility programs for Windows may need this option
994 enabling to be able to control PuTTY's window successfully. For
995 instance, Dragon NaturallySpeaking requires it both to open the
996 system menu via voice, and to close, minimise, maximise and restore
999 \S{config-altonly} \q{System menu appears on Alt alone}
1001 \cfg{winhelp-topic}{behaviour.altonly}
1003 If this option is enabled, then pressing and releasing ALT will
1004 bring up the PuTTY window's menu, like clicking on the top left
1005 corner. If it is disabled, then pressing and releasing ALT will have
1008 \S{config-alwaysontop} \q{Ensure window is always on top}
1010 \cfg{winhelp-topic}{behaviour.alwaysontop}
1012 If this option is enabled, the PuTTY window will stay on top of all
1015 \S{config-fullscreen} \q{Full screen on Alt-Enter}
1017 \cfg{winhelp-topic}{behaviour.altenter}
1019 If this option is enabled, then pressing Alt-Enter will cause the
1020 PuTTY window to become full-screen. Pressing Alt-Enter again will
1021 restore the previous window size.
1023 The full-screen feature is also available from the System menu, even
1024 when it is configured not to be available on the Alt-Enter key. See
1025 \k{using-fullscreen}.
1027 \H{config-translation} The Translation panel
1029 The Translation configuration panel allows you to control the
1030 translation between the character set understood by the server and
1031 the character set understood by PuTTY.
1033 \S{config-charset} Controlling character set translation
1035 \cfg{winhelp-topic}{translation.codepage}
1037 During an interactive session, PuTTY receives a stream of 8-bit
1038 bytes from the server, and in order to display them on the screen it
1039 needs to know what character set to interpret them in.
1041 There are a lot of character sets to choose from. The \q{Received
1042 data assumed to be in which character set} option lets you select
1043 one. By default PuTTY will attempt to choose a character set that is
1044 right for your locale as reported by Windows; if it gets it wrong,
1045 you can select a different one using this control.
1047 A few notable character sets are:
1049 \b The ISO-8859 series are all standard character sets that include
1050 various accented characters appropriate for different sets of
1053 \b The Win125x series are defined by Microsoft, for similar
1054 purposes. In particular Win1252 is almost equivalent to ISO-8859-1,
1055 but contains a few extra characters such as matched quotes and the
1058 \b If you want the old IBM PC character set with block graphics and
1059 line-drawing characters, you can select \q{CP437}.
1061 \b PuTTY also supports Unicode mode, in which the data coming from
1062 the server is interpreted as being in the UTF-8 encoding of Unicode.
1063 If you select \q{UTF-8} as a character set you can use this mode.
1064 Not all server-side applications will support it.
1066 If you need support for a numeric code page which is not listed in
1067 the drop-down list, such as code page 866, then you should be able
1068 to enter its name manually (\c{CP866} for example) in the list box
1069 and get the right result.
1071 \S{config-cyr} \q{Caps Lock acts as Cyrillic switch}
1073 \cfg{winhelp-topic}{translation.cyrillic}
1075 This feature allows you to switch between a US/UK keyboard layout
1076 and a Cyrillic keyboard layout by using the Caps Lock key, if you
1077 need to type (for example) Russian and English side by side in the
1080 Currently this feature is not expected to work properly if your
1081 native keyboard layout is not US or UK.
1083 \S{config-linedraw} Controlling display of line drawing characters
1085 \cfg{winhelp-topic}{translation.linedraw}
1087 VT100-series terminals allow the server to send control sequences
1088 that shift temporarily into a separate character set for drawing
1089 lines and boxes. PuTTY has a variety of ways to support this
1090 capability. In general you should probably try lots of options until
1091 you find one that your particular font supports.
1093 \b \q{Font has XWindows encoding} is for use with fonts that have a
1094 special encoding, where the lowest 32 character positions (below the
1095 ASCII printable range) contain the line-drawing characters. This is
1096 unlikely to be the case with any standard Windows font; it will
1097 probably only apply to custom-built fonts or fonts that have been
1098 automatically converted from the X Window System.
1100 \b \q{Use font in both ANSI and OEM modes} tries to use the same
1101 font in two different character sets, to obtain a wider range of
1102 characters. This doesn't always work; some fonts claim to be a
1103 different size depending on which character set you try to use.
1105 \b \q{Use font in OEM mode only} is more reliable than that, but can
1106 miss out other characters from the main character set.
1108 \b \q{Poor man's line drawing} assumes that the font \e{cannot}
1109 generate the line and box characters at all, so it will use the
1110 \c{+}, \c{-} and \c{|} characters to draw approximations to boxes.
1111 You should use this option if none of the other options works.
1113 \b \q{Unicode mode} tries to use the box characters that are present
1114 in Unicode. For good Unicode-supporting fonts this is probably the
1115 most reliable and functional option.
1117 \H{config-selection} The Selection panel
1119 The Selection panel allows you to control the way copy and paste
1120 work in the PuTTY window.
1122 \S{config-linedrawpaste} Controlling the pasting of line drawing
1125 \cfg{winhelp-topic}{selection.linedraw}
1127 By default, when you copy and paste a piece of the PuTTY screen that
1128 contains VT100 line and box drawing characters, PuTTY will translate
1129 them into the \q{poor man's} line-drawing characters \c{+}, \c{-}
1130 and \c{|}. The checkbox \q{Don't translate line drawing chars}
1131 disables this feature, so line-drawing characters will be pasted as
1132 if they were in the normal character set. This will typically mean
1133 they come out mostly as \c{q} and \c{x}, with a scattering of
1134 \c{jklmntuvw} at the corners. This might be useful if you were
1135 trying to recreate the same box layout in another program, for
1138 \S{config-rtfpaste} Pasting in Rich Text Format
1140 \cfg{winhelp-topic}{selection.rtf}
1142 If you enable \q{Paste to clipboard in RTF as well as plain text},
1143 PuTTY will write formatting information to the clipboard as well as
1144 the actual text you copy. Currently the only effect of this will be
1145 that if you paste into (say) a word processor, the text will appear
1146 in the word processor in the same font PuTTY was using to display
1147 it. In future it is likely that other formatting information (bold,
1148 underline, colours) will be copied as well.
1150 This option can easily be inconvenient, so by default it is
1153 \S{config-mouse} Changing the actions of the mouse buttons
1155 \cfg{winhelp-topic}{selection.buttons}
1157 PuTTY's copy and paste mechanism is modelled on the Unix \c{xterm}
1158 application. The X Window System uses a three-button mouse, and the
1159 convention is that the left button selects, the right button extends
1160 an existing selection, and the middle button pastes.
1162 Windows typically only has two mouse buttons, so in PuTTY's default
1163 configuration, the \e{right} button pastes, and the \e{middle}
1164 button (if you have one) extends a selection.
1166 If you have a three-button mouse and you are already used to the
1167 \c{xterm} arrangement, you can select it using the \q{Action of
1168 mouse buttons} control.
1170 \S{config-mouseshift} \q{Shift overrides application's use of mouse}
1172 \cfg{winhelp-topic}{selection.shiftdrag}
1174 PuTTY allows the server to send control codes that let it take over
1175 the mouse and use it for purposes other than copy and paste.
1176 Applications which use this feature include the text-mode web
1177 browser \c{links}, the Usenet newsreader \c{trn} version 4, and the
1178 file manager \c{mc} (Midnight Commander).
1180 When running one of these applications, pressing the mouse buttons
1181 no longer performs copy and paste. If you do need to copy and paste,
1182 you can still do so if you hold down Shift while you do your mouse
1185 However, it is possible in theory for applications to even detect
1186 and make use of Shift + mouse clicks. We don't know of any
1187 applications that do this, but in case someone ever writes one,
1188 unchecking the \q{Shift overrides application's use of mouse}
1189 checkbox will cause Shift + mouse clicks to go to the server as well
1190 (so that mouse-driven copy and paste will be completely disabled).
1192 If you want to prevent the application from taking over the mouse at
1193 all, you can do this using the Features control panel; see
1194 \k{config-features-mouse}.
1196 \S{config-rectselect} Default selection mode
1198 \cfg{winhelp-topic}{selection.rect}
1200 As described in \k{using-selection}, PuTTY has two modes of
1201 selecting text to be copied to the clipboard. In the default mode
1202 (\q{Normal}), dragging the mouse from point A to point B selects to
1203 the end of the line containing A, all the lines in between, and from
1204 the very beginning of the line containing B. In the other mode
1205 (\q{Rectangular block}), dragging the mouse between two points
1206 defines a rectangle, and everything within that rectangle is copied.
1208 Normally, you have to hold down Alt while dragging the mouse to
1209 select a rectangular block. Using the \q{Default selection mode}
1210 control, you can set rectangular selection as the default, and then
1211 you have to hold down Alt to get the \e{normal} behaviour.
1213 \S{config-charclasses} Configuring word-by-word selection
1215 \cfg{winhelp-topic}{selection.charclasses}
1217 PuTTY will select a word at a time in the terminal window if you
1218 double-click to begin the drag. This panel allows you to control
1219 precisely what is considered to be a word.
1221 Each character is given a \e{class}, which is a small number
1222 (typically 0, 1 or 2). PuTTY considers a single word to be any
1223 number of adjacent characters in the same class. So by modifying the
1224 assignment of characters to classes, you can modify the word-by-word
1225 selection behaviour.
1227 In the default configuration, the character classes are:
1229 \b Class 0 contains white space and control characters.
1231 \b Class 1 contains most punctuation.
1233 \b Class 2 contains letters, numbers and a few pieces of punctuation
1234 (the double quote, minus sign, period, forward slash and
1237 So, for example, if you assign the \c{@} symbol into character class
1238 2, you will be able to select an e-mail address with just a double
1241 In order to adjust these assignments, you start by selecting a group
1242 of characters in the list box. Then enter a class number in the edit
1243 box below, and press the \q{Set} button.
1245 This mechanism currently only covers ASCII characters, because it
1246 isn't feasible to expand the list to cover the whole of Unicode.
1248 Character class definitions can be modified by control sequences
1249 sent by the server. This configuration option controls the
1250 \e{default} state, which will be restored when you reset the
1251 terminal (see \k{reset-terminal}). However, if you modify this
1252 option in mid-session using \q{Change Settings}, it will take effect
1255 \H{config-colours} The Colours panel
1257 The Colours panel allows you to control PuTTY's use of colour.
1259 \S{config-boldcolour} \q{Bolded text is a different colour}
1261 \cfg{winhelp-topic}{colours.bold}
1263 When the server sends a control sequence indicating that some text
1264 should be displayed in bold, PuTTY can handle this two ways. It can
1265 either change the font for a bold version, or use the same font in a
1266 brighter colour. This control lets you choose which.
1268 By default the box is checked, so non-bold text is displayed in
1269 light grey and bold text is displayed in bright white (and similarly
1270 in other colours). If you uncheck the box, bold and non-bold text
1271 will be displayed in the same colour, and instead the font will
1272 change to indicate the difference.
1274 \S{config-logpalette} \q{Attempt to use logical palettes}
1276 \cfg{winhelp-topic}{colours.logpal}
1278 Logical palettes are a mechanism by which a Windows application
1279 running on an 8-bit colour display can select precisely the colours
1280 it wants instead of going with the Windows standard defaults.
1282 If you are not getting the colours you ask for on an 8-bit display,
1283 you can try enabling this option. However, be warned that it's never
1286 \S{config-colourcfg} Adjusting the colours in the terminal window
1288 \cfg{winhelp-topic}{colours.config}
1290 The main colour control allows you to specify exactly what colours
1291 things should be displayed in. To modify one of the PuTTY colours,
1292 use the list box to select which colour you want to modify. The RGB
1293 values for that colour will appear on the right-hand side of the
1294 list box. Now, if you press the \q{Modify} button, you will be
1295 presented with a colour selector, in which you can choose a new
1296 colour to go in place of the old one.
1298 PuTTY allows you to set the cursor colour, the default foreground
1299 and background, and the precise shades of all the ANSI configurable
1300 colours (black, red, green, yellow, blue, magenta, cyan, and white).
1301 You can also modify the precise shades used for the bold versions of
1302 these colours; these are used to display bold text if you have
1303 selected \q{Bolded text is a different colour}, and can also be used
1304 if the server asks specifically to use them.
1306 \H{config-connection} The Connection panel
1308 The Connection panel allows you to configure options that apply to
1309 more than one type of connection.
1311 \S{config-termtype} \q{Terminal-type string}
1313 \cfg{winhelp-topic}{connection.termtype}
1315 Most servers you might connect to with PuTTY are designed to be
1316 connected to from lots of different types of terminal. In order to
1317 send the right control sequences to each one, the server will need
1318 to know what type of terminal it is dealing with. Therefore, each of
1319 the SSH, Telnet and Rlogin protocols allow a text string to be sent
1320 down the connection describing the terminal.
1322 PuTTY attempts to emulate the Unix \c{xterm} program, and by default
1323 it reflects this by sending \c{xterm} as a terminal-type string. If
1324 you find this is not doing what you want - perhaps the remote
1325 terminal reports \q{Unknown terminal type} - you could try setting
1326 this to something different, such as \c{vt220}.
1328 If you're not sure whether a problem is due to the terminal type
1329 setting or not, you probably need to consult the manual for your
1330 application or your server.
1332 \S{config-username} \q{Auto-login username}
1334 \cfg{winhelp-topic}{connection.username}
1336 All three of the SSH, Telnet and Rlogin protocols allow you to
1337 specify what user name you want to log in as, without having to type
1338 it explicitly every time. (Some Telnet servers don't support this.)
1340 In this box you can type that user name.
1342 \S{config-keepalive} Using keepalives to prevent disconnection
1344 \cfg{winhelp-topic}{connection.keepalive}
1346 If you find your sessions are closing unexpectedly (\q{Connection
1347 reset by peer}) after they have been idle for a while, you might
1348 want to try using this option.
1350 Some network routers and firewalls need to keep track of all
1351 connections through them. Usually, these firewalls will assume a
1352 connection is dead if no data is transferred in either direction
1353 after a certain time interval. This can cause PuTTY sessions to be
1354 unexpectedly closed by the firewall if no traffic is seen in the
1355 session for some time.
1357 The keepalive option (\q{Seconds between keepalives}) allows you to
1358 configure PuTTY to send data through the session at regular
1359 intervals, in a way that does not disrupt the actual terminal
1360 session. If you find your firewall is cutting idle connections off,
1361 you can try entering a non-zero value in this field. The value is
1362 measured in seconds; so, for example, if your firewall cuts
1363 connections off after ten minutes then you might want to enter 300
1364 seconds (5 minutes) in the box.
1366 Note that keepalives are not always helpful. They help if you have a
1367 firewall which drops your connection after an idle period; but if
1368 the network between you and the server suffers from breaks in
1369 connectivity then keepalives can actually make things worse. If a
1370 session is idle, and connectivity is temporarily lost between the
1371 endpoints, but the connectivity is restored before either side tries
1372 to send anything, then there will be no problem - neither endpoint
1373 will notice that anything was wrong. However, if one side does send
1374 something during the break, it will repeatedly try to re-send, and
1375 eventually give up and abandon the connection. Then when
1376 connectivity is restored, the other side will find that the first
1377 side doesn't believe there is an open connection any more.
1378 Keepalives can make this sort of problem worse, because they
1379 increase the probability that PuTTY will attempt to send data during
1380 a break in connectivity. Therefore, you might find they help
1381 connection loss, or you might find they make it worse, depending on
1382 what \e{kind} of network problems you have between you and the
1385 Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
1386 protocols offer no way of implementing them.
1388 Note that if you are using SSH1 and the server has a bug that makes
1389 it unable to deal with SSH1 ignore messages (see
1390 \k{config-ssh-bug-ignore1}), enabling keepalives will have no effect.
1392 \S{config-nodelay} \q{Disable Nagle's algorithm}
1394 \cfg{winhelp-topic}{connection.nodelay}
1396 Nagle's algorithm is a detail of TCP/IP implementations that tries
1397 to minimise the number of small data packets sent down a network
1398 connection. With Nagle's algorithm enabled, PuTTY's bandwidth usage
1399 will be slightly more efficient; with it disabled, you may find you
1400 get a faster response to your keystrokes when connecting to some
1403 The Nagle algorithm is disabled by default.
1405 \H{config-proxy} The Proxy panel
1407 \cfg{winhelp-topic}{proxy.main}
1409 The Proxy panel allows you to configure PuTTY to use various types
1410 of proxy in order to make its network connections. The settings in
1411 this panel affect the primary network connection forming your PuTTY
1412 session, but also any extra connections made as a result of SSH port
1413 forwarding (see \k{using-port-forwarding}).
1415 \S{config-proxy-type} Setting the proxy type
1417 \cfg{winhelp-topic}{proxy.type}
1419 The \q{Proxy type} radio buttons allow you to configure what type of
1420 proxy you want PuTTY to use for its network connections. The default
1421 setting is \q{None}; in this mode no proxy is used for any
1424 \b Selecting \q{HTTP} allows you to proxy your connections through a
1425 web server supporting the HTTP \cw{CONNECT} command, as documented
1426 in \W{http://www.ietf.org/rfc/rfc2817.txt}{RFC 2817}.
1428 \b Selecting \q{SOCKS} allows you to proxy your connections through
1431 \b Many firewalls implement a less formal type of proxy in which a
1432 user can make a Telnet connection directly to the firewall machine
1433 and enter a command such as \c{connect myhost.com 22} to connect
1434 through to an external host. Selecting \q{Telnet} allows you to tell
1435 PuTTY to use this type of proxy.
1437 \S{config-proxy-exclude} Excluding parts of the network from proxying
1439 \cfg{winhelp-topic}{proxy.exclude}
1441 Typically you will only need to use a proxy to connect to non-local
1442 parts of your network; for example, your proxy might be required for
1443 connections outside your company's internal network. In the
1444 \q{Exclude Hosts/IPs} box you can enter ranges of IP addresses, or
1445 ranges of DNS names, for which PuTTY will avoid using the proxy and
1446 make a direct connection instead.
1448 The \q{Exclude Hosts/IPs} box may contain more than one exclusion
1449 range, separated by commas. Each range can be an IP address or a DNS
1450 name, with a \c{*} character allowing wildcards. For example:
1454 This excludes any host with a name ending in \c{.example.com} from
1459 This excludes any host with an IP address starting with 192.168.88
1462 \c 192.168.88.*,*.example.com
1464 This excludes both of the above ranges at once.
1466 Connections to the local host (the host name \c{localhost}, and any
1467 loopback IP address) are never proxied, even if the proxy exclude
1468 list does not explicitly contain them. It is very unlikely that this
1469 behaviour would ever cause problems, but if it does you can change
1470 it by enabling \q{Consider proxying local host connections}.
1472 Note that if you are doing DNS at the proxy (see
1473 \k{config-proxy-dns}), you should make sure that your proxy
1474 exclusion settings do not depend on knowing the IP address of a
1475 host. If the name is passed on to the proxy without PuTTY looking it
1476 up, it will never know the IP address and cannot check it against
1479 \S{config-proxy-dns} Name resolution when using a proxy
1481 \cfg{winhelp-topic}{proxy.dns}
1483 If you are using a proxy to access a private network, it can make a
1484 difference whether DNS name resolution is performed by PuTTY itself
1485 (on the client machine) or performed by the proxy.
1487 The \q{Do DNS name lookup at proxy end} configuration option allows
1488 you to control this. If you set it to \q{No}, PuTTY will always do
1489 its own DNS, and will always pass an IP address to the proxy. If you
1490 set it to \q{Yes}, PuTTY will always pass host names straight to the
1491 proxy without trying to look them up first.
1493 If you set this option to \q{Auto} (the default), PuTTY will do
1494 something it considers appropriate for each type of proxy. Telnet
1495 and HTTP proxies will have host names passed straight to them; SOCKS
1498 Note that if you are doing DNS at the proxy, you should make sure
1499 that your proxy exclusion settings (see \k{config-proxy-exclude}) do
1500 not depend on knowing the IP address of a host. If the name is
1501 passed on to the proxy without PuTTY looking it up, it will never
1502 know the IP address and cannot check it against your list.
1504 The original SOCKS 4 protocol does not support proxy-side DNS. There
1505 is a protocol extension (SOCKS 4A) which does support it, but not
1506 all SOCKS 4 servers provide this extension. If you enable proxy DNS
1507 and your SOCKS 4 server cannot deal with it, this might be why.
1509 \S{config-proxy-auth} Username and password
1511 \cfg{winhelp-topic}{proxy.auth}
1513 If your proxy requires authentication, you can enter a username and
1514 a password in the \q{Username} and \q{Password} boxes.
1516 Authentication is not fully supported for all forms of proxy:
1518 \b Username and password authentication is supported for HTTP
1519 proxies and SOCKS 5 proxies.
1521 \b SOCKS 4 can use the \q{Username} field, but does not support
1524 \b You can specify a way to include a username and password in the
1525 Telnet proxy command (see \k{config-proxy-command}).
1527 \S{config-proxy-command} Specifying the Telnet proxy command
1529 \cfg{winhelp-topic}{proxy.command}
1531 If you are using the Telnet proxy type, the usual command required
1532 by the firewall's Telnet server is \c{connect}, followed by a host
1533 name and a port number. If your proxy needs a different command,
1534 you can enter an alternative here.
1536 In this string, you can use \c{\\n} to represent a new-line, \c{\\r}
1537 to represent a carriage return, \c{\\t} to represent a tab
1538 character, and \c{\\x} followed by two hex digits to represent any
1539 other character. \c{\\\\} is used to encode the \c{\\} character
1542 Also, the special strings \c{%host} and \c{%port} will be replaced
1543 by the host name and port number you want to connect to. The strings
1544 \c{%user} and \c{%pass} will be replaced by the proxy username and
1545 password you specify. To get a literal \c{%} sign, enter \c{%%}.
1547 If the Telnet proxy server prompts for a username and password
1548 before commands can be sent, you can use a command such as:
1550 \c %user\n%pass\nconnect %host %port\n
1552 This will send your username and password as the first two lines to
1553 the proxy, followed by a command to connect to the desired host and
1554 port. Note that if you do not include the \c{%user} or \c{%pass}
1555 tokens in the Telnet command, then the \q{Username} and \q{Password}
1556 configuration fields will be ignored.
1558 \S{config-proxy-socksver} Selecting the version of the SOCKS protocol
1560 \cfg{winhelp-topic}{proxy.socksver}
1562 SOCKS servers exist in two versions: version 5
1563 (\W{http://www.ietf.org/rfc/rfc1928.txt}{RFC 1928}) and the earlier
1564 version 4. The \q{SOCKS Version} radio buttons allow you to select
1565 which one to use, if you have selected the SOCKS proxy type.
1567 \H{config-telnet} The Telnet panel
1569 The Telnet panel allows you to configure options that only apply to
1572 \S{config-termspeed} \q{Terminal-speed string}
1574 \cfg{winhelp-topic}{telnet.termspeed}
1576 Telnet allows the client to send a text string that describes the
1577 terminal speed. PuTTY lets you configure this, in case you find the
1578 server is reacting badly to the default value. (I'm not aware of any
1579 servers that do have a problem with it.)
1581 \S{config-environ} Setting environment variables on the server
1583 \cfg{winhelp-topic}{telnet.environ}
1585 The Telnet protocol also provides a means for the client to pass
1586 environment variables to the server. Many Telnet servers have
1587 stopped supporting this feature due to security flaws, but PuTTY
1588 still supports it for the benefit of any servers which have found
1589 other ways around the security problems than just disabling the
1592 To add an environment variable to the list transmitted down the
1593 connection, you enter the variable name in the \q{Variable} box,
1594 enter its value in the \q{Value} box, and press the \q{Add} button.
1595 To remove one from the list, select it in the list box and press
1598 \S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
1600 \cfg{winhelp-topic}{telnet.oldenviron}
1602 The original Telnet mechanism for passing environment variables was
1603 badly specified. At the time the standard (RFC 1408) was written,
1604 BSD telnet implementations were already supporting the feature, and
1605 the intention of the standard was to describe the behaviour the BSD
1606 implementations were already using.
1608 Sadly there was a typing error in the standard when it was issued,
1609 and two vital function codes were specified the wrong way round. BSD
1610 implementations did not change, and the standard was not corrected.
1611 Therefore, it's possible you might find either BSD or RFC-compliant
1612 implementations out there. This switch allows you to choose which
1613 one PuTTY claims to be.
1615 The problem was solved by issuing a second standard, defining a new
1616 Telnet mechanism called \cw{NEW_ENVIRON}, which behaved exactly like
1617 the original \cw{OLD_ENVIRON} but was not encumbered by existing
1618 implementations. Most Telnet servers now support this, and it's
1619 unambiguous. This feature should only be needed if you have trouble
1620 passing environment variables to quite an old server.
1622 \S{config-ptelnet} Passive and active Telnet negotiation modes
1624 \cfg{winhelp-topic}{telnet.passive}
1626 In a Telnet connection, there are two types of data passed between
1627 the client and the server: actual text, and \e{negotiations} about
1628 which Telnet extra features to use.
1630 PuTTY can use two different strategies for negotiation:
1632 \b In \e{active} mode, PuTTY starts to send negotiations as soon as
1633 the connection is opened.
1635 \b In \e{passive} mode, PuTTY will wait to negotiate until it sees a
1636 negotiation from the server.
1638 The obvious disadvantage of passive mode is that if the server is
1639 also operating in a passive mode, then negotiation will never begin
1640 at all. For this reason PuTTY defaults to active mode.
1642 However, sometimes passive mode is required in order to successfully
1643 get through certain types of firewall and Telnet proxy server. If
1644 you have confusing trouble with a firewall, you could try enabling
1645 passive mode to see if it helps.
1647 \S{config-telnetkey} \q{Keyboard sends telnet Backspace and Interrupt}
1649 \cfg{winhelp-topic}{telnet.specialkeys}
1651 If this box is checked, the Backspace key on the keyboard will send
1652 the Telnet special backspace code, and Control-C will send the
1653 Telnet special interrupt code. You probably shouldn't enable this
1654 unless you know what you're doing.
1656 \S{config-telnetnl} \q{Return key sends telnet New Line instead of ^M}
1658 \cfg{winhelp-topic}{telnet.newline}
1660 Unlike most other remote login protocols, the Telnet protocol has a
1661 special \q{new line} code that is not the same as the usual line
1662 endings of Control-M or Control-J. By default, PuTTY sends the
1663 Telnet New Line code when you press Return, instead of sending
1664 Control-M as it does in most other protocols.
1666 Most Unix-style Telnet servers don't mind whether they receive
1667 Telnet New Line or Control-M; some servers do expect New Line, and
1668 some servers prefer to see ^M. If you are seeing surprising
1669 behaviour when you press Return in a Telnet session, you might try
1670 turning this option off to see if it helps.
1672 \H{config-rlogin} The Rlogin panel
1674 The Rlogin panel allows you to configure options that only apply to
1677 \S{config-rlogin-termspeed} \q{Terminal-speed string}
1679 \cfg{winhelp-topic}{rlogin.termspeed}
1681 Like Telnet, Rlogin allows the client to send a text string that
1682 describes the terminal speed. PuTTY lets you configure this, in case
1683 you find the server is reacting badly to the default value. (I'm not
1684 aware of any servers that do have a problem with it.)
1686 \S{config-rlogin-localuser} \q{Local username}
1688 \cfg{winhelp-topic}{rlogin.localuser}
1690 Rlogin allows an automated (password-free) form of login by means of
1691 a file called \c{.rhosts} on the server. You put a line in your
1692 \c{.rhosts} file saying something like \c{jbloggs@pc1.example.com},
1693 and then when you make an Rlogin connection the client transmits the
1694 username of the user running the Rlogin client. The server checks
1695 the username and hostname against \c{.rhosts}, and if they match it
1696 does not ask for a password.
1698 This only works because Unix systems contain a safeguard to stop a
1699 user from pretending to be another user in an Rlogin connection.
1700 Rlogin connections have to come from port numbers below 1024, and
1701 Unix systems prohibit this to unprivileged processes; so when the
1702 server sees a connection from a low-numbered port, it assumes the
1703 client end of the connection is held by a privileged (and therefore
1704 trusted) process, so it believes the claim of who the user is.
1706 Windows does not have this restriction: \e{any} user can initiate an
1707 outgoing connection from a low-numbered port. Hence, the Rlogin
1708 \c{.rhosts} mechanism is completely useless for securely
1709 distinguishing several different users on a Windows machine. If you
1710 have a \c{.rhosts} entry pointing at a Windows PC, you should assume
1711 that \e{anyone} using that PC can spoof your username in an Rlogin
1712 connection and access your account on the server.
1714 The \q{Local username} control allows you to specify what user name
1715 PuTTY should claim you have, in case it doesn't match your Windows
1716 user name (or in case you didn't bother to set up a Windows user
1719 \H{config-ssh} The SSH panel
1721 The SSH panel allows you to configure options that only apply to
1724 \S{config-command} Executing a specific command on the server
1726 \cfg{winhelp-topic}{ssh.command}
1728 In SSH, you don't have to run a general shell session on the server.
1729 Instead, you can choose to run a single specific command (such as a
1730 mail user agent, for example). If you want to do this, enter the
1731 command in the \q{Remote command} box.
1733 \S{config-ssh-pty} \q{Don't allocate a pseudo-terminal}
1735 \cfg{winhelp-topic}{ssh.nopty}
1737 When connecting to a Unix system, most interactive shell sessions
1738 are run in a \e{pseudo-terminal}, which allows the Unix system to
1739 pretend it's talking to a real physical terminal device but allows
1740 the SSH server to catch all the data coming from that fake device
1741 and send it back to the client.
1743 Occasionally you might find you have a need to run a session \e{not}
1744 in a pseudo-terminal. In PuTTY, this is generally only useful for
1745 very specialist purposes; although in Plink (see \k{plink}) it is
1746 the usual way of working.
1748 \S{config-ssh-comp} \q{Enable compression}
1750 \cfg{winhelp-topic}{ssh.compress}
1752 This enables data compression in the SSH connection: data sent by
1753 the server is compressed before sending, and decompressed at the
1754 client end. Likewise, data sent by PuTTY to the server is compressed
1755 first and the server decompresses it at the other end. This can help
1756 make the most of a low-bandwidth connection.
1758 \S{config-ssh-prot} \q{Preferred SSH protocol version}
1760 \cfg{winhelp-topic}{ssh.protocol}
1762 This allows you to select whether you would like to use SSH protocol
1763 version 1 or version 2. \#{FIXME: say something about this elsewhere?}
1765 PuTTY will attempt to use protocol 1 if the server you connect to
1766 does not offer protocol 2, and vice versa.
1768 If you select \q{1 only} or \q{2 only} here, PuTTY will only connect
1769 if the server you connect to offers the SSH protocol version you
1772 \S{config-ssh-encryption} Encryption algorithm selection
1774 \cfg{winhelp-topic}{ssh.ciphers}
1776 PuTTY supports a variety of different encryption algorithms, and
1777 allows you to choose which one you prefer to use. You can do this by
1778 dragging the algorithms up and down in the list box (or moving them
1779 using the Up and Down buttons) to specify a preference order. When
1780 you make an SSH connection, PuTTY will search down the list from the
1781 top until it finds an algorithm supported by the server, and then
1784 If the algorithm PuTTY finds is below the \q{warn below here} line,
1785 you will see a warning box when you make the connection:
1787 \c The first cipher supported by the server
1788 \c is single-DES, which is below the configured
1789 \c warning threshold.
1790 \c Do you want to continue with this connection?
1792 This warns you that the first available encryption is not a very
1793 secure one. Typically you would put the \q{warn below here} line
1794 between the encryptions you consider secure and the ones you
1795 consider substandard. By default, PuTTY supplies a preference order
1796 intended to reflect a reasonable preference in terms of security and
1799 In SSH-2, the encryption algorithm is negotiated independently for
1800 each direction of the connection, although PuTTY does not support
1801 separate configuration of the preference orders. As a result you may
1802 get two warnings similar to the one above, possibly with different
1805 Single-DES is not supported natively in the SSH 2 draft protocol
1806 standards. One or two server implementations do support it, by a
1807 non-standard name. PuTTY can use single-DES to interoperate with
1808 these servers if you enable the \q{Enable non-standard single-DES in
1809 SSH 2} option; by default this is disabled and PuTTY will stick to
1812 \H{config-ssh-auth} The Auth panel
1814 The Auth panel allows you to configure authentication options for
1817 \S{config-ssh-tis} \q{Attempt TIS or CryptoCard authentication}
1819 \cfg{winhelp-topic}{ssh.auth.tis}
1821 TIS and CryptoCard authentication are simple challenge/response
1822 forms of authentication available in SSH protocol version 1 only.
1823 You might use them if you were using S/Key one-time passwords, for
1824 example, or if you had a physical security token that generated
1825 responses to authentication challenges.
1827 With this switch enabled, PuTTY will attempt these forms of
1828 authentication if the server is willing to try them. You will be
1829 presented with a challenge string (which will be different every
1830 time) and must supply the correct response in order to log in. If
1831 your server supports this, you should talk to your system
1832 administrator about precisely what form these challenges and
1835 \S{config-ssh-ki} \q{Attempt keyboard-interactive authentication}
1837 \cfg{winhelp-topic}{ssh.auth.ki}
1839 The SSH 2 equivalent of TIS authentication is called
1840 \q{keyboard-interactive}. It is a flexible authentication method
1841 using an arbitrary sequence of requests and responses; so it is not
1842 only useful for challenge/response mechanisms such as S/Key, but it
1843 can also be used for (for example) asking the user for a new
1844 password when the old one has expired.
1846 PuTTY leaves this option enabled by default, but supplies a switch
1847 to turn it off in case you should have trouble with it.
1849 \S{config-ssh-agentfwd} \q{Allow agent forwarding}
1851 \cfg{winhelp-topic}{ssh.auth.agentfwd}
1853 This option allows the SSH server to open forwarded connections back
1854 to your local copy of Pageant. If you are not running Pageant, this
1855 option will do nothing.
1857 See \k{pageant} for general information on Pageant, and
1858 \k{pageant-forward} for information on agent forwarding. Note that
1859 there is a security risk involved with enabling this option; see
1860 \k{pageant-security} for details.
1862 \S{config-ssh-changeuser} \q{Allow attempted changes of username in SSH2}
1864 \cfg{winhelp-topic}{ssh.auth.changeuser}
1866 In the SSH 1 protocol, it is impossible to change username after
1867 failing to authenticate. So if you mis-type your username at the
1868 PuTTY \q{login as:} prompt, you will not be able to change it except
1869 by restarting PuTTY.
1871 The SSH 2 protocol \e{does} allow changes of username, in principle,
1872 but does not make it mandatory for SSH 2 servers to accept them. In
1873 particular, OpenSSH does not accept a change of username; once you
1874 have sent one username, it will reject attempts to try to
1875 authenticate as another user. (Depending on the version of OpenSSH,
1876 it may quietly return failure for all login attempts, or it may send
1879 For this reason, PuTTY will by default not prompt you for your
1880 username more than once, in case the server complains. If you know
1881 your server can cope with it, you can enable the \q{Allow attempted
1882 changes of username} option to modify PuTTY's behaviour.
1884 \S{config-ssh-privkey} \q{Private key file for authentication}
1886 \cfg{winhelp-topic}{ssh.auth.privkey}
1888 This box is where you enter the name of your private key file if you
1889 are using public key authentication. See \k{pubkey} for information
1890 about public key authentication in SSH.
1892 This key must be in PuTTY's native format (\c{*.PPK}).
1894 \H{config-ssh-tunnels} The Tunnels panel
1896 The Tunnels panel allows you to configure tunnelling of other
1897 connection types through an SSH connection.
1899 \S{config-ssh-x11} X11 forwarding
1901 \cfg{winhelp-topic}{ssh.tunnels.x11}
1903 If your server lets you run X Window System applications, X11
1904 forwarding allows you to securely give those applications access to
1905 a local X display on your PC.
1907 To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
1908 If your X display is not the primary display on your local machine
1909 (which it almost certainly will be unless you have deliberately
1910 arranged otherwise), you need to enter its location in the \q{X
1911 display location} box.
1913 See \k{using-x-forwarding} for more information about X11
1916 \S2{config-ssh-x11auth} Remote X11 authentication
1918 \cfg{winhelp-topic}{ssh.tunnels.x11auth}
1920 If you are using X11 forwarding, the virtual X server created on the
1921 SSH server machine will be protected by authorisation data. This
1922 data is invented, and checked, by PuTTY.
1924 The usual authorisation method used for this is called
1925 \cw{MIT-MAGIC-COOKIE-1}. This is a simple password-style protocol:
1926 the X client sends some cookie data to the server, and the server
1927 checks that it matches the real cookie. The cookie data is sent over
1928 an unencrypted X11 connection; so if you allow a client on a third
1929 machine to access the virtual X server, then the cookie will be sent
1932 PuTTY offers the alternative protocol \cw{XDM-AUTHORIZATION-1}. This
1933 is a cryptographically authenticated protocol: the data sent by the
1934 X client is different every time, and it depends on the IP address
1935 and port of the client's end of the connection and is also stamped
1936 with the current time. So an eavesdropper who captures an
1937 \cw{XDM-AUTHORIZATION-1} string cannot immediately re-use it for
1938 their own X connection.
1940 PuTTY's support for \cw{XDM-AUTHORIZATION-1} is a somewhat
1941 experimental feature, and may encounter several problems:
1943 \b Some X clients probably do not even support
1944 \cw{XDM-AUTHORIZATION-1}, so they will not know what to do with the
1945 data PuTTY has provided.
1947 \b This authentication mechanism will only work in SSH v2. In SSH
1948 v1, the SSH server does not tell the client the source address of
1949 a forwarded connection in a machine-readable format, so it's
1950 impossible to verify the \cw{XDM-AUTHORIZATION-1} data.
1952 \b You may find this feature causes problems with some SSH servers,
1953 which will not clean up \cw{XDM-AUTHORIZATION-1} data after a
1954 session, so that if you then connect to the same server using
1955 a client which only does \cw{MIT-MAGIC-COOKIE-1} and are allocated
1956 the same remote display number, you might find that out-of-date
1957 authentication data is still present on your server and your X
1960 PuTTY's default is \cw{MIT-MAGIC-COOKIE-1}. If you change it, you
1961 should be sure you know what you're doing.
1963 \S{config-ssh-portfwd} Port forwarding
1965 \cfg{winhelp-topic}{ssh.tunnels.portfwd}
1967 Port forwarding allows you to tunnel other types of network
1968 connection down an SSH session. See \k{using-port-forwarding} for a
1969 general discussion of port forwarding and how it works.
1971 The port forwarding section in the Tunnels panel shows a list of all
1972 the port forwardings that PuTTY will try to set up when it connects
1973 to the server. By default no port forwardings are set up, so this
1976 To add a port forwarding:
1978 \b Set one of the \q{Local} or \q{Remote} radio buttons, depending
1979 on whether you want to forward a local port to a remote destination
1980 (\q{Local}) or forward a remote port to a local destination
1983 \b Enter a source port number into the \q{Source port} box. For
1984 local forwardings, PuTTY will listen on this port of your PC. For
1985 remote forwardings, your SSH server will listen on this port of the
1986 remote machine. Note that most servers will not allow you to listen
1987 on port numbers less than 1024.
1989 \b Enter a hostname and port number separated by a colon, in the
1990 \q{Destination} box. Connections received on the source port will be
1991 directed to this destination. For example, to connect to a POP-3
1992 server, you might enter \c{popserver.example.com:110}.
1994 \b Click the \q{Add} button. Your forwarding details should appear
1997 To remove a port forwarding, simply select its details in the list
1998 box, and click the \q{Remove} button.
2000 In the \q{Source port} box, you can also optionally enter an IP
2001 address to listen on. Typically a Windows machine can be asked to
2002 listen on any single IP address in the \cw{127.*.*.*} range, and all
2003 of these are loopback addresses available only to the local machine.
2004 So if you forward (for example) \c{127.0.0.5:79} to a remote
2005 machine's \cw{finger} port, then you should be able to run commands
2006 such as \c{finger fred@127.0.0.5}. This can be useful if the program
2007 connecting to the forwarded port doesn't allow you to change the
2008 port number it uses. This feature is available for local-to-remote
2009 forwarded ports; SSH1 is unable to support it for remote-to-local
2010 ports, while SSH2 can support it in theory but servers will not
2011 necessarily cooperate.
2013 \S{config-ssh-portfwd-localhost} Controlling the visibility of
2016 \cfg{winhelp-topic}{ssh.tunnels.portfwd.localhost}
2018 The source port for a forwarded connection usually does not accept
2019 connections from any machine except the SSH client or server machine
2020 itself (for local and remote forwardings respectively). There are
2021 controls in the Tunnels panel to change this:
2023 \b The \q{Local ports accept connections from other hosts} option
2024 allows you to set up local-to-remote port forwardings in such a way
2025 that machines other than your client PC can connect to the forwarded
2028 \b The \q{Remote ports do the same} option does the same thing for
2029 remote-to-local port forwardings (so that machines other than the
2030 SSH server machine can connect to the forwarded port.) Note that
2031 this feature is only available in the SSH 2 protocol, and not all
2032 SSH 2 servers support it (OpenSSH 3.0 does not, for example).
2034 \H{config-ssh-bugs} The Bugs panel
2036 Not all SSH servers work properly. Various existing servers have
2037 bugs in them, which can make it impossible for a client to talk to
2038 them unless it knows about the bug and works around it.
2040 Since most servers announce their software version number at the
2041 beginning of the SSH connection, PuTTY will attempt to detect which
2042 bugs it can expect to see in the server and automatically enable
2043 workarounds. However, sometimes it will make mistakes; if the server
2044 has been deliberately configured to conceal its version number, or
2045 if the server is a version which PuTTY's bug database does not know
2046 about, then PuTTY will not know what bugs to expect.
2048 The Bugs panel allows you to manually configure the bugs PuTTY
2049 expects to see in the server. Each bug can be configured in three
2052 \b \q{Off}: PuTTY will assume the server does not have the bug.
2054 \b \q{On}: PuTTY will assume the server \e{does} have the bug.
2056 \b \q{Auto}: PuTTY will use the server's version number announcement
2057 to try to guess whether or not the server has the bug.
2059 \S{config-ssh-bug-ignore1} \q{Chokes on SSH1 ignore messages}
2061 \cfg{winhelp-topic}{ssh.bugs.ignore1}
2063 An ignore message (SSH_MSG_IGNORE) is a message in the SSH protocol
2064 which can be sent from the client to the server, or from the server
2065 to the client, at any time. Either side is required to ignore the
2066 message whenever it receives it. PuTTY uses ignore messages to hide
2067 the password packet in SSH1, so that a listener cannot tell the
2068 length of the user's password; it also uses ignore messages for
2069 connection keepalives (see \k{config-keepalive}).
2071 If this bug is detected, PuTTY will stop using ignore messages. This
2072 means that keepalives will stop working, and PuTTY will have to fall
2073 back to a secondary defence against SSH1 password-length
2074 eavesdropping. See \k{config-ssh-bug-plainpw1}. If this bug is
2075 enabled when talking to a correct server, the session will succeed,
2076 but keepalives will not work and the session might be more
2077 vulnerable to eavesdroppers than it could be.
2079 This is an SSH1-specific bug. No known SSH2 server fails to deal
2080 with SSH2 ignore messages.
2082 \S{config-ssh-bug-plainpw1} \q{Refuses all SSH1 password camouflage}
2084 \cfg{winhelp-topic}{ssh.bugs.plainpw1}
2086 When talking to an SSH1 server which cannot deal with ignore
2087 messages (see \k{config-ssh-bug-ignore1}), PuTTY will attempt to
2088 disguise the length of the user's password by sending additional
2089 padding \e{within} the password packet. This is technically a
2090 violation of the SSH1 specification, and so PuTTY will only do it
2091 when it cannot use standards-compliant ignore messages as
2092 camouflage. In this sense, for a server to refuse to accept a padded
2093 password packet is not really a bug, but it does make life
2094 inconvenient if the server can also not handle ignore messages.
2096 If this \q{bug} is detected, PuTTY will have no choice but to send
2097 the user's password with no form of camouflage, so that an
2098 eavesdropping user will be easily able to find out the exact length
2099 of the password. If this bug is enabled when talking to a correct
2100 server, the session will succeed, but will be more vulnerable to
2101 eavesdroppers than it could be.
2103 This is an SSH1-specific bug. SSH2 is secure against this type of
2106 \S{config-ssh-bug-rsa1} \q{Chokes on SSH1 RSA authentication}
2108 \cfg{winhelp-topic}{ssh.bugs.rsa1}
2110 Some SSH1 servers cannot deal with RSA authentication messages at
2111 all. If Pageant is running and contains any SSH1 keys, PuTTY will
2112 normally automatically try RSA authentication before falling back to
2113 passwords, so these servers will crash when they see the RSA attempt.
2115 If this bug is detected, PuTTY will go straight to password
2116 authentication. If this bug is enabled when talking to a correct
2117 server, the session will succeed, but of course RSA authentication
2120 This is an SSH1-specific bug.
2122 \S{config-ssh-bug-hmac2} \q{Miscomputes SSH2 HMAC keys}
2124 \cfg{winhelp-topic}{ssh.bugs.hmac2}
2126 Versions 2.3.0 and below of the SSH server software from
2127 \cw{ssh.com} compute the keys for their HMAC message authentication
2128 codes incorrectly. A typical symptom of this problem is that PuTTY
2129 dies unexpectedly at the beginning of the session, saying
2130 \q{Incorrect MAC received on packet}.
2132 If this bug is detected, PuTTY will compute its HMAC keys in the
2133 same way as the buggy server, so that communication will still be
2134 possible. If this bug is enabled when talking to a correct server,
2135 communication will fail.
2137 This is an SSH2-specific bug.
2139 \S{config-ssh-bug-derivekey2} \q{Miscomputes SSH2 encryption keys}
2141 \cfg{winhelp-topic}{ssh.bugs.derivekey2}
2143 Versions below 2.0.11 of the SSH server software from \cw{ssh.com}
2144 compute the keys for the session encryption incorrectly. This
2145 problem can cause various error messages, such as \q{Incoming packet
2146 was garbled on decryption}, or possibly even \q{Out of memory}.
2148 If this bug is detected, PuTTY will compute its encryption keys in
2149 the same way as the buggy server, so that communication will still
2150 be possible. If this bug is enabled when talking to a correct
2151 server, communication will fail.
2153 This is an SSH2-specific bug.
2155 \S{config-ssh-bug-sig} \q{Requires padding on SSH2 RSA signatures}
2157 \cfg{winhelp-topic}{ssh.bugs.rsapad2}
2159 Versions below 3.3 of OpenSSH require SSH2 RSA signatures to be
2160 padded with zero bytes to the same length as the RSA key modulus.
2161 The SSH2 draft specification says that an unpadded signature MUST be
2162 accepted, so this is a bug. A typical symptom of this problem is
2163 that PuTTY mysteriously fails RSA authentication once in every few
2164 hundred attempts, and falls back to passwords.
2166 If this bug is detected, PuTTY will pad its signatures in the way
2167 OpenSSH expects. If this bug is enabled when talking to a correct
2168 server, it is likely that no damage will be done, since correct
2169 servers usually still accept padded signatures because they're used
2170 to talking to OpenSSH.
2172 This is an SSH2-specific bug.
2174 \S{config-ssh-bug-dhgex} \q{Chokes on Diffie-Hellman group exchange}
2176 \cfg{winhelp-topic}{ssh.bugs.dhgex2}
2178 We have anecdotal evidence that some SSH servers claim to be able to
2179 perform Diffie-Hellman group exchange, but fail to actually do so
2180 when PuTTY tries to. If your SSH2 sessions spontaneously close
2181 immediately after opening the PuTTY window, it might be worth
2182 enabling the workaround for this bug to see if it helps.
2184 We have no hard evidence that any specific version of specific
2185 server software reliably demonstrates this bug. Therefore, PuTTY
2186 will never \e{assume} a server has this bug; if you want the
2187 workaround, you need to enable it manually.
2189 This is an SSH2-specific bug.
2191 \S{config-ssh-bug-pksessid2} \q{Misuses the session ID in PK auth}
2193 \cfg{winhelp-topic}{ssh.bugs.pksessid2}
2195 Versions below 2.3 of OpenSSH require SSH2 public-key authentication
2196 to be done slightly differently: the data to be signed by the client
2197 contains the session ID formatted in a different way. If public-key
2198 authentication mysteriously does not work but the Event Log (see
2199 \k{using-eventlog}) thinks it has successfully sent a signature, it
2200 might be worth enabling the workaround for this bug to see if it
2203 If this bug is detected, PuTTY will sign data in the way OpenSSH
2204 expects. If this bug is enabled when talking to a correct server,
2205 SSH2 public-key authentication will fail.
2207 This is an SSH2-specific bug.
2209 \H{config-file} Storing configuration in a file
2211 PuTTY does not currently support storing its configuration in a file
2212 instead of the Registry. However, you can work around this with a
2213 couple of batch files.
2215 You will need a file called (say) \c{PUTTY.BAT} which imports the
2216 contents of a file into the Registry, then runs PuTTY, exports the
2217 contents of the Registry back into the file, and deletes the
2218 Registry entries. This can all be done using the Regedit command
2219 line options, so it's all automatic. Here is what you need in
2223 \c regedit /s putty.reg
2224 \c regedit /s puttyrnd.reg
2225 \c start /w putty.exe
2226 \c regedit /e puttynew.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
2227 \c copy puttynew.reg putty.reg
2229 \c regedit /s puttydel.reg
2231 This batch file needs two auxiliary files: \c{PUTTYRND.REG} which
2232 sets up an initial safe location for the \c{PUTTY.RND} random seed
2233 file, and \c{PUTTYDEL.REG} which destroys everything in the Registry
2234 once it's been successfully saved back to the file.
2236 Here is \c{PUTTYDEL.REG}:
2240 \c [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
2242 Here is an example \c{PUTTYRND.REG} file:
2246 \c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
2247 \c "RandSeedFile"="a:\putty.rnd"
2249 You should replace \c{a:\\putty.rnd} with the location where you
2250 want to store your random number data. If the aim is to carry around
2251 PuTTY and its settings on one floppy, you probably want to store it