1 \define{versionidconfig} \versionid $Id$
3 \C{config} Configuring PuTTY
5 This chapter describes all the \i{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 \i{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 \i{IP
26 address}, of the server you want to connect to.
28 \b The \q{Connection type} radio buttons let you choose what type of
29 connection you want to make: a \I{raw TCP connections}raw
30 connection, a \i{Telnet} connection, an \i{Rlogin} connection, an
31 \i{SSH} connection, or a connection to a local \i{serial line}. (See
32 \k{which-one} for a summary of the differences between SSH, Telnet
33 and rlogin; see \k{using-rawprot} for an explanation of \q{raw}
34 connections; see \k{using-serial} for information about using a
37 \b The \q{Port} box lets you specify which \i{port number} on the
38 server to connect to. If you select Telnet, Rlogin, or SSH, this box
39 will be filled in automatically to the usual value, and you will
40 only need to change it if you have an unusual server. If you select
41 Raw mode, you will almost certainly need to fill in the \q{Port} box
44 If you select \q{Serial} from the \q{Connection type} radio buttons,
45 the \q{Host Name} and \q{Port} boxes are replaced by \q{Serial line}
46 and \q{Speed}; see \k{config-serial} for more details of these.
48 \S{config-saving} \ii{Loading and storing saved sessions}
50 \cfg{winhelp-topic}{session.saved}
52 The next part of the Session configuration panel allows you to save
53 your preferred PuTTY options so they will appear automatically the
54 next time you start PuTTY. It also allows you to create \e{saved
55 sessions}, which contain a full set of configuration options plus a
56 host name and protocol. A saved session contains all the information
57 PuTTY needs to start exactly the session you want.
59 \b To save your default settings: first set up the settings the way
60 you want them saved. Then come back to the Session panel. Select the
61 \q{\i{Default Settings}} entry in the saved sessions list, with a single
62 click. Then press the \q{Save} button.
65 Note that PuTTY does not allow you to save a host name into the
66 Default Settings entry. This ensures that when PuTTY is started up,
67 the host name box is always empty, so a user can always just type in
68 a host name and connect.
71 If there is a specific host you want to store the details of how to
72 connect to, you should create a saved session, which will be
73 separate from the Default Settings.
75 \b To save a session: first go through the rest of the configuration
76 box setting up all the options you want. Then come back to the
77 Session panel. Enter a name for the saved session in the \q{Saved
78 Sessions} input box. (The server name is often a good choice for a
79 saved session name.) Then press the \q{Save} button. Your saved
80 session name should now appear in the list box.
83 You can also save settings in mid-session, from the \q{Change Settings}
84 dialog. Settings changed since the start of the session will be saved
85 with their current values; as well as settings changed through the
86 dialog, this includes changes in window size, window title changes
87 sent by the server, and so on.
90 \b To reload a saved session: single-click to select the session
91 name in the list box, and then press the \q{Load} button. Your saved
92 settings should all appear in the configuration panel.
94 \b To modify a saved session: first load it as described above. Then
95 make the changes you want. Come back to the Session panel, and press
96 the \q{Save} button. The new settings will be saved over the top of
100 To save the new settings under a different name, you can enter the new
101 name in the \q{Saved Sessions} box, or single-click to select a
102 session name in the list box to overwrite that session. To save
103 \q{Default Settings}, you must single-click the name before saving.
106 \b To start a saved session immediately: double-click on the session
107 name in the list box.
109 \b To delete a saved session: single-click to select the session
110 name in the list box, and then press the \q{Delete} button.
112 Each saved session is independent of the Default Settings
113 configuration. If you change your preferences and update Default
114 Settings, you must also update every saved session separately.
116 Saved sessions are stored in the \i{Registry}, at the location
118 \c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\Sessions
120 If you need to store them in a file, you could try the method
121 described in \k{config-file}.
123 \S{config-closeonexit} \q{\ii{Close Window} on Exit}
125 \cfg{winhelp-topic}{session.coe}
127 Finally in the Session panel, there is an option labelled \q{Close
128 Window on Exit}. This controls whether the PuTTY \i{terminal window}
129 disappears as soon as the session inside it terminates. If you are
130 likely to want to copy and paste text out of the session after it
131 has terminated, or restart the session, you should arrange for this
134 \q{Close Window On Exit} has three settings. \q{Always} means always
135 close the window on exit; \q{Never} means never close on exit
136 (always leave the window open, but \I{inactive window}inactive). The
137 third setting, and the default one, is \q{Only on clean exit}. In this
138 mode, a session which terminates normally will cause its window to
139 close, but one which is aborted unexpectedly by network trouble or a
140 confusing message from the server will leave the window up.
142 \H{config-logging} The Logging panel
144 \cfg{winhelp-topic}{logging.main}
146 The Logging configuration panel allows you to save \i{log file}s of your
147 PuTTY sessions, for debugging, analysis or future reference.
149 The main option is a radio-button set that specifies whether PuTTY
150 will log anything at all. The options are:
152 \b \q{None}. This is the default option; in this mode PuTTY will not
153 create a log file at all.
155 \b \q{Printable output}. In this mode, a log file will be
156 created and written to, but only printable text will be saved into
157 it. The various terminal control codes that are typically sent down
158 an interactive session alongside the printable text will be omitted.
159 This might be a useful mode if you want to read a log file in a text
160 editor and hope to be able to make sense of it.
162 \b \q{All session output}. In this mode, \e{everything} sent by
163 the server into your terminal session is logged. If you view the log
164 file in a text editor, therefore, you may well find it full of
165 strange control characters. This is a particularly useful mode if
166 you are experiencing problems with PuTTY's terminal handling: you
167 can record everything that went to the terminal, so that someone
168 else can replay the session later in slow motion and watch to see
171 \b \I{SSH packet log}\q{SSH packets}. In this mode (which is only used
172 by SSH connections), the SSH message packets sent over the encrypted
173 connection are written to the log file (as well as \i{Event Log}
174 entries). You might need this to debug a network-level problem, or
175 more likely to send to the PuTTY authors as part of a bug report.
176 \e{BE WARNED} that if you log in using a password, the password can
177 appear in the log file; see \k{config-logssh} for options that may
178 help to remove sensitive material from the log file before you send it
181 \b \q{SSH packets and raw data}. In this mode, as well as the
182 decrypted packets (as in the previous mode), the \e{raw} (encrypted,
183 compressed, etc) packets are \e{also} logged. This could be useful to
184 diagnose corruption in transit. (The same caveats as the previous mode
187 \S{config-logfilename} \q{Log file name}
189 \cfg{winhelp-topic}{logging.filename}
191 In this edit box you enter the name of the file you want to log the
192 session to. The \q{Browse} button will let you look around your file
193 system to find the right place to put the file; or if you already
194 know exactly where you want it to go, you can just type a pathname
197 There are a few special features in this box. If you use the \c{&}
198 character in the file name box, PuTTY will insert details of the
199 current session in the name of the file it actually opens. The
200 precise replacements it will do are:
202 \b \c{&Y} will be replaced by the current year, as four digits.
204 \b \c{&M} will be replaced by the current month, as two digits.
206 \b \c{&D} will be replaced by the current day of the month, as two
209 \b \c{&T} will be replaced by the current time, as six digits
210 (HHMMSS) with no punctuation.
212 \b \c{&H} will be replaced by the host name you are connecting to.
214 For example, if you enter the host name
215 \c{c:\\puttylogs\\log-&h-&y&m&d-&t.dat}, you will end up with files looking
218 \c log-server1.example.com-20010528-110859.dat
219 \c log-unixbox.somewhere.org-20010611-221001.dat
221 \S{config-logfileexists} \q{What to do if the log file already exists}
223 \cfg{winhelp-topic}{logging.exists}
225 This control allows you to specify what PuTTY should do if it tries
226 to start writing to a log file and it finds the file already exists.
227 You might want to automatically destroy the existing log file and
228 start a new one with the same name. Alternatively, you might want to
229 open the existing log file and add data to the \e{end} of it.
230 Finally (the default option), you might not want to have any
231 automatic behaviour, but to ask the user every time the problem
234 \S{config-logflush} \I{log file, flushing}\q{Flush log file frequently}
236 \cfg{winhelp-topic}{logging.flush}
238 This option allows you to control how frequently logged data is
239 flushed to disc. By default, PuTTY will flush data as soon as it is
240 displayed, so that if you view the log file while a session is still
241 open, it will be up to date; and if the client system crashes, there's
242 a greater chance that the data will be preserved.
244 However, this can incur a performance penalty. If PuTTY is running
245 slowly with logging enabled, you could try unchecking this option. Be
246 warned that the log file may not always be up to date as a result
247 (although it will of course be flushed when it is closed, for instance
248 at the end of a session).
250 \S{config-logssh} Options specific to \i{SSH packet log}ging
252 These options only apply if SSH packet data is being logged.
254 The following options allow particularly sensitive portions of
255 unencrypted packets to be automatically left out of the log file.
256 They are only intended to deter casual nosiness; an attacker could
257 glean a lot of useful information from even these obfuscated logs
258 (e.g., length of password).
260 \S2{config-logssh-omitpw} \q{Omit known password fields}
262 \cfg{winhelp-topic}{logging.ssh.omitpassword}
264 When checked, decrypted password fields are removed from the log of
265 transmitted packets. (This includes any user responses to
266 challenge-response authentication methods such as
267 \q{keyboard-interactive}.) This does not include X11 authentication
268 data if using X11 forwarding.
270 Note that this will only omit data that PuTTY \e{knows} to be a
271 password. However, if you start another login session within your
272 PuTTY session, for instance, any password used will appear in the
273 clear in the packet log. The next option may be of use to protect
276 This option is enabled by default.
278 \S2{config-logssh-omitdata} \q{Omit session data}
280 \cfg{winhelp-topic}{logging.ssh.omitdata}
282 When checked, all decrypted \q{session data} is omitted; this is
283 defined as data in terminal sessions and in forwarded channels (TCP,
284 X11, and authentication agent). This will usually substantially reduce
285 the size of the resulting log file.
287 This option is disabled by default.
289 \H{config-terminal} The Terminal panel
291 The Terminal configuration panel allows you to control the behaviour
292 of PuTTY's \i{terminal emulation}.
294 \S{config-autowrap} \q{Auto wrap mode initially on}
296 \cfg{winhelp-topic}{terminal.autowrap}
298 \ii{Auto wrap mode} controls what happens when text printed in a PuTTY
299 window reaches the right-hand edge of the window.
301 With auto wrap mode on, if a long line of text reaches the
302 right-hand edge, it will wrap over on to the next line so you can
303 still see all the text. With auto wrap mode off, the cursor will
304 stay at the right-hand edge of the screen, and all the characters in
305 the line will be printed on top of each other.
307 If you are running a full-screen application and you occasionally
308 find the screen scrolling up when it looks as if it shouldn't, you
309 could try turning this option off.
311 Auto wrap mode can be turned on and off by \i{control sequence}s sent by
312 the server. This configuration option controls the \e{default}
313 state, which will be restored when you reset the terminal (see
314 \k{reset-terminal}). However, if you modify this option in
315 mid-session using \q{Change Settings}, it will take effect
318 \S{config-decom} \q{DEC Origin Mode initially on}
320 \cfg{winhelp-topic}{terminal.decom}
322 \i{DEC Origin Mode} is a minor option which controls how PuTTY
323 interprets cursor-position \i{control sequence}s sent by the server.
325 The server can send a control sequence that restricts the \i{scrolling
326 region} of the display. For example, in an editor, the server might
327 reserve a line at the top of the screen and a line at the bottom,
328 and might send a control sequence that causes scrolling operations
329 to affect only the remaining lines.
331 With DEC Origin Mode on, \i{cursor coordinates} are counted from the top
332 of the scrolling region. With it turned off, cursor coordinates are
333 counted from the top of the whole screen regardless of the scrolling
336 It is unlikely you would need to change this option, but if you find
337 a full-screen application is displaying pieces of text in what looks
338 like the wrong part of the screen, you could try turning DEC Origin
339 Mode on to see whether that helps.
341 DEC Origin Mode can be turned on and off by control sequences sent
342 by the server. This configuration option controls the \e{default}
343 state, which will be restored when you reset the terminal (see
344 \k{reset-terminal}). However, if you modify this option in
345 mid-session using \q{Change Settings}, it will take effect
348 \S{config-crlf} \q{Implicit CR in every LF}
350 \cfg{winhelp-topic}{terminal.lfhascr}
352 Most servers send two control characters, \i{CR} and \i{LF}, to start a
353 \i{new line} of the screen. The CR character makes the cursor return to the
354 left-hand side of the screen. The LF character makes the cursor move
355 one line down (and might make the screen scroll).
357 Some servers only send LF, and expect the terminal to move the
358 cursor over to the left automatically. If you come across a server
359 that does this, you will see a \I{stair-stepping}stepped effect on the
362 \c First line of text
366 If this happens to you, try enabling the \q{Implicit CR in every LF}
367 option, and things might go back to normal:
369 \c First line of text
373 \S{config-erase} \q{Use \i{background colour} to erase screen}
375 \cfg{winhelp-topic}{terminal.bce}
377 Not all terminals agree on what colour to turn the screen when the
378 server sends a \q{\i{clear screen}} sequence. Some terminals believe the
379 screen should always be cleared to the \e{default} background
380 colour. Others believe the screen should be cleared to whatever the
381 server has selected as a background colour.
383 There exist applications that expect both kinds of behaviour.
384 Therefore, PuTTY can be configured to do either.
386 With this option disabled, screen clearing is always done in the
387 default background colour. With this option enabled, it is done in
388 the \e{current} background colour.
390 Background-colour erase can be turned on and off by \i{control
391 sequences} sent by the server. This configuration option controls the
392 \e{default} state, which will be restored when you reset the
393 terminal (see \k{reset-terminal}). However, if you modify this
394 option in mid-session using \q{Change Settings}, it will take effect
397 \S{config-blink} \q{Enable \i{blinking text}}
399 \cfg{winhelp-topic}{terminal.blink}
401 The server can ask PuTTY to display text that blinks on and off.
402 This is very distracting, so PuTTY allows you to turn blinking text
405 When blinking text is disabled and the server attempts to make some
406 text blink, PuTTY will instead display the text with a \I{background
407 colour, bright}bolded background colour.
409 Blinking text can be turned on and off by \i{control sequence}s sent by
410 the server. This configuration option controls the \e{default}
411 state, which will be restored when you reset the terminal (see
412 \k{reset-terminal}). However, if you modify this option in
413 mid-session using \q{Change Settings}, it will take effect
416 \S{config-answerback} \q{\ii{Answerback} to ^E}
418 \cfg{winhelp-topic}{terminal.answerback}
420 This option controls what PuTTY will send back to the server if the
421 server sends it the ^E \i{enquiry character}. Normally it just sends
422 the string \q{PuTTY}.
424 If you accidentally write the contents of a binary file to your
425 terminal, you will probably find that it contains more than one ^E
426 character, and as a result your next command line will probably read
427 \q{PuTTYPuTTYPuTTY...} as if you had typed the answerback string
428 multiple times at the keyboard. If you set the answerback string to
429 be empty, this problem should go away, but doing so might cause
432 Note that this is \e{not} the feature of PuTTY which the server will
433 typically use to determine your terminal type. That feature is the
434 \q{\ii{Terminal-type} string} in the Connection panel; see
435 \k{config-termtype} for details.
437 You can include control characters in the answerback string using
438 \c{^C} notation. (Use \c{^~} to get a literal \c{^}.)
440 \S{config-localecho} \q{\ii{Local echo}}
442 \cfg{winhelp-topic}{terminal.localecho}
444 With local echo disabled, characters you type into the PuTTY window
445 are not echoed in the window \e{by PuTTY}. They are simply sent to
446 the server. (The \e{server} might choose to \I{remote echo}echo them
447 back to you; this can't be controlled from the PuTTY control panel.)
449 Some types of session need local echo, and many do not. In its
450 default mode, PuTTY will automatically attempt to deduce whether or
451 not local echo is appropriate for the session you are working in. If
452 you find it has made the wrong decision, you can use this
453 configuration option to override its choice: you can force local
454 echo to be turned on, or force it to be turned off, instead of
455 relying on the automatic detection.
457 \S{config-localedit} \q{\ii{Local line editing}}
459 \cfg{winhelp-topic}{terminal.localedit}
461 Normally, every character you type into the PuTTY window is sent
462 immediately to the server the moment you type it.
464 If you enable local line editing, this changes. PuTTY will let you
465 edit a whole line at a time locally, and the line will only be sent
466 to the server when you press Return. If you make a mistake, you can
467 use the Backspace key to correct it before you press Return, and the
468 server will never see the mistake.
470 Since it is hard to edit a line locally without being able to see
471 it, local line editing is mostly used in conjunction with \i{local echo}
472 (\k{config-localecho}). This makes it ideal for use in raw mode
473 \#{FIXME} or when connecting to \i{MUD}s or \i{talker}s. (Although some more
474 advanced MUDs do occasionally turn local line editing on and turn
475 local echo off, in order to accept a password from the user.)
477 Some types of session need local line editing, and many do not. In
478 its default mode, PuTTY will automatically attempt to deduce whether
479 or not local line editing is appropriate for the session you are
480 working in. If you find it has made the wrong decision, you can use
481 this configuration option to override its choice: you can force
482 local line editing to be turned on, or force it to be turned off,
483 instead of relying on the automatic detection.
485 \S{config-printing} \ii{Remote-controlled printing}
487 \cfg{winhelp-topic}{terminal.printing}
489 A lot of VT100-compatible terminals support printing under control
490 of the remote server. PuTTY supports this feature as well, but it is
491 turned off by default.
493 To enable remote-controlled printing, choose a printer from the
494 \q{Printer to send ANSI printer output to} drop-down list box. This
495 should allow you to select from all the printers you have installed
496 drivers for on your computer. Alternatively, you can type the
497 network name of a networked printer (for example,
498 \c{\\\\printserver\\printer1}) even if you haven't already
499 installed a driver for it on your own machine.
501 When the remote server attempts to print some data, PuTTY will send
502 that data to the printer \e{raw} - without translating it,
503 attempting to format it, or doing anything else to it. It is up to
504 you to ensure your remote server knows what type of printer it is
507 Since PuTTY sends data to the printer raw, it cannot offer options
508 such as portrait versus landscape, print quality, or paper tray
509 selection. All these things would be done by your PC printer driver
510 (which PuTTY bypasses); if you need them done, you will have to find
511 a way to configure your remote server to do them.
513 To disable remote printing again, choose \q{None (printing
514 disabled)} from the printer selection list. This is the default
517 \H{config-keyboard} The Keyboard panel
519 The Keyboard configuration panel allows you to control the behaviour
520 of the \i{keyboard} in PuTTY. The correct state for many of these
521 settings depends on what the server to which PuTTY is connecting
522 expects. With a \i{Unix} server, this is likely to depend on the
523 \i\c{termcap} or \i\c{terminfo} entry it uses, which in turn is likely to
524 be controlled by the \q{\ii{Terminal-type} string} setting in the Connection
525 panel; see \k{config-termtype} for details. If none of the settings here
526 seems to help, you may find \k{faq-keyboard} to be useful.
528 \S{config-backspace} Changing the action of the \ii{Backspace key}
530 \cfg{winhelp-topic}{keyboard.backspace}
532 Some terminals believe that the Backspace key should send the same
533 thing to the server as \i{Control-H} (ASCII code 8). Other terminals
534 believe that the Backspace key should send ASCII code 127 (usually
535 known as \i{Control-?}) so that it can be distinguished from Control-H.
536 This option allows you to choose which code PuTTY generates when you
539 If you are connecting over SSH, PuTTY by default tells the server
540 the value of this option (see \k{config-ttymodes}), so you may find
541 that the Backspace key does the right thing either way. Similarly,
542 if you are connecting to a \i{Unix} system, you will probably find that
543 the Unix \i\c{stty} command lets you configure which the server
544 expects to see, so again you might not need to change which one PuTTY
545 generates. On other systems, the server's expectation might be fixed
546 and you might have no choice but to configure PuTTY.
548 If you do have the choice, we recommend configuring PuTTY to
549 generate Control-? and configuring the server to expect it, because
550 that allows applications such as \c{emacs} to use Control-H for
553 (Typing \i{Shift-Backspace} will cause PuTTY to send whichever code
554 isn't configured here as the default.)
556 \S{config-homeend} Changing the action of the \i{Home and End keys}
558 \cfg{winhelp-topic}{keyboard.homeend}
560 The Unix terminal emulator \i\c{rxvt} disagrees with the rest of the
561 world about what character sequences should be sent to the server by
562 the Home and End keys.
564 \i\c{xterm}, and other terminals, send \c{ESC [1~} for the Home key,
565 and \c{ESC [4~} for the End key. \c{rxvt} sends \c{ESC [H} for the
566 Home key and \c{ESC [Ow} for the End key.
568 If you find an application on which the Home and End keys aren't
569 working, you could try switching this option to see if it helps.
571 \S{config-funkeys} Changing the action of the \i{function keys} and
574 \cfg{winhelp-topic}{keyboard.funkeys}
576 This option affects the function keys (F1 to F12) and the top row of
579 \b In the default mode, labelled \c{ESC [n~}, the function keys
580 generate sequences like \c{ESC [11~}, \c{ESC [12~} and so on. This
581 matches the general behaviour of Digital's terminals.
583 \b In Linux mode, F6 to F12 behave just like the default mode, but
584 F1 to F5 generate \c{ESC [[A} through to \c{ESC [[E}. This mimics the
585 \i{Linux virtual console}.
587 \b In \I{xterm}Xterm R6 mode, F5 to F12 behave like the default mode, but F1
588 to F4 generate \c{ESC OP} through to \c{ESC OS}, which are the
589 sequences produced by the top row of the \e{keypad} on Digital's
592 \b In \i{VT400} mode, all the function keys behave like the default
593 mode, but the actual top row of the numeric keypad generates \c{ESC
594 OP} through to \c{ESC OS}.
596 \b In \i{VT100+} mode, the function keys generate \c{ESC OP} through to
599 \b In \i{SCO} mode, the function keys F1 to F12 generate \c{ESC [M}
600 through to \c{ESC [X}. Together with shift, they generate \c{ESC [Y}
601 through to \c{ESC [j}. With control they generate \c{ESC [k} through
602 to \c{ESC [v}, and with shift and control together they generate
603 \c{ESC [w} through to \c{ESC [\{}.
605 If you don't know what any of this means, you probably don't need to
608 \S{config-appcursor} Controlling \i{Application Cursor Keys} mode
610 \cfg{winhelp-topic}{keyboard.appcursor}
612 Application Cursor Keys mode is a way for the server to change the
613 control sequences sent by the arrow keys. In normal mode, the arrow
614 keys send \c{ESC [A} through to \c{ESC [D}. In application mode,
615 they send \c{ESC OA} through to \c{ESC OD}.
617 Application Cursor Keys mode can be turned on and off by the server,
618 depending on the application. PuTTY allows you to configure the
621 You can also disable application cursor keys mode completely, using
622 the \q{Features} configuration panel; see
623 \k{config-features-application}.
625 \S{config-appkeypad} Controlling \i{Application Keypad} mode
627 \cfg{winhelp-topic}{keyboard.appkeypad}
629 Application Keypad mode is a way for the server to change the
630 behaviour of the numeric keypad.
632 In normal mode, the keypad behaves like a normal Windows keypad:
633 with \i{NumLock} on, the number keys generate numbers, and with NumLock
634 off they act like the arrow keys and Home, End etc.
636 In application mode, all the keypad keys send special control
637 sequences, \e{including} Num Lock. Num Lock stops behaving like Num
638 Lock and becomes another function key.
640 Depending on which version of Windows you run, you may find the Num
641 Lock light still flashes on and off every time you press Num Lock,
642 even when application mode is active and Num Lock is acting like a
643 function key. This is unavoidable.
645 Application keypad mode can be turned on and off by the server,
646 depending on the application. PuTTY allows you to configure the
649 You can also disable application keypad mode completely, using the
650 \q{Features} configuration panel; see
651 \k{config-features-application}.
653 \S{config-nethack} Using \i{NetHack keypad mode}
655 \cfg{winhelp-topic}{keyboard.nethack}
657 PuTTY has a special mode for playing NetHack. You can enable it by
658 selecting \q{NetHack} in the \q{Initial state of numeric keypad}
661 In this mode, the numeric keypad keys 1-9 generate the NetHack
662 movement commands (\cw{hjklyubn}). The 5 key generates the \c{.}
663 command (do nothing).
665 In addition, pressing Shift or Ctrl with the keypad keys generate
666 the Shift- or Ctrl-keys you would expect (e.g. keypad-7 generates
667 \cq{y}, so Shift-keypad-7 generates \cq{Y} and Ctrl-keypad-7
668 generates Ctrl-Y); these commands tell NetHack to keep moving you in
669 the same direction until you encounter something interesting.
671 For some reason, this feature only works properly when \i{Num Lock} is
672 on. We don't know why.
674 \S{config-compose} Enabling a DEC-like \ii{Compose key}
676 \cfg{winhelp-topic}{keyboard.compose}
678 DEC terminals have a Compose key, which provides an easy-to-remember
679 way of typing \i{accented characters}. You press Compose and then type
680 two more characters. The two characters are \q{combined} to produce
681 an accented character. The choices of character are designed to be
682 easy to remember; for example, composing \q{e} and \q{`} produces
683 the \q{\u00e8{e-grave}} character.
685 If your keyboard has a Windows \i{Application key}, it acts as a Compose
686 key in PuTTY. Alternatively, if you enable the \q{\i{AltGr} acts as
687 Compose key} option, the AltGr key will become a Compose key.
689 \S{config-ctrlalt} \q{Control-Alt is different from \i{AltGr}}
691 \cfg{winhelp-topic}{keyboard.ctrlalt}
693 Some old keyboards do not have an AltGr key, which can make it
694 difficult to type some characters. PuTTY can be configured to treat
695 the key combination Ctrl + Left Alt the same way as the AltGr key.
697 By default, this checkbox is checked, and the key combination Ctrl +
698 Left Alt does something completely different. PuTTY's usual handling
699 of the left Alt key is to prefix the Escape (Control-\cw{[})
700 character to whatever character sequence the rest of the keypress
701 would generate. For example, Alt-A generates Escape followed by
702 \c{a}. So Alt-Ctrl-A would generate Escape, followed by Control-A.
704 If you uncheck this box, Ctrl-Alt will become a synonym for AltGr,
705 so you can use it to type extra graphic characters if your keyboard
708 (However, Ctrl-Alt will never act as a Compose key, regardless of the
709 setting of \q{AltGr acts as Compose key} described in
712 \H{config-bell} The Bell panel
714 The Bell panel controls the \i{terminal bell} feature: the server's
715 ability to cause PuTTY to beep at you.
717 In the default configuration, when the server sends the character
718 with ASCII code 7 (Control-G), PuTTY will play the \i{Windows Default
719 Beep} sound. This is not always what you want the terminal bell
720 feature to do; the Bell panel allows you to configure alternative
723 \S{config-bellstyle} \q{Set the style of bell}
725 \cfg{winhelp-topic}{bell.style}
727 This control allows you to select various different actions to occur
730 \b Selecting \q{None} \I{terminal bell, disabling}disables the bell
731 completely. In this mode, the server can send as many Control-G
732 characters as it likes and nothing at all will happen.
734 \b \q{Make default system alert sound} is the default setting. It
735 causes the Windows \q{Default Beep} sound to be played. To change
736 what this sound is, or to test it if nothing seems to be happening,
737 use the Sound configurer in the Windows Control Panel.
739 \b \q{\ii{Visual bell}} is a silent alternative to a beeping computer. In
740 this mode, when the server sends a Control-G, the whole PuTTY window
741 will flash white for a fraction of a second.
743 \b \q{Beep using the \i{PC speaker}} is self-explanatory.
745 \b \q{Play a custom \i{sound file}} allows you to specify a particular
746 sound file to be used by PuTTY alone, or even by a particular
747 individual PuTTY session. This allows you to distinguish your PuTTY
748 beeps from any other beeps on the system. If you select this option,
749 you will also need to enter the name of your sound file in the edit
750 control \q{Custom sound file to play as a bell}.
752 \S{config-belltaskbar} \q{\ii{Taskbar}/\I{window caption}caption
755 \cfg{winhelp-topic}{bell.taskbar}
757 This feature controls what happens to the PuTTY window's entry in
758 the Windows Taskbar if a bell occurs while the window does not have
761 In the default state (\q{Disabled}) nothing unusual happens.
763 If you select \q{Steady}, then when a bell occurs and the window is
764 not in focus, the window's Taskbar entry and its title bar will
765 change colour to let you know that PuTTY session is asking for your
766 attention. The change of colour will persist until you select the
767 window, so you can leave several PuTTY windows minimised in your
768 terminal, go away from your keyboard, and be sure not to have missed
769 any important beeps when you get back.
771 \q{Flashing} is even more eye-catching: the Taskbar entry will
772 continuously flash on and off until you select the window.
774 \S{config-bellovl} \q{Control the \i{bell overload} behaviour}
776 \cfg{winhelp-topic}{bell.overload}
778 A common user error in a terminal session is to accidentally run the
779 Unix command \c{cat} (or equivalent) on an inappropriate file type,
780 such as an executable, image file, or ZIP file. This produces a huge
781 stream of non-text characters sent to the terminal, which typically
782 includes a lot of bell characters. As a result of this the terminal
783 often doesn't stop beeping for ten minutes, and everybody else in
784 the office gets annoyed.
786 To try to avoid this behaviour, or any other cause of excessive
787 beeping, PuTTY includes a bell overload management feature. In the
788 default configuration, receiving more than five bell characters in a
789 two-second period will cause the overload feature to activate. Once
790 the overload feature is active, further bells will \I{terminal bell,
791 disabling} have no effect at all, so the rest of your binary file
792 will be sent to the screen in silence. After a period of five seconds
793 during which no further bells are received, the overload feature will
794 turn itself off again and bells will be re-enabled.
796 If you want this feature completely disabled, you can turn it off
797 using the checkbox \q{Bell is temporarily disabled when over-used}.
799 Alternatively, if you like the bell overload feature but don't agree
800 with the settings, you can configure the details: how many bells
801 constitute an overload, how short a time period they have to arrive
802 in to do so, and how much silent time is required before the
803 overload feature will deactivate itself.
805 Bell overload mode is always deactivated by any keypress in the
806 terminal. This means it can respond to large unexpected streams of
807 data, but does not interfere with ordinary command-line activities
808 that generate beeps (such as filename completion).
810 \H{config-features} The Features panel
812 PuTTY's \i{terminal emulation} is very highly featured, and can do a lot
813 of things under remote server control. Some of these features can
814 cause problems due to buggy or strangely configured server
817 The Features configuration panel allows you to disable some of
818 PuTTY's more advanced terminal features, in case they cause trouble.
820 \S{config-features-application} Disabling application keypad and cursor keys
822 \cfg{winhelp-topic}{features.application}
824 \I{Application Keypad}Application keypad mode (see
825 \k{config-appkeypad}) and \I{Application Cursor Keys}application
826 cursor keys mode (see \k{config-appcursor}) alter the behaviour of
827 the keypad and cursor keys. Some applications enable these modes but
828 then do not deal correctly with the modified keys. You can force
829 these modes to be permanently disabled no matter what the server
832 \S{config-features-mouse} Disabling \cw{xterm}-style \i{mouse reporting}
834 \cfg{winhelp-topic}{features.mouse}
836 PuTTY allows the server to send \i{control codes} that let it take over
837 the mouse and use it for purposes other than \i{copy and paste}.
838 Applications which use this feature include the text-mode web
839 browser \i\c{links}, the Usenet newsreader \i\c{trn} version 4, and the
840 file manager \i\c{mc} (Midnight Commander).
842 If you find this feature inconvenient, you can disable it using the
843 \q{Disable xterm-style mouse reporting} control. With this box
844 ticked, the mouse will \e{always} do copy and paste in the normal
847 Note that even if the application takes over the mouse, you can
848 still manage PuTTY's copy and paste by holding down the Shift key
849 while you select and paste, unless you have deliberately turned this
850 feature off (see \k{config-mouseshift}).
852 \S{config-features-resize} Disabling remote \i{terminal resizing}
854 \cfg{winhelp-topic}{features.resize}
856 PuTTY has the ability to change the terminal's size and position in
857 response to commands from the server. If you find PuTTY is doing
858 this unexpectedly or inconveniently, you can tell PuTTY not to
859 respond to those server commands.
861 \S{config-features-altscreen} Disabling switching to the \i{alternate screen}
863 \cfg{winhelp-topic}{features.altscreen}
865 Many terminals, including PuTTY, support an \q{alternate screen}.
866 This is the same size as the ordinary terminal screen, but separate.
867 Typically a screen-based program such as a text editor might switch
868 the terminal to the alternate screen before starting up. Then at the
869 end of the run, it switches back to the primary screen, and you see
870 the screen contents just as they were before starting the editor.
872 Some people prefer this not to happen. If you want your editor to
873 run in the same screen as the rest of your terminal activity, you
874 can disable the alternate screen feature completely.
876 \S{config-features-retitle} Disabling remote \i{window title} changing
878 \cfg{winhelp-topic}{features.retitle}
880 PuTTY has the ability to change the window title in response to
881 commands from the server. If you find PuTTY is doing this
882 unexpectedly or inconveniently, you can tell PuTTY not to respond to
883 those server commands.
885 \S{config-features-qtitle} Disabling remote \i{window title} querying
887 \cfg{winhelp-topic}{features.qtitle}
889 PuTTY can optionally provide the xterm service of allowing server
890 applications to find out the local window title. This feature is
891 disabled by default, but you can turn it on if you really want it.
893 NOTE that this feature is a \e{potential \i{security hazard}}. If a
894 malicious application can write data to your terminal (for example,
895 if you merely \c{cat} a file owned by someone else on the server
896 machine), it can change your window title (unless you have disabled
897 this as mentioned in \k{config-features-retitle}) and then use this
898 service to have the new window title sent back to the server as if
899 typed at the keyboard. This allows an attacker to fake keypresses
900 and potentially cause your server-side applications to do things you
901 didn't want. Therefore this feature is disabled by default, and we
902 recommend you do not turn it on unless you \e{really} know what you
905 \S{config-features-dbackspace} Disabling \i{destructive backspace}
907 \cfg{winhelp-topic}{features.dbackspace}
909 Normally, when PuTTY receives character 127 (^?) from the server, it
910 will perform a \q{destructive backspace}: move the cursor one space
911 left and delete the character under it. This can apparently cause
912 problems in some applications, so PuTTY provides the ability to
913 configure character 127 to perform a normal backspace (without
914 deleting a character) instead.
916 \S{config-features-charset} Disabling remote \i{character set}
919 \cfg{winhelp-topic}{features.charset}
921 PuTTY has the ability to change its character set configuration in
922 response to commands from the server. Some programs send these
923 commands unexpectedly or inconveniently. In particular, \I{BitchX} (an
924 IRC client) seems to have a habit of reconfiguring the character set
925 to something other than the user intended.
927 If you find that accented characters are not showing up the way you
928 expect them to, particularly if you're running BitchX, you could try
929 disabling the remote character set configuration commands.
931 \S{config-features-shaping} Disabling \i{Arabic text shaping}
933 \cfg{winhelp-topic}{features.arabicshaping}
935 PuTTY supports shaping of Arabic text, which means that if your
936 server sends text written in the basic \i{Unicode} Arabic alphabet then
937 it will convert it to the correct display forms before printing it
940 If you are using full-screen software which was not expecting this
941 to happen (especially if you are not an Arabic speaker and you
942 unexpectedly find yourself dealing with Arabic text files in
943 applications which are not Arabic-aware), you might find that the
944 \i{display becomes corrupted}. By ticking this box, you can disable
945 Arabic text shaping so that PuTTY displays precisely the characters
946 it is told to display.
948 You may also find you need to disable bidirectional text display;
949 see \k{config-features-bidi}.
951 \S{config-features-bidi} Disabling \i{bidirectional text} display
953 \cfg{winhelp-topic}{features.bidi}
955 PuTTY supports bidirectional text display, which means that if your
956 server sends text written in a language which is usually displayed
957 from right to left (such as \i{Arabic} or \i{Hebrew}) then PuTTY will
958 automatically flip it round so that it is displayed in the right
959 direction on the screen.
961 If you are using full-screen software which was not expecting this
962 to happen (especially if you are not an Arabic speaker and you
963 unexpectedly find yourself dealing with Arabic text files in
964 applications which are not Arabic-aware), you might find that the
965 \i{display becomes corrupted}. By ticking this box, you can disable
966 bidirectional text display, so that PuTTY displays text from left to
967 right in all situations.
969 You may also find you need to disable Arabic text shaping;
970 see \k{config-features-shaping}.
972 \H{config-window} The Window panel
974 The Window configuration panel allows you to control aspects of the
977 \S{config-winsize} Setting the \I{window size}size of the PuTTY window
979 \cfg{winhelp-topic}{window.size}
981 The \q{\ii{Rows}} and \q{\ii{Columns}} boxes let you set the PuTTY
982 window to a precise size. Of course you can also \I{window resizing}drag
983 the window to a new size while a session is running.
985 \S{config-winsizelock} What to do when the window is resized
987 \cfg{winhelp-topic}{window.resize}
989 These options allow you to control what happens when the user tries
990 to \I{window resizing}resize the PuTTY window using its window furniture.
992 There are four options here:
994 \b \q{Change the number of rows and columns}: the font size will not
995 change. (This is the default.)
997 \b \q{Change the size of the font}: the number of rows and columns in
998 the terminal will stay the same, and the \i{font size} will change.
1000 \b \q{Change font size when maximised}: when the window is resized,
1001 the number of rows and columns will change, \e{except} when the window
1002 is \i{maximise}d (or restored), when the font size will change.
1004 \b \q{Forbid resizing completely}: the terminal will refuse to be
1007 \S{config-scrollback} Controlling \i{scrollback}
1009 \cfg{winhelp-topic}{window.scrollback}
1011 These options let you configure the way PuTTY keeps text after it
1012 scrolls off the top of the screen (see \k{using-scrollback}).
1014 The \q{Lines of scrollback} box lets you configure how many lines of
1015 text PuTTY keeps. The \q{Display scrollbar} options allow you to
1016 hide the \i{scrollbar} (although you can still view the scrollback using
1017 the keyboard as described in \k{using-scrollback}). You can separately
1018 configure whether the scrollbar is shown in \i{full-screen} mode and in
1021 If you are viewing part of the scrollback when the server sends more
1022 text to PuTTY, the screen will revert to showing the current
1023 terminal contents. You can disable this behaviour by turning off
1024 \q{Reset scrollback on display activity}. You can also make the
1025 screen revert when you press a key, by turning on \q{Reset
1026 scrollback on keypress}.
1028 \S{config-erasetoscrollback} \q{Push erased text into scrollback}
1030 \cfg{winhelp-topic}{window.erased}
1032 When this option is enabled, the contents of the terminal screen
1033 will be pushed into the scrollback when a server-side application
1034 clears the screen, so that your scrollback will contain a better
1035 record of what was on your screen in the past.
1037 If the application switches to the \i{alternate screen} (see
1038 \k{config-features-altscreen} for more about this), then the
1039 contents of the primary screen will be visible in the scrollback
1040 until the application switches back again.
1042 This option is enabled by default.
1044 \H{config-appearance} The Appearance panel
1046 The Appearance configuration panel allows you to control aspects of
1047 the appearance of \I{PuTTY window}PuTTY's window.
1049 \S{config-cursor} Controlling the appearance of the \i{cursor}
1051 \cfg{winhelp-topic}{appearance.cursor}
1053 The \q{Cursor appearance} option lets you configure the cursor to be
1054 a block, an underline, or a vertical line. A block cursor becomes an
1055 empty box when the window loses focus; an underline or a vertical
1056 line becomes dotted.
1058 The \q{\ii{Cursor blinks}} option makes the cursor blink on and off. This
1059 works in any of the cursor modes.
1061 \S{config-font} Controlling the \i{font} used in the terminal window
1063 \cfg{winhelp-topic}{appearance.font}
1065 This option allows you to choose what font, in what \I{font size}size,
1066 the PuTTY terminal window uses to display the text in the session. You
1067 will be offered a choice from all the fixed-width fonts installed on the
1068 system. (VT100-style terminal handling can only deal with fixed-width
1071 \S{config-mouseptr} \q{Hide \i{mouse pointer} when typing in window}
1073 \cfg{winhelp-topic}{appearance.hidemouse}
1075 If you enable this option, the mouse pointer will disappear if the
1076 PuTTY window is selected and you press a key. This way, it will not
1077 obscure any of the text in the window while you work in your
1078 session. As soon as you move the mouse, the pointer will reappear.
1080 This option is disabled by default, so the mouse pointer remains
1081 visible at all times.
1083 \S{config-winborder} Controlling the \i{window border}
1085 \cfg{winhelp-topic}{appearance.border}
1087 PuTTY allows you to configure the appearance of the window border to
1090 The checkbox marked \q{Sunken-edge border} changes the appearance of
1091 the window border to something more like a DOS box: the inside edge
1092 of the border is highlighted as if it sank down to meet the surface
1093 inside the window. This makes the border a little bit thicker as
1094 well. It's hard to describe well. Try it and see if you like it.
1096 You can also configure a completely blank gap between the text in
1097 the window and the border, using the \q{Gap between text and window
1098 edge} control. By default this is set at one pixel. You can reduce
1099 it to zero, or increase it further.
1101 \H{config-behaviour} The Behaviour panel
1103 The Behaviour configuration panel allows you to control aspects of
1104 the behaviour of \I{PuTTY window}PuTTY's window.
1106 \S{config-title} Controlling the \i{window title}
1108 \cfg{winhelp-topic}{appearance.title}
1110 The \q{Window title} edit box allows you to set the title of the
1111 PuTTY window. By default the window title will contain the \i{host name}
1112 followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
1113 If you want a different window title, this is where to set it.
1115 PuTTY allows the server to send \c{xterm} \i{control sequence}s which
1116 modify the title of the window in mid-session (unless this is disabled -
1117 see \k{config-features-retitle}); the title string set here
1118 is therefore only the \e{initial} window title.
1120 As well as the \e{window} title, there is also an \c{xterm}
1121 sequence to modify the \I{icon title}title of the window's \e{icon}.
1122 This makes sense in a windowing system where the window becomes an
1123 icon when minimised, such as Windows 3.1 or most X Window System
1124 setups; but in the Windows 95-like user interface it isn't as
1127 By default, PuTTY only uses the server-supplied \e{window} title, and
1128 ignores the icon title entirely. If for some reason you want to see
1129 both titles, check the box marked \q{Separate window and icon titles}.
1130 If you do this, PuTTY's window title and Taskbar \I{window caption}caption will
1131 change into the server-supplied icon title if you \i{minimise} the PuTTY
1132 window, and change back to the server-supplied window title if you
1133 restore it. (If the server has not bothered to supply a window or
1134 icon title, none of this will happen.)
1136 \S{config-warnonclose} \q{Warn before \i{closing window}}
1138 \cfg{winhelp-topic}{behaviour.closewarn}
1140 If you press the \i{Close button} in a PuTTY window that contains a
1141 running session, PuTTY will put up a warning window asking if you
1142 really meant to close the window. A window whose session has already
1143 terminated can always be closed without a warning.
1145 If you want to be able to close a window quickly, you can disable
1146 the \q{Warn before closing window} option.
1148 \S{config-altf4} \q{Window closes on \i{ALT-F4}}
1150 \cfg{winhelp-topic}{behaviour.altf4}
1152 By default, pressing ALT-F4 causes the \I{closing window}window to
1153 close (or a warning box to appear; see \k{config-warnonclose}). If you
1154 disable the \q{Window closes on ALT-F4} option, then pressing ALT-F4
1155 will simply send a key sequence to the server.
1157 \S{config-altspace} \q{\ii{System menu} appears on \i{ALT-Space}}
1159 \cfg{winhelp-topic}{behaviour.altspace}
1161 If this option is enabled, then pressing ALT-Space will bring up the
1162 PuTTY window's menu, like clicking on the top left corner. If it is
1163 disabled, then pressing ALT-Space will just send \c{ESC SPACE} to
1166 Some \i{accessibility} programs for Windows may need this option
1167 enabling to be able to control PuTTY's window successfully. For
1168 instance, \i{Dragon NaturallySpeaking} requires it both to open the
1169 system menu via voice, and to close, minimise, maximise and restore
1172 \S{config-altonly} \q{\ii{System menu} appears on \i{Alt} alone}
1174 \cfg{winhelp-topic}{behaviour.altonly}
1176 If this option is enabled, then pressing and releasing ALT will
1177 bring up the PuTTY window's menu, like clicking on the top left
1178 corner. If it is disabled, then pressing and releasing ALT will have
1181 \S{config-alwaysontop} \q{Ensure window is \i{always on top}}
1183 \cfg{winhelp-topic}{behaviour.alwaysontop}
1185 If this option is enabled, the PuTTY window will stay on top of all
1188 \S{config-fullscreen} \q{\ii{Full screen} on Alt-Enter}
1190 \cfg{winhelp-topic}{behaviour.altenter}
1192 If this option is enabled, then pressing Alt-Enter will cause the
1193 PuTTY window to become full-screen. Pressing Alt-Enter again will
1194 restore the previous window size.
1196 The full-screen feature is also available from the \ii{System menu}, even
1197 when it is configured not to be available on the Alt-Enter key. See
1198 \k{using-fullscreen}.
1200 \H{config-translation} The Translation panel
1202 The Translation configuration panel allows you to control the
1203 translation between the \i{character set} understood by the server and
1204 the character set understood by PuTTY.
1206 \S{config-charset} Controlling character set translation
1208 \cfg{winhelp-topic}{translation.codepage}
1210 During an interactive session, PuTTY receives a stream of 8-bit
1211 bytes from the server, and in order to display them on the screen it
1212 needs to know what character set to interpret them in.
1214 There are a lot of character sets to choose from. The \q{Received
1215 data assumed to be in which character set} option lets you select
1216 one. By default PuTTY will attempt to choose a character set that is
1217 right for your \i{locale} as reported by Windows; if it gets it wrong,
1218 you can select a different one using this control.
1220 A few notable character sets are:
1222 \b The \i{ISO-8859} series are all standard character sets that include
1223 various accented characters appropriate for different sets of
1226 \b The \i{Win125x} series are defined by Microsoft, for similar
1227 purposes. In particular Win1252 is almost equivalent to ISO-8859-1,
1228 but contains a few extra characters such as matched quotes and the
1231 \b If you want the old IBM PC character set with block graphics and
1232 line-drawing characters, you can select \q{\i{CP437}}.
1234 \b PuTTY also supports \i{Unicode} mode, in which the data coming from
1235 the server is interpreted as being in the \i{UTF-8} encoding of Unicode.
1236 If you select \q{UTF-8} as a character set you can use this mode.
1237 Not all server-side applications will support it.
1239 If you need support for a numeric \i{code page} which is not listed in
1240 the drop-down list, such as code page 866, then you can try entering
1241 its name manually (\c{\i{CP866}} for example) in the list box. If the
1242 underlying version of Windows has the appropriate translation table
1243 installed, PuTTY will use it.
1245 \S{config-cjk-ambig-wide} \q{Treat \i{CJK} ambiguous characters as wide}
1247 \cfg{winhelp-topic}{translation.cjkambigwide}
1249 There are \I{East Asian Ambiguous characters}some Unicode characters
1250 whose \I{character width}width is not well-defined. In most contexts, such
1251 characters should be treated as single-width for the purposes of \I{wrapping,
1252 terminal}wrapping and so on; however, in some CJK contexts, they are better
1253 treated as double-width for historical reasons, and some server-side
1254 applications may expect them to be displayed as such. Setting this option
1255 will cause PuTTY to take the double-width interpretation.
1257 If you use legacy CJK applications, and you find your lines are
1258 wrapping in the wrong places, or you are having other display
1259 problems, you might want to play with this setting.
1261 This option only has any effect in \i{UTF-8} mode (see \k{config-charset}).
1263 \S{config-cyr} \q{\i{Caps Lock} acts as \i{Cyrillic} switch}
1265 \cfg{winhelp-topic}{translation.cyrillic}
1267 This feature allows you to switch between a US/UK keyboard layout
1268 and a Cyrillic keyboard layout by using the Caps Lock key, if you
1269 need to type (for example) \i{Russian} and English side by side in the
1272 Currently this feature is not expected to work properly if your
1273 native keyboard layout is not US or UK.
1275 \S{config-linedraw} Controlling display of \i{line-drawing characters}
1277 \cfg{winhelp-topic}{translation.linedraw}
1279 VT100-series terminals allow the server to send \i{control sequence}s that
1280 shift temporarily into a separate character set for drawing simple
1281 lines and boxes. However, there are a variety of ways in which PuTTY
1282 can attempt to find appropriate characters, and the right one to use
1283 depends on the locally configured \i{font}. In general you should probably
1284 try lots of options until you find one that your particular font
1287 \b \q{Use Unicode line drawing code points} tries to use the box
1288 characters that are present in \i{Unicode}. For good Unicode-supporting
1289 fonts this is probably the most reliable and functional option.
1291 \b \q{Poor man's line drawing} assumes that the font \e{cannot}
1292 generate the line and box characters at all, so it will use the
1293 \c{+}, \c{-} and \c{|} characters to draw approximations to boxes.
1294 You should use this option if none of the other options works.
1296 \b \q{Font has XWindows encoding} is for use with fonts that have a
1297 special encoding, where the lowest 32 character positions (below the
1298 ASCII printable range) contain the line-drawing characters. This is
1299 unlikely to be the case with any standard Windows font; it will
1300 probably only apply to custom-built fonts or fonts that have been
1301 automatically converted from the X Window System.
1303 \b \q{Use font in both ANSI and OEM modes} tries to use the same
1304 font in two different character sets, to obtain a wider range of
1305 characters. This doesn't always work; some fonts claim to be a
1306 different size depending on which character set you try to use.
1308 \b \q{Use font in OEM mode only} is more reliable than that, but can
1309 miss out other characters from the main character set.
1311 \S{config-linedrawpaste} Controlling \i{copy and paste} of line drawing
1314 \cfg{winhelp-topic}{selection.linedraw}
1316 By default, when you copy and paste a piece of the PuTTY screen that
1317 contains VT100 line and box drawing characters, PuTTY will paste
1318 them in the form they appear on the screen: either \i{Unicode} line
1319 drawing code points, or the \q{poor man's} line-drawing characters
1320 \c{+}, \c{-} and \c{|}. The checkbox \q{Copy and paste VT100 line
1321 drawing chars as lqqqk} disables this feature, so line-drawing
1322 characters will be pasted as the \i{ASCII} characters that were printed
1323 to produce them. This will typically mean they come out mostly as
1324 \c{q} and \c{x}, with a scattering of \c{jklmntuvw} at the corners.
1325 This might be useful if you were trying to recreate the same box
1326 layout in another program, for example.
1328 Note that this option only applies to line-drawing characters which
1329 \e{were} printed by using the VT100 mechanism. Line-drawing
1330 characters that were received as Unicode code points will paste as
1333 \H{config-selection} The Selection panel
1335 The Selection panel allows you to control the way \i{copy and paste}
1336 work in the PuTTY window.
1338 \S{config-rtfpaste} Pasting in \i{Rich Text Format}
1340 \cfg{winhelp-topic}{selection.rtf}
1342 If you enable \q{Paste to clipboard in RTF as well as plain text},
1343 PuTTY will write formatting information to the clipboard as well as
1344 the actual text you copy. The effect of this is
1345 that if you paste into (say) a word processor, the text will appear
1346 in the word processor in the same \i{font}, \i{colour}, and style
1347 (e.g. bold, underline) PuTTY was using to display it.
1349 This option can easily be inconvenient, so by default it is
1352 \S{config-mouse} Changing the actions of the mouse buttons
1354 \cfg{winhelp-topic}{selection.buttons}
1356 PuTTY's copy and paste mechanism is by default modelled on the Unix
1357 \c{xterm} application. The X Window System uses a three-button mouse,
1358 and the convention is that the \i{left button} \I{selecting text}selects,
1359 the \i{right button} extends an existing selection, and the
1360 \i{middle button} pastes.
1362 Windows often only has two mouse buttons, so in PuTTY's default
1363 configuration (\q{Compromise}), the \e{right} button pastes, and the
1364 \e{middle} button (if you have one) \I{adjusting a selection}extends
1367 If you have a \i{three-button mouse} and you are already used to the
1368 \c{xterm} arrangement, you can select it using the \q{Action of
1369 mouse buttons} control.
1371 Alternatively, with the \q{Windows} option selected, the middle
1372 button extends, and the right button brings up a \i{context menu} (on
1373 which one of the options is \q{Paste}). (This context menu is always
1374 available by holding down Ctrl and right-clicking, regardless of the
1375 setting of this option.)
1377 \S{config-mouseshift} \q{Shift overrides application's use of mouse}
1379 \cfg{winhelp-topic}{selection.shiftdrag}
1381 PuTTY allows the server to send \i{control codes} that let it
1382 \I{mouse reporting}take over the mouse and use it for purposes other
1383 than \i{copy and paste}.
1384 Applications which use this feature include the text-mode web
1385 browser \c{links}, the Usenet newsreader \c{trn} version 4, and the
1386 file manager \c{mc} (Midnight Commander).
1388 When running one of these applications, pressing the mouse buttons
1389 no longer performs copy and paste. If you do need to copy and paste,
1390 you can still do so if you hold down Shift while you do your mouse
1393 However, it is possible in theory for applications to even detect
1394 and make use of Shift + mouse clicks. We don't know of any
1395 applications that do this, but in case someone ever writes one,
1396 unchecking the \q{Shift overrides application's use of mouse}
1397 checkbox will cause Shift + mouse clicks to go to the server as well
1398 (so that mouse-driven copy and paste will be completely disabled).
1400 If you want to prevent the application from taking over the mouse at
1401 all, you can do this using the Features control panel; see
1402 \k{config-features-mouse}.
1404 \S{config-rectselect} Default selection mode
1406 \cfg{winhelp-topic}{selection.rect}
1408 As described in \k{using-selection}, PuTTY has two modes of
1409 selecting text to be copied to the clipboard. In the default mode
1410 (\q{Normal}), dragging the mouse from point A to point B selects to
1411 the end of the line containing A, all the lines in between, and from
1412 the very beginning of the line containing B. In the other mode
1413 (\q{Rectangular block}), dragging the mouse between two points
1414 defines a rectangle, and everything within that rectangle is copied.
1416 Normally, you have to hold down Alt while dragging the mouse to
1417 select a rectangular block. Using the \q{Default selection mode}
1418 control, you can set \i{rectangular selection} as the default, and then
1419 you have to hold down Alt to get the \e{normal} behaviour.
1421 \S{config-charclasses} Configuring \i{word-by-word selection}
1423 \cfg{winhelp-topic}{selection.charclasses}
1425 PuTTY will select a word at a time in the terminal window if you
1426 \i{double-click} to begin the drag. This panel allows you to control
1427 precisely what is considered to be a word.
1429 Each character is given a \e{class}, which is a small number
1430 (typically 0, 1 or 2). PuTTY considers a single word to be any
1431 number of adjacent characters in the same class. So by modifying the
1432 assignment of characters to classes, you can modify the word-by-word
1433 selection behaviour.
1435 In the default configuration, the \i{character classes} are:
1437 \b Class 0 contains \i{white space} and control characters.
1439 \b Class 1 contains most \i{punctuation}.
1441 \b Class 2 contains letters, numbers and a few pieces of punctuation
1442 (the double quote, minus sign, period, forward slash and
1445 So, for example, if you assign the \c{@} symbol into character class
1446 2, you will be able to select an e-mail address with just a double
1449 In order to adjust these assignments, you start by selecting a group
1450 of characters in the list box. Then enter a class number in the edit
1451 box below, and press the \q{Set} button.
1453 This mechanism currently only covers ASCII characters, because it
1454 isn't feasible to expand the list to cover the whole of Unicode.
1456 Character class definitions can be modified by \i{control sequence}s
1457 sent by the server. This configuration option controls the
1458 \e{default} state, which will be restored when you reset the
1459 terminal (see \k{reset-terminal}). However, if you modify this
1460 option in mid-session using \q{Change Settings}, it will take effect
1463 \H{config-colours} The Colours panel
1465 The Colours panel allows you to control PuTTY's use of \i{colour}.
1467 \S{config-ansicolour} \q{Allow terminal to specify \i{ANSI colours}}
1469 \cfg{winhelp-topic}{colours.ansi}
1471 This option is enabled by default. If it is disabled, PuTTY will
1472 ignore any \i{control sequence}s sent by the server to request coloured
1475 If you have a particularly garish application, you might want to
1476 turn this option off and make PuTTY only use the default foreground
1477 and background colours.
1479 \S{config-xtermcolour} \q{Allow terminal to use xterm \i{256-colour mode}}
1481 \cfg{winhelp-topic}{colours.xterm256}
1483 This option is enabled by default. If it is disabled, PuTTY will
1484 ignore any control sequences sent by the server which use the
1485 extended 256-colour mode supported by recent versions of \cw{xterm}.
1487 If you have an application which is supposed to use 256-colour mode
1488 and it isn't working, you may find you need to tell your server that
1489 your terminal supports 256 colours. On Unix, you do this by ensuring
1490 that the setting of \i\cw{TERM} describes a 256-colour-capable
1491 terminal. You can check this using a command such as \c{infocmp}:
1493 \c $ infocmp | grep colors
1494 \c colors#256, cols#80, it#8, lines#24, pairs#256,
1497 If you do not see \cq{colors#256} in the output, you may need to
1498 change your terminal setting. On modern Linux machines, you could
1499 try \cq{xterm-256color}.
1501 \S{config-boldcolour} \q{Bolded text is a different colour}
1503 \cfg{winhelp-topic}{colours.bold}
1505 When the server sends a \i{control sequence} indicating that some text
1506 should be displayed in \i{bold}, PuTTY can handle this two ways. It can
1507 either change the \i{font} for a bold version, or use the same font in a
1508 brighter colour. This control lets you choose which.
1510 By default the box is checked, so non-bold text is displayed in
1511 light grey and bold text is displayed in bright white (and similarly
1512 in other colours). If you uncheck the box, bold and non-bold text
1513 will be displayed in the same colour, and instead the font will
1514 change to indicate the difference.
1516 \S{config-logpalette} \q{Attempt to use \i{logical palettes}}
1518 \cfg{winhelp-topic}{colours.logpal}
1520 Logical palettes are a mechanism by which a Windows application
1521 running on an \i{8-bit colour} display can select precisely the colours
1522 it wants instead of going with the Windows standard defaults.
1524 If you are not getting the colours you ask for on an 8-bit display,
1525 you can try enabling this option. However, be warned that it's never
1528 \S{config-syscolour} \q{Use \i{system colours}}
1530 \cfg{winhelp-topic}{colours.system}
1532 Enabling this option will cause PuTTY to ignore the configured colours
1533 for \I{default background}\I{default foreground}\q{Default
1534 Background/Foreground} and \I{cursor colour}\q{Cursor Colour/Text} (see
1535 \k{config-colourcfg}), instead going with the system-wide defaults.
1537 Note that non-bold and \i{bold text} will be the same colour if this
1538 option is enabled. You might want to change to indicating bold text
1539 by font changes (see \k{config-boldcolour}).
1541 \S{config-colourcfg} Adjusting the colours in the \i{terminal window}
1543 \cfg{winhelp-topic}{colours.config}
1545 The main colour control allows you to specify exactly what colours
1546 things should be displayed in. To modify one of the PuTTY colours,
1547 use the list box to select which colour you want to modify. The \i{RGB
1548 values} for that colour will appear on the right-hand side of the
1549 list box. Now, if you press the \q{Modify} button, you will be
1550 presented with a colour selector, in which you can choose a new
1551 colour to go in place of the old one. (You may also edit the RGB
1552 values directly in the edit boxes, if you wish; each value is an
1553 integer from 0 to 255.)
1555 PuTTY allows you to set the \i{cursor colour}, the \i{default foreground}
1556 and \I{default background}background, and the precise shades of all the
1557 \I{ANSI colours}ANSI configurable colours (black, red, green, yellow, blue,
1558 magenta, cyan, and white). You can also modify the precise shades used for
1559 the \i{bold} versions of these colours; these are used to display bold text
1560 if you have selected \q{Bolded text is a different colour}, and can also be
1561 used if the server asks specifically to use them. (Note that \q{Default
1562 Bold Background} is \e{not} the background colour used for bold text;
1563 it is only used if the server specifically asks for a bold
1566 \H{config-connection} The Connection panel
1568 The Connection panel allows you to configure options that apply to
1569 more than one type of \i{connection}.
1571 \S{config-keepalive} Using \i{keepalives} to prevent disconnection
1573 \cfg{winhelp-topic}{connection.keepalive}
1575 If you find your sessions are closing unexpectedly (most often with
1576 \q{Connection reset by peer}) after they have been idle for a while,
1577 you might want to try using this option.
1579 Some network \i{routers} and \i{firewalls} need to keep track of all
1580 connections through them. Usually, these firewalls will assume a
1581 connection is dead if no data is transferred in either direction
1582 after a certain time interval. This can cause PuTTY sessions to be
1583 unexpectedly closed by the firewall if no traffic is seen in the
1584 session for some time.
1586 The keepalive option (\q{Seconds between keepalives}) allows you to
1587 configure PuTTY to send data through the session at regular
1588 intervals, in a way that does not disrupt the actual terminal
1589 session. If you find your firewall is cutting \i{idle connections} off,
1590 you can try entering a non-zero value in this field. The value is
1591 measured in seconds; so, for example, if your firewall cuts
1592 connections off after ten minutes then you might want to enter 300
1593 seconds (5 minutes) in the box.
1595 Note that keepalives are not always helpful. They help if you have a
1596 firewall which drops your connection after an idle period; but if
1597 the network between you and the server suffers from \i{breaks in
1598 connectivity} then keepalives can actually make things worse. If a
1599 session is idle, and connectivity is temporarily lost between the
1600 endpoints, but the connectivity is restored before either side tries
1601 to send anything, then there will be no problem - neither endpoint
1602 will notice that anything was wrong. However, if one side does send
1603 something during the break, it will repeatedly try to re-send, and
1604 eventually give up and abandon the connection. Then when
1605 connectivity is restored, the other side will find that the first
1606 side doesn't believe there is an open connection any more.
1607 Keepalives can make this sort of problem worse, because they
1608 increase the probability that PuTTY will attempt to send data during
1609 a break in connectivity. (Other types of periodic network activity
1610 can cause this behaviour; in particular, SSH-2 re-keys can have
1611 this effect. See \k{config-ssh-kex-rekey}.)
1613 Therefore, you might find that keepalives help
1614 connection loss, or you might find they make it worse, depending on
1615 what \e{kind} of network problems you have between you and the
1618 Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
1619 protocols offer no way of implementing them. (For an alternative, see
1620 \k{config-tcp-keepalives}.)
1622 Note that if you are using \i{SSH-1} and the server has a bug that makes
1623 it unable to deal with SSH-1 ignore messages (see
1624 \k{config-ssh-bug-ignore1}), enabling keepalives will have no effect.
1626 \S{config-nodelay} \q{Disable \i{Nagle's algorithm}}
1628 \cfg{winhelp-topic}{connection.nodelay}
1630 Nagle's algorithm is a detail of TCP/IP implementations that tries
1631 to minimise the number of small data packets sent down a network
1632 connection. With Nagle's algorithm enabled, PuTTY's \i{bandwidth} usage
1633 will be slightly more efficient; with it disabled, you may find you
1634 get a faster response to your keystrokes when connecting to some
1637 The Nagle algorithm is disabled by default for \i{interactive connections}.
1639 \S{config-tcp-keepalives} \q{Enable \i{TCP keepalives}}
1641 \cfg{winhelp-topic}{connection.tcpkeepalive}
1643 \e{NOTE:} TCP keepalives should not be confused with the
1644 application-level keepalives described in \k{config-keepalive}. If in
1645 doubt, you probably want application-level keepalives; TCP keepalives
1646 are provided for completeness.
1648 The idea of TCP keepalives is similar to application-level keepalives,
1649 and the same caveats apply. The main differences are:
1651 \b TCP keepalives are available on \e{all} connection types, including
1654 \b The interval between TCP keepalives is usually much longer,
1655 typically two hours; this is set by the operating system, and cannot
1656 be configured within PuTTY.
1658 \b If the operating system does not receive a response to a keepalive,
1659 it may send out more in quick succession and terminate the connection
1660 if no response is received.
1662 TCP keepalives may be more useful for ensuring that \i{half-open connections}
1663 are terminated than for keeping a connection alive.
1665 TCP keepalives are disabled by default.
1667 \S{config-address-family} \I{Internet protocol version}\q{Internet protocol}
1669 \cfg{winhelp-topic}{connection.ipversion}
1671 This option allows the user to select between the old and new
1672 Internet protocols and addressing schemes (\i{IPv4} and \i{IPv6}). The
1673 default setting is \q{Auto}, which means PuTTY will do something
1674 sensible and try to guess which protocol you wanted. (If you specify
1675 a literal \i{Internet address}, it will use whichever protocol that
1676 address implies. If you provide a \i{hostname}, it will see what kinds
1677 of address exist for that hostname; it will use IPv6 if there is an
1678 IPv6 address available, and fall back to IPv4 if not.)
1680 If you need to force PuTTY to use a particular protocol, you can
1681 explicitly set this to \q{IPv4} or \q{IPv6}.
1683 \H{config-data} The Data panel
1685 The Data panel allows you to configure various pieces of data which
1686 can be sent to the server to affect your connection at the far end.
1688 Each option on this panel applies to more than one protocol.
1689 Options which apply to only one protocol appear on that protocol's
1690 configuration panels.
1692 \S{config-username} \q{\ii{Auto-login username}}
1694 \cfg{winhelp-topic}{connection.username}
1696 All three of the SSH, Telnet and Rlogin protocols allow you to
1697 specify what user name you want to log in as, without having to type
1698 it explicitly every time. (Some Telnet servers don't support this.)
1700 In this box you can type that user name.
1702 \S{config-termtype} \q{\ii{Terminal-type} string}
1704 \cfg{winhelp-topic}{connection.termtype}
1706 Most servers you might connect to with PuTTY are designed to be
1707 connected to from lots of different types of terminal. In order to
1708 send the right \i{control sequence}s to each one, the server will need
1709 to know what type of terminal it is dealing with. Therefore, each of
1710 the SSH, Telnet and Rlogin protocols allow a text string to be sent
1711 down the connection describing the terminal. On a \i{Unix} server,
1712 this selects an entry from the \i\c{termcap} or \i\c{terminfo} database
1713 that tells applications what \i{control sequences} to send to the
1714 terminal, and what character sequences to expect the \i{keyboard}
1717 PuTTY attempts to emulate the Unix \i\c{xterm} program, and by default
1718 it reflects this by sending \c{xterm} as a terminal-type string. If
1719 you find this is not doing what you want - perhaps the remote
1720 system reports \q{Unknown terminal type} - you could try setting
1721 this to something different, such as \i\c{vt220}.
1723 If you're not sure whether a problem is due to the terminal type
1724 setting or not, you probably need to consult the manual for your
1725 application or your server.
1727 \S{config-termspeed} \q{\ii{Terminal speed}s}
1729 \cfg{winhelp-topic}{connection.termspeed}
1731 The Telnet, Rlogin, and SSH protocols allow the client to specify
1732 terminal speeds to the server.
1734 This parameter does \e{not} affect the actual speed of the connection,
1735 which is always \q{as fast as possible}; it is just a hint that is
1736 sometimes used by server software to modify its behaviour. For
1737 instance, if a slow speed is indicated, the server may switch to a
1738 less \i{bandwidth}-hungry display mode.
1740 The value is usually meaningless in a network environment, but
1741 PuTTY lets you configure it, in case you find the server is reacting
1742 badly to the default value.
1744 The format is a pair of numbers separated by a comma, for instance,
1745 \c{38400,38400}. The first number represents the output speed
1746 (\e{from} the server) in bits per second, and the second is the input
1747 speed (\e{to} the server). (Only the first is used in the Rlogin
1750 This option has no effect on Raw connections.
1752 \S{config-environ} Setting \i{environment variables} on the server
1754 \cfg{winhelp-topic}{telnet.environ}
1756 The Telnet protocol provides a means for the client to pass
1757 environment variables to the server. Many Telnet servers have
1758 stopped supporting this feature due to security flaws, but PuTTY
1759 still supports it for the benefit of any servers which have found
1760 other ways around the security problems than just disabling the
1763 Version 2 of the SSH protocol also provides a similar mechanism,
1764 which is easier to implement without security flaws. Newer \i{SSH-2}
1765 servers are more likely to support it than older ones.
1767 This configuration data is not used in the SSH-1, rlogin or raw
1770 To add an environment variable to the list transmitted down the
1771 connection, you enter the variable name in the \q{Variable} box,
1772 enter its value in the \q{Value} box, and press the \q{Add} button.
1773 To remove one from the list, select it in the list box and press
1776 \H{config-proxy} The Proxy panel
1778 \cfg{winhelp-topic}{proxy.main}
1780 The \ii{Proxy} panel allows you to configure PuTTY to use various types
1781 of proxy in order to make its network connections. The settings in
1782 this panel affect the primary network connection forming your PuTTY
1783 session, and also any extra connections made as a result of SSH \i{port
1784 forwarding} (see \k{using-port-forwarding}).
1786 \S{config-proxy-type} Setting the proxy type
1788 \cfg{winhelp-topic}{proxy.type}
1790 The \q{Proxy type} radio buttons allow you to configure what type of
1791 proxy you want PuTTY to use for its network connections. The default
1792 setting is \q{None}; in this mode no proxy is used for any
1795 \b Selecting \I{HTTP proxy}\q{HTTP} allows you to proxy your connections
1796 through a web server supporting the HTTP \cw{CONNECT} command, as documented
1797 in \W{http://www.ietf.org/rfc/rfc2817.txt}{RFC 2817}.
1799 \b Selecting \q{SOCKS 4} or \q{SOCKS 5} allows you to proxy your
1800 connections through a \i{SOCKS server}.
1802 \b Many firewalls implement a less formal type of proxy in which a
1803 user can make a Telnet connection directly to the firewall machine
1804 and enter a command such as \c{connect myhost.com 22} to connect
1805 through to an external host. Selecting \I{Telnet proxy}\q{Telnet}
1806 allows you to tell PuTTY to use this type of proxy.
1808 \b Selecting \I{Local proxy}\q{Local} allows you to specify an arbitrary
1809 command on the local machine to act as a proxy. When the session is
1810 started, instead of creating a TCP connection, PuTTY runs the command
1811 (specified in \k{config-proxy-command}), and uses its standard input and
1815 This could be used, for instance, to talk to some kind of network proxy
1816 that PuTTY does not natively support; or you could tunnel a connection
1817 over something other than TCP/IP entirely.
1819 If you want your local proxy command to make a secondary SSH
1820 connection to a proxy host and then tunnel the primary connection
1821 over that, you might well want the \c{-nc} command-line option in
1822 Plink. See \k{using-cmdline-ncmode} for more information.
1825 \S{config-proxy-exclude} Excluding parts of the network from proxying
1827 \cfg{winhelp-topic}{proxy.exclude}
1829 Typically you will only need to use a proxy to connect to non-local
1830 parts of your network; for example, your proxy might be required for
1831 connections outside your company's internal network. In the
1832 \q{Exclude Hosts/IPs} box you can enter ranges of IP addresses, or
1833 ranges of DNS names, for which PuTTY will avoid using the proxy and
1834 make a direct connection instead.
1836 The \q{Exclude Hosts/IPs} box may contain more than one exclusion
1837 range, separated by commas. Each range can be an IP address or a DNS
1838 name, with a \c{*} character allowing wildcards. For example:
1842 This excludes any host with a name ending in \c{.example.com} from
1847 This excludes any host with an IP address starting with 192.168.88
1850 \c 192.168.88.*,*.example.com
1852 This excludes both of the above ranges at once.
1854 Connections to the local host (the host name \i\c{localhost}, and any
1855 \i{loopback IP address}) are never proxied, even if the proxy exclude
1856 list does not explicitly contain them. It is very unlikely that this
1857 behaviour would ever cause problems, but if it does you can change
1858 it by enabling \q{Consider proxying local host connections}.
1860 Note that if you are doing \I{proxy DNS}DNS at the proxy (see
1861 \k{config-proxy-dns}), you should make sure that your proxy
1862 exclusion settings do not depend on knowing the IP address of a
1863 host. If the name is passed on to the proxy without PuTTY looking it
1864 up, it will never know the IP address and cannot check it against
1867 \S{config-proxy-dns} \I{proxy DNS}\ii{Name resolution} when using a proxy
1869 \cfg{winhelp-topic}{proxy.dns}
1871 If you are using a proxy to access a private network, it can make a
1872 difference whether \i{DNS} name resolution is performed by PuTTY itself
1873 (on the client machine) or performed by the proxy.
1875 The \q{Do DNS name lookup at proxy end} configuration option allows
1876 you to control this. If you set it to \q{No}, PuTTY will always do
1877 its own DNS, and will always pass an IP address to the proxy. If you
1878 set it to \q{Yes}, PuTTY will always pass host names straight to the
1879 proxy without trying to look them up first.
1881 If you set this option to \q{Auto} (the default), PuTTY will do
1882 something it considers appropriate for each type of proxy. Telnet,
1883 HTTP, and SOCKS5 proxies will have host names passed straight to
1884 them; SOCKS4 proxies will not.
1886 Note that if you are doing DNS at the proxy, you should make sure
1887 that your proxy exclusion settings (see \k{config-proxy-exclude}) do
1888 not depend on knowing the IP address of a host. If the name is
1889 passed on to the proxy without PuTTY looking it up, it will never
1890 know the IP address and cannot check it against your list.
1892 The original SOCKS 4 protocol does not support proxy-side DNS. There
1893 is a protocol extension (SOCKS 4A) which does support it, but not
1894 all SOCKS 4 servers provide this extension. If you enable proxy DNS
1895 and your SOCKS 4 server cannot deal with it, this might be why.
1897 \S{config-proxy-auth} \I{proxy username}Username and \I{proxy password}password
1899 \cfg{winhelp-topic}{proxy.auth}
1901 If your proxy requires \I{proxy authentication}authentication, you can
1902 enter a username and a password in the \q{Username} and \q{Password} boxes.
1904 \I{security hazard}Note that if you save your session, the proxy
1905 password will be saved in plain text, so anyone who can access your PuTTY
1906 configuration data will be able to discover it.
1908 Authentication is not fully supported for all forms of proxy:
1910 \b Username and password authentication is supported for HTTP
1911 proxies and SOCKS 5 proxies.
1915 \b With SOCKS 5, authentication is via \i{CHAP} if the proxy
1916 supports it (this is not supported in \i{PuTTYtel}); otherwise the
1917 password is sent to the proxy in \I{plaintext password}plain text.
1919 \b With HTTP proxying, the only currently supported authentication
1920 method is \I{HTTP basic}\q{basic}, where the password is sent to the proxy
1921 in \I{plaintext password}plain text.
1925 \b SOCKS 4 can use the \q{Username} field, but does not support
1928 \b You can specify a way to include a username and password in the
1929 Telnet/Local proxy command (see \k{config-proxy-command}).
1931 \S{config-proxy-command} Specifying the Telnet or Local proxy command
1933 \cfg{winhelp-topic}{proxy.command}
1935 If you are using the \i{Telnet proxy} type, the usual command required
1936 by the firewall's Telnet server is \c{connect}, followed by a host
1937 name and a port number. If your proxy needs a different command,
1938 you can enter an alternative here.
1940 If you are using the \i{Local proxy} type, the local command to run
1943 In this string, you can use \c{\\n} to represent a new-line, \c{\\r}
1944 to represent a carriage return, \c{\\t} to represent a tab
1945 character, and \c{\\x} followed by two hex digits to represent any
1946 other character. \c{\\\\} is used to encode the \c{\\} character
1949 Also, the special strings \c{%host} and \c{%port} will be replaced
1950 by the host name and port number you want to connect to. The strings
1951 \c{%user} and \c{%pass} will be replaced by the proxy username and
1952 password you specify. The strings \c{%proxyhost} and \c{%proxyport}
1953 will be replaced by the host details specified on the \e{Proxy} panel,
1954 if any (this is most likely to be useful for the Local proxy type).
1955 To get a literal \c{%} sign, enter \c{%%}.
1957 If a Telnet proxy server prompts for a username and password
1958 before commands can be sent, you can use a command such as:
1960 \c %user\n%pass\nconnect %host %port\n
1962 This will send your username and password as the first two lines to
1963 the proxy, followed by a command to connect to the desired host and
1964 port. Note that if you do not include the \c{%user} or \c{%pass}
1965 tokens in the Telnet command, then the \q{Username} and \q{Password}
1966 configuration fields will be ignored.
1968 \H{config-telnet} The \i{Telnet} panel
1970 The Telnet panel allows you to configure options that only apply to
1973 \S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
1975 \cfg{winhelp-topic}{telnet.oldenviron}
1977 The original Telnet mechanism for passing \i{environment variables} was
1978 badly specified. At the time the standard (RFC 1408) was written,
1979 BSD telnet implementations were already supporting the feature, and
1980 the intention of the standard was to describe the behaviour the BSD
1981 implementations were already using.
1983 Sadly there was a typing error in the standard when it was issued,
1984 and two vital function codes were specified the wrong way round. BSD
1985 implementations did not change, and the standard was not corrected.
1986 Therefore, it's possible you might find either \i{BSD} or \i{RFC}-compliant
1987 implementations out there. This switch allows you to choose which
1988 one PuTTY claims to be.
1990 The problem was solved by issuing a second standard, defining a new
1991 Telnet mechanism called \i\cw{NEW_ENVIRON}, which behaved exactly like
1992 the original \i\cw{OLD_ENVIRON} but was not encumbered by existing
1993 implementations. Most Telnet servers now support this, and it's
1994 unambiguous. This feature should only be needed if you have trouble
1995 passing environment variables to quite an old server.
1997 \S{config-ptelnet} Passive and active \i{Telnet negotiation} modes
1999 \cfg{winhelp-topic}{telnet.passive}
2001 In a Telnet connection, there are two types of data passed between
2002 the client and the server: actual text, and \e{negotiations} about
2003 which Telnet extra features to use.
2005 PuTTY can use two different strategies for negotiation:
2007 \b In \I{active Telnet negotiation}\e{active} mode, PuTTY starts to send
2008 negotiations as soon as the connection is opened.
2010 \b In \I{passive Telnet negotiation}\e{passive} mode, PuTTY will wait to
2011 negotiate until it sees a negotiation from the server.
2013 The obvious disadvantage of passive mode is that if the server is
2014 also operating in a passive mode, then negotiation will never begin
2015 at all. For this reason PuTTY defaults to active mode.
2017 However, sometimes passive mode is required in order to successfully
2018 get through certain types of firewall and \i{Telnet proxy} server. If
2019 you have confusing trouble with a \i{firewall}, you could try enabling
2020 passive mode to see if it helps.
2022 \S{config-telnetkey} \q{Keyboard sends \i{Telnet special commands}}
2024 \cfg{winhelp-topic}{telnet.specialkeys}
2026 If this box is checked, several key sequences will have their normal
2029 \b the Backspace key on the keyboard will send the \I{Erase Character,
2030 Telnet special command}Telnet special backspace code;
2032 \b Control-C will send the Telnet special \I{Interrupt Process, Telnet
2033 special command}Interrupt Process code;
2035 \b Control-Z will send the Telnet special \I{Suspend Process, Telnet
2036 special command}Suspend Process code.
2038 You probably shouldn't enable this
2039 unless you know what you're doing.
2041 \S{config-telnetnl} \q{Return key sends \i{Telnet New Line} instead of ^M}
2043 \cfg{winhelp-topic}{telnet.newline}
2045 Unlike most other remote login protocols, the Telnet protocol has a
2046 special \q{\i{new line}} code that is not the same as the usual line
2047 endings of Control-M or Control-J. By default, PuTTY sends the
2048 Telnet New Line code when you press Return, instead of sending
2049 Control-M as it does in most other protocols.
2051 Most Unix-style Telnet servers don't mind whether they receive
2052 Telnet New Line or Control-M; some servers do expect New Line, and
2053 some servers prefer to see ^M. If you are seeing surprising
2054 behaviour when you press Return in a Telnet session, you might try
2055 turning this option off to see if it helps.
2057 \H{config-rlogin} The Rlogin panel
2059 The \i{Rlogin} panel allows you to configure options that only apply to
2062 \S{config-rlogin-localuser} \I{local username in Rlogin}\q{Local username}
2064 \cfg{winhelp-topic}{rlogin.localuser}
2066 Rlogin allows an automated (password-free) form of login by means of
2067 a file called \i\c{.rhosts} on the server. You put a line in your
2068 \c{.rhosts} file saying something like \c{jbloggs@pc1.example.com},
2069 and then when you make an Rlogin connection the client transmits the
2070 username of the user running the Rlogin client. The server checks
2071 the username and hostname against \c{.rhosts}, and if they match it
2072 \I{passwordless login}does not ask for a password.
2074 This only works because Unix systems contain a safeguard to stop a
2075 user from pretending to be another user in an Rlogin connection.
2076 Rlogin connections have to come from \I{privileged port}port numbers below
2077 1024, and Unix systems prohibit this to unprivileged processes; so when the
2078 server sees a connection from a low-numbered port, it assumes the
2079 client end of the connection is held by a privileged (and therefore
2080 trusted) process, so it believes the claim of who the user is.
2082 Windows does not have this restriction: \e{any} user can initiate an
2083 outgoing connection from a low-numbered port. Hence, the Rlogin
2084 \c{.rhosts} mechanism is completely useless for securely
2085 distinguishing several different users on a Windows machine. If you
2086 have a \c{.rhosts} entry pointing at a Windows PC, you should assume
2087 that \e{anyone} using that PC can \i{spoof} your username in
2088 an Rlogin connection and access your account on the server.
2090 The \q{Local username} control allows you to specify what user name
2091 PuTTY should claim you have, in case it doesn't match your \i{Windows
2092 user name} (or in case you didn't bother to set up a Windows user
2095 \H{config-ssh} The SSH panel
2097 The \i{SSH} panel allows you to configure options that only apply to
2100 \S{config-command} Executing a specific command on the server
2102 \cfg{winhelp-topic}{ssh.command}
2104 In SSH, you don't have to run a general shell session on the server.
2105 Instead, you can choose to run a single specific command (such as a
2106 mail user agent, for example). If you want to do this, enter the
2107 command in the \q{\ii{Remote command}} box.
2109 Note that most servers will close the session after executing the
2112 \S{config-ssh-noshell} \q{Don't start a \I{remote shell}shell or
2113 \I{remote command}command at all}
2115 \cfg{winhelp-topic}{ssh.noshell}
2117 If you tick this box, PuTTY will not attempt to run a shell or
2118 command after connecting to the remote server. You might want to use
2119 this option if you are only using the SSH connection for \i{port
2120 forwarding}, and your user account on the server does not have the
2121 ability to run a shell.
2123 This feature is only available in \i{SSH protocol version 2} (since the
2124 version 1 protocol assumes you will always want to run a shell).
2126 This feature can also be enabled using the \c{-N} command-line
2127 option; see \k{using-cmdline-noshell}.
2129 If you use this feature in Plink, you will not be able to terminate
2130 the Plink process by any graceful means; the only way to kill it
2131 will be by pressing Control-C or sending a kill signal from another
2134 \S{config-ssh-comp} \q{Enable \i{compression}}
2136 \cfg{winhelp-topic}{ssh.compress}
2138 This enables data compression in the SSH connection: data sent by
2139 the server is compressed before sending, and decompressed at the
2140 client end. Likewise, data sent by PuTTY to the server is compressed
2141 first and the server decompresses it at the other end. This can help
2142 make the most of a low-\i{bandwidth} connection.
2144 \S{config-ssh-prot} \q{Preferred \i{SSH protocol version}}
2146 \cfg{winhelp-topic}{ssh.protocol}
2148 This allows you to select whether you would like to use \i{SSH protocol
2149 version 1} or \I{SSH-2}version 2. \#{FIXME: say something about this elsewhere?}
2151 PuTTY will attempt to use protocol 1 if the server you connect to
2152 does not offer protocol 2, and vice versa.
2154 If you select \q{1 only} or \q{2 only} here, PuTTY will only connect
2155 if the server you connect to offers the SSH protocol version you
2158 \S{config-ssh-encryption} \ii{Encryption} algorithm selection
2160 \cfg{winhelp-topic}{ssh.ciphers}
2162 PuTTY supports a variety of different \i{encryption algorithm}s, and
2163 allows you to choose which one you prefer to use. You can do this by
2164 dragging the algorithms up and down in the list box (or moving them
2165 using the Up and Down buttons) to specify a preference order. When
2166 you make an SSH connection, PuTTY will search down the list from the
2167 top until it finds an algorithm supported by the server, and then
2170 PuTTY currently supports the following algorithms:
2172 \b \i{AES} (Rijndael) - 256, 192, or 128-bit SDCTR or CBC (SSH-2 only)
2174 \b \i{Arcfour} (RC4) - 256 or 128-bit stream cipher (SSH-2 only)
2176 \b \i{Blowfish} - 256-bit SDCTR (SSH-2 only) or 128-bit CBC
2178 \b \ii{Triple-DES} - 168-bit SDCTR (SSH-2 only) or CBC
2180 \b \ii{Single-DES} - 56-bit CBC (see below for SSH-2)
2182 If the algorithm PuTTY finds is below the \q{warn below here} line,
2183 you will see a warning box when you make the connection:
2185 \c The first cipher supported by the server
2186 \c is single-DES, which is below the configured
2187 \c warning threshold.
2188 \c Do you want to continue with this connection?
2190 This warns you that the first available encryption is not a very
2191 secure one. Typically you would put the \q{warn below here} line
2192 between the encryptions you consider secure and the ones you
2193 consider substandard. By default, PuTTY supplies a preference order
2194 intended to reflect a reasonable preference in terms of security and
2197 In SSH-2, the encryption algorithm is negotiated independently for
2198 each direction of the connection, although PuTTY does not support
2199 separate configuration of the preference orders. As a result you may
2200 get two warnings similar to the one above, possibly with different
2203 Single-DES is not recommended in the SSH-2 draft protocol
2204 standards, but one or two server implementations do support it.
2205 PuTTY can use single-DES to interoperate with
2206 these servers if you enable the \q{Enable legacy use of single-DES in
2207 SSH-2} option; by default this is disabled and PuTTY will stick to
2208 recommended ciphers.
2210 \H{config-ssh-kex} The Kex panel
2212 \# FIXME: This whole section is draft. Feel free to revise.
2214 The Kex panel (short for \q{\i{key exchange}}) allows you to configure
2215 options related to SSH-2 key exchange.
2217 Key exchange occurs at the start of an SSH connection (and
2218 occasionally thereafter); it establishes a \i{shared secret} that is used
2219 as the basis for all of SSH's security features. It is therefore very
2220 important for the security of the connection that the key exchange is
2223 Key exchange is a cryptographically intensive process; if either the
2224 client or the server is a relatively slow machine, the slower methods
2225 may take several tens of seconds to complete.
2227 If connection startup is too slow, or the connection hangs
2228 periodically, you may want to try changing these settings.
2230 If you don't understand what any of this means, it's safe to leave
2231 these settings alone.
2233 This entire panel is only relevant to SSH protocol version 2; none of
2234 these settings affect SSH-1 at all.
2236 \S{config-ssh-kex-order} \ii{Key exchange algorithm} selection
2238 \cfg{winhelp-topic}{ssh.kex.order}
2240 PuTTY supports a variety of SSH-2 key exchange methods, and allows you
2241 to choose which one you prefer to use; configuration is similar to
2242 cipher selection (see \k{config-ssh-encryption}).
2244 PuTTY currently supports the following varieties of \i{Diffie-Hellman key
2247 \b \q{Group 14}: a well-known 2048-bit group.
2249 \b \q{Group 1}: a well-known 1024-bit group. This is less secure
2250 \#{FIXME better words} than group 14, but may be faster with slow
2251 client or server machines, and may be the only method supported by
2252 older server software.
2254 \b \q{\ii{Group exchange}}: with this method, instead of using a fixed
2255 group, PuTTY requests that the server suggest a group to use for key
2256 exchange; the server can avoid groups known to be weak, and possibly
2257 invent new ones over time, without any changes required to PuTTY's
2258 configuration. We recommend use of this method, if possible.
2260 If the first algorithm PuTTY finds is below the \q{warn below here}
2261 line, you will see a warning box when you make the connection, similar
2262 to that for cipher selection (see \k{config-ssh-encryption}).
2264 \S{config-ssh-kex-rekey} \ii{Repeat key exchange}
2266 \cfg{winhelp-topic}{ssh.kex.repeat}
2268 If the session key negotiated at connection startup is used too much
2269 or for too long, it may become feasible to mount attacks against the
2270 SSH connection. Therefore, the SSH-2 protocol specifies that a new key
2271 exchange should take place every so often; this can be initiated by
2272 either the client or the server.
2274 While this renegotiation is taking place, no data can pass through
2275 the SSH connection, so it may appear to \q{freeze}. (The occurrence of
2276 repeat key exchange is noted in the Event Log; see
2277 \k{using-eventlog}.) Usually the same algorithm is used as at the
2278 start of the connection, with a similar overhead.
2280 These options control how often PuTTY will initiate a repeat key
2281 exchange (\q{rekey}). You can also force a key exchange at any time
2282 from the Special Commands menu (see \k{using-specials}).
2284 \# FIXME: do we have any additions to the SSH-2 drafts' advice on
2285 these values? Do we want to enforce any limits?
2287 \b \q{Max minutes before rekey} specifies the amount of time that is
2288 allowed to elapse before a rekey is initiated. If this is set to zero,
2289 PuTTY will not rekey due to elapsed time. The SSH-2 protocol
2290 specification recommends a timeout of at most 60 minutes.
2292 You might have a need to disable time-based rekeys completely for the same
2293 reasons that \i{keepalives} aren't always helpful. If you anticipate
2294 suffering a network dropout of several hours in the middle of an SSH
2295 connection, but were not actually planning to send \e{data} down
2296 that connection during those hours, then an attempted rekey in the
2297 middle of the dropout will probably cause the connection to be
2298 abandoned, whereas if rekeys are disabled then the connection should
2299 in principle survive (in the absence of interfering \i{firewalls}). See
2300 \k{config-keepalive} for more discussion of these issues; for these
2301 purposes, rekeys have much the same properties as keepalives.
2302 (Except that rekeys have cryptographic value in themselves, so you
2303 should bear that in mind when deciding whether to turn them off.)
2304 Note, however, the the SSH \e{server} can still initiate rekeys.
2306 \b \q{Max data before rekey} specifies the amount of data (in bytes)
2307 that is permitted to flow in either direction before a rekey is
2308 initiated. If this is set to zero, PuTTY will not rekey due to
2309 transferred data. The SSH-2 protocol specification recommends a limit
2310 of at most 1 gigabyte.
2314 As well as specifying a value in bytes, the following shorthand can be
2317 \b \cq{1k} specifies 1 kilobyte (1024 bytes).
2319 \b \cq{1M} specifies 1 megabyte (1024 kilobytes).
2321 \b \cq{1G} specifies 1 gigabyte (1024 megabytes).
2325 Disabling data-based rekeys entirely is a bad idea. The \i{integrity},
2326 and to a lesser extent, \i{confidentiality} of the SSH-2 protocol depend
2327 in part on rekeys occuring before a 32-bit packet sequence number
2328 wraps around. Unlike time-based rekeys, data-based rekeys won't occur
2329 when the SSH connection is idle, so they shouldn't cause the same
2330 problems. The SSH-1 protocol, incidentally, has even weaker integrity
2331 protection than SSH-2 without rekeys.
2333 \H{config-ssh-auth} The Auth panel
2335 The Auth panel allows you to configure \i{authentication} options for
2338 \S{config-ssh-noauth} \q{Bypass authentication entirely}
2340 \cfg{winhelp-topic}{ssh.auth.bypass}
2342 In SSH-2, it is possible to establish a connection without using SSH's
2343 mechanisms to identify or authenticate oneself to the server. Some
2344 servers may prefer to handle authentication in the data channel, for
2345 instance, or may simply require no authentication whatsoever.
2347 By default, PuTTY assumes the server requires authentication (most
2348 do), and thus must provide a username. If you find you are getting
2349 unwanted username prompts, you could try checking this option.
2351 This option only affects SSH-2 connections. SSH-1 connections always
2352 require an authentication step.
2354 \S{config-ssh-tryagent} \q{Attempt authentication using Pageant}
2356 \cfg{winhelp-topic}{ssh.auth.pageant}
2358 If this option is enabled, then PuTTY will look for Pageant (the SSH
2359 private-key storage agent) and attempt to authenticate with any
2360 suitable public keys Pageant currently holds.
2362 This behaviour is almost always desirable, and is therefore enabled
2363 by default. In rare cases you might need to turn it off in order to
2364 force authentication by some non-public-key method such as
2367 This option can also be controlled using the \c{-noagent}
2368 command-line option. See \k{using-cmdline-agentauth}.
2370 See \k{pageant} for more information about Pageant in general.
2372 \S{config-ssh-tis} \q{Attempt \I{TIS authentication}TIS or
2373 \i{CryptoCard authentication}}
2375 \cfg{winhelp-topic}{ssh.auth.tis}
2377 TIS and CryptoCard authentication are (despite their names) generic
2378 forms of simple \I{challenge/response authentication}challenge/response
2379 authentication available in SSH protocol version 1 only. You might use
2380 them if you were using \i{S/Key} \i{one-time passwords}, for example,
2381 or if you had a physical \i{security token} that generated responses
2382 to authentication challenges.
2384 With this switch enabled, PuTTY will attempt these forms of
2385 authentication if the server is willing to try them. You will be
2386 presented with a challenge string (which will be different every
2387 time) and must supply the correct response in order to log in. If
2388 your server supports this, you should talk to your system
2389 administrator about precisely what form these challenges and
2392 \S{config-ssh-ki} \q{Attempt \i{keyboard-interactive authentication}}
2394 \cfg{winhelp-topic}{ssh.auth.ki}
2396 The SSH-2 equivalent of TIS authentication is called
2397 \q{keyboard-interactive}. It is a flexible authentication method
2398 using an arbitrary sequence of requests and responses; so it is not
2399 only useful for \I{challenge/response authentication}challenge/response
2400 mechanisms such as \i{S/Key}, but it can also be used for (for example)
2401 asking the user for a \I{password expiry}new password when the old one
2404 PuTTY leaves this option enabled by default, but supplies a switch
2405 to turn it off in case you should have trouble with it.
2407 \S{config-ssh-agentfwd} \q{Allow \i{agent forwarding}}
2409 \cfg{winhelp-topic}{ssh.auth.agentfwd}
2411 This option allows the SSH server to open forwarded connections back
2412 to your local copy of \i{Pageant}. If you are not running Pageant, this
2413 option will do nothing.
2415 See \k{pageant} for general information on Pageant, and
2416 \k{pageant-forward} for information on agent forwarding. Note that
2417 there is a security risk involved with enabling this option; see
2418 \k{pageant-security} for details.
2420 \S{config-ssh-changeuser} \q{Allow attempted \i{changes of username} in SSH-2}
2422 \cfg{winhelp-topic}{ssh.auth.changeuser}
2424 In the SSH-1 protocol, it is impossible to change username after
2425 failing to authenticate. So if you mis-type your username at the
2426 PuTTY \q{login as:} prompt, you will not be able to change it except
2427 by restarting PuTTY.
2429 The SSH-2 protocol \e{does} allow changes of username, in principle,
2430 but does not make it mandatory for SSH-2 servers to accept them. In
2431 particular, \i{OpenSSH} does not accept a change of username; once you
2432 have sent one username, it will reject attempts to try to
2433 authenticate as another user. (Depending on the version of OpenSSH,
2434 it may quietly return failure for all login attempts, or it may send
2437 For this reason, PuTTY will by default not prompt you for your
2438 username more than once, in case the server complains. If you know
2439 your server can cope with it, you can enable the \q{Allow attempted
2440 changes of username} option to modify PuTTY's behaviour.
2442 \S{config-ssh-privkey} \q{\ii{Private key} file for authentication}
2444 \cfg{winhelp-topic}{ssh.auth.privkey}
2446 This box is where you enter the name of your private key file if you
2447 are using \i{public key authentication}. See \k{pubkey} for information
2448 about public key authentication in SSH.
2450 This key must be in PuTTY's native format (\c{*.\i{PPK}}). If you have a
2451 private key in another format that you want to use with PuTTY, see
2452 \k{puttygen-conversions}.
2454 If a key file is specified here, and \i{Pageant} is running (see
2455 \k{pageant}), PuTTY will first try asking Pageant to authenticate with
2456 that key, and ignore any other keys Pageant may have. If that fails,
2457 PuTTY will ask for a passphrase as normal.
2459 \H{config-ssh-tty} The TTY panel
2461 The TTY panel lets you configure the remote pseudo-terminal.
2463 \S{config-ssh-pty} \I{pseudo-terminal allocation}\q{Don't allocate
2466 \cfg{winhelp-topic}{ssh.nopty}
2468 When connecting to a \i{Unix} system, most \I{interactive
2469 connections}interactive shell sessions are run in a \e{pseudo-terminal},
2470 which allows the Unix system to pretend it's talking to a real physical
2471 terminal device but allows the SSH server to catch all the data coming
2472 from that fake device and send it back to the client.
2474 Occasionally you might find you have a need to run a session \e{not}
2475 in a pseudo-terminal. In PuTTY, this is generally only useful for
2476 very specialist purposes; although in Plink (see \k{plink}) it is
2477 the usual way of working.
2479 \S{config-ttymodes} Sending \i{terminal modes}
2481 \cfg{winhelp-topic}{ssh.ttymodes}
2483 The SSH protocol allows the client to send \q{terminal modes} for
2484 the remote pseudo-terminal. These usually control the server's
2485 expectation of the local terminal's behaviour.
2487 If your server does not have sensible defaults for these modes, you
2488 may find that changing them here helps. If you don't understand any of
2489 this, it's safe to leave these settings alone.
2491 (None of these settings will have any effect if no pseudo-terminal
2492 is requested or allocated.)
2494 You can add or modify a mode by selecting it from the drop-down list,
2495 choosing whether it's set automatically or to a specific value with
2496 the radio buttons and edit box, and hitting \q{Add}. A mode (or
2497 several) can be removed from the list by selecting them and hitting
2498 \q{Remove}. The effect of the mode list is as follows:
2500 \b If a mode is not on the list, it will not be specified to the
2501 server under any circumstances.
2503 \b If a mode is on the list:
2507 \b If the \q{Auto} option is selected, the PuTTY tools will decide
2508 whether to specify that mode to the server, and if so, will send
2513 PuTTY proper will send modes that it has an opinion on (currently only
2514 the code for the Backspace key, \cw{ERASE}). Plink on Unix
2515 will propagate appropriate modes from the local terminal, if any.
2519 \b If a value is specified, it will be sent to the server under all
2520 circumstances. The precise syntax of the value box depends on the
2525 By default, all of the available modes are listed as \q{Auto},
2526 which should do the right thing in most circumstances.
2528 The precise effect of each setting, if any, is up to the server. Their
2529 names come from \i{POSIX} and other Unix systems, and they are most
2530 likely to have a useful effect on such systems. (These are the same
2531 settings that can usually be changed using the \i\c{stty} command once
2532 logged in to such servers.)
2534 Some notable modes are described below; for fuller explanations, see
2535 your server documentation.
2537 \b \I{ERASE special character}\cw{ERASE} is the character that when typed
2538 by the user will delete one space to the left. When set to \q{Auto}
2539 (the default setting), this follows the setting of the local Backspace
2540 key in PuTTY (see \k{config-backspace}).
2543 This and other \i{special character}s are specified using \c{^C} notation
2544 for Ctrl-C, and so on. Use \c{^<27>} or \c{^<0x1B>} to specify a
2545 character numerically, and \c{^~} to get a literal \c{^}. Other
2546 non-control characters are denoted by themselves. Leaving the box
2547 entirely blank indicates that \e{no} character should be assigned to
2548 the specified function, although this may not be supported by all
2552 \b \I{QUIT special character}\cw{QUIT} is a special character that
2553 usually forcefully ends the current process on the server
2554 (\cw{SIGQUIT}). On many servers its default setting is Ctrl-backslash
2555 (\c{^\\}), which is easy to accidentally invoke on many keyboards. If
2556 this is getting in your way, you may want to change it to another
2557 character or turn it off entirely.
2559 \b Boolean modes such as \cw{ECHO} and \cw{ICANON} can be specified in
2560 PuTTY in a variety of ways, such as \cw{true}/\cw{false},
2561 \cw{yes}/\cw{no}, and \cw{0}/\cw{1}.
2563 \b Terminal speeds are configured elsewhere; see \k{config-termspeed}.
2565 \H{config-ssh-x11} The X11 panel
2567 \cfg{winhelp-topic}{ssh.tunnels.x11}
2569 The X11 panel allows you to configure \i{forwarding of X11} over an
2572 If your server lets you run X Window System applications, X11
2573 forwarding allows you to securely give those applications access to
2574 a local X display on your PC.
2576 To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
2577 If your X display is somewhere unusual, you will need to enter its
2578 location in the \q{X display location} box; if this is left blank,
2579 PuTTY will try to find a sensible default in the environment, or use the
2580 primary local display (\c{:0}) if that fails.
2582 See \k{using-x-forwarding} for more information about X11
2585 \S{config-ssh-x11auth} Remote \i{X11 authentication}
2587 \cfg{winhelp-topic}{ssh.tunnels.x11auth}
2589 If you are using X11 forwarding, the virtual X server created on the
2590 SSH server machine will be protected by authorisation data. This
2591 data is invented, and checked, by PuTTY.
2593 The usual authorisation method used for this is called
2594 \i\cw{MIT-MAGIC-COOKIE-1}. This is a simple password-style protocol:
2595 the X client sends some cookie data to the server, and the server
2596 checks that it matches the real cookie. The cookie data is sent over
2597 an unencrypted X11 connection; so if you allow a client on a third
2598 machine to access the virtual X server, then the cookie will be sent
2601 PuTTY offers the alternative protocol \i\cw{XDM-AUTHORIZATION-1}. This
2602 is a cryptographically authenticated protocol: the data sent by the
2603 X client is different every time, and it depends on the IP address
2604 and port of the client's end of the connection and is also stamped
2605 with the current time. So an eavesdropper who captures an
2606 \cw{XDM-AUTHORIZATION-1} string cannot immediately re-use it for
2607 their own X connection.
2609 PuTTY's support for \cw{XDM-AUTHORIZATION-1} is a somewhat
2610 experimental feature, and may encounter several problems:
2612 \b Some X clients probably do not even support
2613 \cw{XDM-AUTHORIZATION-1}, so they will not know what to do with the
2614 data PuTTY has provided.
2616 \b This authentication mechanism will only work in SSH-2. In SSH-1,
2617 the SSH server does not tell the client the source address of
2618 a forwarded connection in a machine-readable format, so it's
2619 impossible to verify the \cw{XDM-AUTHORIZATION-1} data.
2621 \b You may find this feature causes problems with some SSH servers,
2622 which will not clean up \cw{XDM-AUTHORIZATION-1} data after a
2623 session, so that if you then connect to the same server using
2624 a client which only does \cw{MIT-MAGIC-COOKIE-1} and are allocated
2625 the same remote display number, you might find that out-of-date
2626 authentication data is still present on your server and your X
2629 PuTTY's default is \cw{MIT-MAGIC-COOKIE-1}. If you change it, you
2630 should be sure you know what you're doing.
2632 \H{config-ssh-portfwd} \I{port forwarding}The Tunnels panel
2634 \cfg{winhelp-topic}{ssh.tunnels.portfwd}
2636 The Tunnels panel allows you to configure tunnelling of arbitrary
2637 connection types through an SSH connection.
2639 Port forwarding allows you to tunnel other types of \i{network
2640 connection} down an SSH session. See \k{using-port-forwarding} for a
2641 general discussion of port forwarding and how it works.
2643 The port forwarding section in the Tunnels panel shows a list of all
2644 the port forwardings that PuTTY will try to set up when it connects
2645 to the server. By default no port forwardings are set up, so this
2648 To add a port forwarding:
2650 \b Set one of the \q{Local} or \q{Remote} radio buttons, depending
2651 on whether you want to \I{local port forwarding}forward a local port
2652 to a remote destination (\q{Local}) or \I{remote port forwarding}forward
2653 a remote port to a local destination (\q{Remote}). Alternatively,
2654 select \q{Dynamic} if you want PuTTY to \I{dynamic port forwarding}provide
2655 a local SOCKS 4/4A/5 proxy on a local port.
2657 \b Enter a source \i{port number} into the \q{Source port} box. For
2658 local forwardings, PuTTY will listen on this port of your PC. For
2659 remote forwardings, your SSH server will listen on this port of the
2660 remote machine. Note that most servers will not allow you to listen
2661 on \I{privileged port}port numbers less than 1024.
2663 \b If you have selected \q{Local} or \q{Remote} (this step is not
2664 needed with \q{Dynamic}), enter a hostname and port number separated
2665 by a colon, in the \q{Destination} box. Connections received on the
2666 source port will be directed to this destination. For example, to
2667 connect to a POP-3 server, you might enter
2668 \c{popserver.example.com:110}.
2670 \b Click the \q{Add} button. Your forwarding details should appear
2673 To remove a port forwarding, simply select its details in the list
2674 box, and click the \q{Remove} button.
2676 In the \q{Source port} box, you can also optionally enter an \I{listen
2677 address}IP address to listen on, by specifying (for instance)
2679 See \k{using-port-forwarding} for more information on how this
2680 works and its restrictions.
2682 In place of port numbers, you can enter \i{service names}, if they are
2683 known to the local system. For instance, in the \q{Destination} box,
2684 you could enter \c{popserver.example.com:pop3}.
2686 You can \I{port forwarding, changing mid-session}modify the currently
2687 active set of port forwardings in mid-session using \q{Change
2688 Settings} (see \k{using-changesettings}). If you delete a local or
2689 dynamic port forwarding in mid-session, PuTTY will stop listening for
2690 connections on that port, so it can be re-used by another program. If
2691 you delete a remote port forwarding, note that:
2693 \b The SSH-1 protocol contains no mechanism for asking the server to
2694 stop listening on a remote port.
2696 \b The SSH-2 protocol does contain such a mechanism, but not all SSH
2697 servers support it. (In particular, \i{OpenSSH} does not support it in
2698 any version earlier than 3.9.)
2700 If you ask to delete a remote port forwarding and PuTTY cannot make
2701 the server actually stop listening on the port, it will instead just
2702 start refusing incoming connections on that port. Therefore,
2703 although the port cannot be reused by another program, you can at
2704 least be reasonably sure that server-side programs can no longer
2705 access the service at your end of the port forwarding.
2707 If you delete a forwarding, any existing connections established using
2708 that forwarding remain open. Similarly, changes to global settings
2709 such as \q{Local ports accept connections from other hosts} only take
2710 effect on new forwardings.
2712 \S{config-ssh-portfwd-localhost} Controlling the visibility of
2715 \cfg{winhelp-topic}{ssh.tunnels.portfwd.localhost}
2717 The source port for a forwarded connection usually does not accept
2718 connections from any machine except the \I{localhost}SSH client or
2719 server machine itself (for local and remote forwardings respectively).
2720 There are controls in the Tunnels panel to change this:
2722 \b The \q{Local ports accept connections from other hosts} option
2723 allows you to set up local-to-remote port forwardings in such a way
2724 that machines other than your client PC can connect to the forwarded
2725 port. (This also applies to dynamic SOCKS forwarding.)
2727 \b The \q{Remote ports do the same} option does the same thing for
2728 remote-to-local port forwardings (so that machines other than the
2729 SSH server machine can connect to the forwarded port.) Note that
2730 this feature is only available in the SSH-2 protocol, and not all
2731 SSH-2 servers support it (\i{OpenSSH} 3.0 does not, for example).
2733 \S{config-ssh-portfwd-address-family} Selecting \i{Internet protocol
2734 version} for forwarded ports
2736 \cfg{winhelp-topic}{ssh.tunnels.portfwd.ipversion}
2738 This switch allows you to select a specific Internet protocol (\i{IPv4}
2739 or \i{IPv6}) for the local end of a forwarded port. By default, it is
2740 set on \q{Auto}, which means that:
2742 \b for a local-to-remote port forwarding, PuTTY will listen for
2743 incoming connections in both IPv4 and (if available) IPv6
2745 \b for a remote-to-local port forwarding, PuTTY will choose a
2746 sensible protocol for the outgoing connection.
2748 Note that some operating systems may listen for incoming connections
2749 in IPv4 even if you specifically asked for IPv6, because their IPv4
2750 and IPv6 protocol stacks are linked together. Apparently \i{Linux} does
2751 this, and Windows does not. So if you're running PuTTY on Windows
2752 and you tick \q{IPv6} for a local or dynamic port forwarding, it
2753 will \e{only} be usable by connecting to it using IPv6; whereas if
2754 you do the same on Linux, you can also use it with IPv4. However,
2755 ticking \q{Auto} should always give you a port which you can connect
2756 to using either protocol.
2758 \H{config-ssh-bugs} \I{SSH server bugs}The Bugs panel
2760 Not all SSH servers work properly. Various existing servers have
2761 bugs in them, which can make it impossible for a client to talk to
2762 them unless it knows about the bug and works around it.
2764 Since most servers announce their software version number at the
2765 beginning of the SSH connection, PuTTY will attempt to detect which
2766 bugs it can expect to see in the server and automatically enable
2767 workarounds. However, sometimes it will make mistakes; if the server
2768 has been deliberately configured to conceal its version number, or
2769 if the server is a version which PuTTY's bug database does not know
2770 about, then PuTTY will not know what bugs to expect.
2772 The Bugs panel allows you to manually configure the bugs PuTTY
2773 expects to see in the server. Each bug can be configured in three
2776 \b \q{Off}: PuTTY will assume the server does not have the bug.
2778 \b \q{On}: PuTTY will assume the server \e{does} have the bug.
2780 \b \q{Auto}: PuTTY will use the server's version number announcement
2781 to try to guess whether or not the server has the bug.
2783 \S{config-ssh-bug-ignore1} \q{Chokes on SSH-1 \i{ignore message}s}
2785 \cfg{winhelp-topic}{ssh.bugs.ignore1}
2787 An ignore message (SSH_MSG_IGNORE) is a message in the SSH protocol
2788 which can be sent from the client to the server, or from the server
2789 to the client, at any time. Either side is required to ignore the
2790 message whenever it receives it. PuTTY uses ignore messages to hide
2791 the password packet in SSH-1, so that a listener cannot tell the
2792 length of the user's password; it also uses ignore messages for
2793 connection keepalives (see \k{config-keepalive}).
2795 If this bug is detected, PuTTY will stop using ignore messages. This
2796 means that keepalives will stop working, and PuTTY will have to fall
2797 back to a secondary defence against SSH-1 password-length
2798 eavesdropping. See \k{config-ssh-bug-plainpw1}. If this bug is
2799 enabled when talking to a correct server, the session will succeed,
2800 but keepalives will not work and the session might be more
2801 vulnerable to eavesdroppers than it could be.
2803 This is an SSH-1-specific bug. No known SSH-2 server fails to deal
2804 with SSH-2 ignore messages.
2806 \S{config-ssh-bug-plainpw1} \q{Refuses all SSH-1 \i{password camouflage}}
2808 \cfg{winhelp-topic}{ssh.bugs.plainpw1}
2810 When talking to an SSH-1 server which cannot deal with ignore
2811 messages (see \k{config-ssh-bug-ignore1}), PuTTY will attempt to
2812 disguise the length of the user's password by sending additional
2813 padding \e{within} the password packet. This is technically a
2814 violation of the SSH-1 specification, and so PuTTY will only do it
2815 when it cannot use standards-compliant ignore messages as
2816 camouflage. In this sense, for a server to refuse to accept a padded
2817 password packet is not really a bug, but it does make life
2818 inconvenient if the server can also not handle ignore messages.
2820 If this \q{bug} is detected, PuTTY will have no choice but to send
2821 the user's password with no form of camouflage, so that an
2822 eavesdropping user will be easily able to find out the exact length
2823 of the password. If this bug is enabled when talking to a correct
2824 server, the session will succeed, but will be more vulnerable to
2825 eavesdroppers than it could be.
2827 This is an SSH-1-specific bug. SSH-2 is secure against this type of
2830 \S{config-ssh-bug-rsa1} \q{Chokes on SSH-1 \i{RSA} authentication}
2832 \cfg{winhelp-topic}{ssh.bugs.rsa1}
2834 Some SSH-1 servers cannot deal with RSA authentication messages at
2835 all. If \i{Pageant} is running and contains any SSH-1 keys, PuTTY will
2836 normally automatically try RSA authentication before falling back to
2837 passwords, so these servers will crash when they see the RSA attempt.
2839 If this bug is detected, PuTTY will go straight to password
2840 authentication. If this bug is enabled when talking to a correct
2841 server, the session will succeed, but of course RSA authentication
2844 This is an SSH-1-specific bug.
2846 \S{config-ssh-bug-hmac2} \q{Miscomputes SSH-2 HMAC keys}
2848 \cfg{winhelp-topic}{ssh.bugs.hmac2}
2850 Versions 2.3.0 and below of the SSH server software from
2851 \cw{ssh.com} compute the keys for their \i{HMAC} \i{message authentication
2852 code}s incorrectly. A typical symptom of this problem is that PuTTY
2853 dies unexpectedly at the beginning of the session, saying
2854 \q{Incorrect MAC received on packet}.
2856 If this bug is detected, PuTTY will compute its HMAC keys in the
2857 same way as the buggy server, so that communication will still be
2858 possible. If this bug is enabled when talking to a correct server,
2859 communication will fail.
2861 This is an SSH-2-specific bug.
2863 \S{config-ssh-bug-derivekey2} \q{Miscomputes SSH-2 \i{encryption} keys}
2865 \cfg{winhelp-topic}{ssh.bugs.derivekey2}
2867 Versions below 2.0.11 of the SSH server software from \i\cw{ssh.com}
2868 compute the keys for the session encryption incorrectly. This
2869 problem can cause various error messages, such as \q{Incoming packet
2870 was garbled on decryption}, or possibly even \q{Out of memory}.
2872 If this bug is detected, PuTTY will compute its encryption keys in
2873 the same way as the buggy server, so that communication will still
2874 be possible. If this bug is enabled when talking to a correct
2875 server, communication will fail.
2877 This is an SSH-2-specific bug.
2879 \S{config-ssh-bug-sig} \q{Requires padding on SSH-2 \i{RSA} \i{signatures}}
2881 \cfg{winhelp-topic}{ssh.bugs.rsapad2}
2883 Versions below 3.3 of \i{OpenSSH} require SSH-2 RSA signatures to be
2884 padded with zero bytes to the same length as the RSA key modulus.
2885 The SSH-2 draft specification says that an unpadded signature MUST be
2886 accepted, so this is a bug. A typical symptom of this problem is
2887 that PuTTY mysteriously fails RSA authentication once in every few
2888 hundred attempts, and falls back to passwords.
2890 If this bug is detected, PuTTY will pad its signatures in the way
2891 OpenSSH expects. If this bug is enabled when talking to a correct
2892 server, it is likely that no damage will be done, since correct
2893 servers usually still accept padded signatures because they're used
2894 to talking to OpenSSH.
2896 This is an SSH-2-specific bug.
2898 \S{config-ssh-bug-pksessid2} \q{Misuses the \i{session ID} in SSH-2 PK auth}
2900 \cfg{winhelp-topic}{ssh.bugs.pksessid2}
2902 Versions below 2.3 of \i{OpenSSH} require SSH-2 \i{public-key authentication}
2903 to be done slightly differently: the data to be signed by the client
2904 contains the session ID formatted in a different way. If public-key
2905 authentication mysteriously does not work but the Event Log (see
2906 \k{using-eventlog}) thinks it has successfully sent a signature, it
2907 might be worth enabling the workaround for this bug to see if it
2910 If this bug is detected, PuTTY will sign data in the way OpenSSH
2911 expects. If this bug is enabled when talking to a correct server,
2912 SSH-2 public-key authentication will fail.
2914 This is an SSH-2-specific bug.
2916 \S{config-ssh-bug-rekey} \q{Handles SSH-2 key re-exchange badly}
2918 \cfg{winhelp-topic}{ssh.bugs.rekey2}
2920 Some SSH servers cannot cope with \i{repeat key exchange} at
2921 all, and will ignore attempts by the client to start one. Since
2922 PuTTY pauses the session while performing a repeat key exchange, the
2923 effect of this would be to cause the session to hang after an hour
2924 (unless you have your rekey timeout set differently; see
2925 \k{config-ssh-kex-rekey} for more about rekeys).
2926 Other, very old, SSH servers handle repeat key exchange even more
2927 badly, and disconnect upon receiving a repeat key exchange request.
2929 If this bug is detected, PuTTY will never initiate a repeat key
2930 exchange. If this bug is enabled when talking to a correct server,
2931 the session should still function, but may be less secure than you
2934 This is an SSH-2-specific bug.
2936 \H{config-serial} The Serial panel
2938 The \i{Serial} panel allows you to configure options that only apply
2939 when PuTTY is connecting to a local \I{serial port}\i{serial line}.
2941 \S{config-serial-line} Selecting a serial line to connect to
2943 \cfg{winhelp-topic}{serial.line}
2945 The \q{Serial line to connect to} box allows you to choose which
2946 serial line you want PuTTY to talk to, if your computer has more
2947 than one serial port.
2949 On Windows, the first serial line is called \cw{COM1}, and if there
2950 is a second it is called \cw{COM2}, and so on.
2952 This configuration setting is also visible on the Session panel,
2953 where it replaces the \q{Host Name} box (see \k{config-hostname}) if
2954 the connection type is set to \q{Serial}.
2956 \S{config-serial-speed} Selecting the speed of your serial line
2958 \cfg{winhelp-topic}{serial.speed}
2960 The \q{Speed} box allows you to choose the speed (or \q{baud rate})
2961 at which to talk to the serial line. Typical values might be 9600,
2962 19200, 38400 or 57600. Which one you need will depend on the device
2963 at the other end of the serial cable; consult the manual for that
2964 device if you are in doubt.
2966 This configuration setting is also visible on the Session panel,
2967 where it replaces the \q{Port} box (see \k{config-hostname}) if the
2968 connection type is set to \q{Serial}.
2970 \S{config-serial-databits} Selecting the number of data bits
2972 \cfg{winhelp-topic}{serial.databits}
2974 The \q{Data bits} box allows you to choose how many data bits are
2975 transmitted in each byte sent or received through the serial line.
2976 Typical values are 7 or 8.
2978 \S{config-serial-stopbits} Selecting the number of stop bits
2980 \cfg{winhelp-topic}{serial.stopbits}
2982 The \q{Stop bits} box allows you to choose how many stop bits are
2983 used in the serial line protocol. Typical values are 1, 1.5 or 2.
2985 \S{config-serial-parity} Selecting the serial parity checking scheme
2987 \cfg{winhelp-topic}{serial.parity}
2989 The \q{Parity} box allows you to choose what type of parity checking
2990 is used on the serial line. The settings are:
2992 \b \q{None}: no parity bit is sent at all.
2994 \b \q{Odd}: an extra parity bit is sent alongside each byte, and
2995 arranged so that the total number of 1 bits is odd.
2997 \b \q{Even}: an extra parity bit is sent alongside each byte, and
2998 arranged so that the total number of 1 bits is even.
3000 \b \q{Mark}: an extra parity bit is sent alongside each byte, and
3003 \b \q{Space}: an extra parity bit is sent alongside each byte, and
3006 \S{config-serial-flow} Selecting the serial flow control scheme
3008 \cfg{winhelp-topic}{serial.flow}
3010 The \q{Flow control} box allows you to choose what type of flow
3011 control checking is used on the serial line. The settings are:
3013 \b \q{None}: no flow control is done. Data may be lost if either
3014 side attempts to send faster than the serial line permits.
3016 \b \q{XON/XOFF}: flow control is done by sending XON and XOFF
3017 characters within the data stream.
3019 \b \q{RTS/CTS}: flow control is done using the RTS and CTS wires on
3022 \b \q{DSR/DTR}: flow control is done using the DSR and DTR wires on
3025 \H{config-file} \ii{Storing configuration in a file}
3027 PuTTY does not currently support storing its configuration in a file
3028 instead of the \i{Registry}. However, you can work around this with a
3029 couple of \i{batch file}s.
3031 You will need a file called (say) \c{PUTTY.BAT} which imports the
3032 contents of a file into the Registry, then runs PuTTY, exports the
3033 contents of the Registry back into the file, and deletes the
3034 Registry entries. This can all be done using the Regedit command
3035 line options, so it's all automatic. Here is what you need in
3039 \c regedit /s putty.reg
3040 \c regedit /s puttyrnd.reg
3041 \c start /w putty.exe
3042 \c regedit /ea new.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
3043 \c copy new.reg putty.reg
3045 \c regedit /s puttydel.reg
3047 This batch file needs two auxiliary files: \c{PUTTYRND.REG} which
3048 sets up an initial safe location for the \c{PUTTY.RND} random seed
3049 file, and \c{PUTTYDEL.REG} which destroys everything in the Registry
3050 once it's been successfully saved back to the file.
3052 Here is \c{PUTTYDEL.REG}:
3056 \c [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
3058 Here is an example \c{PUTTYRND.REG} file:
3062 \c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
3063 \c "RandSeedFile"="a:\\putty.rnd"
3065 You should replace \c{a:\\putty.rnd} with the location where you
3066 want to store your random number data. If the aim is to carry around
3067 PuTTY and its settings on one floppy, you probably want to store it