1 \C{config} Configuring PuTTY
3 This chapter describes all the \i{configuration options} in PuTTY.
5 PuTTY is configured using the control panel that comes up before you
6 start a session. Some options can also be changed in the middle of a
7 session, by selecting \q{Change Settings} from the window menu.
9 \H{config-session} The Session panel
11 The Session configuration panel contains the basic options you need
12 to specify in order to open a session at all, and also allows you to
13 save your settings to be reloaded later.
15 \S{config-hostname} The \i{host name} section
17 \cfg{winhelp-topic}{session.hostname}
19 The top box on the Session panel, labelled \q{Specify your
20 connection by host name}, contains the details that need to be
21 filled in before PuTTY can open a session at all.
23 \b The \q{Host Name} box is where you type the name, or the \i{IP
24 address}, of the server you want to connect to.
26 \b The \q{Connection type} radio buttons let you choose what type of
27 connection you want to make: a \I{raw TCP connections}raw
28 connection, a \i{Telnet} connection, an \i{Rlogin} connection, an
29 \i{SSH} connection, or a connection to a local \i{serial line}. (See
30 \k{which-one} for a summary of the differences between SSH, Telnet
31 and rlogin; see \k{using-rawprot} for an explanation of \q{raw}
32 connections; see \k{using-serial} for information about using a
35 \b The \q{Port} box lets you specify which \i{port number} on the
36 server to connect to. If you select Telnet, Rlogin, or SSH, this box
37 will be filled in automatically to the usual value, and you will
38 only need to change it if you have an unusual server. If you select
39 Raw mode, you will almost certainly need to fill in the \q{Port} box
42 If you select \q{Serial} from the \q{Connection type} radio buttons,
43 the \q{Host Name} and \q{Port} boxes are replaced by \q{Serial line}
44 and \q{Speed}; see \k{config-serial} for more details of these.
46 \S{config-saving} \ii{Loading and storing saved sessions}
48 \cfg{winhelp-topic}{session.saved}
50 The next part of the Session configuration panel allows you to save
51 your preferred PuTTY options so they will appear automatically the
52 next time you start PuTTY. It also allows you to create \e{saved
53 sessions}, which contain a full set of configuration options plus a
54 host name and protocol. A saved session contains all the information
55 PuTTY needs to start exactly the session you want.
57 \b To save your default settings: first set up the settings the way
58 you want them saved. Then come back to the Session panel. Select the
59 \q{\i{Default Settings}} entry in the saved sessions list, with a single
60 click. Then press the \q{Save} button.
62 If there is a specific host you want to store the details of how to
63 connect to, you should create a saved session, which will be
64 separate from the Default Settings.
66 \b To save a session: first go through the rest of the configuration
67 box setting up all the options you want. Then come back to the
68 Session panel. Enter a name for the saved session in the \q{Saved
69 Sessions} input box. (The server name is often a good choice for a
70 saved session name.) Then press the \q{Save} button. Your saved
71 session name should now appear in the list box.
74 You can also save settings in mid-session, from the \q{Change Settings}
75 dialog. Settings changed since the start of the session will be saved
76 with their current values; as well as settings changed through the
77 dialog, this includes changes in window size, window title changes
78 sent by the server, and so on.
81 \b To reload a saved session: single-click to select the session
82 name in the list box, and then press the \q{Load} button. Your saved
83 settings should all appear in the configuration panel.
85 \b To modify a saved session: first load it as described above. Then
86 make the changes you want. Come back to the Session panel, and press
87 the \q{Save} button. The new settings will be saved over the top of
91 To save the new settings under a different name, you can enter the new
92 name in the \q{Saved Sessions} box, or single-click to select a
93 session name in the list box to overwrite that session. To save
94 \q{Default Settings}, you must single-click the name before saving.
97 \b To start a saved session immediately: double-click on the session
100 \b To delete a saved session: single-click to select the session
101 name in the list box, and then press the \q{Delete} button.
103 Each saved session is independent of the Default Settings
104 configuration. If you change your preferences and update Default
105 Settings, you must also update every saved session separately.
107 Saved sessions are stored in the \i{Registry}, at the location
109 \c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\Sessions
111 If you need to store them in a file, you could try the method
112 described in \k{config-file}.
114 \S{config-closeonexit} \q{\ii{Close Window} on Exit}
116 \cfg{winhelp-topic}{session.coe}
118 Finally in the Session panel, there is an option labelled \q{Close
119 Window on Exit}. This controls whether the PuTTY \i{terminal window}
120 disappears as soon as the session inside it terminates. If you are
121 likely to want to copy and paste text out of the session after it
122 has terminated, or restart the session, you should arrange for this
125 \q{Close Window On Exit} has three settings. \q{Always} means always
126 close the window on exit; \q{Never} means never close on exit
127 (always leave the window open, but \I{inactive window}inactive). The
128 third setting, and the default one, is \q{Only on clean exit}. In this
129 mode, a session which terminates normally will cause its window to
130 close, but one which is aborted unexpectedly by network trouble or a
131 confusing message from the server will leave the window up.
133 \H{config-logging} The Logging panel
135 \cfg{winhelp-topic}{logging.main}
137 The Logging configuration panel allows you to save \i{log file}s of your
138 PuTTY sessions, for debugging, analysis or future reference.
140 The main option is a radio-button set that specifies whether PuTTY
141 will log anything at all. The options are:
143 \b \q{None}. This is the default option; in this mode PuTTY will not
144 create a log file at all.
146 \b \q{Printable output}. In this mode, a log file will be
147 created and written to, but only printable text will be saved into
148 it. The various terminal control codes that are typically sent down
149 an interactive session alongside the printable text will be omitted.
150 This might be a useful mode if you want to read a log file in a text
151 editor and hope to be able to make sense of it.
153 \b \q{All session output}. In this mode, \e{everything} sent by
154 the server into your terminal session is logged. If you view the log
155 file in a text editor, therefore, you may well find it full of
156 strange control characters. This is a particularly useful mode if
157 you are experiencing problems with PuTTY's terminal handling: you
158 can record everything that went to the terminal, so that someone
159 else can replay the session later in slow motion and watch to see
162 \b \I{SSH packet log}\q{SSH packets}. In this mode (which is only used
163 by SSH connections), the SSH message packets sent over the encrypted
164 connection are written to the log file (as well as \i{Event Log}
165 entries). You might need this to debug a network-level problem, or
166 more likely to send to the PuTTY authors as part of a bug report.
167 \e{BE WARNED} that if you log in using a password, the password can
168 appear in the log file; see \k{config-logssh} for options that may
169 help to remove sensitive material from the log file before you send it
172 \b \q{SSH packets and raw data}. In this mode, as well as the
173 decrypted packets (as in the previous mode), the \e{raw} (encrypted,
174 compressed, etc) packets are \e{also} logged. This could be useful to
175 diagnose corruption in transit. (The same caveats as the previous mode
178 Note that the non-SSH logging options (\q{Printable output} and
179 \q{All session output}) only work with PuTTY proper; in programs
180 without terminal emulation (such as Plink), they will have no effect,
181 even if enabled via saved settings.
183 \S{config-logfilename} \q{Log file name}
185 \cfg{winhelp-topic}{logging.filename}
187 In this edit box you enter the name of the file you want to log the
188 session to. The \q{Browse} button will let you look around your file
189 system to find the right place to put the file; or if you already
190 know exactly where you want it to go, you can just type a pathname
193 There are a few special features in this box. If you use the \c{&}
194 character in the file name box, PuTTY will insert details of the
195 current session in the name of the file it actually opens. The
196 precise replacements it will do are:
198 \b \c{&Y} will be replaced by the current year, as four digits.
200 \b \c{&M} will be replaced by the current month, as two digits.
202 \b \c{&D} will be replaced by the current day of the month, as two
205 \b \c{&T} will be replaced by the current time, as six digits
206 (HHMMSS) with no punctuation.
208 \b \c{&H} will be replaced by the host name you are connecting to.
210 \b \c{&P} will be replaced by the port number you are connecting to on
213 For example, if you enter the host name
214 \c{c:\\puttylogs\\log-&h-&y&m&d-&t.dat}, you will end up with files looking
217 \c log-server1.example.com-20010528-110859.dat
218 \c log-unixbox.somewhere.org-20010611-221001.dat
220 \S{config-logfileexists} \q{What to do if the log file already exists}
222 \cfg{winhelp-topic}{logging.exists}
224 This control allows you to specify what PuTTY should do if it tries
225 to start writing to a log file and it finds the file already exists.
226 You might want to automatically destroy the existing log file and
227 start a new one with the same name. Alternatively, you might want to
228 open the existing log file and add data to the \e{end} of it.
229 Finally (the default option), you might not want to have any
230 automatic behaviour, but to ask the user every time the problem
233 \S{config-logflush} \I{log file, flushing}\q{Flush log file frequently}
235 \cfg{winhelp-topic}{logging.flush}
237 This option allows you to control how frequently logged data is
238 flushed to disc. By default, PuTTY will flush data as soon as it is
239 displayed, so that if you view the log file while a session is still
240 open, it will be up to date; and if the client system crashes, there's
241 a greater chance that the data will be preserved.
243 However, this can incur a performance penalty. If PuTTY is running
244 slowly with logging enabled, you could try unchecking this option. Be
245 warned that the log file may not always be up to date as a result
246 (although it will of course be flushed when it is closed, for instance
247 at the end of a session).
249 \S{config-logssh} Options specific to \i{SSH packet log}ging
251 These options only apply if SSH packet data is being logged.
253 The following options allow particularly sensitive portions of
254 unencrypted packets to be automatically left out of the log file.
255 They are only intended to deter casual nosiness; an attacker could
256 glean a lot of useful information from even these obfuscated logs
257 (e.g., length of password).
259 \S2{config-logssh-omitpw} \q{Omit known password fields}
261 \cfg{winhelp-topic}{logging.ssh.omitpassword}
263 When checked, decrypted password fields are removed from the log of
264 transmitted packets. (This includes any user responses to
265 challenge-response authentication methods such as
266 \q{keyboard-interactive}.) This does not include X11 authentication
267 data if using X11 forwarding.
269 Note that this will only omit data that PuTTY \e{knows} to be a
270 password. However, if you start another login session within your
271 PuTTY session, for instance, any password used will appear in the
272 clear in the packet log. The next option may be of use to protect
275 This option is enabled by default.
277 \S2{config-logssh-omitdata} \q{Omit session data}
279 \cfg{winhelp-topic}{logging.ssh.omitdata}
281 When checked, all decrypted \q{session data} is omitted; this is
282 defined as data in terminal sessions and in forwarded channels (TCP,
283 X11, and authentication agent). This will usually substantially reduce
284 the size of the resulting log file.
286 This option is disabled by default.
288 \H{config-terminal} The Terminal panel
290 The Terminal configuration panel allows you to control the behaviour
291 of PuTTY's \i{terminal emulation}.
293 \S{config-autowrap} \q{Auto wrap mode initially on}
295 \cfg{winhelp-topic}{terminal.autowrap}
297 \ii{Auto wrap mode} controls what happens when text printed in a PuTTY
298 window reaches the right-hand edge of the window.
300 With auto wrap mode on, if a long line of text reaches the
301 right-hand edge, it will wrap over on to the next line so you can
302 still see all the text. With auto wrap mode off, the cursor will
303 stay at the right-hand edge of the screen, and all the characters in
304 the line will be printed on top of each other.
306 If you are running a full-screen application and you occasionally
307 find the screen scrolling up when it looks as if it shouldn't, you
308 could try turning this option off.
310 Auto wrap mode can be turned on and off by \i{control sequence}s sent by
311 the server. This configuration option controls the \e{default}
312 state, which will be restored when you reset the terminal (see
313 \k{reset-terminal}). However, if you modify this option in
314 mid-session using \q{Change Settings}, it will take effect
317 \S{config-decom} \q{DEC Origin Mode initially on}
319 \cfg{winhelp-topic}{terminal.decom}
321 \i{DEC Origin Mode} is a minor option which controls how PuTTY
322 interprets cursor-position \i{control sequence}s sent by the server.
324 The server can send a control sequence that restricts the \i{scrolling
325 region} of the display. For example, in an editor, the server might
326 reserve a line at the top of the screen and a line at the bottom,
327 and might send a control sequence that causes scrolling operations
328 to affect only the remaining lines.
330 With DEC Origin Mode on, \i{cursor coordinates} are counted from the top
331 of the scrolling region. With it turned off, cursor coordinates are
332 counted from the top of the whole screen regardless of the scrolling
335 It is unlikely you would need to change this option, but if you find
336 a full-screen application is displaying pieces of text in what looks
337 like the wrong part of the screen, you could try turning DEC Origin
338 Mode on to see whether that helps.
340 DEC Origin Mode can be turned on and off by control sequences sent
341 by the server. This configuration option controls the \e{default}
342 state, which will be restored when you reset the terminal (see
343 \k{reset-terminal}). However, if you modify this option in
344 mid-session using \q{Change Settings}, it will take effect
347 \S{config-crlf} \q{Implicit CR in every LF}
349 \cfg{winhelp-topic}{terminal.lfhascr}
351 Most servers send two control characters, \i{CR} and \i{LF}, to start a
352 \i{new line} of the screen. The CR character makes the cursor return to the
353 left-hand side of the screen. The LF character makes the cursor move
354 one line down (and might make the screen scroll).
356 Some servers only send LF, and expect the terminal to move the
357 cursor over to the left automatically. If you come across a server
358 that does this, you will see a \I{stair-stepping}stepped effect on the
361 \c First line of text
365 If this happens to you, try enabling the \q{Implicit CR in every LF}
366 option, and things might go back to normal:
368 \c First line of text
372 \S{config-lfcr} \q{Implicit LF in every CR}
374 \cfg{winhelp-topic}{terminal.crhaslf}
376 Most servers send two control characters, \i{CR} and \i{LF}, to start a
377 \i{new line} of the screen. The CR character makes the cursor return to the
378 left-hand side of the screen. The LF character makes the cursor move
379 one line down (and might make the screen scroll).
381 Some servers only send CR, and so the newly
382 written line is overwritten by the following line. This option causes
383 a line feed so that all lines are displayed.
385 \S{config-erase} \q{Use \i{background colour} to erase screen}
387 \cfg{winhelp-topic}{terminal.bce}
389 Not all terminals agree on what colour to turn the screen when the
390 server sends a \q{\i{clear screen}} sequence. Some terminals believe the
391 screen should always be cleared to the \e{default} background
392 colour. Others believe the screen should be cleared to whatever the
393 server has selected as a background colour.
395 There exist applications that expect both kinds of behaviour.
396 Therefore, PuTTY can be configured to do either.
398 With this option disabled, screen clearing is always done in the
399 default background colour. With this option enabled, it is done in
400 the \e{current} background colour.
402 Background-colour erase can be turned on and off by \i{control
403 sequences} sent by the server. This configuration option controls the
404 \e{default} state, which will be restored when you reset the
405 terminal (see \k{reset-terminal}). However, if you modify this
406 option in mid-session using \q{Change Settings}, it will take effect
409 \S{config-blink} \q{Enable \i{blinking text}}
411 \cfg{winhelp-topic}{terminal.blink}
413 The server can ask PuTTY to display text that blinks on and off.
414 This is very distracting, so PuTTY allows you to turn blinking text
417 When blinking text is disabled and the server attempts to make some
418 text blink, PuTTY will instead display the text with a \I{background
419 colour, bright}bolded background colour.
421 Blinking text can be turned on and off by \i{control sequence}s sent by
422 the server. This configuration option controls the \e{default}
423 state, which will be restored when you reset the terminal (see
424 \k{reset-terminal}). However, if you modify this option in
425 mid-session using \q{Change Settings}, it will take effect
428 \S{config-answerback} \q{\ii{Answerback} to ^E}
430 \cfg{winhelp-topic}{terminal.answerback}
432 This option controls what PuTTY will send back to the server if the
433 server sends it the ^E \i{enquiry character}. Normally it just sends
434 the string \q{PuTTY}.
436 If you accidentally write the contents of a binary file to your
437 terminal, you will probably find that it contains more than one ^E
438 character, and as a result your next command line will probably read
439 \q{PuTTYPuTTYPuTTY...} as if you had typed the answerback string
440 multiple times at the keyboard. If you set the answerback string to
441 be empty, this problem should go away, but doing so might cause
444 Note that this is \e{not} the feature of PuTTY which the server will
445 typically use to determine your terminal type. That feature is the
446 \q{\ii{Terminal-type} string} in the Connection panel; see
447 \k{config-termtype} for details.
449 You can include control characters in the answerback string using
450 \c{^C} notation. (Use \c{^~} to get a literal \c{^}.)
452 \S{config-localecho} \q{\ii{Local echo}}
454 \cfg{winhelp-topic}{terminal.localecho}
456 With local echo disabled, characters you type into the PuTTY window
457 are not echoed in the window \e{by PuTTY}. They are simply sent to
458 the server. (The \e{server} might choose to \I{remote echo}echo them
459 back to you; this can't be controlled from the PuTTY control panel.)
461 Some types of session need local echo, and many do not. In its
462 default mode, PuTTY will automatically attempt to deduce whether or
463 not local echo is appropriate for the session you are working in. If
464 you find it has made the wrong decision, you can use this
465 configuration option to override its choice: you can force local
466 echo to be turned on, or force it to be turned off, instead of
467 relying on the automatic detection.
469 \S{config-localedit} \q{\ii{Local line editing}}
471 \cfg{winhelp-topic}{terminal.localedit}
473 Normally, every character you type into the PuTTY window is sent
474 immediately to the server the moment you type it.
476 If you enable local line editing, this changes. PuTTY will let you
477 edit a whole line at a time locally, and the line will only be sent
478 to the server when you press Return. If you make a mistake, you can
479 use the Backspace key to correct it before you press Return, and the
480 server will never see the mistake.
482 Since it is hard to edit a line locally without being able to see
483 it, local line editing is mostly used in conjunction with \i{local echo}
484 (\k{config-localecho}). This makes it ideal for use in raw mode
485 \#{FIXME} or when connecting to \i{MUD}s or \i{talker}s. (Although some more
486 advanced MUDs do occasionally turn local line editing on and turn
487 local echo off, in order to accept a password from the user.)
489 Some types of session need local line editing, and many do not. In
490 its default mode, PuTTY will automatically attempt to deduce whether
491 or not local line editing is appropriate for the session you are
492 working in. If you find it has made the wrong decision, you can use
493 this configuration option to override its choice: you can force
494 local line editing to be turned on, or force it to be turned off,
495 instead of relying on the automatic detection.
497 \S{config-printing} \ii{Remote-controlled printing}
499 \cfg{winhelp-topic}{terminal.printing}
501 A lot of VT100-compatible terminals support printing under control
502 of the remote server. PuTTY supports this feature as well, but it is
503 turned off by default.
505 To enable remote-controlled printing, choose a printer from the
506 \q{Printer to send ANSI printer output to} drop-down list box. This
507 should allow you to select from all the printers you have installed
508 drivers for on your computer. Alternatively, you can type the
509 network name of a networked printer (for example,
510 \c{\\\\printserver\\printer1}) even if you haven't already
511 installed a driver for it on your own machine.
513 When the remote server attempts to print some data, PuTTY will send
514 that data to the printer \e{raw} - without translating it,
515 attempting to format it, or doing anything else to it. It is up to
516 you to ensure your remote server knows what type of printer it is
519 Since PuTTY sends data to the printer raw, it cannot offer options
520 such as portrait versus landscape, print quality, or paper tray
521 selection. All these things would be done by your PC printer driver
522 (which PuTTY bypasses); if you need them done, you will have to find
523 a way to configure your remote server to do them.
525 To disable remote printing again, choose \q{None (printing
526 disabled)} from the printer selection list. This is the default
529 \H{config-keyboard} The Keyboard panel
531 The Keyboard configuration panel allows you to control the behaviour
532 of the \i{keyboard} in PuTTY. The correct state for many of these
533 settings depends on what the server to which PuTTY is connecting
534 expects. With a \i{Unix} server, this is likely to depend on the
535 \i\c{termcap} or \i\c{terminfo} entry it uses, which in turn is likely to
536 be controlled by the \q{\ii{Terminal-type} string} setting in the Connection
537 panel; see \k{config-termtype} for details. If none of the settings here
538 seems to help, you may find \k{faq-keyboard} to be useful.
540 \S{config-backspace} Changing the action of the \ii{Backspace key}
542 \cfg{winhelp-topic}{keyboard.backspace}
544 Some terminals believe that the Backspace key should send the same
545 thing to the server as \i{Control-H} (ASCII code 8). Other terminals
546 believe that the Backspace key should send ASCII code 127 (usually
547 known as \i{Control-?}) so that it can be distinguished from Control-H.
548 This option allows you to choose which code PuTTY generates when you
551 If you are connecting over SSH, PuTTY by default tells the server
552 the value of this option (see \k{config-ttymodes}), so you may find
553 that the Backspace key does the right thing either way. Similarly,
554 if you are connecting to a \i{Unix} system, you will probably find that
555 the Unix \i\c{stty} command lets you configure which the server
556 expects to see, so again you might not need to change which one PuTTY
557 generates. On other systems, the server's expectation might be fixed
558 and you might have no choice but to configure PuTTY.
560 If you do have the choice, we recommend configuring PuTTY to
561 generate Control-? and configuring the server to expect it, because
562 that allows applications such as \c{emacs} to use Control-H for
565 (Typing \i{Shift-Backspace} will cause PuTTY to send whichever code
566 isn't configured here as the default.)
568 \S{config-homeend} Changing the action of the \i{Home and End keys}
570 \cfg{winhelp-topic}{keyboard.homeend}
572 The Unix terminal emulator \i\c{rxvt} disagrees with the rest of the
573 world about what character sequences should be sent to the server by
574 the Home and End keys.
576 \i\c{xterm}, and other terminals, send \c{ESC [1~} for the Home key,
577 and \c{ESC [4~} for the End key. \c{rxvt} sends \c{ESC [H} for the
578 Home key and \c{ESC [Ow} for the End key.
580 If you find an application on which the Home and End keys aren't
581 working, you could try switching this option to see if it helps.
583 \S{config-funkeys} Changing the action of the \i{function keys} and
586 \cfg{winhelp-topic}{keyboard.funkeys}
588 This option affects the function keys (F1 to F12) and the top row of
591 \b In the default mode, labelled \c{ESC [n~}, the function keys
592 generate sequences like \c{ESC [11~}, \c{ESC [12~} and so on. This
593 matches the general behaviour of Digital's terminals.
595 \b In Linux mode, F6 to F12 behave just like the default mode, but
596 F1 to F5 generate \c{ESC [[A} through to \c{ESC [[E}. This mimics the
597 \i{Linux virtual console}.
599 \b In \I{xterm}Xterm R6 mode, F5 to F12 behave like the default mode, but F1
600 to F4 generate \c{ESC OP} through to \c{ESC OS}, which are the
601 sequences produced by the top row of the \e{keypad} on Digital's
604 \b In \i{VT400} mode, all the function keys behave like the default
605 mode, but the actual top row of the numeric keypad generates \c{ESC
606 OP} through to \c{ESC OS}.
608 \b In \i{VT100+} mode, the function keys generate \c{ESC OP} through to
611 \b In \i{SCO} mode, the function keys F1 to F12 generate \c{ESC [M}
612 through to \c{ESC [X}. Together with shift, they generate \c{ESC [Y}
613 through to \c{ESC [j}. With control they generate \c{ESC [k} through
614 to \c{ESC [v}, and with shift and control together they generate
615 \c{ESC [w} through to \c{ESC [\{}.
617 If you don't know what any of this means, you probably don't need to
620 \S{config-appcursor} Controlling \i{Application Cursor Keys} mode
622 \cfg{winhelp-topic}{keyboard.appcursor}
624 Application Cursor Keys mode is a way for the server to change the
625 control sequences sent by the arrow keys. In normal mode, the arrow
626 keys send \c{ESC [A} through to \c{ESC [D}. In application mode,
627 they send \c{ESC OA} through to \c{ESC OD}.
629 Application Cursor Keys mode can be turned on and off by the server,
630 depending on the application. PuTTY allows you to configure the
633 You can also disable application cursor keys mode completely, using
634 the \q{Features} configuration panel; see
635 \k{config-features-application}.
637 \S{config-appkeypad} Controlling \i{Application Keypad} mode
639 \cfg{winhelp-topic}{keyboard.appkeypad}
641 Application Keypad mode is a way for the server to change the
642 behaviour of the numeric keypad.
644 In normal mode, the keypad behaves like a normal Windows keypad:
645 with \i{NumLock} on, the number keys generate numbers, and with NumLock
646 off they act like the arrow keys and Home, End etc.
648 In application mode, all the keypad keys send special control
649 sequences, \e{including} Num Lock. Num Lock stops behaving like Num
650 Lock and becomes another function key.
652 Depending on which version of Windows you run, you may find the Num
653 Lock light still flashes on and off every time you press Num Lock,
654 even when application mode is active and Num Lock is acting like a
655 function key. This is unavoidable.
657 Application keypad mode can be turned on and off by the server,
658 depending on the application. PuTTY allows you to configure the
661 You can also disable application keypad mode completely, using the
662 \q{Features} configuration panel; see
663 \k{config-features-application}.
665 \S{config-nethack} Using \i{NetHack keypad mode}
667 \cfg{winhelp-topic}{keyboard.nethack}
669 PuTTY has a special mode for playing NetHack. You can enable it by
670 selecting \q{NetHack} in the \q{Initial state of numeric keypad}
673 In this mode, the numeric keypad keys 1-9 generate the NetHack
674 movement commands (\cw{hjklyubn}). The 5 key generates the \c{.}
675 command (do nothing).
677 In addition, pressing Shift or Ctrl with the keypad keys generate
678 the Shift- or Ctrl-keys you would expect (e.g. keypad-7 generates
679 \cq{y}, so Shift-keypad-7 generates \cq{Y} and Ctrl-keypad-7
680 generates Ctrl-Y); these commands tell NetHack to keep moving you in
681 the same direction until you encounter something interesting.
683 For some reason, this feature only works properly when \i{Num Lock} is
684 on. We don't know why.
686 \S{config-compose} Enabling a DEC-like \ii{Compose key}
688 \cfg{winhelp-topic}{keyboard.compose}
690 DEC terminals have a Compose key, which provides an easy-to-remember
691 way of typing \i{accented characters}. You press Compose and then type
692 two more characters. The two characters are \q{combined} to produce
693 an accented character. The choices of character are designed to be
694 easy to remember; for example, composing \q{e} and \q{`} produces
695 the \q{\u00e8{e-grave}} character.
697 If your keyboard has a Windows \i{Application key}, it acts as a Compose
698 key in PuTTY. Alternatively, if you enable the \q{\i{AltGr} acts as
699 Compose key} option, the AltGr key will become a Compose key.
701 \S{config-ctrlalt} \q{Control-Alt is different from \i{AltGr}}
703 \cfg{winhelp-topic}{keyboard.ctrlalt}
705 Some old keyboards do not have an AltGr key, which can make it
706 difficult to type some characters. PuTTY can be configured to treat
707 the key combination Ctrl + Left Alt the same way as the AltGr key.
709 By default, this checkbox is checked, and the key combination Ctrl +
710 Left Alt does something completely different. PuTTY's usual handling
711 of the left Alt key is to prefix the Escape (Control-\cw{[})
712 character to whatever character sequence the rest of the keypress
713 would generate. For example, Alt-A generates Escape followed by
714 \c{a}. So Alt-Ctrl-A would generate Escape, followed by Control-A.
716 If you uncheck this box, Ctrl-Alt will become a synonym for AltGr,
717 so you can use it to type extra graphic characters if your keyboard
720 (However, Ctrl-Alt will never act as a Compose key, regardless of the
721 setting of \q{AltGr acts as Compose key} described in
724 \H{config-bell} The Bell panel
726 The Bell panel controls the \i{terminal bell} feature: the server's
727 ability to cause PuTTY to beep at you.
729 In the default configuration, when the server sends the character
730 with ASCII code 7 (Control-G), PuTTY will play the \i{Windows Default
731 Beep} sound. This is not always what you want the terminal bell
732 feature to do; the Bell panel allows you to configure alternative
735 \S{config-bellstyle} \q{Set the style of bell}
737 \cfg{winhelp-topic}{bell.style}
739 This control allows you to select various different actions to occur
742 \b Selecting \q{None} \I{terminal bell, disabling}disables the bell
743 completely. In this mode, the server can send as many Control-G
744 characters as it likes and nothing at all will happen.
746 \b \q{Make default system alert sound} is the default setting. It
747 causes the Windows \q{Default Beep} sound to be played. To change
748 what this sound is, or to test it if nothing seems to be happening,
749 use the Sound configurer in the Windows Control Panel.
751 \b \q{\ii{Visual bell}} is a silent alternative to a beeping computer. In
752 this mode, when the server sends a Control-G, the whole PuTTY window
753 will flash white for a fraction of a second.
755 \b \q{Beep using the \i{PC speaker}} is self-explanatory.
757 \b \q{Play a custom \i{sound file}} allows you to specify a particular
758 sound file to be used by PuTTY alone, or even by a particular
759 individual PuTTY session. This allows you to distinguish your PuTTY
760 beeps from any other beeps on the system. If you select this option,
761 you will also need to enter the name of your sound file in the edit
762 control \q{Custom sound file to play as a bell}.
764 \S{config-belltaskbar} \q{\ii{Taskbar}/\I{window caption}caption
767 \cfg{winhelp-topic}{bell.taskbar}
769 This feature controls what happens to the PuTTY window's entry in
770 the Windows Taskbar if a bell occurs while the window does not have
773 In the default state (\q{Disabled}) nothing unusual happens.
775 If you select \q{Steady}, then when a bell occurs and the window is
776 not in focus, the window's Taskbar entry and its title bar will
777 change colour to let you know that PuTTY session is asking for your
778 attention. The change of colour will persist until you select the
779 window, so you can leave several PuTTY windows minimised in your
780 terminal, go away from your keyboard, and be sure not to have missed
781 any important beeps when you get back.
783 \q{Flashing} is even more eye-catching: the Taskbar entry will
784 continuously flash on and off until you select the window.
786 \S{config-bellovl} \q{Control the \i{bell overload} behaviour}
788 \cfg{winhelp-topic}{bell.overload}
790 A common user error in a terminal session is to accidentally run the
791 Unix command \c{cat} (or equivalent) on an inappropriate file type,
792 such as an executable, image file, or ZIP file. This produces a huge
793 stream of non-text characters sent to the terminal, which typically
794 includes a lot of bell characters. As a result of this the terminal
795 often doesn't stop beeping for ten minutes, and everybody else in
796 the office gets annoyed.
798 To try to avoid this behaviour, or any other cause of excessive
799 beeping, PuTTY includes a bell overload management feature. In the
800 default configuration, receiving more than five bell characters in a
801 two-second period will cause the overload feature to activate. Once
802 the overload feature is active, further bells will \I{terminal bell,
803 disabling} have no effect at all, so the rest of your binary file
804 will be sent to the screen in silence. After a period of five seconds
805 during which no further bells are received, the overload feature will
806 turn itself off again and bells will be re-enabled.
808 If you want this feature completely disabled, you can turn it off
809 using the checkbox \q{Bell is temporarily disabled when over-used}.
811 Alternatively, if you like the bell overload feature but don't agree
812 with the settings, you can configure the details: how many bells
813 constitute an overload, how short a time period they have to arrive
814 in to do so, and how much silent time is required before the
815 overload feature will deactivate itself.
817 Bell overload mode is always deactivated by any keypress in the
818 terminal. This means it can respond to large unexpected streams of
819 data, but does not interfere with ordinary command-line activities
820 that generate beeps (such as filename completion).
822 \H{config-features} The Features panel
824 PuTTY's \i{terminal emulation} is very highly featured, and can do a lot
825 of things under remote server control. Some of these features can
826 cause problems due to buggy or strangely configured server
829 The Features configuration panel allows you to disable some of
830 PuTTY's more advanced terminal features, in case they cause trouble.
832 \S{config-features-application} Disabling application keypad and cursor keys
834 \cfg{winhelp-topic}{features.application}
836 \I{Application Keypad}Application keypad mode (see
837 \k{config-appkeypad}) and \I{Application Cursor Keys}application
838 cursor keys mode (see \k{config-appcursor}) alter the behaviour of
839 the keypad and cursor keys. Some applications enable these modes but
840 then do not deal correctly with the modified keys. You can force
841 these modes to be permanently disabled no matter what the server
844 \S{config-features-mouse} Disabling \cw{xterm}-style \i{mouse reporting}
846 \cfg{winhelp-topic}{features.mouse}
848 PuTTY allows the server to send \i{control codes} that let it take over
849 the mouse and use it for purposes other than \i{copy and paste}.
850 Applications which use this feature include the text-mode web
851 browser \i\c{links}, the Usenet newsreader \i\c{trn} version 4, and the
852 file manager \i\c{mc} (Midnight Commander).
854 If you find this feature inconvenient, you can disable it using the
855 \q{Disable xterm-style mouse reporting} control. With this box
856 ticked, the mouse will \e{always} do copy and paste in the normal
859 Note that even if the application takes over the mouse, you can
860 still manage PuTTY's copy and paste by holding down the Shift key
861 while you select and paste, unless you have deliberately turned this
862 feature off (see \k{config-mouseshift}).
864 \S{config-features-resize} Disabling remote \i{terminal resizing}
866 \cfg{winhelp-topic}{features.resize}
868 PuTTY has the ability to change the terminal's size and position in
869 response to commands from the server. If you find PuTTY is doing
870 this unexpectedly or inconveniently, you can tell PuTTY not to
871 respond to those server commands.
873 \S{config-features-altscreen} Disabling switching to the \i{alternate screen}
875 \cfg{winhelp-topic}{features.altscreen}
877 Many terminals, including PuTTY, support an \q{alternate screen}.
878 This is the same size as the ordinary terminal screen, but separate.
879 Typically a screen-based program such as a text editor might switch
880 the terminal to the alternate screen before starting up. Then at the
881 end of the run, it switches back to the primary screen, and you see
882 the screen contents just as they were before starting the editor.
884 Some people prefer this not to happen. If you want your editor to
885 run in the same screen as the rest of your terminal activity, you
886 can disable the alternate screen feature completely.
888 \S{config-features-retitle} Disabling remote \i{window title} changing
890 \cfg{winhelp-topic}{features.retitle}
892 PuTTY has the ability to change the window title in response to
893 commands from the server. If you find PuTTY is doing this
894 unexpectedly or inconveniently, you can tell PuTTY not to respond to
895 those server commands.
897 \S{config-features-qtitle} Response to remote \i{window title} querying
899 \cfg{winhelp-topic}{features.qtitle}
901 PuTTY can optionally provide the xterm service of allowing server
902 applications to find out the local window title. This feature is
903 disabled by default, but you can turn it on if you really want it.
905 NOTE that this feature is a \e{potential \i{security hazard}}. If a
906 malicious application can write data to your terminal (for example,
907 if you merely \c{cat} a file owned by someone else on the server
908 machine), it can change your window title (unless you have disabled
909 this as mentioned in \k{config-features-retitle}) and then use this
910 service to have the new window title sent back to the server as if
911 typed at the keyboard. This allows an attacker to fake keypresses
912 and potentially cause your server-side applications to do things you
913 didn't want. Therefore this feature is disabled by default, and we
914 recommend you do not set it to \q{Window title} unless you \e{really}
915 know what you are doing.
917 There are three settings for this option:
921 \dd PuTTY makes no response whatsoever to the relevant escape
922 sequence. This may upset server-side software that is expecting some
927 \dd PuTTY makes a well-formed response, but leaves it blank. Thus,
928 server-side software that expects a response is kept happy, but an
929 attacker cannot influence the response string. This is probably the
930 setting you want if you have no better ideas.
934 \dd PuTTY responds with the actual window title. This is dangerous for
935 the reasons described above.
937 \S{config-features-dbackspace} Disabling \i{destructive backspace}
939 \cfg{winhelp-topic}{features.dbackspace}
941 Normally, when PuTTY receives character 127 (^?) from the server, it
942 will perform a \q{destructive backspace}: move the cursor one space
943 left and delete the character under it. This can apparently cause
944 problems in some applications, so PuTTY provides the ability to
945 configure character 127 to perform a normal backspace (without
946 deleting a character) instead.
948 \S{config-features-charset} Disabling remote \i{character set}
951 \cfg{winhelp-topic}{features.charset}
953 PuTTY has the ability to change its character set configuration in
954 response to commands from the server. Some programs send these
955 commands unexpectedly or inconveniently. In particular, \i{BitchX} (an
956 IRC client) seems to have a habit of reconfiguring the character set
957 to something other than the user intended.
959 If you find that accented characters are not showing up the way you
960 expect them to, particularly if you're running BitchX, you could try
961 disabling the remote character set configuration commands.
963 \S{config-features-shaping} Disabling \i{Arabic text shaping}
965 \cfg{winhelp-topic}{features.arabicshaping}
967 PuTTY supports shaping of Arabic text, which means that if your
968 server sends text written in the basic \i{Unicode} Arabic alphabet then
969 it will convert it to the correct display forms before printing it
972 If you are using full-screen software which was not expecting this
973 to happen (especially if you are not an Arabic speaker and you
974 unexpectedly find yourself dealing with Arabic text files in
975 applications which are not Arabic-aware), you might find that the
976 \i{display becomes corrupted}. By ticking this box, you can disable
977 Arabic text shaping so that PuTTY displays precisely the characters
978 it is told to display.
980 You may also find you need to disable bidirectional text display;
981 see \k{config-features-bidi}.
983 \S{config-features-bidi} Disabling \i{bidirectional text} display
985 \cfg{winhelp-topic}{features.bidi}
987 PuTTY supports bidirectional text display, which means that if your
988 server sends text written in a language which is usually displayed
989 from right to left (such as \i{Arabic} or \i{Hebrew}) then PuTTY will
990 automatically flip it round so that it is displayed in the right
991 direction on the screen.
993 If you are using full-screen software which was not expecting this
994 to happen (especially if you are not an Arabic speaker and you
995 unexpectedly find yourself dealing with Arabic text files in
996 applications which are not Arabic-aware), you might find that the
997 \i{display becomes corrupted}. By ticking this box, you can disable
998 bidirectional text display, so that PuTTY displays text from left to
999 right in all situations.
1001 You may also find you need to disable Arabic text shaping;
1002 see \k{config-features-shaping}.
1004 \H{config-window} The Window panel
1006 The Window configuration panel allows you to control aspects of the
1009 \S{config-winsize} Setting the \I{window size}size of the PuTTY window
1011 \cfg{winhelp-topic}{window.size}
1013 The \q{\ii{Columns}} and \q{\ii{Rows}} boxes let you set the PuTTY
1014 window to a precise size. Of course you can also \I{window resizing}drag
1015 the window to a new size while a session is running.
1017 \S{config-winsizelock} What to do when the window is resized
1019 \cfg{winhelp-topic}{window.resize}
1021 These options allow you to control what happens when the user tries
1022 to \I{window resizing}resize the PuTTY window using its window furniture.
1024 There are four options here:
1026 \b \q{Change the number of rows and columns}: the font size will not
1027 change. (This is the default.)
1029 \b \q{Change the size of the font}: the number of rows and columns in
1030 the terminal will stay the same, and the \i{font size} will change.
1032 \b \q{Change font size when maximised}: when the window is resized,
1033 the number of rows and columns will change, \e{except} when the window
1034 is \i{maximise}d (or restored), when the font size will change. (In
1035 this mode, holding down the Alt key while resizing will also cause the
1036 font size to change.)
1038 \b \q{Forbid resizing completely}: the terminal will refuse to be
1041 \S{config-scrollback} Controlling \i{scrollback}
1043 \cfg{winhelp-topic}{window.scrollback}
1045 These options let you configure the way PuTTY keeps text after it
1046 scrolls off the top of the screen (see \k{using-scrollback}).
1048 The \q{Lines of scrollback} box lets you configure how many lines of
1049 text PuTTY keeps. The \q{Display scrollbar} options allow you to
1050 hide the \i{scrollbar} (although you can still view the scrollback using
1051 the keyboard as described in \k{using-scrollback}). You can separately
1052 configure whether the scrollbar is shown in \i{full-screen} mode and in
1055 If you are viewing part of the scrollback when the server sends more
1056 text to PuTTY, the screen will revert to showing the current
1057 terminal contents. You can disable this behaviour by turning off
1058 \q{Reset scrollback on display activity}. You can also make the
1059 screen revert when you press a key, by turning on \q{Reset
1060 scrollback on keypress}.
1062 \S{config-erasetoscrollback} \q{Push erased text into scrollback}
1064 \cfg{winhelp-topic}{window.erased}
1066 When this option is enabled, the contents of the terminal screen
1067 will be pushed into the scrollback when a server-side application
1068 clears the screen, so that your scrollback will contain a better
1069 record of what was on your screen in the past.
1071 If the application switches to the \i{alternate screen} (see
1072 \k{config-features-altscreen} for more about this), then the
1073 contents of the primary screen will be visible in the scrollback
1074 until the application switches back again.
1076 This option is enabled by default.
1078 \H{config-appearance} The Appearance panel
1080 The Appearance configuration panel allows you to control aspects of
1081 the appearance of \I{PuTTY window}PuTTY's window.
1083 \S{config-cursor} Controlling the appearance of the \i{cursor}
1085 \cfg{winhelp-topic}{appearance.cursor}
1087 The \q{Cursor appearance} option lets you configure the cursor to be
1088 a block, an underline, or a vertical line. A block cursor becomes an
1089 empty box when the window loses focus; an underline or a vertical
1090 line becomes dotted.
1092 The \q{\ii{Cursor blinks}} option makes the cursor blink on and off. This
1093 works in any of the cursor modes.
1095 \S{config-font} Controlling the \i{font} used in the terminal window
1097 \cfg{winhelp-topic}{appearance.font}
1099 This option allows you to choose what font, in what \I{font size}size,
1100 the PuTTY terminal window uses to display the text in the session.
1102 By default, you will be offered a choice from all the fixed-width
1103 fonts installed on the system, since VT100-style terminal handling
1104 expects a fixed-width font. If you tick the box marked \q{Allow
1105 selection of variable-pitch fonts}, however, PuTTY will offer
1106 variable-width fonts as well: if you select one of these, the font
1107 will be coerced into fixed-size character cells, which will probably
1108 not look very good (but can work OK with some fonts).
1110 \S{config-mouseptr} \q{Hide \i{mouse pointer} when typing in window}
1112 \cfg{winhelp-topic}{appearance.hidemouse}
1114 If you enable this option, the mouse pointer will disappear if the
1115 PuTTY window is selected and you press a key. This way, it will not
1116 obscure any of the text in the window while you work in your
1117 session. As soon as you move the mouse, the pointer will reappear.
1119 This option is disabled by default, so the mouse pointer remains
1120 visible at all times.
1122 \S{config-winborder} Controlling the \i{window border}
1124 \cfg{winhelp-topic}{appearance.border}
1126 PuTTY allows you to configure the appearance of the window border to
1129 The checkbox marked \q{Sunken-edge border} changes the appearance of
1130 the window border to something more like a DOS box: the inside edge
1131 of the border is highlighted as if it sank down to meet the surface
1132 inside the window. This makes the border a little bit thicker as
1133 well. It's hard to describe well. Try it and see if you like it.
1135 You can also configure a completely blank gap between the text in
1136 the window and the border, using the \q{Gap between text and window
1137 edge} control. By default this is set at one pixel. You can reduce
1138 it to zero, or increase it further.
1140 \H{config-behaviour} The Behaviour panel
1142 The Behaviour configuration panel allows you to control aspects of
1143 the behaviour of \I{PuTTY window}PuTTY's window.
1145 \S{config-title} Controlling the \i{window title}
1147 \cfg{winhelp-topic}{appearance.title}
1149 The \q{Window title} edit box allows you to set the title of the
1150 PuTTY window. By default the window title will contain the \i{host name}
1151 followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
1152 If you want a different window title, this is where to set it.
1154 PuTTY allows the server to send \c{xterm} \i{control sequence}s which
1155 modify the title of the window in mid-session (unless this is disabled -
1156 see \k{config-features-retitle}); the title string set here
1157 is therefore only the \e{initial} window title.
1159 As well as the \e{window} title, there is also an \c{xterm}
1160 sequence to modify the \I{icon title}title of the window's \e{icon}.
1161 This makes sense in a windowing system where the window becomes an
1162 icon when minimised, such as Windows 3.1 or most X Window System
1163 setups; but in the Windows 95-like user interface it isn't as
1166 By default, PuTTY only uses the server-supplied \e{window} title, and
1167 ignores the icon title entirely. If for some reason you want to see
1168 both titles, check the box marked \q{Separate window and icon titles}.
1169 If you do this, PuTTY's window title and Taskbar \I{window caption}caption will
1170 change into the server-supplied icon title if you \i{minimise} the PuTTY
1171 window, and change back to the server-supplied window title if you
1172 restore it. (If the server has not bothered to supply a window or
1173 icon title, none of this will happen.)
1175 \S{config-warnonclose} \q{Warn before \i{closing window}}
1177 \cfg{winhelp-topic}{behaviour.closewarn}
1179 If you press the \i{Close button} in a PuTTY window that contains a
1180 running session, PuTTY will put up a warning window asking if you
1181 really meant to close the window. A window whose session has already
1182 terminated can always be closed without a warning.
1184 If you want to be able to close a window quickly, you can disable
1185 the \q{Warn before closing window} option.
1187 \S{config-altf4} \q{Window closes on \i{ALT-F4}}
1189 \cfg{winhelp-topic}{behaviour.altf4}
1191 By default, pressing ALT-F4 causes the \I{closing window}window to
1192 close (or a warning box to appear; see \k{config-warnonclose}). If you
1193 disable the \q{Window closes on ALT-F4} option, then pressing ALT-F4
1194 will simply send a key sequence to the server.
1196 \S{config-altspace} \q{\ii{System menu} appears on \i{ALT-Space}}
1198 \cfg{winhelp-topic}{behaviour.altspace}
1200 If this option is enabled, then pressing ALT-Space will bring up the
1201 PuTTY window's menu, like clicking on the top left corner. If it is
1202 disabled, then pressing ALT-Space will just send \c{ESC SPACE} to
1205 Some \i{accessibility} programs for Windows may need this option
1206 enabling to be able to control PuTTY's window successfully. For
1207 instance, \i{Dragon NaturallySpeaking} requires it both to open the
1208 system menu via voice, and to close, minimise, maximise and restore
1211 \S{config-altonly} \q{\ii{System menu} appears on \i{Alt} alone}
1213 \cfg{winhelp-topic}{behaviour.altonly}
1215 If this option is enabled, then pressing and releasing ALT will
1216 bring up the PuTTY window's menu, like clicking on the top left
1217 corner. If it is disabled, then pressing and releasing ALT will have
1220 \S{config-alwaysontop} \q{Ensure window is \i{always on top}}
1222 \cfg{winhelp-topic}{behaviour.alwaysontop}
1224 If this option is enabled, the PuTTY window will stay on top of all
1227 \S{config-fullscreen} \q{\ii{Full screen} on Alt-Enter}
1229 \cfg{winhelp-topic}{behaviour.altenter}
1231 If this option is enabled, then pressing Alt-Enter will cause the
1232 PuTTY window to become full-screen. Pressing Alt-Enter again will
1233 restore the previous window size.
1235 The full-screen feature is also available from the \ii{System menu}, even
1236 when it is configured not to be available on the Alt-Enter key. See
1237 \k{using-fullscreen}.
1239 \H{config-translation} The Translation panel
1241 The Translation configuration panel allows you to control the
1242 translation between the \i{character set} understood by the server and
1243 the character set understood by PuTTY.
1245 \S{config-charset} Controlling character set translation
1247 \cfg{winhelp-topic}{translation.codepage}
1249 During an interactive session, PuTTY receives a stream of 8-bit
1250 bytes from the server, and in order to display them on the screen it
1251 needs to know what character set to interpret them in. Similarly,
1252 PuTTY needs to know how to translate your keystrokes into the encoding
1253 the server expects. Unfortunately, there is no satisfactory
1254 mechanism for PuTTY and the server to communicate this information,
1255 so it must usually be manually configured.
1257 There are a lot of character sets to choose from. The \q{Remote
1258 character set} option lets you select one.
1260 By default PuTTY will use the \i{UTF-8} encoding of \i{Unicode}, which
1261 can represent pretty much any character; data coming from the server
1262 is interpreted as UTF-8, and keystrokes are sent UTF-8 encoded. This
1263 is what most modern distributions of Linux will expect by default.
1264 However, if this is wrong for your server, you can select a different
1265 character set using this control.
1267 A few other notable character sets are:
1269 \b The \i{ISO-8859} series are all standard character sets that include
1270 various accented characters appropriate for different sets of
1273 \b The \i{Win125x} series are defined by Microsoft, for similar
1274 purposes. In particular Win1252 is almost equivalent to ISO-8859-1,
1275 but contains a few extra characters such as matched quotes and the
1278 \b If you want the old IBM PC character set with block graphics and
1279 line-drawing characters, you can select \q{\i{CP437}}.
1281 If you need support for a numeric \i{code page} which is not listed in
1282 the drop-down list, such as code page 866, then you can try entering
1283 its name manually (\c{\i{CP866}} for example) in the list box. If the
1284 underlying version of Windows has the appropriate translation table
1285 installed, PuTTY will use it.
1287 \S{config-cjk-ambig-wide} \q{Treat \i{CJK} ambiguous characters as wide}
1289 \cfg{winhelp-topic}{translation.cjkambigwide}
1291 There are \I{East Asian Ambiguous characters}some Unicode characters
1292 whose \I{character width}width is not well-defined. In most contexts, such
1293 characters should be treated as single-width for the purposes of \I{wrapping,
1294 terminal}wrapping and so on; however, in some CJK contexts, they are better
1295 treated as double-width for historical reasons, and some server-side
1296 applications may expect them to be displayed as such. Setting this option
1297 will cause PuTTY to take the double-width interpretation.
1299 If you use legacy CJK applications, and you find your lines are
1300 wrapping in the wrong places, or you are having other display
1301 problems, you might want to play with this setting.
1303 This option only has any effect in \i{UTF-8} mode (see \k{config-charset}).
1305 \S{config-cyr} \q{\i{Caps Lock} acts as \i{Cyrillic} switch}
1307 \cfg{winhelp-topic}{translation.cyrillic}
1309 This feature allows you to switch between a US/UK keyboard layout
1310 and a Cyrillic keyboard layout by using the Caps Lock key, if you
1311 need to type (for example) \i{Russian} and English side by side in the
1314 Currently this feature is not expected to work properly if your
1315 native keyboard layout is not US or UK.
1317 \S{config-linedraw} Controlling display of \i{line-drawing characters}
1319 \cfg{winhelp-topic}{translation.linedraw}
1321 VT100-series terminals allow the server to send \i{control sequence}s that
1322 shift temporarily into a separate character set for drawing simple
1323 lines and boxes. However, there are a variety of ways in which PuTTY
1324 can attempt to find appropriate characters, and the right one to use
1325 depends on the locally configured \i{font}. In general you should probably
1326 try lots of options until you find one that your particular font
1329 \b \q{Use Unicode line drawing code points} tries to use the box
1330 characters that are present in \i{Unicode}. For good Unicode-supporting
1331 fonts this is probably the most reliable and functional option.
1333 \b \q{Poor man's line drawing} assumes that the font \e{cannot}
1334 generate the line and box characters at all, so it will use the
1335 \c{+}, \c{-} and \c{|} characters to draw approximations to boxes.
1336 You should use this option if none of the other options works.
1338 \b \q{Font has XWindows encoding} is for use with fonts that have a
1339 special encoding, where the lowest 32 character positions (below the
1340 ASCII printable range) contain the line-drawing characters. This is
1341 unlikely to be the case with any standard Windows font; it will
1342 probably only apply to custom-built fonts or fonts that have been
1343 automatically converted from the X Window System.
1345 \b \q{Use font in both ANSI and OEM modes} tries to use the same
1346 font in two different character sets, to obtain a wider range of
1347 characters. This doesn't always work; some fonts claim to be a
1348 different size depending on which character set you try to use.
1350 \b \q{Use font in OEM mode only} is more reliable than that, but can
1351 miss out other characters from the main character set.
1353 \S{config-linedrawpaste} Controlling \i{copy and paste} of line drawing
1356 \cfg{winhelp-topic}{selection.linedraw}
1358 By default, when you copy and paste a piece of the PuTTY screen that
1359 contains VT100 line and box drawing characters, PuTTY will paste
1360 them in the form they appear on the screen: either \i{Unicode} line
1361 drawing code points, or the \q{poor man's} line-drawing characters
1362 \c{+}, \c{-} and \c{|}. The checkbox \q{Copy and paste VT100 line
1363 drawing chars as lqqqk} disables this feature, so line-drawing
1364 characters will be pasted as the \i{ASCII} characters that were printed
1365 to produce them. This will typically mean they come out mostly as
1366 \c{q} and \c{x}, with a scattering of \c{jklmntuvw} at the corners.
1367 This might be useful if you were trying to recreate the same box
1368 layout in another program, for example.
1370 Note that this option only applies to line-drawing characters which
1371 \e{were} printed by using the VT100 mechanism. Line-drawing
1372 characters that were received as Unicode code points will paste as
1375 \H{config-selection} The Selection panel
1377 The Selection panel allows you to control the way \i{copy and paste}
1378 work in the PuTTY window.
1380 \S{config-rtfpaste} Pasting in \i{Rich Text Format}
1382 \cfg{winhelp-topic}{selection.rtf}
1384 If you enable \q{Paste to clipboard in RTF as well as plain text},
1385 PuTTY will write formatting information to the clipboard as well as
1386 the actual text you copy. The effect of this is
1387 that if you paste into (say) a word processor, the text will appear
1388 in the word processor in the same \i{font}, \i{colour}, and style
1389 (e.g. bold, underline) PuTTY was using to display it.
1391 This option can easily be inconvenient, so by default it is
1394 \S{config-mouse} Changing the actions of the mouse buttons
1396 \cfg{winhelp-topic}{selection.buttons}
1398 PuTTY's copy and paste mechanism is by default modelled on the Unix
1399 \c{xterm} application. The X Window System uses a three-button mouse,
1400 and the convention is that the \i{left button} \I{selecting text}selects,
1401 the \i{right button} extends an existing selection, and the
1402 \i{middle button} pastes.
1404 Windows often only has two mouse buttons, so in PuTTY's default
1405 configuration (\q{Compromise}), the \e{right} button pastes, and the
1406 \e{middle} button (if you have one) \I{adjusting a selection}extends
1409 If you have a \i{three-button mouse} and you are already used to the
1410 \c{xterm} arrangement, you can select it using the \q{Action of
1411 mouse buttons} control.
1413 Alternatively, with the \q{Windows} option selected, the middle
1414 button extends, and the right button brings up a \i{context menu} (on
1415 which one of the options is \q{Paste}). (This context menu is always
1416 available by holding down Ctrl and right-clicking, regardless of the
1417 setting of this option.)
1419 \S{config-mouseshift} \q{Shift overrides application's use of mouse}
1421 \cfg{winhelp-topic}{selection.shiftdrag}
1423 PuTTY allows the server to send \i{control codes} that let it
1424 \I{mouse reporting}take over the mouse and use it for purposes other
1425 than \i{copy and paste}.
1426 Applications which use this feature include the text-mode web
1427 browser \c{links}, the Usenet newsreader \c{trn} version 4, and the
1428 file manager \c{mc} (Midnight Commander).
1430 When running one of these applications, pressing the mouse buttons
1431 no longer performs copy and paste. If you do need to copy and paste,
1432 you can still do so if you hold down Shift while you do your mouse
1435 However, it is possible in theory for applications to even detect
1436 and make use of Shift + mouse clicks. We don't know of any
1437 applications that do this, but in case someone ever writes one,
1438 unchecking the \q{Shift overrides application's use of mouse}
1439 checkbox will cause Shift + mouse clicks to go to the server as well
1440 (so that mouse-driven copy and paste will be completely disabled).
1442 If you want to prevent the application from taking over the mouse at
1443 all, you can do this using the Features control panel; see
1444 \k{config-features-mouse}.
1446 \S{config-rectselect} Default selection mode
1448 \cfg{winhelp-topic}{selection.rect}
1450 As described in \k{using-selection}, PuTTY has two modes of
1451 selecting text to be copied to the clipboard. In the default mode
1452 (\q{Normal}), dragging the mouse from point A to point B selects to
1453 the end of the line containing A, all the lines in between, and from
1454 the very beginning of the line containing B. In the other mode
1455 (\q{Rectangular block}), dragging the mouse between two points
1456 defines a rectangle, and everything within that rectangle is copied.
1458 Normally, you have to hold down Alt while dragging the mouse to
1459 select a rectangular block. Using the \q{Default selection mode}
1460 control, you can set \i{rectangular selection} as the default, and then
1461 you have to hold down Alt to get the \e{normal} behaviour.
1463 \S{config-charclasses} Configuring \i{word-by-word selection}
1465 \cfg{winhelp-topic}{selection.charclasses}
1467 PuTTY will select a word at a time in the terminal window if you
1468 \i{double-click} to begin the drag. This panel allows you to control
1469 precisely what is considered to be a word.
1471 Each character is given a \e{class}, which is a small number
1472 (typically 0, 1 or 2). PuTTY considers a single word to be any
1473 number of adjacent characters in the same class. So by modifying the
1474 assignment of characters to classes, you can modify the word-by-word
1475 selection behaviour.
1477 In the default configuration, the \i{character classes} are:
1479 \b Class 0 contains \i{white space} and control characters.
1481 \b Class 1 contains most \i{punctuation}.
1483 \b Class 2 contains letters, numbers and a few pieces of punctuation
1484 (the double quote, minus sign, period, forward slash and
1487 So, for example, if you assign the \c{@} symbol into character class
1488 2, you will be able to select an e-mail address with just a double
1491 In order to adjust these assignments, you start by selecting a group
1492 of characters in the list box. Then enter a class number in the edit
1493 box below, and press the \q{Set} button.
1495 This mechanism currently only covers ASCII characters, because it
1496 isn't feasible to expand the list to cover the whole of Unicode.
1498 Character class definitions can be modified by \i{control sequence}s
1499 sent by the server. This configuration option controls the
1500 \e{default} state, which will be restored when you reset the
1501 terminal (see \k{reset-terminal}). However, if you modify this
1502 option in mid-session using \q{Change Settings}, it will take effect
1505 \H{config-colours} The Colours panel
1507 The Colours panel allows you to control PuTTY's use of \i{colour}.
1509 \S{config-ansicolour} \q{Allow terminal to specify \i{ANSI colours}}
1511 \cfg{winhelp-topic}{colours.ansi}
1513 This option is enabled by default. If it is disabled, PuTTY will
1514 ignore any \i{control sequence}s sent by the server to request coloured
1517 If you have a particularly garish application, you might want to
1518 turn this option off and make PuTTY only use the default foreground
1519 and background colours.
1521 \S{config-xtermcolour} \q{Allow terminal to use xterm \i{256-colour mode}}
1523 \cfg{winhelp-topic}{colours.xterm256}
1525 This option is enabled by default. If it is disabled, PuTTY will
1526 ignore any control sequences sent by the server which use the
1527 extended 256-colour mode supported by recent versions of \cw{xterm}.
1529 If you have an application which is supposed to use 256-colour mode
1530 and it isn't working, you may find you need to tell your server that
1531 your terminal supports 256 colours. On Unix, you do this by ensuring
1532 that the setting of \i\cw{TERM} describes a 256-colour-capable
1533 terminal. You can check this using a command such as \c{infocmp}:
1535 \c $ infocmp | grep colors
1536 \c colors#256, cols#80, it#8, lines#24, pairs#256,
1539 If you do not see \cq{colors#256} in the output, you may need to
1540 change your terminal setting. On modern Linux machines, you could
1541 try \cq{xterm-256color}.
1543 \S{config-boldcolour} \q{Indicate bolded text by changing...}
1545 \cfg{winhelp-topic}{colours.bold}
1547 When the server sends a \i{control sequence} indicating that some text
1548 should be displayed in \i{bold}, PuTTY can handle this in several
1549 ways. It can either change the \i{font} for a bold version, or use the
1550 same font in a brighter colour, or it can do both (brighten the colour
1551 \e{and} embolden the font). This control lets you choose which.
1553 By default bold is indicated by colour, so non-bold text is displayed
1554 in light grey and bold text is displayed in bright white (and
1555 similarly in other colours). If you change the setting to \q{The font}
1556 box, bold and non-bold text will be displayed in the same colour, and
1557 instead the font will change to indicate the difference. If you select
1558 \q{Both}, the font and the colour will both change.
1560 Some applications rely on \q{\i{bold black}} being distinguishable
1561 from a black background; if you choose \q{The font}, their text may
1564 \S{config-logpalette} \q{Attempt to use \i{logical palettes}}
1566 \cfg{winhelp-topic}{colours.logpal}
1568 Logical palettes are a mechanism by which a Windows application
1569 running on an \i{8-bit colour} display can select precisely the colours
1570 it wants instead of going with the Windows standard defaults.
1572 If you are not getting the colours you ask for on an 8-bit display,
1573 you can try enabling this option. However, be warned that it's never
1576 \S{config-syscolour} \q{Use \i{system colours}}
1578 \cfg{winhelp-topic}{colours.system}
1580 Enabling this option will cause PuTTY to ignore the configured colours
1581 for \I{default background}\I{default foreground}\q{Default
1582 Background/Foreground} and \I{cursor colour}\q{Cursor Colour/Text} (see
1583 \k{config-colourcfg}), instead going with the system-wide defaults.
1585 Note that non-bold and \i{bold text} will be the same colour if this
1586 option is enabled. You might want to change to indicating bold text
1587 by font changes (see \k{config-boldcolour}).
1589 \S{config-colourcfg} Adjusting the colours in the \i{terminal window}
1591 \cfg{winhelp-topic}{colours.config}
1593 The main colour control allows you to specify exactly what colours
1594 things should be displayed in. To modify one of the PuTTY colours,
1595 use the list box to select which colour you want to modify. The \i{RGB
1596 values} for that colour will appear on the right-hand side of the
1597 list box. Now, if you press the \q{Modify} button, you will be
1598 presented with a colour selector, in which you can choose a new
1599 colour to go in place of the old one. (You may also edit the RGB
1600 values directly in the edit boxes, if you wish; each value is an
1601 integer from 0 to 255.)
1603 PuTTY allows you to set the \i{cursor colour}, the \i{default foreground}
1604 and \I{default background}background, and the precise shades of all the
1605 \I{ANSI colours}ANSI configurable colours (black, red, green, yellow, blue,
1606 magenta, cyan, and white). You can also modify the precise shades used for
1607 the \i{bold} versions of these colours; these are used to display bold text
1608 if you have chosen to indicate that by colour (see \k{config-boldcolour}),
1609 and can also be used if the server asks specifically to use them. (Note
1610 that \q{Default Bold Background} is \e{not} the background colour used for
1611 bold text; it is only used if the server specifically asks for a bold
1614 \H{config-connection} The Connection panel
1616 The Connection panel allows you to configure options that apply to
1617 more than one type of \i{connection}.
1619 \S{config-keepalive} Using \i{keepalives} to prevent disconnection
1621 \cfg{winhelp-topic}{connection.keepalive}
1623 If you find your sessions are closing unexpectedly (most often with
1624 \q{Connection reset by peer}) after they have been idle for a while,
1625 you might want to try using this option.
1627 Some network \i{routers} and \i{firewalls} need to keep track of all
1628 connections through them. Usually, these firewalls will assume a
1629 connection is dead if no data is transferred in either direction
1630 after a certain time interval. This can cause PuTTY sessions to be
1631 unexpectedly closed by the firewall if no traffic is seen in the
1632 session for some time.
1634 The keepalive option (\q{Seconds between keepalives}) allows you to
1635 configure PuTTY to send data through the session at regular
1636 intervals, in a way that does not disrupt the actual terminal
1637 session. If you find your firewall is cutting \i{idle connections} off,
1638 you can try entering a non-zero value in this field. The value is
1639 measured in seconds; so, for example, if your firewall cuts
1640 connections off after ten minutes then you might want to enter 300
1641 seconds (5 minutes) in the box.
1643 Note that keepalives are not always helpful. They help if you have a
1644 firewall which drops your connection after an idle period; but if
1645 the network between you and the server suffers from \i{breaks in
1646 connectivity} then keepalives can actually make things worse. If a
1647 session is idle, and connectivity is temporarily lost between the
1648 endpoints, but the connectivity is restored before either side tries
1649 to send anything, then there will be no problem - neither endpoint
1650 will notice that anything was wrong. However, if one side does send
1651 something during the break, it will repeatedly try to re-send, and
1652 eventually give up and abandon the connection. Then when
1653 connectivity is restored, the other side will find that the first
1654 side doesn't believe there is an open connection any more.
1655 Keepalives can make this sort of problem worse, because they
1656 increase the probability that PuTTY will attempt to send data during
1657 a break in connectivity. (Other types of periodic network activity
1658 can cause this behaviour; in particular, SSH-2 re-keys can have
1659 this effect. See \k{config-ssh-kex-rekey}.)
1661 Therefore, you might find that keepalives help
1662 connection loss, or you might find they make it worse, depending on
1663 what \e{kind} of network problems you have between you and the
1666 Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
1667 protocols offer no way of implementing them. (For an alternative, see
1668 \k{config-tcp-keepalives}.)
1670 Note that if you are using \i{SSH-1} and the server has a bug that makes
1671 it unable to deal with SSH-1 ignore messages (see
1672 \k{config-ssh-bug-ignore1}), enabling keepalives will have no effect.
1674 \S{config-nodelay} \q{Disable \i{Nagle's algorithm}}
1676 \cfg{winhelp-topic}{connection.nodelay}
1678 Nagle's algorithm is a detail of TCP/IP implementations that tries
1679 to minimise the number of small data packets sent down a network
1680 connection. With Nagle's algorithm enabled, PuTTY's \i{bandwidth} usage
1681 will be slightly more efficient; with it disabled, you may find you
1682 get a faster response to your keystrokes when connecting to some
1685 The Nagle algorithm is disabled by default for \i{interactive connections}.
1687 \S{config-tcp-keepalives} \q{Enable \i{TCP keepalives}}
1689 \cfg{winhelp-topic}{connection.tcpkeepalive}
1691 \e{NOTE:} TCP keepalives should not be confused with the
1692 application-level keepalives described in \k{config-keepalive}. If in
1693 doubt, you probably want application-level keepalives; TCP keepalives
1694 are provided for completeness.
1696 The idea of TCP keepalives is similar to application-level keepalives,
1697 and the same caveats apply. The main differences are:
1699 \b TCP keepalives are available on \e{all} connection types, including
1702 \b The interval between TCP keepalives is usually much longer,
1703 typically two hours; this is set by the operating system, and cannot
1704 be configured within PuTTY.
1706 \b If the operating system does not receive a response to a keepalive,
1707 it may send out more in quick succession and terminate the connection
1708 if no response is received.
1710 TCP keepalives may be more useful for ensuring that \i{half-open connections}
1711 are terminated than for keeping a connection alive.
1713 TCP keepalives are disabled by default.
1715 \S{config-address-family} \I{Internet protocol version}\q{Internet protocol}
1717 \cfg{winhelp-topic}{connection.ipversion}
1719 This option allows the user to select between the old and new
1720 Internet protocols and addressing schemes (\i{IPv4} and \i{IPv6}).
1721 The selected protocol will be used for most outgoing network
1722 connections (including connections to \I{proxy}proxies); however,
1723 tunnels have their own configuration, for which see
1724 \k{config-ssh-portfwd-address-family}.
1726 The default setting is \q{Auto}, which means PuTTY will do something
1727 sensible and try to guess which protocol you wanted. (If you specify
1728 a literal \i{Internet address}, it will use whichever protocol that
1729 address implies. If you provide a \i{hostname}, it will see what kinds
1730 of address exist for that hostname; it will use IPv6 if there is an
1731 IPv6 address available, and fall back to IPv4 if not.)
1733 If you need to force PuTTY to use a particular protocol, you can
1734 explicitly set this to \q{IPv4} or \q{IPv6}.
1736 \S{config-loghost} \I{logical host name}\q{Logical name of remote host}
1738 \cfg{winhelp-topic}{connection.loghost}
1740 This allows you to tell PuTTY that the host it will really end up
1741 connecting to is different from where it thinks it is making a
1744 You might use this, for instance, if you had set up an SSH port
1745 forwarding in one PuTTY session so that connections to some
1746 arbitrary port (say, \cw{localhost} port 10022) were forwarded to a
1747 second machine's SSH port (say, \cw{foovax} port 22), and then
1748 started a second PuTTY connecting to the forwarded port.
1750 In normal usage, the second PuTTY will access the \i{host key cache}
1751 under the host name and port it actually connected to (i.e.
1752 \cw{localhost} port 10022 in this example). Using the logical host
1753 name option, however, you can configure the second PuTTY to cache
1754 the host key under the name of the host \e{you} know that it's
1755 \e{really} going to end up talking to (here \c{foovax}).
1757 This can be useful if you expect to connect to the same actual
1758 server through many different channels (perhaps because your port
1759 forwarding arrangements keep changing): by consistently setting the
1760 logical host name, you can arrange that PuTTY will not keep asking
1761 you to reconfirm its host key. Conversely, if you expect to use the
1762 same local port number for port forwardings to lots of different
1763 servers, you probably didn't want any particular server's host key
1764 cached under that local port number. (For this latter case, you
1765 could instead explicitly configure host keys in the relevant sessions;
1766 see \k{config-ssh-kex-manual-hostkeys}.)
1768 If you just enter a host name for this option, PuTTY will cache the
1769 SSH host key under the default SSH port for that host, irrespective
1770 of the port you really connected to (since the typical scenario is
1771 like the above example: you connect to a silly real port number and
1772 your connection ends up forwarded to the normal port-22 SSH server
1773 of some other machine). To override this, you can append a port
1774 number to the logical host name, separated by a colon. E.g. entering
1775 \cq{foovax:2200} as the logical host name will cause the host key to
1776 be cached as if you had connected to port 2200 of \c{foovax}.
1778 If you provide a host name using this option, it is also displayed
1779 in other locations which contain the remote host name, such as the
1780 default window title and the default SSH password prompt. This
1781 reflects the fact that this is the host you're \e{really} connecting
1782 to, which is more important than the mere means you happen to be
1783 using to contact that host. (This applies even if you're using a
1784 protocol other than SSH.)
1786 \H{config-data} The Data panel
1788 The Data panel allows you to configure various pieces of data which
1789 can be sent to the server to affect your connection at the far end.
1791 Each option on this panel applies to more than one protocol.
1792 Options which apply to only one protocol appear on that protocol's
1793 configuration panels.
1795 \S{config-username} \q{\ii{Auto-login username}}
1797 \cfg{winhelp-topic}{connection.username}
1799 All three of the SSH, Telnet and Rlogin protocols allow you to
1800 specify what user name you want to log in as, without having to type
1801 it explicitly every time. (Some Telnet servers don't support this.)
1803 In this box you can type that user name.
1805 \S{config-username-from-env} Use of system username
1807 \cfg{winhelp-topic}{connection.usernamefromenv}
1809 When the previous box (\k{config-username}) is left blank, by default,
1810 PuTTY will prompt for a username at the time you make a connection.
1812 In some environments, such as the networks of large organisations
1813 implementing \i{single sign-on}, a more sensible default may be to use
1814 the name of the user logged in to the local operating system (if any);
1815 this is particularly likely to be useful with \i{GSSAPI} authentication
1816 (see \k{config-ssh-auth-gssapi}). This control allows you to change
1817 the default behaviour.
1819 The current system username is displayed in the dialog as a
1820 convenience. It is not saved in the configuration; if a saved session
1821 is later used by a different user, that user's name will be used.
1823 \S{config-termtype} \q{\ii{Terminal-type} string}
1825 \cfg{winhelp-topic}{connection.termtype}
1827 Most servers you might connect to with PuTTY are designed to be
1828 connected to from lots of different types of terminal. In order to
1829 send the right \i{control sequence}s to each one, the server will need
1830 to know what type of terminal it is dealing with. Therefore, each of
1831 the SSH, Telnet and Rlogin protocols allow a text string to be sent
1832 down the connection describing the terminal. On a \i{Unix} server,
1833 this selects an entry from the \i\c{termcap} or \i\c{terminfo} database
1834 that tells applications what \i{control sequences} to send to the
1835 terminal, and what character sequences to expect the \i{keyboard}
1838 PuTTY attempts to emulate the Unix \i\c{xterm} program, and by default
1839 it reflects this by sending \c{xterm} as a terminal-type string. If
1840 you find this is not doing what you want - perhaps the remote
1841 system reports \q{Unknown terminal type} - you could try setting
1842 this to something different, such as \i\c{vt220}.
1844 If you're not sure whether a problem is due to the terminal type
1845 setting or not, you probably need to consult the manual for your
1846 application or your server.
1848 \S{config-termspeed} \q{\ii{Terminal speed}s}
1850 \cfg{winhelp-topic}{connection.termspeed}
1852 The Telnet, Rlogin, and SSH protocols allow the client to specify
1853 terminal speeds to the server.
1855 This parameter does \e{not} affect the actual speed of the connection,
1856 which is always \q{as fast as possible}; it is just a hint that is
1857 sometimes used by server software to modify its behaviour. For
1858 instance, if a slow speed is indicated, the server may switch to a
1859 less \i{bandwidth}-hungry display mode.
1861 The value is usually meaningless in a network environment, but
1862 PuTTY lets you configure it, in case you find the server is reacting
1863 badly to the default value.
1865 The format is a pair of numbers separated by a comma, for instance,
1866 \c{38400,38400}. The first number represents the output speed
1867 (\e{from} the server) in bits per second, and the second is the input
1868 speed (\e{to} the server). (Only the first is used in the Rlogin
1871 This option has no effect on Raw connections.
1873 \S{config-environ} Setting \i{environment variables} on the server
1875 \cfg{winhelp-topic}{telnet.environ}
1877 The Telnet protocol provides a means for the client to pass
1878 environment variables to the server. Many Telnet servers have
1879 stopped supporting this feature due to security flaws, but PuTTY
1880 still supports it for the benefit of any servers which have found
1881 other ways around the security problems than just disabling the
1884 Version 2 of the SSH protocol also provides a similar mechanism,
1885 which is easier to implement without security flaws. Newer \i{SSH-2}
1886 servers are more likely to support it than older ones.
1888 This configuration data is not used in the SSH-1, rlogin or raw
1891 To add an environment variable to the list transmitted down the
1892 connection, you enter the variable name in the \q{Variable} box,
1893 enter its value in the \q{Value} box, and press the \q{Add} button.
1894 To remove one from the list, select it in the list box and press
1897 \H{config-proxy} The Proxy panel
1899 \cfg{winhelp-topic}{proxy.main}
1901 The \ii{Proxy} panel allows you to configure PuTTY to use various types
1902 of proxy in order to make its network connections. The settings in
1903 this panel affect the primary network connection forming your PuTTY
1904 session, and also any extra connections made as a result of SSH \i{port
1905 forwarding} (see \k{using-port-forwarding}).
1907 Note that unlike some software (such as web browsers), PuTTY does not
1908 attempt to automatically determine whether to use a proxy and (if so)
1909 which one to use for a given destination. If you need to use a proxy,
1910 it must always be explicitly configured.
1912 \S{config-proxy-type} Setting the proxy type
1914 \cfg{winhelp-topic}{proxy.type}
1916 The \q{Proxy type} radio buttons allow you to configure what type of
1917 proxy you want PuTTY to use for its network connections. The default
1918 setting is \q{None}; in this mode no proxy is used for any
1921 \b Selecting \I{HTTP proxy}\q{HTTP} allows you to proxy your connections
1922 through a web server supporting the HTTP \cw{CONNECT} command, as documented
1923 in \W{http://www.ietf.org/rfc/rfc2817.txt}{RFC 2817}.
1925 \b Selecting \q{SOCKS 4} or \q{SOCKS 5} allows you to proxy your
1926 connections through a \i{SOCKS server}.
1928 \b Many firewalls implement a less formal type of proxy in which a
1929 user can make a Telnet connection directly to the firewall machine
1930 and enter a command such as \c{connect myhost.com 22} to connect
1931 through to an external host. Selecting \I{Telnet proxy}\q{Telnet}
1932 allows you to tell PuTTY to use this type of proxy.
1934 \b Selecting \I{Local proxy}\q{Local} allows you to specify an arbitrary
1935 command on the local machine to act as a proxy. When the session is
1936 started, instead of creating a TCP connection, PuTTY runs the command
1937 (specified in \k{config-proxy-command}), and uses its standard input and
1941 This could be used, for instance, to talk to some kind of network proxy
1942 that PuTTY does not natively support; or you could tunnel a connection
1943 over something other than TCP/IP entirely.
1945 If you want your local proxy command to make a secondary SSH
1946 connection to a proxy host and then tunnel the primary connection
1947 over that, you might well want the \c{-nc} command-line option in
1948 Plink. See \k{using-cmdline-ncmode} for more information.
1951 \S{config-proxy-exclude} Excluding parts of the network from proxying
1953 \cfg{winhelp-topic}{proxy.exclude}
1955 Typically you will only need to use a proxy to connect to non-local
1956 parts of your network; for example, your proxy might be required for
1957 connections outside your company's internal network. In the
1958 \q{Exclude Hosts/IPs} box you can enter ranges of IP addresses, or
1959 ranges of DNS names, for which PuTTY will avoid using the proxy and
1960 make a direct connection instead.
1962 The \q{Exclude Hosts/IPs} box may contain more than one exclusion
1963 range, separated by commas. Each range can be an IP address or a DNS
1964 name, with a \c{*} character allowing wildcards. For example:
1968 This excludes any host with a name ending in \c{.example.com} from
1973 This excludes any host with an IP address starting with 192.168.88
1976 \c 192.168.88.*,*.example.com
1978 This excludes both of the above ranges at once.
1980 Connections to the local host (the host name \i\c{localhost}, and any
1981 \i{loopback IP address}) are never proxied, even if the proxy exclude
1982 list does not explicitly contain them. It is very unlikely that this
1983 behaviour would ever cause problems, but if it does you can change
1984 it by enabling \q{Consider proxying local host connections}.
1986 Note that if you are doing \I{proxy DNS}DNS at the proxy (see
1987 \k{config-proxy-dns}), you should make sure that your proxy
1988 exclusion settings do not depend on knowing the IP address of a
1989 host. If the name is passed on to the proxy without PuTTY looking it
1990 up, it will never know the IP address and cannot check it against
1993 \S{config-proxy-dns} \I{proxy DNS}\ii{Name resolution} when using a proxy
1995 \cfg{winhelp-topic}{proxy.dns}
1997 If you are using a proxy to access a private network, it can make a
1998 difference whether \i{DNS} name resolution is performed by PuTTY itself
1999 (on the client machine) or performed by the proxy.
2001 The \q{Do DNS name lookup at proxy end} configuration option allows
2002 you to control this. If you set it to \q{No}, PuTTY will always do
2003 its own DNS, and will always pass an IP address to the proxy. If you
2004 set it to \q{Yes}, PuTTY will always pass host names straight to the
2005 proxy without trying to look them up first.
2007 If you set this option to \q{Auto} (the default), PuTTY will do
2008 something it considers appropriate for each type of proxy. Telnet,
2009 HTTP, and SOCKS5 proxies will have host names passed straight to
2010 them; SOCKS4 proxies will not.
2012 Note that if you are doing DNS at the proxy, you should make sure
2013 that your proxy exclusion settings (see \k{config-proxy-exclude}) do
2014 not depend on knowing the IP address of a host. If the name is
2015 passed on to the proxy without PuTTY looking it up, it will never
2016 know the IP address and cannot check it against your list.
2018 The original SOCKS 4 protocol does not support proxy-side DNS. There
2019 is a protocol extension (SOCKS 4A) which does support it, but not
2020 all SOCKS 4 servers provide this extension. If you enable proxy DNS
2021 and your SOCKS 4 server cannot deal with it, this might be why.
2023 \S{config-proxy-auth} \I{proxy username}Username and \I{proxy password}password
2025 \cfg{winhelp-topic}{proxy.auth}
2027 If your proxy requires \I{proxy authentication}authentication, you can
2028 enter a username and a password in the \q{Username} and \q{Password} boxes.
2030 \I{security hazard}Note that if you save your session, the proxy
2031 password will be saved in plain text, so anyone who can access your PuTTY
2032 configuration data will be able to discover it.
2034 Authentication is not fully supported for all forms of proxy:
2036 \b Username and password authentication is supported for HTTP
2037 proxies and SOCKS 5 proxies.
2041 \b With SOCKS 5, authentication is via \i{CHAP} if the proxy
2042 supports it (this is not supported in \i{PuTTYtel}); otherwise the
2043 password is sent to the proxy in \I{plaintext password}plain text.
2045 \b With HTTP proxying, the only currently supported authentication
2046 method is \I{HTTP basic}\q{basic}, where the password is sent to the proxy
2047 in \I{plaintext password}plain text.
2051 \b SOCKS 4 can use the \q{Username} field, but does not support
2054 \b You can specify a way to include a username and password in the
2055 Telnet/Local proxy command (see \k{config-proxy-command}).
2057 \S{config-proxy-command} Specifying the Telnet or Local proxy command
2059 \cfg{winhelp-topic}{proxy.command}
2061 If you are using the \i{Telnet proxy} type, the usual command required
2062 by the firewall's Telnet server is \c{connect}, followed by a host
2063 name and a port number. If your proxy needs a different command,
2064 you can enter an alternative here.
2066 If you are using the \i{Local proxy} type, the local command to run
2069 In this string, you can use \c{\\n} to represent a new-line, \c{\\r}
2070 to represent a carriage return, \c{\\t} to represent a tab
2071 character, and \c{\\x} followed by two hex digits to represent any
2072 other character. \c{\\\\} is used to encode the \c{\\} character
2075 Also, the special strings \c{%host} and \c{%port} will be replaced
2076 by the host name and port number you want to connect to. The strings
2077 \c{%user} and \c{%pass} will be replaced by the proxy username and
2078 password you specify. The strings \c{%proxyhost} and \c{%proxyport}
2079 will be replaced by the host details specified on the \e{Proxy} panel,
2080 if any (this is most likely to be useful for the Local proxy type).
2081 To get a literal \c{%} sign, enter \c{%%}.
2083 If a Telnet proxy server prompts for a username and password
2084 before commands can be sent, you can use a command such as:
2086 \c %user\n%pass\nconnect %host %port\n
2088 This will send your username and password as the first two lines to
2089 the proxy, followed by a command to connect to the desired host and
2090 port. Note that if you do not include the \c{%user} or \c{%pass}
2091 tokens in the Telnet command, then the \q{Username} and \q{Password}
2092 configuration fields will be ignored.
2094 \H{config-telnet} The \i{Telnet} panel
2096 The Telnet panel allows you to configure options that only apply to
2099 \S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
2101 \cfg{winhelp-topic}{telnet.oldenviron}
2103 The original Telnet mechanism for passing \i{environment variables} was
2104 badly specified. At the time the standard (RFC 1408) was written,
2105 BSD telnet implementations were already supporting the feature, and
2106 the intention of the standard was to describe the behaviour the BSD
2107 implementations were already using.
2109 Sadly there was a typing error in the standard when it was issued,
2110 and two vital function codes were specified the wrong way round. BSD
2111 implementations did not change, and the standard was not corrected.
2112 Therefore, it's possible you might find either \i{BSD} or \i{RFC}-compliant
2113 implementations out there. This switch allows you to choose which
2114 one PuTTY claims to be.
2116 The problem was solved by issuing a second standard, defining a new
2117 Telnet mechanism called \i\cw{NEW_ENVIRON}, which behaved exactly like
2118 the original \i\cw{OLD_ENVIRON} but was not encumbered by existing
2119 implementations. Most Telnet servers now support this, and it's
2120 unambiguous. This feature should only be needed if you have trouble
2121 passing environment variables to quite an old server.
2123 \S{config-ptelnet} Passive and active \i{Telnet negotiation} modes
2125 \cfg{winhelp-topic}{telnet.passive}
2127 In a Telnet connection, there are two types of data passed between
2128 the client and the server: actual text, and \e{negotiations} about
2129 which Telnet extra features to use.
2131 PuTTY can use two different strategies for negotiation:
2133 \b In \I{active Telnet negotiation}\e{active} mode, PuTTY starts to send
2134 negotiations as soon as the connection is opened.
2136 \b In \I{passive Telnet negotiation}\e{passive} mode, PuTTY will wait to
2137 negotiate until it sees a negotiation from the server.
2139 The obvious disadvantage of passive mode is that if the server is
2140 also operating in a passive mode, then negotiation will never begin
2141 at all. For this reason PuTTY defaults to active mode.
2143 However, sometimes passive mode is required in order to successfully
2144 get through certain types of firewall and \i{Telnet proxy} server. If
2145 you have confusing trouble with a \i{firewall}, you could try enabling
2146 passive mode to see if it helps.
2148 \S{config-telnetkey} \q{Keyboard sends \i{Telnet special commands}}
2150 \cfg{winhelp-topic}{telnet.specialkeys}
2152 If this box is checked, several key sequences will have their normal
2155 \b the Backspace key on the keyboard will send the \I{Erase Character,
2156 Telnet special command}Telnet special backspace code;
2158 \b Control-C will send the Telnet special \I{Interrupt Process, Telnet
2159 special command}Interrupt Process code;
2161 \b Control-Z will send the Telnet special \I{Suspend Process, Telnet
2162 special command}Suspend Process code.
2164 You probably shouldn't enable this
2165 unless you know what you're doing.
2167 \S{config-telnetnl} \q{Return key sends \i{Telnet New Line} instead of ^M}
2169 \cfg{winhelp-topic}{telnet.newline}
2171 Unlike most other remote login protocols, the Telnet protocol has a
2172 special \q{\i{new line}} code that is not the same as the usual line
2173 endings of Control-M or Control-J. By default, PuTTY sends the
2174 Telnet New Line code when you press Return, instead of sending
2175 Control-M as it does in most other protocols.
2177 Most Unix-style Telnet servers don't mind whether they receive
2178 Telnet New Line or Control-M; some servers do expect New Line, and
2179 some servers prefer to see ^M. If you are seeing surprising
2180 behaviour when you press Return in a Telnet session, you might try
2181 turning this option off to see if it helps.
2183 \H{config-rlogin} The Rlogin panel
2185 The \i{Rlogin} panel allows you to configure options that only apply to
2188 \S{config-rlogin-localuser} \I{local username in Rlogin}\q{Local username}
2190 \cfg{winhelp-topic}{rlogin.localuser}
2192 Rlogin allows an automated (password-free) form of login by means of
2193 a file called \i\c{.rhosts} on the server. You put a line in your
2194 \c{.rhosts} file saying something like \c{jbloggs@pc1.example.com},
2195 and then when you make an Rlogin connection the client transmits the
2196 username of the user running the Rlogin client. The server checks
2197 the username and hostname against \c{.rhosts}, and if they match it
2198 \I{passwordless login}does not ask for a password.
2200 This only works because Unix systems contain a safeguard to stop a
2201 user from pretending to be another user in an Rlogin connection.
2202 Rlogin connections have to come from \I{privileged port}port numbers below
2203 1024, and Unix systems prohibit this to unprivileged processes; so when the
2204 server sees a connection from a low-numbered port, it assumes the
2205 client end of the connection is held by a privileged (and therefore
2206 trusted) process, so it believes the claim of who the user is.
2208 Windows does not have this restriction: \e{any} user can initiate an
2209 outgoing connection from a low-numbered port. Hence, the Rlogin
2210 \c{.rhosts} mechanism is completely useless for securely
2211 distinguishing several different users on a Windows machine. If you
2212 have a \c{.rhosts} entry pointing at a Windows PC, you should assume
2213 that \e{anyone} using that PC can \i{spoof} your username in
2214 an Rlogin connection and access your account on the server.
2216 The \q{Local username} control allows you to specify what user name
2217 PuTTY should claim you have, in case it doesn't match your \i{Windows
2218 user name} (or in case you didn't bother to set up a Windows user
2221 \H{config-ssh} The SSH panel
2223 The \i{SSH} panel allows you to configure options that only apply to
2226 \S{config-command} Executing a specific command on the server
2228 \cfg{winhelp-topic}{ssh.command}
2230 In SSH, you don't have to run a general shell session on the server.
2231 Instead, you can choose to run a single specific command (such as a
2232 mail user agent, for example). If you want to do this, enter the
2233 command in the \q{\ii{Remote command}} box.
2235 Note that most servers will close the session after executing the
2238 \S{config-ssh-noshell} \q{Don't start a \I{remote shell}shell or
2239 \I{remote command}command at all}
2241 \cfg{winhelp-topic}{ssh.noshell}
2243 If you tick this box, PuTTY will not attempt to run a shell or
2244 command after connecting to the remote server. You might want to use
2245 this option if you are only using the SSH connection for \i{port
2246 forwarding}, and your user account on the server does not have the
2247 ability to run a shell.
2249 This feature is only available in \i{SSH protocol version 2} (since the
2250 version 1 protocol assumes you will always want to run a shell).
2252 This feature can also be enabled using the \c{-N} command-line
2253 option; see \k{using-cmdline-noshell}.
2255 If you use this feature in Plink, you will not be able to terminate
2256 the Plink process by any graceful means; the only way to kill it
2257 will be by pressing Control-C or sending a kill signal from another
2260 \S{config-ssh-comp} \q{Enable \i{compression}}
2262 \cfg{winhelp-topic}{ssh.compress}
2264 This enables data compression in the SSH connection: data sent by
2265 the server is compressed before sending, and decompressed at the
2266 client end. Likewise, data sent by PuTTY to the server is compressed
2267 first and the server decompresses it at the other end. This can help
2268 make the most of a low-\i{bandwidth} connection.
2270 \S{config-ssh-prot} \q{Preferred \i{SSH protocol version}}
2272 \cfg{winhelp-topic}{ssh.protocol}
2274 This allows you to select whether you would prefer to use \i{SSH protocol
2275 version 1} or \I{SSH-2}version 2, and whether to permit falling back
2276 to the other version.
2278 With the settings \q{1} and \q{2}, PuTTY will attempt to use protocol 1
2279 if the server you connect to does not offer protocol 2, and vice versa.
2281 If you select \q{1 only} or \q{2 only} here, PuTTY will only connect
2282 if the server you connect to offers the SSH protocol version you
2285 You should normally leave this at the default, \q{2 only}. The older
2286 SSH-1 protocol is no longer developed, has many known cryptographic
2287 weaknesses, and is generally not considered to be secure. If you
2288 permit use of SSH-1 by selecting \q{2} instead of \q{2 only}, an
2289 active attacker can force downgrade to SSH-1 even if the server
2290 you're connecting to supports SSH-2.
2292 PuTTY's protocol 1 implementation is provided mainly for
2293 compatibility, and is no longer being enhanced.
2295 \S{config-ssh-sharing} Sharing an SSH connection between PuTTY tools
2297 \cfg{winhelp-topic}{ssh.sharing}
2299 The controls in this box allow you to configure PuTTY to reuse an
2300 existing SSH connection, where possible.
2302 The SSH-2 protocol permits you to run multiple data channels over the
2303 same SSH connection, so that you can log in just once (and do the
2304 expensive encryption setup just once) and then have more than one
2305 terminal window open.
2307 Each instance of PuTTY can still run at most one terminal session, but
2308 using the controls in this box, you can configure PuTTY to check if
2309 another instance of itself has already connected to the target host,
2310 and if so, share that instance's SSH connection instead of starting a
2313 To enable this feature, just tick the box \q{Share SSH connections if
2314 possible}. Then, whenever you start up a PuTTY session connecting to a
2315 particular host, it will try to reuse an existing SSH connection if
2316 one is available. For example, selecting \q{Duplicate Session} from
2317 the system menu will launch another session on the same host, and if
2318 sharing is enabled then it will reuse the existing SSH connection.
2320 When this mode is in use, the first PuTTY that connected to a given
2321 server becomes the \q{upstream}, which means that it is the one
2322 managing the real SSH connection. All subsequent PuTTYs which reuse
2323 the connection are referred to as \q{downstreams}: they do not connect
2324 to the real server at all, but instead connect to the upstream PuTTY
2325 via local inter-process communication methods.
2327 For this system to be activated, \e{both} the upstream and downstream
2328 instances of PuTTY must have the sharing option enabled.
2330 The upstream PuTTY can therefore not terminate until all its
2331 downstreams have closed. This is similar to the effect you get with
2332 port forwarding or X11 forwarding, in which a PuTTY whose terminal
2333 session has already finished will still remain open so as to keep
2334 serving forwarded connections.
2336 In case you need to configure this system in more detail, there are
2337 two additional checkboxes which allow you to specify whether a
2338 particular PuTTY can act as an upstream or a downstream or both.
2339 (These boxes only take effect if the main \q{Share SSH connections if
2340 possible} box is also ticked.) By default both of these boxes are
2341 ticked, so that multiple PuTTYs started from the same configuration
2342 will designate one of themselves as the upstream and share a single
2343 connection; but if for some reason you need a particular PuTTY
2344 configuration \e{not} to be an upstream (e.g. because you definitely
2345 need it to close promptly) or not to be a downstream (e.g. because it
2346 needs to do its own authentication using a special private key) then
2347 you can untick one or the other of these boxes.
2349 I have referred to \q{PuTTY} throughout the above discussion, but all
2350 the other PuTTY tools which make SSH connections can use this
2351 mechanism too. For example, if PSCP or PSFTP loads a configuration
2352 with sharing enabled, then it can act as a downstream and use an
2353 existing SSH connection set up by an instance of GUI PuTTY. The one
2354 special case is that PSCP and PSFTP will \e{never} act as upstreams.
2356 It is possible to test programmatically for the existence of a live
2357 upstream using Plink. See \k{plink-option-shareexists}.
2359 \H{config-ssh-kex} The Kex panel
2361 The Kex panel (short for \q{\i{key exchange}}) allows you to configure
2362 options related to SSH-2 key exchange.
2364 Key exchange occurs at the start of an SSH connection (and
2365 occasionally thereafter); it establishes a \i{shared secret} that is used
2366 as the basis for all of SSH's security features. It is therefore very
2367 important for the security of the connection that the key exchange is
2370 Key exchange is a cryptographically intensive process; if either the
2371 client or the server is a relatively slow machine, the slower methods
2372 may take several tens of seconds to complete.
2374 If connection startup is too slow, or the connection hangs
2375 periodically, you may want to try changing these settings.
2377 If you don't understand what any of this means, it's safe to leave
2378 these settings alone.
2380 This entire panel is only relevant to SSH protocol version 2; none of
2381 these settings affect SSH-1 at all.
2383 \S{config-ssh-kex-order} \ii{Key exchange algorithm} selection
2385 \cfg{winhelp-topic}{ssh.kex.order}
2387 PuTTY supports a variety of SSH-2 key exchange methods, and allows you
2388 to choose which one you prefer to use; configuration is similar to
2389 cipher selection (see \k{config-ssh-encryption}).
2391 PuTTY currently supports the following key exchange methods:
2393 \b \q{ECDH}: \i{elliptic curve} \i{Diffie-Hellman key exchange}.
2395 \b \q{Group 14}: Diffie-Hellman key exchange with a well-known
2398 \b \q{Group 1}: Diffie-Hellman key exchange with a well-known
2399 1024-bit group. This is less secure \#{FIXME better words} than
2400 group 14, but may be faster with slow client or server machines,
2401 and may be the only method supported by older server software.
2403 \b \q{\ii{Group exchange}}: with this method, instead of using a fixed
2404 group, PuTTY requests that the server suggest a group to use for key
2405 exchange; the server can avoid groups known to be weak, and possibly
2406 invent new ones over time, without any changes required to PuTTY's
2407 configuration. We recommend use of this method, if possible.
2409 \b \q{\i{RSA key exchange}}: this requires much less computational
2410 effort on the part of the client, and somewhat less on the part of
2411 the server, than Diffie-Hellman key exchange.
2413 If the first algorithm PuTTY finds is below the \q{warn below here}
2414 line, you will see a warning box when you make the connection, similar
2415 to that for cipher selection (see \k{config-ssh-encryption}).
2417 \S{config-ssh-kex-rekey} \ii{Repeat key exchange}
2419 \cfg{winhelp-topic}{ssh.kex.repeat}
2421 If the session key negotiated at connection startup is used too much
2422 or for too long, it may become feasible to mount attacks against the
2423 SSH connection. Therefore, the SSH-2 protocol specifies that a new key
2424 exchange should take place every so often; this can be initiated by
2425 either the client or the server.
2427 While this renegotiation is taking place, no data can pass through
2428 the SSH connection, so it may appear to \q{freeze}. (The occurrence of
2429 repeat key exchange is noted in the Event Log; see
2430 \k{using-eventlog}.) Usually the same algorithm is used as at the
2431 start of the connection, with a similar overhead.
2433 These options control how often PuTTY will initiate a repeat key
2434 exchange (\q{rekey}). You can also force a key exchange at any time
2435 from the Special Commands menu (see \k{using-specials}).
2437 \# FIXME: do we have any additions to the SSH-2 specs' advice on
2438 these values? Do we want to enforce any limits?
2440 \b \q{Max minutes before rekey} specifies the amount of time that is
2441 allowed to elapse before a rekey is initiated. If this is set to zero,
2442 PuTTY will not rekey due to elapsed time. The SSH-2 protocol
2443 specification recommends a timeout of at most 60 minutes.
2445 You might have a need to disable time-based rekeys completely for the same
2446 reasons that \i{keepalives} aren't always helpful. If you anticipate
2447 suffering a network dropout of several hours in the middle of an SSH
2448 connection, but were not actually planning to send \e{data} down
2449 that connection during those hours, then an attempted rekey in the
2450 middle of the dropout will probably cause the connection to be
2451 abandoned, whereas if rekeys are disabled then the connection should
2452 in principle survive (in the absence of interfering \i{firewalls}). See
2453 \k{config-keepalive} for more discussion of these issues; for these
2454 purposes, rekeys have much the same properties as keepalives.
2455 (Except that rekeys have cryptographic value in themselves, so you
2456 should bear that in mind when deciding whether to turn them off.)
2457 Note, however, the the SSH \e{server} can still initiate rekeys.
2459 \b \q{Max data before rekey} specifies the amount of data (in bytes)
2460 that is permitted to flow in either direction before a rekey is
2461 initiated. If this is set to zero, PuTTY will not rekey due to
2462 transferred data. The SSH-2 protocol specification recommends a limit
2463 of at most 1 gigabyte.
2467 As well as specifying a value in bytes, the following shorthand can be
2470 \b \cq{1k} specifies 1 kilobyte (1024 bytes).
2472 \b \cq{1M} specifies 1 megabyte (1024 kilobytes).
2474 \b \cq{1G} specifies 1 gigabyte (1024 megabytes).
2478 Disabling data-based rekeys entirely is a bad idea. The \i{integrity},
2479 and to a lesser extent, \i{confidentiality} of the SSH-2 protocol depend
2480 in part on rekeys occuring before a 32-bit packet sequence number
2481 wraps around. Unlike time-based rekeys, data-based rekeys won't occur
2482 when the SSH connection is idle, so they shouldn't cause the same
2483 problems. The SSH-1 protocol, incidentally, has even weaker integrity
2484 protection than SSH-2 without rekeys.
2486 \H{config-ssh-hostkey} The Host Keys panel
2488 The Host Keys panel allows you to configure options related to SSH-2
2489 \i{host key management}.
2491 Host keys are used to prove the server's identity, and assure you that
2492 the server is not being spoofed (either by a man-in-the-middle attack
2493 or by completely replacing it on the network). See \k{gs-hostkey} for
2494 a basic introduction to host keys.
2496 This entire panel is only relevant to SSH protocol version 2; none of
2497 these settings affect SSH-1 at all.
2499 \S{config-ssh-hostkey-order} \ii{Host key type} selection
2501 \cfg{winhelp-topic}{ssh.hostkey.order}
2503 PuTTY supports a variety of SSH-2 host key types, and allows you to
2504 choose which one you prefer to use to identify the server.
2505 Configuration is similar to cipher selection (see
2506 \k{config-ssh-encryption}).
2508 PuTTY currently supports the following host key types:
2510 \b \q{Ed25519}: \i{Edwards-curve} \i{DSA} using a twisted Edwards
2511 curve with modulus \cw{2^255-19}.
2513 \b \q{ECDSA}: \i{elliptic curve} \i{DSA} using one of the
2514 NIST-standardised elliptic curves.
2516 \b \q{DSA}: straightforward \i{DSA} using modular exponentiation.
2518 \b \q{RSA}: the ordinary \i{RSA} algorithm.
2520 If PuTTY already has one or more host keys stored for the server,
2521 it will prefer to use one of those, even if the server has a key
2522 type that is higher in the preference order. You can add such a
2523 key to PuTTY's cache from within an existing session using the
2524 \q{Special Commands} menu; see \k{using-specials}.
2526 Otherwise, PuTTY will choose a key type based purely on the
2527 preference order you specify in the configuration.
2529 If the first key type PuTTY finds is below the \q{warn below here}
2530 line, you will see a warning box when you make the connection, similar
2531 to that for cipher selection (see \k{config-ssh-encryption}).
2533 \S{config-ssh-kex-manual-hostkeys} \ii{Manually configuring host keys}
2535 \cfg{winhelp-topic}{ssh.kex.manualhostkeys}
2537 In some situations, if PuTTY's automated host key management is not
2538 doing what you need, you might need to manually configure PuTTY to
2539 accept a specific host key, or one of a specific set of host keys.
2541 One reason why you might want to do this is because the host name
2542 PuTTY is connecting to is using round-robin DNS to return one of
2543 multiple actual servers, and they all have different host keys. In
2544 that situation, you might need to configure PuTTY to accept any of a
2545 list of host keys for the possible servers, while still rejecting any
2546 key not in that list.
2548 Another reason is if PuTTY's automated host key management is
2549 completely unavailable, e.g. because PuTTY (or Plink or PSFTP, etc) is
2550 running in a Windows environment without access to the Registry. In
2551 that situation, you will probably want to use the \cw{-hostkey}
2552 command-line option to configure the expected host key(s); see
2553 \k{using-cmdline-hostkey}.
2555 For situations where PuTTY's automated host key management simply
2556 picks the wrong host name to store a key under, you may want to
2557 consider setting a \q{logical host name} instead; see
2560 To configure manual host keys via the GUI, enter some text describing
2561 the host key into the edit box in the \q{Manually configure host keys
2562 for this connection} container, and press the \q{Add} button. The text
2563 will appear in the \q{Host keys or fingerprints to accept} list box.
2564 You can remove keys again with the \q{Remove} button.
2566 The text describing a host key can be in one of the following formats:
2568 \b An MD5-based host key fingerprint of the form displayed in PuTTY's
2569 Event Log and host key dialog boxes, i.e. sixteen 2-digit hex numbers
2570 separated by colons.
2572 \b A base64-encoded blob describing an SSH-2 public key in
2573 OpenSSH's one-line public key format. How you acquire a public key in
2574 this format is server-dependent; on an OpenSSH server it can typically
2575 be found in a location like \c{/etc/ssh/ssh_host_rsa_key.pub}.
2577 If this box contains at least one host key or fingerprint when PuTTY
2578 makes an SSH connection, then PuTTY's automated host key management is
2579 completely bypassed: the connection will be permitted if and only if
2580 the host key presented by the server is one of the keys listed in this
2581 box, and the \I{host key cache}host key store in the Registry will be
2582 neither read \e{nor written}, unless you explicitly do so.
2584 If the box is empty (as it usually is), then PuTTY's automated host
2585 key management will work as normal.
2587 \H{config-ssh-encryption} The Cipher panel
2589 \cfg{winhelp-topic}{ssh.ciphers}
2591 PuTTY supports a variety of different \i{encryption algorithm}s, and
2592 allows you to choose which one you prefer to use. You can do this by
2593 dragging the algorithms up and down in the list box (or moving them
2594 using the Up and Down buttons) to specify a preference order. When
2595 you make an SSH connection, PuTTY will search down the list from the
2596 top until it finds an algorithm supported by the server, and then
2599 PuTTY currently supports the following algorithms:
2601 \b \i{ChaCha20-Poly1305}, a combined cipher and \i{MAC} (SSH-2 only)
2603 \b \i{AES} (Rijndael) - 256, 192, or 128-bit SDCTR or CBC (SSH-2 only)
2605 \b \i{Arcfour} (RC4) - 256 or 128-bit stream cipher (SSH-2 only)
2607 \b \i{Blowfish} - 256-bit SDCTR (SSH-2 only) or 128-bit CBC
2609 \b \ii{Triple-DES} - 168-bit SDCTR (SSH-2 only) or CBC
2611 \b \ii{Single-DES} - 56-bit CBC (see below for SSH-2)
2613 If the algorithm PuTTY finds is below the \q{warn below here} line,
2614 you will see a warning box when you make the connection:
2616 \c The first cipher supported by the server
2617 \c is single-DES, which is below the configured
2618 \c warning threshold.
2619 \c Do you want to continue with this connection?
2621 This warns you that the first available encryption is not a very
2622 secure one. Typically you would put the \q{warn below here} line
2623 between the encryptions you consider secure and the ones you
2624 consider substandard. By default, PuTTY supplies a preference order
2625 intended to reflect a reasonable preference in terms of security and
2628 In SSH-2, the encryption algorithm is negotiated independently for
2629 each direction of the connection, although PuTTY does not support
2630 separate configuration of the preference orders. As a result you may
2631 get two warnings similar to the one above, possibly with different
2634 Single-DES is not recommended in the SSH-2 protocol
2635 standards, but one or two server implementations do support it.
2636 PuTTY can use single-DES to interoperate with
2637 these servers if you enable the \q{Enable legacy use of single-DES in
2638 SSH-2} option; by default this is disabled and PuTTY will stick to
2639 recommended ciphers.
2641 \H{config-ssh-auth} The Auth panel
2643 The Auth panel allows you to configure \i{authentication} options for
2646 \S{config-ssh-banner} \q{Display pre-authentication banner}
2648 \cfg{winhelp-topic}{ssh.auth.banner}
2650 SSH-2 servers can provide a message for clients to display to the
2651 prospective user before the user logs in; this is sometimes known as a
2652 pre-authentication \q{\i{banner}}. Typically this is used to provide
2653 information about the server and legal notices.
2655 By default, PuTTY displays this message before prompting for a
2656 password or similar credentials (although, unfortunately, not before
2657 prompting for a login name, due to the nature of the protocol design).
2658 By unchecking this option, display of the banner can be suppressed
2661 \S{config-ssh-noauth} \q{Bypass authentication entirely}
2663 \cfg{winhelp-topic}{ssh.auth.bypass}
2665 In SSH-2, it is in principle possible to establish a connection
2666 without using SSH's mechanisms to identify or prove who you are
2667 to the server. An SSH server could prefer to handle authentication
2668 in the data channel, for instance, or simply require no user
2669 authentication whatsoever.
2671 By default, PuTTY assumes the server requires authentication (we've
2672 never heard of one that doesn't), and thus must start this process
2673 with a username. If you find you are getting username prompts that
2674 you cannot answer, you could try enabling this option. However,
2675 most SSH servers will reject this.
2677 This is not the option you want if you have a username and just want
2678 PuTTY to remember it; for that see \k{config-username}.
2679 It's also probably not what if you're trying to set up passwordless
2680 login to a mainstream SSH server; depending on the server, you
2681 probably wanted public-key authentication (\k{pubkey})
2682 or perhaps GSSAPI authentication (\k{config-ssh-auth-gssapi}).
2683 (These are still forms of authentication, even if you don't have to
2684 interact with them.)
2686 This option only affects SSH-2 connections. SSH-1 connections always
2687 require an authentication step.
2689 \S{config-ssh-tryagent} \q{Attempt authentication using Pageant}
2691 \cfg{winhelp-topic}{ssh.auth.pageant}
2693 If this option is enabled, then PuTTY will look for Pageant (the SSH
2694 private-key storage agent) and attempt to authenticate with any
2695 suitable public keys Pageant currently holds.
2697 This behaviour is almost always desirable, and is therefore enabled
2698 by default. In rare cases you might need to turn it off in order to
2699 force authentication by some non-public-key method such as
2702 This option can also be controlled using the \c{-noagent}
2703 command-line option. See \k{using-cmdline-agentauth}.
2705 See \k{pageant} for more information about Pageant in general.
2707 \S{config-ssh-tis} \q{Attempt \I{TIS authentication}TIS or
2708 \i{CryptoCard authentication}}
2710 \cfg{winhelp-topic}{ssh.auth.tis}
2712 TIS and CryptoCard authentication are (despite their names) generic
2713 forms of simple \I{challenge/response authentication}challenge/response
2714 authentication available in SSH protocol version 1 only. You might use
2715 them if you were using \i{S/Key} \i{one-time passwords}, for example,
2716 or if you had a physical \i{security token} that generated responses
2717 to authentication challenges. They can even be used to prompt for
2720 With this switch enabled, PuTTY will attempt these forms of
2721 authentication if the server is willing to try them. You will be
2722 presented with a challenge string (which may be different every
2723 time) and must supply the correct response in order to log in. If
2724 your server supports this, you should talk to your system
2725 administrator about precisely what form these challenges and
2728 \S{config-ssh-ki} \q{Attempt \i{keyboard-interactive authentication}}
2730 \cfg{winhelp-topic}{ssh.auth.ki}
2732 The SSH-2 equivalent of TIS authentication is called
2733 \q{keyboard-interactive}. It is a flexible authentication method
2734 using an arbitrary sequence of requests and responses; so it is not
2735 only useful for \I{challenge/response authentication}challenge/response
2736 mechanisms such as \i{S/Key}, but it can also be used for (for example)
2737 asking the user for a \I{password expiry}new password when the old one
2740 PuTTY leaves this option enabled by default, but supplies a switch
2741 to turn it off in case you should have trouble with it.
2743 \S{config-ssh-agentfwd} \q{Allow \i{agent forwarding}}
2745 \cfg{winhelp-topic}{ssh.auth.agentfwd}
2747 This option allows the SSH server to open forwarded connections back
2748 to your local copy of \i{Pageant}. If you are not running Pageant, this
2749 option will do nothing.
2751 See \k{pageant} for general information on Pageant, and
2752 \k{pageant-forward} for information on agent forwarding. Note that
2753 there is a security risk involved with enabling this option; see
2754 \k{pageant-security} for details.
2756 \S{config-ssh-changeuser} \q{Allow attempted \i{changes of username} in SSH-2}
2758 \cfg{winhelp-topic}{ssh.auth.changeuser}
2760 In the SSH-1 protocol, it is impossible to change username after
2761 failing to authenticate. So if you mis-type your username at the
2762 PuTTY \q{login as:} prompt, you will not be able to change it except
2763 by restarting PuTTY.
2765 The SSH-2 protocol \e{does} allow changes of username, in principle,
2766 but does not make it mandatory for SSH-2 servers to accept them. In
2767 particular, \i{OpenSSH} does not accept a change of username; once you
2768 have sent one username, it will reject attempts to try to
2769 authenticate as another user. (Depending on the version of OpenSSH,
2770 it may quietly return failure for all login attempts, or it may send
2773 For this reason, PuTTY will by default not prompt you for your
2774 username more than once, in case the server complains. If you know
2775 your server can cope with it, you can enable the \q{Allow attempted
2776 changes of username} option to modify PuTTY's behaviour.
2778 \S{config-ssh-privkey} \q{\ii{Private key} file for authentication}
2780 \cfg{winhelp-topic}{ssh.auth.privkey}
2782 This box is where you enter the name of your private key file if you
2783 are using \i{public key authentication}. See \k{pubkey} for information
2784 about public key authentication in SSH.
2786 This key must be in PuTTY's native format (\c{*.\i{PPK}}). If you have a
2787 private key in another format that you want to use with PuTTY, see
2788 \k{puttygen-conversions}.
2790 You can use the authentication agent \i{Pageant} so that you do not
2791 need to explicitly configure a key here; see \k{pageant}.
2793 If a private key file is specified here with Pageant running, PuTTY
2794 will first try asking Pageant to authenticate with that key, and
2795 ignore any other keys Pageant may have. If that fails, PuTTY will ask
2796 for a passphrase as normal. You can also specify a \e{public} key file
2797 in this case (in RFC 4716 or OpenSSH format), as that's sufficient to
2798 identify the key to Pageant, but of course if Pageant isn't present
2799 PuTTY can't fall back to using this file itself.
2801 \H{config-ssh-auth-gssapi} The \i{GSSAPI} panel
2803 \cfg{winhelp-topic}{ssh.auth.gssapi}
2805 The \q{GSSAPI} subpanel of the \q{Auth} panel controls the use of
2806 GSSAPI authentication. This is a mechanism which delegates the
2807 authentication exchange to a library elsewhere on the client
2808 machine, which in principle can authenticate in many different ways
2809 but in practice is usually used with the \i{Kerberos} \i{single sign-on}
2810 protocol to implement \i{passwordless login}.
2812 GSSAPI is only available in the SSH-2 protocol.
2814 The topmost control on the GSSAPI subpanel is the checkbox labelled
2815 \q{Attempt GSSAPI authentication}. If this is disabled, GSSAPI will
2816 not be attempted at all and the rest of this panel is unused. If it
2817 is enabled, GSSAPI authentication will be attempted, and (typically)
2818 if your client machine has valid Kerberos credentials loaded, then
2819 PuTTY should be able to authenticate automatically to servers that
2820 support Kerberos logins.
2822 \S{config-ssh-auth-gssapi-delegation} \q{Allow GSSAPI credential
2825 \cfg{winhelp-topic}{ssh.auth.gssapi.delegation}
2827 \i{GSSAPI credential delegation} is a mechanism for passing on your
2828 Kerberos (or other) identity to the session on the SSH server. If
2829 you enable this option, then not only will PuTTY be able to log in
2830 automatically to a server that accepts your Kerberos credentials,
2831 but also you will be able to connect out from that server to other
2832 Kerberos-supporting services and use the same credentials just as
2835 (This option is the Kerberos analogue of SSH agent forwarding; see
2836 \k{pageant-forward} for some information on that.)
2838 Note that, like SSH agent forwarding, there is a security
2839 implication in the use of this option: the administrator of the
2840 server you connect to, or anyone else who has cracked the
2841 administrator account on that server, could fake your identity when
2842 connecting to further Kerberos-supporting services. However,
2843 Kerberos sites are typically run by a central authority, so the
2844 administrator of one server is likely to already have access to the
2845 other services too; so this would typically be less of a risk than
2846 SSH agent forwarding.
2848 \S{config-ssh-auth-gssapi-libraries} Preference order for GSSAPI
2851 \cfg{winhelp-topic}{ssh.auth.gssapi.libraries}
2853 GSSAPI is a mechanism which allows more than one authentication
2854 method to be accessed through the same interface. Therefore, more
2855 than one authentication library may exist on your system which can
2856 be accessed using GSSAPI.
2858 PuTTY contains native support for a few well-known such libraries,
2859 and will look for all of them on your system and use whichever it
2860 finds. If more than one exists on your system and you need to use a
2861 specific one, you can adjust the order in which it will search using
2862 this preference list control.
2864 One of the options in the preference list is to use a user-specified
2865 GSSAPI library. If the library you want to use is not mentioned by
2866 name in PuTTY's list of options, you can enter its full pathname in
2867 the \q{User-supplied GSSAPI library path} field, and move the
2868 \q{User-supplied GSSAPI library} option in the preference list to
2869 make sure it is selected before anything else.
2871 \H{config-ssh-tty} The TTY panel
2873 The TTY panel lets you configure the remote pseudo-terminal.
2875 \S{config-ssh-pty} \I{pseudo-terminal allocation}\q{Don't allocate
2878 \cfg{winhelp-topic}{ssh.nopty}
2880 When connecting to a \i{Unix} system, most \I{interactive
2881 connections}interactive shell sessions are run in a \e{pseudo-terminal},
2882 which allows the Unix system to pretend it's talking to a real physical
2883 terminal device but allows the SSH server to catch all the data coming
2884 from that fake device and send it back to the client.
2886 Occasionally you might find you have a need to run a session \e{not}
2887 in a pseudo-terminal. In PuTTY, this is generally only useful for
2888 very specialist purposes; although in Plink (see \k{plink}) it is
2889 the usual way of working.
2891 \S{config-ttymodes} Sending \i{terminal modes}
2893 \cfg{winhelp-topic}{ssh.ttymodes}
2895 The SSH protocol allows the client to send \q{terminal modes} for
2896 the remote pseudo-terminal. These usually control the server's
2897 expectation of the local terminal's behaviour.
2899 If your server does not have sensible defaults for these modes, you
2900 may find that changing them here helps. If you don't understand any of
2901 this, it's safe to leave these settings alone.
2903 (None of these settings will have any effect if no pseudo-terminal
2904 is requested or allocated.)
2906 You can add or modify a mode by selecting it from the drop-down list,
2907 choosing whether it's set automatically or to a specific value with
2908 the radio buttons and edit box, and hitting \q{Add}. A mode (or
2909 several) can be removed from the list by selecting them and hitting
2910 \q{Remove}. The effect of the mode list is as follows:
2912 \b If a mode is not on the list, it will not be specified to the
2913 server under any circumstances.
2915 \b If a mode is on the list:
2919 \b If the \q{Auto} option is selected, the PuTTY tools will decide
2920 whether to specify that mode to the server, and if so, will send
2925 PuTTY proper will send modes that it has an opinion on (currently only
2926 the code for the Backspace key, \cw{ERASE}). Plink on Unix
2927 will propagate appropriate modes from the local terminal, if any.
2931 \b If a value is specified, it will be sent to the server under all
2932 circumstances. The precise syntax of the value box depends on the
2937 By default, all of the available modes are listed as \q{Auto},
2938 which should do the right thing in most circumstances.
2940 The precise effect of each setting, if any, is up to the server. Their
2941 names come from \i{POSIX} and other Unix systems, and they are most
2942 likely to have a useful effect on such systems. (These are the same
2943 settings that can usually be changed using the \i\c{stty} command once
2944 logged in to such servers.)
2946 Some notable modes are described below; for fuller explanations, see
2947 your server documentation.
2949 \b \I{ERASE special character}\cw{ERASE} is the character that when typed
2950 by the user will delete one space to the left. When set to \q{Auto}
2951 (the default setting), this follows the setting of the local Backspace
2952 key in PuTTY (see \k{config-backspace}).
2955 This and other \i{special character}s are specified using \c{^C} notation
2956 for Ctrl-C, and so on. Use \c{^<27>} or \c{^<0x1B>} to specify a
2957 character numerically, and \c{^~} to get a literal \c{^}. Other
2958 non-control characters are denoted by themselves. Leaving the box
2959 entirely blank indicates that \e{no} character should be assigned to
2960 the specified function, although this may not be supported by all
2964 \b \I{QUIT special character}\cw{QUIT} is a special character that
2965 usually forcefully ends the current process on the server
2966 (\cw{SIGQUIT}). On many servers its default setting is Ctrl-backslash
2967 (\c{^\\}), which is easy to accidentally invoke on many keyboards. If
2968 this is getting in your way, you may want to change it to another
2969 character or turn it off entirely.
2971 \b Boolean modes such as \cw{ECHO} and \cw{ICANON} can be specified in
2972 PuTTY in a variety of ways, such as \cw{true}/\cw{false},
2973 \cw{yes}/\cw{no}, and \cw{0}/\cw{1}.
2975 \b Terminal speeds are configured elsewhere; see \k{config-termspeed}.
2977 \H{config-ssh-x11} The X11 panel
2979 \cfg{winhelp-topic}{ssh.tunnels.x11}
2981 The X11 panel allows you to configure \i{forwarding of X11} over an
2984 If your server lets you run X Window System \i{graphical applications},
2985 X11 forwarding allows you to securely give those applications access to
2986 a local X display on your PC.
2988 To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
2989 If your X display is somewhere unusual, you will need to enter its
2990 location in the \q{X display location} box; if this is left blank,
2991 PuTTY will try to find a sensible default in the environment, or use the
2992 primary local display (\c{:0}) if that fails.
2994 See \k{using-x-forwarding} for more information about X11
2997 \S{config-ssh-x11auth} Remote \i{X11 authentication}
2999 \cfg{winhelp-topic}{ssh.tunnels.x11auth}
3001 If you are using X11 forwarding, the virtual X server created on the
3002 SSH server machine will be protected by authorisation data. This
3003 data is invented, and checked, by PuTTY.
3005 The usual authorisation method used for this is called
3006 \i\cw{MIT-MAGIC-COOKIE-1}. This is a simple password-style protocol:
3007 the X client sends some cookie data to the server, and the server
3008 checks that it matches the real cookie. The cookie data is sent over
3009 an unencrypted X11 connection; so if you allow a client on a third
3010 machine to access the virtual X server, then the cookie will be sent
3013 PuTTY offers the alternative protocol \i\cw{XDM-AUTHORIZATION-1}. This
3014 is a cryptographically authenticated protocol: the data sent by the
3015 X client is different every time, and it depends on the IP address
3016 and port of the client's end of the connection and is also stamped
3017 with the current time. So an eavesdropper who captures an
3018 \cw{XDM-AUTHORIZATION-1} string cannot immediately re-use it for
3019 their own X connection.
3021 PuTTY's support for \cw{XDM-AUTHORIZATION-1} is a somewhat
3022 experimental feature, and may encounter several problems:
3024 \b Some X clients probably do not even support
3025 \cw{XDM-AUTHORIZATION-1}, so they will not know what to do with the
3026 data PuTTY has provided.
3028 \b This authentication mechanism will only work in SSH-2. In SSH-1,
3029 the SSH server does not tell the client the source address of
3030 a forwarded connection in a machine-readable format, so it's
3031 impossible to verify the \cw{XDM-AUTHORIZATION-1} data.
3033 \b You may find this feature causes problems with some SSH servers,
3034 which will not clean up \cw{XDM-AUTHORIZATION-1} data after a
3035 session, so that if you then connect to the same server using
3036 a client which only does \cw{MIT-MAGIC-COOKIE-1} and are allocated
3037 the same remote display number, you might find that out-of-date
3038 authentication data is still present on your server and your X
3041 PuTTY's default is \cw{MIT-MAGIC-COOKIE-1}. If you change it, you
3042 should be sure you know what you're doing.
3044 \S{config-ssh-xauthority} X authority file for local display
3046 \cfg{winhelp-topic}{ssh.tunnels.xauthority}
3048 If you are using X11 forwarding, the local X server to which your
3049 forwarded connections are eventually directed may itself require
3052 Some Windows X servers do not require this: they do authorisation by
3053 simpler means, such as accepting any connection from the local
3054 machine but not from anywhere else. However, if your X server does
3055 require authorisation, then PuTTY needs to know what authorisation
3058 One way in which this data might be made available is for the X
3059 server to store it somewhere in a file which has the same format
3060 as the Unix \c{.Xauthority} file. If this is how your Windows X
3061 server works, then you can tell PuTTY where to find this file by
3062 configuring this option. By default, PuTTY will not attempt to find
3063 any authorisation for your local display.
3065 \H{config-ssh-portfwd} \I{port forwarding}The Tunnels panel
3067 \cfg{winhelp-topic}{ssh.tunnels.portfwd}
3069 The Tunnels panel allows you to configure tunnelling of arbitrary
3070 connection types through an SSH connection.
3072 Port forwarding allows you to tunnel other types of \i{network
3073 connection} down an SSH session. See \k{using-port-forwarding} for a
3074 general discussion of port forwarding and how it works.
3076 The port forwarding section in the Tunnels panel shows a list of all
3077 the port forwardings that PuTTY will try to set up when it connects
3078 to the server. By default no port forwardings are set up, so this
3081 To add a port forwarding:
3083 \b Set one of the \q{Local} or \q{Remote} radio buttons, depending
3084 on whether you want to \I{local port forwarding}forward a local port
3085 to a remote destination (\q{Local}) or \I{remote port forwarding}forward
3086 a remote port to a local destination (\q{Remote}). Alternatively,
3087 select \q{Dynamic} if you want PuTTY to \I{dynamic port forwarding}provide
3088 a local SOCKS 4/4A/5 proxy on a local port (note that this proxy only
3089 supports TCP connections; the SSH protocol does not support forwarding
3092 \b Enter a source \i{port number} into the \q{Source port} box. For
3093 local forwardings, PuTTY will listen on this port of your PC. For
3094 remote forwardings, your SSH server will listen on this port of the
3095 remote machine. Note that most servers will not allow you to listen
3096 on \I{privileged port}port numbers less than 1024.
3098 \b If you have selected \q{Local} or \q{Remote} (this step is not
3099 needed with \q{Dynamic}), enter a hostname and port number separated
3100 by a colon, in the \q{Destination} box. Connections received on the
3101 source port will be directed to this destination. For example, to
3102 connect to a POP-3 server, you might enter
3103 \c{popserver.example.com:110}. (If you need to enter a literal
3104 \i{IPv6 address}, enclose it in square brackets, for instance
3107 \b Click the \q{Add} button. Your forwarding details should appear
3110 To remove a port forwarding, simply select its details in the list
3111 box, and click the \q{Remove} button.
3113 In the \q{Source port} box, you can also optionally enter an \I{listen
3114 address}IP address to listen on, by specifying (for instance)
3116 See \k{using-port-forwarding} for more information on how this
3117 works and its restrictions.
3119 In place of port numbers, you can enter \i{service names}, if they are
3120 known to the local system. For instance, in the \q{Destination} box,
3121 you could enter \c{popserver.example.com:pop3}.
3123 You can \I{port forwarding, changing mid-session}modify the currently
3124 active set of port forwardings in mid-session using \q{Change
3125 Settings} (see \k{using-changesettings}). If you delete a local or
3126 dynamic port forwarding in mid-session, PuTTY will stop listening for
3127 connections on that port, so it can be re-used by another program. If
3128 you delete a remote port forwarding, note that:
3130 \b The SSH-1 protocol contains no mechanism for asking the server to
3131 stop listening on a remote port.
3133 \b The SSH-2 protocol does contain such a mechanism, but not all SSH
3134 servers support it. (In particular, \i{OpenSSH} does not support it in
3135 any version earlier than 3.9.)
3137 If you ask to delete a remote port forwarding and PuTTY cannot make
3138 the server actually stop listening on the port, it will instead just
3139 start refusing incoming connections on that port. Therefore,
3140 although the port cannot be reused by another program, you can at
3141 least be reasonably sure that server-side programs can no longer
3142 access the service at your end of the port forwarding.
3144 If you delete a forwarding, any existing connections established using
3145 that forwarding remain open. Similarly, changes to global settings
3146 such as \q{Local ports accept connections from other hosts} only take
3147 effect on new forwardings.
3149 If the connection you are forwarding over SSH is itself a second SSH
3150 connection made by another copy of PuTTY, you might find the
3151 \q{logical host name} configuration option useful to warn PuTTY of
3152 which host key it should be expecting. See \k{config-loghost} for
3155 \S{config-ssh-portfwd-localhost} Controlling the visibility of
3158 \cfg{winhelp-topic}{ssh.tunnels.portfwd.localhost}
3160 The source port for a forwarded connection usually does not accept
3161 connections from any machine except the \I{localhost}SSH client or
3162 server machine itself (for local and remote forwardings respectively).
3163 There are controls in the Tunnels panel to change this:
3165 \b The \q{Local ports accept connections from other hosts} option
3166 allows you to set up local-to-remote port forwardings in such a way
3167 that machines other than your client PC can connect to the forwarded
3168 port. (This also applies to dynamic SOCKS forwarding.)
3170 \b The \q{Remote ports do the same} option does the same thing for
3171 remote-to-local port forwardings (so that machines other than the
3172 SSH server machine can connect to the forwarded port.) Note that
3173 this feature is only available in the SSH-2 protocol, and not all
3174 SSH-2 servers support it (\i{OpenSSH} 3.0 does not, for example).
3176 \S{config-ssh-portfwd-address-family} Selecting \i{Internet protocol
3177 version} for forwarded ports
3179 \cfg{winhelp-topic}{ssh.tunnels.portfwd.ipversion}
3181 This switch allows you to select a specific Internet protocol (\i{IPv4}
3182 or \i{IPv6}) for the local end of a forwarded port. By default, it is
3183 set on \q{Auto}, which means that:
3185 \b for a local-to-remote port forwarding, PuTTY will listen for
3186 incoming connections in both IPv4 and (if available) IPv6
3188 \b for a remote-to-local port forwarding, PuTTY will choose a
3189 sensible protocol for the outgoing connection.
3191 This overrides the general Internet protocol version preference
3192 on the Connection panel (see \k{config-address-family}).
3194 Note that some operating systems may listen for incoming connections
3195 in IPv4 even if you specifically asked for IPv6, because their IPv4
3196 and IPv6 protocol stacks are linked together. Apparently \i{Linux} does
3197 this, and Windows does not. So if you're running PuTTY on Windows
3198 and you tick \q{IPv6} for a local or dynamic port forwarding, it
3199 will \e{only} be usable by connecting to it using IPv6; whereas if
3200 you do the same on Linux, you can also use it with IPv4. However,
3201 ticking \q{Auto} should always give you a port which you can connect
3202 to using either protocol.
3204 \H{config-ssh-bugs} \I{SSH server bugs}The Bugs and More Bugs panels
3206 Not all SSH servers work properly. Various existing servers have
3207 bugs in them, which can make it impossible for a client to talk to
3208 them unless it knows about the bug and works around it.
3210 Since most servers announce their software version number at the
3211 beginning of the SSH connection, PuTTY will attempt to detect which
3212 bugs it can expect to see in the server and automatically enable
3213 workarounds. However, sometimes it will make mistakes; if the server
3214 has been deliberately configured to conceal its version number, or
3215 if the server is a version which PuTTY's bug database does not know
3216 about, then PuTTY will not know what bugs to expect.
3218 The Bugs and More Bugs panels (there are two because we have so many
3219 bug compatibility modes) allow you to manually configure the bugs
3220 PuTTY expects to see in the server. Each bug can be configured in
3223 \b \q{Off}: PuTTY will assume the server does not have the bug.
3225 \b \q{On}: PuTTY will assume the server \e{does} have the bug.
3227 \b \q{Auto}: PuTTY will use the server's version number announcement
3228 to try to guess whether or not the server has the bug.
3230 \S{config-ssh-bug-ignore1} \q{Chokes on SSH-1 \i{ignore message}s}
3232 \cfg{winhelp-topic}{ssh.bugs.ignore1}
3234 An ignore message (SSH_MSG_IGNORE) is a message in the SSH protocol
3235 which can be sent from the client to the server, or from the server
3236 to the client, at any time. Either side is required to ignore the
3237 message whenever it receives it. PuTTY uses ignore messages to
3238 \I{password camouflage}hide the password packet in SSH-1, so that
3239 a listener cannot tell the length of the user's password; it also
3240 uses ignore messages for connection \i{keepalives} (see
3241 \k{config-keepalive}).
3243 If this bug is detected, PuTTY will stop using ignore messages. This
3244 means that keepalives will stop working, and PuTTY will have to fall
3245 back to a secondary defence against SSH-1 password-length
3246 eavesdropping. See \k{config-ssh-bug-plainpw1}. If this bug is
3247 enabled when talking to a correct server, the session will succeed,
3248 but keepalives will not work and the session might be more
3249 vulnerable to eavesdroppers than it could be.
3251 \S{config-ssh-bug-plainpw1} \q{Refuses all SSH-1 \i{password camouflage}}
3253 \cfg{winhelp-topic}{ssh.bugs.plainpw1}
3255 When talking to an SSH-1 server which cannot deal with ignore
3256 messages (see \k{config-ssh-bug-ignore1}), PuTTY will attempt to
3257 disguise the length of the user's password by sending additional
3258 padding \e{within} the password packet. This is technically a
3259 violation of the SSH-1 specification, and so PuTTY will only do it
3260 when it cannot use standards-compliant ignore messages as
3261 camouflage. In this sense, for a server to refuse to accept a padded
3262 password packet is not really a bug, but it does make life
3263 inconvenient if the server can also not handle ignore messages.
3265 If this \q{bug} is detected, PuTTY will assume that neither ignore
3266 messages nor padding are acceptable, and that it thus has no choice
3267 but to send the user's password with no form of camouflage, so that
3268 an eavesdropping user will be easily able to find out the exact length
3269 of the password. If this bug is enabled when talking to a correct
3270 server, the session will succeed, but will be more vulnerable to
3271 eavesdroppers than it could be.
3273 This is an SSH-1-specific bug. SSH-2 is secure against this type of
3276 \S{config-ssh-bug-rsa1} \q{Chokes on SSH-1 \i{RSA} authentication}
3278 \cfg{winhelp-topic}{ssh.bugs.rsa1}
3280 Some SSH-1 servers cannot deal with RSA authentication messages at
3281 all. If \i{Pageant} is running and contains any SSH-1 keys, PuTTY will
3282 normally automatically try RSA authentication before falling back to
3283 passwords, so these servers will crash when they see the RSA attempt.
3285 If this bug is detected, PuTTY will go straight to password
3286 authentication. If this bug is enabled when talking to a correct
3287 server, the session will succeed, but of course RSA authentication
3290 This is an SSH-1-specific bug.
3292 \S{config-ssh-bug-ignore2} \q{Chokes on SSH-2 \i{ignore message}s}
3294 \cfg{winhelp-topic}{ssh.bugs.ignore2}
3296 An ignore message (SSH_MSG_IGNORE) is a message in the SSH protocol
3297 which can be sent from the client to the server, or from the server
3298 to the client, at any time. Either side is required to ignore the
3299 message whenever it receives it. PuTTY uses ignore messages in SSH-2
3300 to confuse the encrypted data stream and make it harder to
3301 cryptanalyse. It also uses ignore messages for connection
3302 \i{keepalives} (see \k{config-keepalive}).
3304 If it believes the server to have this bug, PuTTY will stop using
3305 ignore messages. If this bug is enabled when talking to a correct
3306 server, the session will succeed, but keepalives will not work and
3307 the session might be less cryptographically secure than it could be.
3309 \S{config-ssh-bug-winadj} \q{Chokes on PuTTY's SSH-2 \cq{winadj} requests}
3311 \cfg{winhelp-topic}{ssh.bugs.winadj}
3313 PuTTY sometimes sends a special request to SSH servers in the middle
3314 of channel data, with the name \cw{winadj@putty.projects.tartarus.org}
3315 (see \k{sshnames-channel}). The purpose of this request is to measure
3316 the round-trip time to the server, which PuTTY uses to tune its flow
3317 control. The server does not actually have to \e{understand} the
3318 message; it is expected to send back a \cw{SSH_MSG_CHANNEL_FAILURE}
3319 message indicating that it didn't understand it. (All PuTTY needs for
3320 its timing calculations is \e{some} kind of response.)
3322 It has been known for some SSH servers to get confused by this message
3323 in one way or another \dash because it has a long name, or because
3324 they can't cope with unrecognised request names even to the extent of
3325 sending back the correct failure response, or because they handle it
3326 sensibly but fill up the server's log file with pointless spam, or
3327 whatever. PuTTY therefore supports this bug-compatibility flag: if it
3328 believes the server has this bug, it will never send its
3329 \cq{winadj@putty.projects.tartarus.org} request, and will make do
3330 without its timing data.
3332 \S{config-ssh-bug-hmac2} \q{Miscomputes SSH-2 HMAC keys}
3334 \cfg{winhelp-topic}{ssh.bugs.hmac2}
3336 Versions 2.3.0 and below of the SSH server software from
3337 \cw{ssh.com} compute the keys for their \i{HMAC} \i{message authentication
3338 code}s incorrectly. A typical symptom of this problem is that PuTTY
3339 dies unexpectedly at the beginning of the session, saying
3340 \q{Incorrect MAC received on packet}.
3342 If this bug is detected, PuTTY will compute its HMAC keys in the
3343 same way as the buggy server, so that communication will still be
3344 possible. If this bug is enabled when talking to a correct server,
3345 communication will fail.
3347 This is an SSH-2-specific bug.
3349 \S{config-ssh-bug-derivekey2} \q{Miscomputes SSH-2 \i{encryption} keys}
3351 \cfg{winhelp-topic}{ssh.bugs.derivekey2}
3353 Versions below 2.0.11 of the SSH server software from \i\cw{ssh.com}
3354 compute the keys for the session encryption incorrectly. This
3355 problem can cause various error messages, such as \q{Incoming packet
3356 was garbled on decryption}, or possibly even \q{Out of memory}.
3358 If this bug is detected, PuTTY will compute its encryption keys in
3359 the same way as the buggy server, so that communication will still
3360 be possible. If this bug is enabled when talking to a correct
3361 server, communication will fail.
3363 This is an SSH-2-specific bug.
3365 \S{config-ssh-bug-sig} \q{Requires padding on SSH-2 \i{RSA} \i{signatures}}
3367 \cfg{winhelp-topic}{ssh.bugs.rsapad2}
3369 Versions below 3.3 of \i{OpenSSH} require SSH-2 RSA signatures to be
3370 padded with zero bytes to the same length as the RSA key modulus.
3371 The SSH-2 specification says that an unpadded signature MUST be
3372 accepted, so this is a bug. A typical symptom of this problem is
3373 that PuTTY mysteriously fails RSA authentication once in every few
3374 hundred attempts, and falls back to passwords.
3376 If this bug is detected, PuTTY will pad its signatures in the way
3377 OpenSSH expects. If this bug is enabled when talking to a correct
3378 server, it is likely that no damage will be done, since correct
3379 servers usually still accept padded signatures because they're used
3380 to talking to OpenSSH.
3382 This is an SSH-2-specific bug.
3384 \S{config-ssh-bug-pksessid2} \q{Misuses the \i{session ID} in SSH-2 PK auth}
3386 \cfg{winhelp-topic}{ssh.bugs.pksessid2}
3388 Versions below 2.3 of \i{OpenSSH} require SSH-2 \i{public-key authentication}
3389 to be done slightly differently: the data to be signed by the client
3390 contains the session ID formatted in a different way. If public-key
3391 authentication mysteriously does not work but the Event Log (see
3392 \k{using-eventlog}) thinks it has successfully sent a signature, it
3393 might be worth enabling the workaround for this bug to see if it
3396 If this bug is detected, PuTTY will sign data in the way OpenSSH
3397 expects. If this bug is enabled when talking to a correct server,
3398 SSH-2 public-key authentication will fail.
3400 This is an SSH-2-specific bug.
3402 \S{config-ssh-bug-rekey} \q{Handles SSH-2 key re-exchange badly}
3404 \cfg{winhelp-topic}{ssh.bugs.rekey2}
3406 Some SSH servers cannot cope with \i{repeat key exchange} at
3407 all, and will ignore attempts by the client to start one. Since
3408 PuTTY pauses the session while performing a repeat key exchange, the
3409 effect of this would be to cause the session to hang after an hour
3410 (unless you have your rekey timeout set differently; see
3411 \k{config-ssh-kex-rekey} for more about rekeys).
3412 Other, very old, SSH servers handle repeat key exchange even more
3413 badly, and disconnect upon receiving a repeat key exchange request.
3415 If this bug is detected, PuTTY will never initiate a repeat key
3416 exchange. If this bug is enabled when talking to a correct server,
3417 the session should still function, but may be less secure than you
3420 This is an SSH-2-specific bug.
3422 \S{config-ssh-bug-maxpkt2} \q{Ignores SSH-2 \i{maximum packet size}}
3424 \cfg{winhelp-topic}{ssh.bugs.maxpkt2}
3426 When an SSH-2 channel is set up, each end announces the maximum size
3427 of data packet that it is willing to receive for that channel. Some
3428 servers ignore PuTTY's announcement and send packets larger than PuTTY
3429 is willing to accept, causing it to report \q{Incoming packet was
3430 garbled on decryption}.
3432 If this bug is detected, PuTTY never allows the channel's
3433 \i{flow-control window} to grow large enough to allow the server to
3434 send an over-sized packet. If this bug is enabled when talking to a
3435 correct server, the session will work correctly, but download
3436 performance will be less than it could be.
3438 \S{config-ssh-bug-chanreq} \q{Replies to requests on closed channels}
3440 \cfg{winhelp-topic}{ssh.bugs.chanreq}
3442 The SSH protocol as published in RFC 4254 has an ambiguity which
3443 arises if one side of a connection tries to close a channel, while the
3444 other side simultaneously sends a request within the channel and asks
3445 for a reply. RFC 4254 leaves it unclear whether the closing side
3446 should reply to the channel request after having announced its
3447 intention to close the channel.
3449 Discussion on the \cw{ietf-ssh} mailing list in April 2014 formed a
3450 clear consensus that the right answer is no. However, because of the
3451 ambiguity in the specification, some SSH servers have implemented the
3452 other policy; for example,
3453 \W{https://bugzilla.mindrot.org/show_bug.cgi?id=1818}{OpenSSH used to}
3456 Because PuTTY sends channel requests with the \q{want reply} flag
3457 throughout channels' lifetime (see \k{config-ssh-bug-winadj}), it's
3458 possible that when connecting to such a server it might receive a
3459 reply to a request after it thinks the channel has entirely closed,
3460 and terminate with an error along the lines of \q{Received
3461 \cw{SSH2_MSG_CHANNEL_FAILURE} for nonexistent channel 256}.
3463 \S{config-ssh-bug-oldgex2} \q{Only supports pre-RFC4419 SSH-2 DH GEX}
3465 \cfg{winhelp-topic}{ssh.bugs.oldgex2}
3467 The SSH key exchange method that uses Diffie-Hellman group exchange
3468 was redesigned after its original release, to use a slightly more
3469 sophisticated setup message. Almost all SSH implementations switched
3470 over to the new version. (PuTTY was one of the last.) A few old
3471 servers still only support the old one.
3473 If this bug is detected, and the client and server negotiate
3474 Diffie-Hellman group exchange, then PuTTY will send the old message
3475 now known as \cw{SSH2_MSG_KEX_DH_GEX_REQUEST_OLD} in place of the new
3476 \cw{SSH2_MSG_KEX_DH_GEX_REQUEST}.
3478 This is an SSH-2-specific bug.
3480 \H{config-serial} The Serial panel
3482 The \i{Serial} panel allows you to configure options that only apply
3483 when PuTTY is connecting to a local \I{serial port}\i{serial line}.
3485 \S{config-serial-line} Selecting a serial line to connect to
3487 \cfg{winhelp-topic}{serial.line}
3489 The \q{Serial line to connect to} box allows you to choose which
3490 serial line you want PuTTY to talk to, if your computer has more
3491 than one serial port.
3493 On Windows, the first serial line is called \i\cw{COM1}, and if there
3494 is a second it is called \cw{COM2}, and so on.
3496 This configuration setting is also visible on the Session panel,
3497 where it replaces the \q{Host Name} box (see \k{config-hostname}) if
3498 the connection type is set to \q{Serial}.
3500 \S{config-serial-speed} Selecting the speed of your serial line
3502 \cfg{winhelp-topic}{serial.speed}
3504 The \q{Speed} box allows you to choose the speed (or \q{baud rate})
3505 at which to talk to the serial line. Typical values might be 9600,
3506 19200, 38400 or 57600. Which one you need will depend on the device
3507 at the other end of the serial cable; consult the manual for that
3508 device if you are in doubt.
3510 This configuration setting is also visible on the Session panel,
3511 where it replaces the \q{Port} box (see \k{config-hostname}) if the
3512 connection type is set to \q{Serial}.
3514 \S{config-serial-databits} Selecting the number of data bits
3516 \cfg{winhelp-topic}{serial.databits}
3518 The \q{Data bits} box allows you to choose how many data bits are
3519 transmitted in each byte sent or received through the serial line.
3520 Typical values are 7 or 8.
3522 \S{config-serial-stopbits} Selecting the number of stop bits
3524 \cfg{winhelp-topic}{serial.stopbits}
3526 The \q{Stop bits} box allows you to choose how many stop bits are
3527 used in the serial line protocol. Typical values are 1, 1.5 or 2.
3529 \S{config-serial-parity} Selecting the serial parity checking scheme
3531 \cfg{winhelp-topic}{serial.parity}
3533 The \q{Parity} box allows you to choose what type of parity checking
3534 is used on the serial line. The settings are:
3536 \b \q{None}: no parity bit is sent at all.
3538 \b \q{Odd}: an extra parity bit is sent alongside each byte, and
3539 arranged so that the total number of 1 bits is odd.
3541 \b \q{Even}: an extra parity bit is sent alongside each byte, and
3542 arranged so that the total number of 1 bits is even.
3544 \b \q{Mark}: an extra parity bit is sent alongside each byte, and
3547 \b \q{Space}: an extra parity bit is sent alongside each byte, and
3550 \S{config-serial-flow} Selecting the serial flow control scheme
3552 \cfg{winhelp-topic}{serial.flow}
3554 The \q{Flow control} box allows you to choose what type of flow
3555 control checking is used on the serial line. The settings are:
3557 \b \q{None}: no flow control is done. Data may be lost if either
3558 side attempts to send faster than the serial line permits.
3560 \b \q{XON/XOFF}: flow control is done by sending XON and XOFF
3561 characters within the data stream.
3563 \b \q{RTS/CTS}: flow control is done using the RTS and CTS wires on
3566 \b \q{DSR/DTR}: flow control is done using the DSR and DTR wires on
3569 \H{config-file} \ii{Storing configuration in a file}
3571 PuTTY does not currently support storing its configuration in a file
3572 instead of the \i{Registry}. However, you can work around this with a
3573 couple of \i{batch file}s.
3575 You will need a file called (say) \c{PUTTY.BAT} which imports the
3576 contents of a file into the Registry, then runs PuTTY, exports the
3577 contents of the Registry back into the file, and deletes the
3578 Registry entries. This can all be done using the Regedit command
3579 line options, so it's all automatic. Here is what you need in
3583 \c regedit /s putty.reg
3584 \c regedit /s puttyrnd.reg
3585 \c start /w putty.exe
3586 \c regedit /ea new.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
3587 \c copy new.reg putty.reg
3589 \c regedit /s puttydel.reg
3591 This batch file needs two auxiliary files: \c{PUTTYRND.REG} which
3592 sets up an initial safe location for the \c{PUTTY.RND} random seed
3593 file, and \c{PUTTYDEL.REG} which destroys everything in the Registry
3594 once it's been successfully saved back to the file.
3596 Here is \c{PUTTYDEL.REG}:
3600 \c [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
3602 Here is an example \c{PUTTYRND.REG} file:
3606 \c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
3607 \c "RandSeedFile"="a:\\putty.rnd"
3609 You should replace \c{a:\\putty.rnd} with the location where you
3610 want to store your random number data. If the aim is to carry around
3611 PuTTY and its settings on one USB stick, you probably want to store it