1 \versionid $Id: config.but,v 1.26 2002/02/24 15:25:19 simon Exp $
3 \C{config} Configuring PuTTY
5 This chapter describes all the configuration options in PuTTY.
7 PuTTY is configured using the control panel that comes up before you
8 start a session. Some options can also be changed in the middle of a
9 session, by selecting \q{Change Settings} from the window menu.
11 \H{config-session} The Session panel
13 The Session configuration panel contains the basic options you need
14 to specify in order to open a session at all, and also allows you to
15 save your settings to be reloaded later.
17 \S{config-hostname} The host name section
19 \cfg{winhelp-topic}{session.hostname}
21 The top box on the Session panel, labelled \q{Specify your
22 connection by host name}, contains the details that need to be
23 filled in before PuTTY can open a session at all.
25 \b The \q{Host Name} box is where you type the name, or the IP
26 address, of the server you want to connect to.
28 \b The \q{Protocol} radio buttons let you choose what type of
29 connection you want to make: a raw connection, a Telnet connection, an
30 rlogin connection or an SSH connection. (See \k{which-one} for a
31 summary of the differences between SSH, Telnet and rlogin.)
33 \b The \q{Port} box lets you specify which port number on the server
34 to connect to. If you select Telnet, Rlogin, or SSH, this box will
35 be filled in automatically to the usual value, and you will only
36 need to change it if you have an unusual server. If you select Raw
37 mode (see \k{using-rawprot}), you will almost certainly need to fill
40 \S{config-saving} Loading and storing saved sessions
42 \cfg{winhelp-topic}{session.saved}
44 The next part of the Session configuration panel allows you to save
45 your preferred PuTTY options so they will appear automatically the
46 next time you start PuTTY. It also allows you to create \e{saved
47 sessions}, which contain a full set of configuration options plus a
48 host name and protocol. A saved session contains all the information
49 PuTTY needs to start exactly the session you want.
51 \b To save your default settings: first set up the settings the way
52 you want them saved. Then come back to the Session panel. Select the
53 \q{Default Settings} entry in the saved sessions list, with a single
54 click. Then press the \q{Save} button.
56 Note that PuTTY does not allow you to save a host name into the
57 Default Settings entry. This ensures that when PuTTY is started up,
58 the host name box is always empty, so a user can always just type in
59 a host name and connect.
61 If there is a specific host you want to store the details of how to
62 connect to, you should create a saved session, which will be
63 separate from the Default Settings.
65 \b To save a session: first go through the rest of the configuration
66 box setting up all the options you want. Then come back to the
67 Session panel. Enter a name for the saved session in the \q{Saved
68 Sessions} input box. (The server name is often a good choice for a
69 saved session name.) Then press the \q{Save} button. Your saved
70 session name should now appear in the list box.
72 \b To reload a saved session: single-click to select the session
73 name in the list box, and then press the \q{Load} button. Your saved
74 settings should all appear in the configuration panel.
76 \b To modify a saved session: first load it as described above. Then
77 make the changes you want. Come back to the Session panel,
78 single-click to select the session name in the list box, and press
79 the \q{Save} button. The new settings will be saved over the top of
82 \b To start a saved session immediately: double-click on the session
85 \b To delete a saved session: single-click to select the session
86 name in the list box, and then press the \q{Delete} button.
88 Each saved session is independent of the Default Settings
89 configuration. If you change your preferences and update Default
90 Settings, you must also update every saved session separately.
92 \S{config-closeonexit} \q{Close Window on Exit}
94 \cfg{winhelp-topic}{session.coe}
96 Finally in the Session panel, there is an option labelled \q{Close
97 Window on Exit}. This controls whether the PuTTY session window
98 disappears as soon as the session inside it terminates. If you are
99 likely to want to copy and paste text out of the session after it
100 has terminated, you should arrange this option to be off.
102 \q{Close Window On Exit} has three settings. \q{Always} means always
103 close the window on exit; \q{Never} means never close on exit
104 (always leave the window open). The third setting, and the default
105 one, is \q{Only on clean exit}. In this mode, a session which
106 terminates normally will cause its window to close, but one which is
107 aborted unexpectedly by network trouble or a confusing message from
108 the server will leave the window up.
110 \H{config-logging} The Logging panel
112 \cfg{winhelp-topic}{logging.main}
114 The Logging configuration panel allows you to save log files of your
115 PuTTY sessions, for debugging, analysis or future reference.
117 The main option is a radio-button set that specifies whether PuTTY
118 will log anything at all. The options are
120 \b \q{Logging turned off completely}. This is the default option; in
121 this mode PuTTY will not create a log file at all.
123 \b \q{Log printable output only}. In this mode, a log file will be
124 created and written to, but only printable text will be saved into
125 it. The various terminal control codes that are typically sent down
126 an interactive session alongside the printable text will be omitted.
127 This might be a useful mode if you want to read a log file in a text
128 editor and hope to be able to make sense of it.
130 \b \q{Log all session output}. In this mode, \e{everything} sent by
131 the server into your terminal session is logged. If you view the log
132 file in a text editor, therefore, you may well find it full of
133 strange control characters. This is a particularly useful mode if
134 you are experiencing problems with PuTTY's terminal handling: you
135 can record everything that went to the terminal, so that someone
136 else can replay the session later in slow motion and watch to see
139 \b \q{Log SSH packet data}. In this mode (which is only used by SSH
140 connections), the SSH message packets sent over the encrypted
141 connection are written to the log file. You might need this to debug
142 a network-level problem, or more likely to send to the PuTTY authors
143 as part of a bug report. \e{BE WARNED} that if you log in using a
144 password, the password will appear in the log file, so be sure to
145 edit it out before sending the log file to anyone else!
147 \S{config-logfilename} \q{Log file name}
149 \cfg{winhelp-topic}{logging.filename}
151 In this edit box you enter the name of the file you want to log the
152 session to. The \q{Browse} button will let you look around your file
153 system to find the right place to put the file; or if you already
154 know exactly where you want it to go, you can just type a pathname
157 There are a few special features in this box. If you use the \c{&}
158 character in the file name box, PuTTY will insert details of the
159 current session in the name of the file it actually opens. The
160 precise replacements it will do are:
162 \b \c{&Y} will be replaced by the current year, as four digits.
164 \b \c{&M} will be replaced by the current month, as two digits.
166 \b \c{&D} will be replaced by the current day of the month, as two
169 \b \c{&T} will be replaced by the current time, as six digits
170 (HHMMSS) with no punctuation.
172 \b \c{&H} will be replaced by the host name you are connecting to.
174 For example, if you enter the host name
175 \c{c:\\puttylogs\\log-&h-&y&m&d-&t.dat}, you will end up with files looking
178 \c log-server1.example.com-20010528-110859.dat
179 \c log-unixbox.somewhere.org-20010611-221001.dat
181 \S{config-logfileexists} \q{What to do if the log file already exists}
183 \cfg{winhelp-topic}{logging.exists}
185 This control allows you to specify what PuTTY should do if it tries
186 to start writing to a log file and it finds the file already exists.
187 You might want to automatically destroy the existing log file and
188 start a new one with the same name. Alternatively, you might want to
189 open the existing log file and add data to the \e{end} of it.
190 Finally (the default option), you might not want to have any
191 automatic behaviour, but to ask the user every time the problem
194 \H{config-terminal} The Terminal panel
196 The Terminal configuration panel allows you to control the behaviour
197 of PuTTY's terminal emulation.
199 \S{config-autowrap} \q{Auto wrap mode initially on}
201 \cfg{winhelp-topic}{terminal.autowrap}
203 Auto wrap mode controls what happens when text printed in a PuTTY
204 window reaches the right-hand edge of the window.
206 With auto wrap mode on, if a long line of text reaches the
207 right-hand edge, it will wrap over on to the next line so you can
208 still see all the text. With auto wrap mode off, the cursor will
209 stay at the right-hand edge of the screen, and all the characters in
210 the line will be printed on top of each other.
212 If you are running a full-screen application and you occasionally
213 find the screen scrolling up when it looks as if it shouldn't, you
214 could try turning this option off.
216 Auto wrap mode can be turned on and off by control sequences sent by
217 the server. This configuration option only controls the \e{default}
218 state. If you modify this option in mid-session using \q{Change
219 Settings}, you will need to reset the terminal (see
220 \k{reset-terminal}) before the change takes effect.
222 \S{config-decom} \q{DEC Origin Mode initially on}
224 \cfg{winhelp-topic}{terminal.decom}
226 DEC Origin Mode is a minor option which controls how PuTTY
227 interprets cursor-position control sequences sent by the server.
229 The server can send a control sequence that restricts the scrolling
230 region of the display. For example, in an editor, the server might
231 reserve a line at the top of the screen and a line at the bottom,
232 and might send a control sequence that causes scrolling operations
233 to affect only the remaining lines.
235 With DEC Origin Mode on, cursor coordinates are counted from the top
236 of the scrolling region. With it turned off, cursor coordinates are
237 counted from the top of the whole screen regardless of the scrolling
240 It is unlikely you would need to change this option, but if you find
241 a full-screen application is displaying pieces of text in what looks
242 like the wrong part of the screen, you could try turning DEC Origin
243 Mode on to see whether that helps.
245 DEC Origin Mode can be turned on and off by control sequences sent
246 by the server. This configuration option only controls the
247 \e{default} state. If you modify this option in mid-session using
248 \q{Change Settings}, you will need to reset the terminal (see
249 \k{reset-terminal}) before the change takes effect.
251 \S{config-crlf} \q{Implicit CR in every LF}
253 \cfg{winhelp-topic}{terminal.lfhascr}
255 Most servers send two control characters, CR and LF, to start a new
256 line of the screen. The CR character makes the cursor return to the
257 left-hand side of the screen. The LF character makes the cursor move
258 one line down (and might make the screen scroll).
260 Some servers only send LF, and expect the terminal to move the
261 cursor over to the left automatically. If you come across a server
262 that does this, you will see a stepped effect on the screen, like
265 \c First line of text
269 If this happens to you, try enabling the \q{Implicit CR in every LF}
270 option, and things might go back to normal:
272 \c First line of text
276 \S{config-erase} \q{Use background colour to erase screen}
278 \cfg{winhelp-topic}{terminal.bce}
280 Not all terminals agree on what colour to turn the screen when the
281 server sends a \q{clear screen} sequence. Some terminals believe the
282 screen should always be cleared to the \e{default} background
283 colour. Others believe the screen should be cleared to whatever the
284 server has selected as a background colour.
286 There exist applications that expect both kinds of behaviour.
287 Therefore, PuTTY can be configured to do either.
289 With this option disabled, screen clearing is always done in the
290 default background colour. With this option enabled, it is done in
291 the \e{current} background colour.
293 Background-colour erase can be turned on and off by control
294 sequences sent by the server. This configuration option only
295 controls the \e{default} state. If you modify this option in
296 mid-session using \q{Change Settings}, you will need to reset the
297 terminal (see \k{reset-terminal}) before the change takes effect.
299 \S{config-blink} \q{Enable blinking text}
301 \cfg{winhelp-topic}{terminal.blink}
303 The server can ask PuTTY to display text that blinks on and off.
304 This is very distracting, so PuTTY allows you to turn blinking text
307 When blinking text is disabled and the server attempts to make some
308 text blink, PuTTY will instead display the text with a bolded
311 Blinking text can be turned on and off by control sequences sent by
312 the server. This configuration option only controls the \e{default}
313 state. If you modify this option in mid-session using \q{Change
314 Settings}, you will need to reset the terminal (see
315 \k{reset-terminal}) before the change takes effect.
317 \S{config-answerback} \q{Answerback to ^E}
319 \cfg{winhelp-topic}{terminal.answerback}
321 This option controls what PuTTY will send back to the server if the
322 server sends it the ^E enquiry character. Normally it just sends
323 the string \q{PuTTY}.
325 If you accidentally write the contents of a binary file to your
326 terminal, you will probably find that it contains more than one ^E
327 character, and as a result your next command line will probably read
328 \q{PuTTYPuTTYPuTTY...} as if you had typed the answerback string
329 multiple times at the keyboard. If you set the answerback string to
330 be empty, this problem should go away, but doing so might cause
333 Note that this is \e{not} the feature of PuTTY which the server will
334 typically use to determine your terminal type. That feature is the
335 \q{Terminal-type string} in the Connection panel; see
336 \k{config-termtype} for details.
338 \S{config-localecho} \q{Local echo}
340 \cfg{winhelp-topic}{terminal.localecho}
342 With local echo disabled, characters you type into the PuTTY window
343 are not echoed in the window \e{by PuTTY}. They are simply sent to
344 the server. (The \e{server} might choose to echo them back to you;
345 this can't be controlled from the PuTTY control panel.)
347 Some types of session need local echo, and many do not. In its
348 default mode, PuTTY will automatically attempt to deduce whether or
349 not local echo is appropriate for the session you are working in. If
350 you find it has made the wrong decision, you can use this
351 configuration option to override its choice: you can force local
352 echo to be turned on, or force it to be turned off, instead of
353 relying on the automatic detection.
355 \S{config-localedit} \q{Local line editing}
357 \cfg{winhelp-topic}{terminal.localedit}
359 Normally, every character you type into the PuTTY window is sent
360 immediately to the server the moment you type it.
362 If you enable local line editing, this changes. PuTTY will let you
363 edit a whole line at a time locally, and the line will only be sent
364 to the server when you press Return. If you make a mistake, you can
365 use the Backspace key to correct it before you press Return, and the
366 server will never see the mistake.
368 Since it is hard to edit a line locally without being able to see
369 it, local line editing is mostly used in conjunction with local echo
370 (\k{config-localecho}). This makes it ideal for use in raw mode
371 \#{FIXME} or when connecting to MUDs or talkers. (Although some more
372 advanced MUDs do occasionally turn local line editing on and turn
373 local echo off, in order to accept a password from the user.)
375 Some types of session need local line editing, and many do not. In
376 its default mode, PuTTY will automatically attempt to deduce whether
377 or not local line editing is appropriate for the session you are
378 working in. If you find it has made the wrong decision, you can use
379 this configuration option to override its choice: you can force
380 local line editing to be turned on, or force it to be turned off,
381 instead of relying on the automatic detection.
383 \H{config-keyboard} The Keyboard panel
385 The Keyboard configuration panel allows you to control the behaviour
386 of the keyboard in PuTTY.
388 \S{config-backspace} Changing the action of the Backspace key
390 \cfg{winhelp-topic}{keyboard.backspace}
392 Some terminals believe that the Backspace key should send the same
393 thing to the server as Control-H (ASCII code 8). Other terminals
394 believe that the Backspace key should send ASCII code 127 (usually
395 known as Control-?) so that it can be distinguished from Control-H.
396 This option allows you to choose which code PuTTY generates when you
399 If you are connecting to a Unix system, you will probably find that
400 the Unix \c{stty} command lets you configure which the server
401 expects to see, so you might not need to change which one PuTTY
402 generates. On other systems, the server's expectation might be fixed
403 and you might have no choice but to configure PuTTY.
405 If you do have the choice, we recommend configuring PuTTY to
406 generate Control-? and configuring the server to expect it, because
407 that allows applications such as \c{emacs} to use Control-H for
410 \S{config-homeend} Changing the action of the Home and End keys
412 \cfg{winhelp-topic}{keyboard.homeend}
414 The Unix terminal emulator \c{rxvt} disagrees with the rest of the
415 world about what character sequences should be sent to the server by
416 the Home and End keys.
418 \c{xterm}, and other terminals, send \c{ESC [1~} for the Home key,
419 and \c{ESC [4~} for the End key. \c{rxvt} sends \c{ESC [H} for the
420 Home key and \c{ESC [Ow} for the End key.
422 If you find an application on which the Home and End keys aren't
423 working, you could try switching this option to see if it helps.
425 \S{config-funkeys} Changing the action of the function keys and keypad
427 \cfg{winhelp-topic}{keyboard.funkeys}
429 This option affects the function keys (F1 to F12) and the top row of
432 \b In the default mode, labelled \c{ESC [n~}, the function keys
433 generate sequences like \c{ESC [11~}, \c{ESC [12~} and so on. This
434 matches the general behaviour of Digital's terminals.
436 \b In Linux mode, F6 to F12 behave just like the default mode, but
437 F1 to F5 generate \c{ESC [[A} through to \c{ESC [[E}. This mimics the
438 Linux virtual console.
440 \b In Xterm R6 mode, F5 to F12 behave like the default mode, but F1
441 to F4 generate \c{ESC OP} through to \c{ESC OS}, which are the
442 sequences produced by the top row of the \e{keypad} on Digital's
445 \b In VT400 mode, all the function keys behave like the default
446 mode, but the actual top row of the numeric keypad generates \c{ESC
447 OP} through to \c{ESC OS}.
449 \b In VT100+ mode, the function keys generate \c{ESC OP} through to
452 \b In SCO mode, the function keys F1 to F12 generate \c{ESC [M}
453 through to \c{ESC [X}. Together with shift, they generate \c{ESC [Y}
454 through to \c{ESC [j}. With control they generate \c{ESC [k} through
455 to \c{ESC [v}, and with shift and control together they generate
456 \c{ESC [w} through to \c{ESC [\{}.
458 If you don't know what any of this means, you probably don't need to
461 \S{config-appcursor} Controlling Application Cursor Keys mode
463 \cfg{winhelp-topic}{keyboard.appcursor}
465 Application Cursor Keys mode is a way for the server to change the
466 control sequences sent by the arrow keys. In normal mode, the arrow
467 keys send \c{ESC [A} through to \c{ESC [D}. In application mode,
468 they send \c{ESC OA} through to \c{ESC OD}.
470 Application Cursor Keys mode can be turned on and off by the server,
471 depending on the application. PuTTY allows you to configure the
472 initial state, and also allows you to disable application mode
475 \S{config-appkeypad} Controlling Application Keypad mode
477 \cfg{winhelp-topic}{keyboard.appkeypad}
479 Application Keypad mode is a way for the server to change the
480 behaviour of the numeric keypad.
482 In normal mode, the keypad behaves like a normal Windows keypad:
483 with NumLock on, the number keys generate numbers, and with NumLock
484 off they act like the arrow keys and Home, End etc.
486 In application mode, all the keypad keys send special control
487 sequences, \e{including} Num Lock. Num Lock stops behaving like Num
488 Lock and becomes another function key.
490 Depending on which version of Windows you run, you may find the Num
491 Lock light still flashes on and off every time you press Num Lock,
492 even when application mode is active and Num Lock is acting like a
493 function key. This is unavoidable.
495 Application keypad mode can be turned on and off by the server,
496 depending on the application. PuTTY allows you to configure the
497 initial state, and also allows you to disable application mode
500 \S{config-nethack} Using NetHack keypad mode
502 \cfg{winhelp-topic}{keyboard.nethack}
504 PuTTY has a special mode for playing NetHack. You can enable it by
505 selecting \q{NetHack} in the \q{Initial state of numeric keypad}
508 In this mode, the numeric keypad keys 1-9 generate the NetHack
509 movement commands (\cw{hjklyubn}). The 5 key generates the \c{.}
510 command (do nothing).
512 Better still, pressing Shift with the keypad keys generates the
513 capital forms of the commands (\cw{HJKLYUBN}), which tells NetHack
514 to keep moving you in the same direction until you encounter
515 something interesting.
517 For some reason, this feature only works properly when Num Lock is
518 on. We don't know why.
520 \S{config-compose} Enabling a DEC-like Compose key
522 \cfg{winhelp-topic}{keyboard.compose}
524 DEC terminals have a Compose key, which provides an easy-to-remember
525 way of typing accented characters. You press Compose and then type
526 two more characters. The two characters are \q{combined} to produce
527 an accented character. The choices of character are designed to be
528 easy to remember; for example, composing \q{e} and \q{`} produces
529 the \q{\u00e8{e-grave}} character.
531 If you enable the \q{Application and AltGr act as Compose key}
532 option, the Windows Application key and the AltGr key will both have
535 \S{config-ctrlalt} \q{Control-Alt is different from AltGr}
537 \cfg{winhelp-topic}{keyboard.ctrlalt}
539 Some old keyboards do not have an AltGr key, which can make it
540 difficult to type some characters. PuTTY can be configured to treat
541 the key combination Ctrl + Left Alt the same way as the AltGr key.
543 By default, this checkbox is checked, and the key combination Ctrl +
544 Left Alt does something completely different. PuTTY's usual handling
545 of the left Alt key is to prefix the Escape (Control-\cw{[})
546 character to whatever character sequence the rest of the keypress
547 would generate. For example, Alt-A generates Escape followed by
548 \c{a}. So Alt-Ctrl-A would generate Escape, followed by Control-A.
550 If you uncheck this box, Ctrl-Alt will become a synonym for AltGr,
551 so you can use it to type extra graphic characters if your keyboard
554 \H{config-bell} The Bell panel
556 The Bell panel controls the terminal bell feature: the server's
557 ability to cause PuTTY to beep at you.
559 In the default configuration, when the server sends the character
560 with ASCII code 7 (Control-G), PuTTY will play the Windows Default
561 Beep sound. This is not always what you want the terminal bell
562 feature to do; the Bell panel allows you to configure alternative
565 \S{config-bellstyle} \q{Set the style of bell}
567 \cfg{winhelp-topic}{bell.style}
569 This control allows you to select various different actions to occur
572 \b Selecting \q{None} disables the bell completely. In this mode,
573 the server can send as many Control-G characters as it likes and
574 nothing at all will happen.
576 \b \q{Play Windows Default Sound} is the default setting. It causes
577 the Windows \q{Default Beep} sound to be played. To change what this
578 sound is, or to test it if nothing seems to be happening, use the
579 Sound configurer in the Windows Control Panel.
581 \b \q{Play a custom sound file} allows you to specify a particular
582 sound file to be used by PuTTY alone, or even by a particular
583 individual PuTTY session. This allows you to distinguish your PuTTY
584 beeps from any other beeps on the system. If you select this option,
585 you will also need to enter the name of your sound file in the edit
586 control \q{Custom sound file to play as a bell}.
588 \b \q{Visual bell} is a silent alternative to a beeping computer. In
589 this mode, when the server sends a Control-G, the whole PuTTY window
590 will flash white for a fraction of a second.
592 \S{config-belltaskbar} \q{Taskbar/caption indication on bell}
594 \cfg{winhelp-topic}{bell.taskbar}
596 This feature controls what happens to the PuTTY window's entry in
597 the Windows Taskbar if a bell occurs while the window does not have
600 In the default state (\q{Disabled}) nothing unusual happens.
602 If you select \q{Steady}, then when a bell occurs and the window is
603 not in focus, the window's Taskbar entry and its title bar will
604 change colour to let you know that PuTTY session is asking for your
605 attention. The change of colour will persist until you select the
606 window, so you can leave several PuTTY windows minimised in your
607 terminal, go away from your keyboard, and be sure not to have missed
608 any important beeps when you get back.
610 \q{Flashing} is even more eye-catching: the Taskbar entry will
611 continuously flash on and off until you select the window.
613 \S{config-bellovl} \q{Control the bell overload behaviour}
615 \cfg{winhelp-topic}{bell.overload}
617 A common user error in a terminal session is to accidentally run the
618 Unix command \c{cat} (or equivalent) on an inappropriate file type,
619 such as an executable, image file, or ZIP file. This produces a huge
620 stream of non-text characters sent to the terminal, which typically
621 includes a lot of bell characters. As a result of this the terminal
622 often doesn't stop beeping for ten minutes, and everybody else in
623 the office gets annoyed.
625 To try to avoid this behaviour, or any other cause of excessive
626 beeping, PuTTY includes a bell overload management feature. In the
627 default configuration, receiving more than five bell characters in a
628 two-second period will cause the overload feature to activate. Once
629 the overload feature is active, further bells will have no effect at
630 all, so the rest of your binary file will be sent to the screen in
631 silence. After a period of five seconds during which no further
632 bells are received, the overload feature will turn itself off again
633 and bells will be re-enabled.
635 If you want this feature completely disabled, you can turn it off
636 using the checkbox \q{Bell is temporarily disabled when over-used}.
638 Alternatively, if you like the bell overload feature but don't agree
639 with the settings, you can configure the details: how many bells
640 constitute an overload, how short a time period they have to arrive
641 in to do so, and how much silent time is required before the
642 overload feature will deactivate itself.
644 \H{config-window} The Window panel
646 The Window configuration panel allows you to control aspects of the
649 \S{config-winsize} Setting the size of the PuTTY window
651 \cfg{winhelp-topic}{window.size}
653 The \q{Rows} and \q{Columns} boxes let you set the PuTTY window to a
654 precise size. Of course you can also drag the window to a new size
655 while a session is running.
657 \S{config-winsizelock} What to do when the window is resized
659 \cfg{winhelp-topic}{window.resize}
661 These options allow you to control what happens when the user tries
662 to resize the PuTTY window.
664 When you resize the PuTTY window, one of four things can happen:
666 \b Nothing (if you have completely disabled resizes).
668 \b The font size can stay the same and the number of rows and
669 columns in the terminal can change.
671 \b The number of rows and columns in the terminal can stay the same,
672 and the font size can change.
674 \b You can allow PuTTY to change \e{either} the terminal size or the
675 font size. In this mode it will change the terminal size most of the
676 time, but enlarge the font when you maximise the window.
678 You can control which of these happens using the \q{Lock terminal
679 size against resizing} and \q{Lock font size against resizing}
680 options. If you lock both, the window will refuse to be resized at
681 all. If you lock just the terminal size, the font size will change
682 when you resize the window. If you lock just the font size, the
683 terminal size will change when you resize the window.
685 \S{config-scrollback} Controlling scrollback
687 \cfg{winhelp-topic}{window.scrollback}
689 These options let you configure the way PuTTY keeps text after it
690 scrolls off the top of the screen (see \k{using-scrollback}).
692 The \q{Lines of scrollback} box lets you configure how many lines of
693 text PuTTY keeps. The \q{Display scrollbar} options allow you to
694 hide the scrollbar (although you can still view the scrollback using
695 Shift-PgUp and Shift-PgDn). You can separately configure whether the
696 scrollbar is shown in full-screen mode and in normal modes.
698 If you are viewing part of the scrollback when the server sends more
699 text to PuTTY, the screen will revert to showing the current
700 terminal contents. You can disable this behaviour by turning off
701 \q{Reset scrollback on display activity}. You can also make the
702 screen revert when you press a key, by turning on \q{Reset
703 scrollback on keypress}.
705 \H{config-appearance} The Appearance panel
707 The Appearance configuration panel allows you to control aspects of
708 the appearance of PuTTY's window.
710 \S{config-cursor} Controlling the appearance of the cursor
712 \cfg{winhelp-topic}{appearance.cursor}
714 The \q{Cursor appearance} option lets you configure the cursor to be
715 a block, an underline, or a vertical line. A block cursor becomes an
716 empty box when the window loses focus; an underline or a vertical
719 The \q{Cursor blinks} option makes the cursor blink on and off. This
720 works in any of the cursor modes.
722 \S{config-font} Controlling the font used in the terminal window
724 \cfg{winhelp-topic}{appearance.font}
726 This option allows you to choose what font, in what size, the PuTTY
727 terminal window uses to display the text in the session. You will be
728 offered a choice from all the fixed-width fonts installed on the
729 system. (VT100-style terminal handling can only deal with fixed-
732 \S{config-title} Controlling the window title
734 \cfg{winhelp-topic}{appearance.title}
736 The \q{Window title} edit box allows you to set the title of the
737 PuTTY window. By default the window title will contain the host name
738 followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
739 If you want a different window title, this is where to set it.
741 PuTTY allows the server to send \c{xterm} control sequences which
742 modify the title of the window in mid-session. There is also an
743 \c{xterm} sequence to modify the title of the window's \e{icon}.
744 This makes sense in a windowing system where the window becomes an
745 icon when minimised, such as Windows 3.1 or most X Window System
746 setups; but in the Windows 95-like user interface it isn't as
747 applicable. By default PuTTY's window title and Taskbar caption will
748 change into the server-supplied icon title if you minimise the PuTTY
749 window, and change back to the server-supplied window title if you
750 restore it. (If the server has not bothered to supply a window or
751 icon title, none of this will happen.) By checking the box marked
752 \q{Avoid ever using icon title}, you can arrange that PuTTY will
753 always display the window title, and completely ignore any icon
754 titles the server sends it.
756 \S{config-mouseptr} \q{Hide mouse pointer when typing in window}
758 \cfg{winhelp-topic}{appearance.hidemouse}
760 If you enable this option, the mouse pointer will disappear if the
761 PuTTY window is selected and you press a key. This way, it will not
762 obscure any of the text in the window while you work in your
763 session. As soon as you move the mouse, the pointer will reappear.
765 This option is disabled by default, so the mouse pointer remains
766 visible at all times.
768 \S{config-winborder} Controlling the window border
770 \cfg{winhelp-topic}{appearance.border}
772 PuTTY allows you to configure the appearance of the window border to
775 The checkbox marked \q{Sunken-edge border} changes the appearance of
776 the window border to something more like a DOS box: the inside edge
777 of the border is highlighted as if it sank down to meet the surface
778 inside the window. This makes the border a little bit thicker as
779 well. It's hard to describe well. Try it and see if you like it.
781 You can also configure a completely blank gap between the text in
782 the window and the border, using the \q{Gap between text and window
783 edge} control. By default this is set at one pixel. You can reduce
784 it to zero, or increase it further.
786 \H{config-behaviour} The Behaviour panel
788 The Behaviour configuration panel allows you to control aspects of
789 the behaviour of PuTTY's window.
791 \S{config-warnonclose} \q{Warn before closing window}
793 \cfg{winhelp-topic}{behaviour.closewarn}
795 If you press the Close button in a PuTTY window that contains a
796 running session, PuTTY will put up a warning window asking if you
797 really meant to close the window. A window whose session has already
798 terminated can always be closed without a warning.
800 If you want to be able to close a window quickly, you can disable
801 the \q{Warn before closing window} option.
803 \S{config-altf4} \q{Window closes on ALT-F4}
805 \cfg{winhelp-topic}{behaviour.altf4}
807 By default, pressing ALT-F4 causes the window to close (or a warning
808 box to appear; see \k{config-warnonclose}). If you disable the
809 \q{Window closes on ALT-F4} option, then pressing ALT-F4 will simply
810 send a key sequence to the server.
812 \S{config-altspace} \q{System menu appears on ALT-Space}
814 \cfg{winhelp-topic}{behaviour.altspace}
816 If this option is enabled, then pressing ALT-Space will bring up the
817 PuTTY window's menu, like clicking on the top left corner. If it is
818 disabled, then pressing ALT-Space will just send \c{ESC SPACE} to
821 Some accessibility programs for Windows may need this option
822 enabling to be able to control PuTTY's window successfully. For
823 instance, Dragon NaturallySpeaking requires it both to open the
824 system menu via voice, and to close, minimise, maximise and restore
827 \S{config-altonly} \q{System menu appears on Alt alone}
829 \cfg{winhelp-topic}{behaviour.altonly}
831 If this option is enabled, then pressing and releasing ALT will
832 bring up the PuTTY window's menu, like clicking on the top left
833 corner. If it is disabled, then pressing and releasing ALT will have
836 \S{config-alwaysontop} \q{Ensure window is always on top}
838 \cfg{winhelp-topic}{behaviour.alwaysontop}
840 If this option is enabled, the PuTTY window will stay on top of all
843 \S{config-fullscreen} \q{Full screen on Alt-Enter}
845 \cfg{winhelp-topic}{behaviour.altenter}
847 If this option is enabled, then pressing Alt-Enter will cause the
848 PuTTY window to become full-screen. Pressing Alt-Enter again will
849 restore the previous window size.
851 The full-screen feature is also available from the System menu, even
852 when it is configured not to be available on the Alt-Enter key. See
853 \k{using-fullscreen}.
855 \H{config-translation} The Translation panel
857 The Translation configuration panel allows you to control the
858 translation between the character set understood by the server and
859 the character set understood by PuTTY.
861 \S{config-charset} Controlling character set translation
863 \cfg{winhelp-topic}{translation.codepage}
865 During an interactive session, PuTTY receives a stream of 8-bit
866 bytes from the server, and in order to display them on the screen it
867 needs to know what character set to interpret them in.
869 There are a lot of character sets to choose from. The \q{Received
870 data assumed to be in which character set} option lets you select
871 one. By default PuTTY will attempt to choose a character set that is
872 right for your locale as reported by Windows; if it gets it wrong,
873 you can select a different one using this control.
875 A few notable character sets are:
877 \b The ISO-8859 series are all standard character sets that include
878 various accented characters appropriate for different sets of
881 \b The Win125x series are defined by Microsoft, for similar
882 purposes. In particular Win1252 is almost equivalent to ISO-8859-1,
883 but contains a few extra characters such as matched quotes and the
886 \b If you want the old IBM PC character set with block graphics and
887 line-drawing characters, you can select \q{CP437}.
889 \b PuTTY also supports Unicode mode, in which the data coming from
890 the server is interpreted as being in the UTF-8 encoding of Unicode.
891 If you select \q{UTF-8} as a character set you can use this mode.
892 Not all server-side applications will support it.
894 \S{config-cyr} \q{Caps Lock acts as Cyrillic switch}
896 \cfg{winhelp-topic}{translation.cyrillic}
898 This feature allows you to switch between a US/UK keyboard layout
899 and a Cyrillic keyboard layout by using the Caps Lock key, if you
900 need to type (for example) Russian and English side by side in the
903 Currently this feature is not expected to work properly if your
904 native keyboard layout is not US or UK.
906 \S{config-linedraw} Controlling display of line drawing characters
908 \cfg{winhelp-topic}{translation.linedraw}
910 VT100-series terminals allow the server to send control sequences
911 that shift temporarily into a separate character set for drawing
912 lines and boxes. PuTTY has a variety of ways to support this
913 capability. In general you should probably try lots of options until
914 you find one that your particular font supports.
916 \b \q{Font has XWindows encoding} is for use with fonts that have a
917 special encoding, where the lowest 32 character positions (below the
918 ASCII printable range) contain the line-drawing characters. This is
919 unlikely to be the case with any standard Windows font; it will
920 probably only apply to custom-built fonts or fonts that have been
921 automatically converted from the X Window System.
923 \b \q{Use font in both ANSI and OEM modes} tries to use the same
924 font in two different character sets, to obtain a wider range of
925 characters. This doesn't always work; some fonts claim to be a
926 different size depending on which character set you try to use.
928 \b \q{Use font in OEM mode only} is more reliable than that, but can
929 miss out other characters from the main character set.
931 \b \q{Poor man's line drawing} assumes that the font \e{cannot}
932 generate the line and box characters at all, so it will use the
933 \c{+}, \c{-} and \c{|} characters to draw approximations to boxes.
934 You should use this option if none of the other options works.
936 \b \q{Unicode mode} tries to use the box characters that are present
937 in Unicode. For good Unicode-supporting fonts this is probably the
938 most reliable and functional option.
940 \H{config-selection} The Selection panel
942 The Selection panel allows you to control the way copy and paste
943 work in the PuTTY window.
945 \S{config-linedrawpaste} Controlling the pasting of line drawing
948 \cfg{winhelp-topic}{selection.linedraw}
950 By default, when you copy and paste a piece of the PuTTY screen that
951 contains VT100 line and box drawing characters, PuTTY will translate
952 them into the \q{poor man's} line-drawing characters \c{+}, \c{-}
953 and \c{|}. The checkbox \q{Don't translate line drawing chars}
954 disables this feature, so line-drawing characters will be pasted as
955 if they were in the normal character set. This will typically mean
956 they come out mostly as \c{q} and \c{x}, with a scattering of
957 \c{jklmntuvw} at the corners. This might be useful if you were
958 trying to recreate the same box layout in another program, for
961 \S{config-rtfpaste} Pasting in Rich Text Format
963 \cfg{winhelp-topic}{selection.rtf}
965 If you enable \q{Paste to clipboard in RTF as well as plain text},
966 PuTTY will write formatting information to the clipboard as well as
967 the actual text you copy. Currently the only effect of this will be
968 that if you paste into (say) a word processor, the text will appear
969 in the word processor in the same font PuTTY was using to display
970 it. In future it is likely that other formatting information (bold,
971 underline, colours) will be copied as well.
973 This option can easily be inconvenient, so by default it is
976 \S{config-mouse} Changing the actions of the mouse buttons
978 \cfg{winhelp-topic}{selection.buttons}
980 PuTTY's copy and paste mechanism is modelled on the Unix \c{xterm}
981 application. The X Window System uses a three-button mouse, and the
982 convention is that the left button selects, the right button extends
983 an existing selection, and the middle button pastes.
985 Windows typically only has two mouse buttons, so in PuTTY's default
986 configuration, the \e{right} button pastes, and the \e{middle}
987 button (if you have one) extends a selection.
989 If you have a three-button mouse and you are already used to the
990 \c{xterm} arrangement, you can select it using the \q{Action of
991 mouse buttons} control.
993 \S{config-mouseshift} \q{Shift overrides application's use of mouse}
995 \cfg{winhelp-topic}{selection.shiftdrag}
997 PuTTY allows the server to send control codes that let it take over
998 the mouse and use it for purposes other than copy and paste.
999 Applications which use this feature include the text-mode web
1000 browser \c{links}, the Usenet newsreader \c{trn} version 4, and the
1001 file manager \c{mc} (Midnight Commander).
1003 When running one of these applications, pressing the mouse buttons
1004 no longer performs copy and paste. If you do need to copy and paste,
1005 you can still do so if you hold down Shift while you do your mouse
1008 However, it is possible in theory for applications to even detect
1009 and make use of Shift + mouse clicks. We don't know of any
1010 applications that do this, but in case someone ever writes one,
1011 unchecking the \q{Shift overrides application's use of mouse}
1012 checkbox will cause Shift + mouse clicks to go to the server as well
1013 (so that mouse-driven copy and paste will be completely disabled).
1015 \S{config-rectselect} Default selection mode
1017 \cfg{winhelp-topic}{selection.rect}
1019 As described in \k{using-selection}, PuTTY has two modes of
1020 selecting text to be copied to the clipboard. In the default mode
1021 (\q{Normal}), dragging the mouse from point A to point B selects to
1022 the end of the line containing A, all the lines in between, and from
1023 the very beginning of the line containing B. In the other mode
1024 (\q{Rectangular block}), dragging the mouse between two points
1025 defines a rectangle, and everything within that rectangle is copied.
1027 Normally, you have to hold down Alt while dragging the mouse to
1028 select a rectangular block. Using the \q{Default selection mode}
1029 control, you can set rectangular selection as the default, and then
1030 you have to hold down Alt to get the \e{normal} behaviour.
1032 \S{config-charclasses} Configuring word-by-word selection
1034 \cfg{winhelp-topic}{selection.charclasses}
1036 PuTTY will select a word at a time in the terminal window if you
1037 double-click to begin the drag. This panel allows you to control
1038 precisely what is considered to be a word.
1040 Each character is given a \e{class}, which is a small number
1041 (typically 0, 1 or 2). PuTTY considers a single word to be any
1042 number of adjacent characters in the same class. So by modifying the
1043 assignment of characters to classes, you can modify the word-by-word
1044 selection behaviour.
1046 In the default configuration, the character classes are:
1048 \b Class 0 contains white space and control characters.
1050 \b Class 1 contains most punctuation.
1052 \b Class 2 contains letters, numbers and a few pieces of punctuation
1053 (the double quote, minus sign, period, forward slash and
1056 So, for example, if you assign the \c{@} symbol into character class
1057 2, you will be able to select an e-mail address with just a double
1060 In order to adjust these assignments, you start by selecting a group
1061 of characters in the list box. Then enter a class number in the edit
1062 box below, and press the \q{Set} button.
1064 This mechanism currently only covers ASCII characters, because it
1065 isn't feasible to expand the list to cover the whole of Unicode.
1067 Character class definitions can be modified by control sequences
1068 sent by the server. This configuration option only controls the
1069 \e{default} state. If you modify this option in mid-session using
1070 \q{Change Settings}, you will need to reset the terminal (see
1071 \k{reset-terminal}) before the change takes effect.
1073 \H{config-colours} The Colours panel
1075 The Colours panel allows you to control PuTTY's use of colour.
1077 \S{config-boldcolour} \q{Bolded text is a different colour}
1079 \cfg{winhelp-topic}{colours.bold}
1081 When the server sends a control sequence indicating that some text
1082 should be displayed in bold, PuTTY can handle this two ways. It can
1083 either change the font for a bold version, or use the same font in a
1084 brighter colour. This control lets you choose which.
1086 By default the box is checked, so non-bold text is displayed in
1087 light grey and bold text is displayed in bright white (and similarly
1088 in other colours). If you uncheck the box, bold and non-bold text
1089 will be displayed in the same colour, and instead the font will
1090 change to indicate the difference.
1092 \S{config-logpalette} \q{Attempt to use logical palettes}
1094 \cfg{winhelp-topic}{colours.logpal}
1096 Logical palettes are a mechanism by which a Windows application
1097 running on an 8-bit colour display can select precisely the colours
1098 it wants instead of going with the Windows standard defaults.
1100 If you are not getting the colours you ask for on an 8-bit display,
1101 you can try enabling this option. However, be warned that it's never
1104 \S{config-colourcfg} Adjusting the colours in the terminal window
1106 \cfg{winhelp-topic}{colours.config}
1108 The main colour control allows you to specify exactly what colours
1109 things should be displayed in. To modify one of the PuTTY colours,
1110 use the list box to select which colour you want to modify. The RGB
1111 values for that colour will appear on the right-hand side of the
1112 list box. Now, if you press the \q{Modify} button, you will be
1113 presented with a colour selector, in which you can choose a new
1114 colour to go in place of the old one.
1116 PuTTY allows you to set the cursor colour, the default foreground
1117 and background, and the precise shades of all the ANSI configurable
1118 colours (black, red, green, yellow, blue, magenta, cyan, and white).
1119 In addition, if you have selected \q{Bolded text is a different
1120 colour}, you can also modify the precise shades used for the bold
1121 versions of these colours.
1123 \H{config-connection} The Connection panel
1125 The Connection panel allows you to configure options that apply to
1126 more than one type of connection.
1128 \S{config-termtype} \q{Terminal-type string}
1130 \cfg{winhelp-topic}{connection.termtype}
1132 Most servers you might connect to with PuTTY are designed to be
1133 connected to from lots of different types of terminal. In order to
1134 send the right control sequences to each one, the server will need
1135 to know what type of terminal it is dealing with. Therefore, each of
1136 the SSH, Telnet and Rlogin protocols allow a text string to be sent
1137 down the connection describing the terminal.
1139 PuTTY attempts to emulate the Unix \c{xterm} program, and by default
1140 it reflects this by sending \c{xterm} as a terminal-type string. If
1141 you find this is not doing what you want - perhaps the remote
1142 terminal reports \q{Unknown terminal type} - you could try setting
1143 this to something different, such as \c{vt220}.
1145 If you're not sure whether a problem is due to the terminal type
1146 setting or not, you probably need to consult the manual for your
1147 application or your server.
1149 \S{config-username} \q{Auto-login username}
1151 \cfg{winhelp-topic}{connection.username}
1153 All three of the SSH, Telnet and Rlogin protocols allow you to
1154 specify what user name you want to log in as, without having to type
1155 it explicitly every time. (Some Telnet servers don't support this.)
1157 In this box you can type that user name.
1159 \S{config-keepalive} Using keepalives to prevent disconnection
1161 \cfg{winhelp-topic}{connection.keepalive}
1163 If you find your sessions are closing unexpectedly (\q{Connection
1164 reset by peer}) after they have been idle for a while, you might
1165 want to try using this option.
1167 Some network routers and firewalls need to keep track of all
1168 connections through them. Usually, these firewalls will assume a
1169 connection is dead if no data is transferred in either direction
1170 after a certain time interval. This can cause PuTTY sessions to be
1171 unexpectedly closed by the firewall if no traffic is seen in the
1172 session for some time.
1174 The keepalive option (\q{Seconds between keepalives}) allows you to
1175 configure PuTTY to send data through the session at regular
1176 intervals, in a way that does not disrupt the actual terminal
1177 session. If you find your firewall is cutting idle connections off,
1178 you can try entering a non-zero value in this field. The value is
1179 measured in seconds; so, for example, if your firewall cuts
1180 connections off after ten minutes then you might want to enter 300
1181 seconds (5 minutes) in the box.
1183 Note that keepalives are not always helpful. They help if you have a
1184 firewall which drops your connection after an idle period; but if
1185 the network between you and the server suffers from breaks in
1186 connectivity then keepalives can actually make things worse. If a
1187 session is idle, and connectivity is temporarily lost between the
1188 endpoints, but the connectivity is restored before either side tries
1189 to send anything, then there will be no problem - neither endpoint
1190 will notice that anything was wrong. However, if one side does send
1191 something during the break, it will repeatedly try to re-send, and
1192 eventually give up and abandon the connection. Then when
1193 connectivity is restored, the other side will find that the first
1194 side doesn't believe there is an open connection any more.
1195 Keepalives can make this sort of problem worse, because they
1196 increase the probability that PuTTY will attempt to send data during
1197 a break in connectivity. Therefore, you might find they help
1198 connection loss, or you might find they make it worse, depending on
1199 what \e{kind} of network problems you have between you and the
1202 Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
1203 protocols offer no way of implementing them.
1205 \S{config-nodelay} \q{Disable Nagle's algorithm}
1207 \cfg{winhelp-topic}{connection.nodelay}
1209 Nagle's algorithm is a detail of TCP/IP implementations that tries
1210 to minimise the number of small data packets sent down a network
1211 connection. With Nagle's algorithm enabled, PuTTY's bandwidth usage
1212 will be slightly more efficient; with it disabled, you may find you
1213 get a faster response to your keystrokes when connecting to some
1216 The Nagle algorithm is disabled by default.
1218 \H{config-telnet} The Telnet panel
1220 The Telnet panel allows you to configure options that only apply to
1223 \S{config-termspeed} \q{Terminal-speed string}
1225 \cfg{winhelp-topic}{telnet.termspeed}
1227 Telnet allows the client to send a text string that describes the
1228 terminal speed. PuTTY lets you configure this, in case you find the
1229 server is reacting badly to the default value. (I'm not aware of any
1230 servers that do have a problem with it.)
1232 \S{config-environ} Setting environment variables on the server
1234 \cfg{winhelp-topic}{telnet.environ}
1236 The Telnet protocol also provides a means for the client to pass
1237 environment variables to the server. Many Telnet servers have
1238 stopped supporting this feature due to security flaws, but PuTTY
1239 still supports it for the benefit of any servers which have found
1240 other ways around the security problems than just disabling the
1243 To add an environment variable to the list transmitted down the
1244 connection, you enter the variable name in the \q{Variable} box,
1245 enter its value in the \q{Value} box, and press the \q{Add} button.
1246 To remove one from the list, select it in the list box and press
1249 \S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
1251 \cfg{winhelp-topic}{telnet.oldenviron}
1253 The original Telnet mechanism for passing environment variables was
1254 badly specified. At the time the standard (RFC 1408) was written,
1255 BSD telnet implementations were already supporting the feature, and
1256 the intention of the standard was to describe the behaviour the BSD
1257 implementations were already using.
1259 Sadly there was a typing error in the standard when it was issued,
1260 and two vital function codes were specified the wrong way round. BSD
1261 implementations did not change, and the standard was not corrected.
1262 Therefore, it's possible you might find either BSD or RFC-compliant
1263 implementations out there. This switch allows you to choose which
1264 one PuTTY claims to be.
1266 The problem was solved by issuing a second standard, defining a new
1267 Telnet mechanism called \cw{NEW_ENVIRON}, which behaved exactly like
1268 the original \cw{OLD_ENVIRON} but was not encumbered by existing
1269 implementations. Most Telnet servers now support this, and it's
1270 unambiguous. This feature should only be needed if you have trouble
1271 passing environment variables to quite an old server.
1273 \S{config-ptelnet} Passive and active Telnet negotiation modes
1275 \cfg{winhelp-topic}{telnet.passive}
1277 In a Telnet connection, there are two types of data passed between
1278 the client and the server: actual text, and \e{negotiations} about
1279 which Telnet extra features to use.
1281 PuTTY can use two different strategies for negotiation:
1283 \b In \e{active} mode, PuTTY starts to send negotiations as soon as
1284 the connection is opened.
1286 \b In \e{passive} mode, PuTTY will wait to negotiate until it sees a
1287 negotiation from the server.
1289 The obvious disadvantage of passive mode is that if the server is
1290 also operating in a passive mode, then negotiation will never begin
1291 at all. For this reason PuTTY defaults to active mode.
1293 However, sometimes passive mode is required in order to successfully
1294 get through certain types of firewall and Telnet proxy server. If
1295 you have confusing trouble with a firewall, you could try enabling
1296 passive mode to see if it helps.
1298 \S{config-telnetkey} \q{Keyboard sends telnet Backspace and Interrupt}
1300 \cfg{winhelp-topic}{telnet.specialkeys}
1302 If this box is checked, the Backspace key on the keyboard will send
1303 the Telnet special backspace code, and Control-C will send the
1304 Telnet special interrupt code. You probably shouldn't enable this
1305 unless you know what you're doing.
1307 \S{config-telnetnl} \q{Return key sends telnet New Line instead of ^M}
1309 \cfg{winhelp-topic}{telnet.newline}
1311 Unlike most other remote login protocols, the Telnet protocol has a
1312 special \q{new line} code that is not the same as the usual line
1313 endings of Control-M or Control-J. By default, PuTTY sends the
1314 Telnet New Line code when you press Return, instead of sending
1315 Control-M as it does in most other protocols.
1317 Most Unix-style Telnet servers don't mind whether they receive
1318 Telnet New Line or Control-M; some servers do expect New Line, and
1319 some servers prefer to see ^M. If you are seeing surprising
1320 behaviour when you press Return in a Telnet session, you might try
1321 turning this option off to see if it helps.
1323 \H{config-rlogin} The Rlogin panel
1325 The Rlogin panel allows you to configure options that only apply to
1328 \S{config-rlogin-termspeed} \q{Terminal-speed string}
1330 \cfg{winhelp-topic}{rlogin.termspeed}
1332 Like Telnet, Rlogin allows the client to send a text string that
1333 describes the terminal speed. PuTTY lets you configure this, in case
1334 you find the server is reacting badly to the default value. (I'm not
1335 aware of any servers that do have a problem with it.)
1337 \S{config-rlogin-localuser} \q{Local username}
1339 \cfg{winhelp-topic}{rlogin.localuser}
1341 Rlogin allows an automated (password-free) form of login by means of
1342 a file called \c{.rhosts} on the server. You put a line in your
1343 \c{.rhosts} file saying something like \c{jbloggs@pc1.example.com},
1344 and then when you make an Rlogin connection the client transmits the
1345 username of the user running the Rlogin client. The server checks
1346 the username and hostname against \c{.rhosts}, and if they match it
1347 does not ask for a password.
1349 This only works because Unix systems contain a safeguard to stop a
1350 user from pretending to be another user in an Rlogin connection.
1351 Rlogin connections have to come from port numbers below 1024, and
1352 Unix systems prohibit this to unprivileged processes; so when the
1353 server sees a connection from a low-numbered port, it assumes the
1354 client end of the connection is held by a privileged (and therefore
1355 trusted) process, so it believes the claim of who the user is.
1357 Windows does not have this restriction: \e{any} user can initiate an
1358 outgoing connection from a low-numbered port. Hence, the Rlogin
1359 \c{.rhosts} mechanism is completely useless for securely
1360 distinguishing several different users on a Windows machine. If you
1361 have a \c{.rhosts} entry pointing at a Windows PC, you should assume
1362 that \e{anyone} using that PC can spoof your username in an Rlogin
1363 connection and access your account on the server.
1365 The \q{Local username} control allows you to specify what user name
1366 PuTTY should claim you have, in case it doesn't match your Windows
1367 user name (or in case you didn't bother to set up a Windows user
1370 \H{config-ssh} The SSH panel
1372 The SSH panel allows you to configure options that only apply to
1375 \S{config-command} Executing a specific command on the server
1377 \cfg{winhelp-topic}{ssh.command}
1379 In SSH, you don't have to run a general shell session on the server.
1380 Instead, you can choose to run a single specific command (such as a
1381 mail user agent, for example). If you want to do this, enter the
1382 command in the \q{Remote command} box.
1384 \S{config-ssh-pty} \q{Don't allocate a pseudo-terminal}
1386 \cfg{winhelp-topic}{ssh.nopty}
1388 When connecting to a Unix system, most interactive shell sessions
1389 are run in a \e{pseudo-terminal}, which allows the Unix system to
1390 pretend it's talking to a real physical terminal device but allows
1391 the SSH server to catch all the data coming from that fake device
1392 and send it back to the client.
1394 Occasionally you might find you have a need to run a session \e{not}
1395 in a pseudo-terminal. In PuTTY, this is generally only useful for
1396 very specialist purposes; although in Plink (see \k{plink}) it is
1397 the usual way of working.
1399 \S{config-ssh-comp} \q{Enable compression}
1401 \cfg{winhelp-topic}{ssh.compress}
1403 This enables data compression in the SSH connection: data sent by
1404 the server is compressed before sending, and decompressed at the
1405 client end. Likewise, data sent by PuTTY to the server is compressed
1406 first and the server decompresses it at the other end. This can help
1407 make the most of a low-bandwidth connection.
1409 \S{config-ssh-prot} \q{Preferred SSH protocol version}
1411 \cfg{winhelp-topic}{ssh.protocol}
1413 This allows you to select whether you would like to use SSH protocol
1414 version 1 or version 2. \#{FIXME: say something about this elsewhere?}
1416 PuTTY will attempt to use protocol 1 if the server you connect to
1417 does not offer protocol 2, and vice versa.
1419 \S{config-ssh-macbug} \q{Imitate SSH 2 MAC bug}
1421 \cfg{winhelp-topic}{ssh.buggymac}
1423 This option \e{should} now be unnecessary. It existed in order to
1424 work around a bug in early versions (2.3.0 and below) of the SSH
1425 server software from \cw{ssh.com}. The symptom of this problem would
1426 be that PuTTY would die unexpectedly at the beginning of the
1427 session, saying \q{Incorrect MAC received on packet}.
1429 Current versions of PuTTY attempt to detect these faulty servers and
1430 enable the bug compatibility automatically, so you should never need
1431 to use this option any more.
1433 \S{config-ssh-encryption} Encryption algorithm selection
1435 \cfg{winhelp-topic}{ssh.ciphers}
1437 PuTTY supports a variety of different encryption algorithms, and
1438 allows you to choose which one you prefer to use. You can do this by
1439 dragging the algorithms up and down in the list box (or moving them
1440 using the Up and Down buttons) to specify a preference order. When
1441 you make an SSH connection, PuTTY will search down the list from the
1442 top until it finds an algorithm supported by the server, and then
1445 If the algorithm PuTTY finds is below the \q{warn below here} line,
1446 you will see a warning box when you make the connection:
1448 \c The first cipher supported by the server
1449 \c is single-DES, which is below the configured
1450 \c warning threshold.
1451 \c Do you want to continue with this connection?
1453 This warns you that the first available encryption is not a very
1454 secure one. Typically you would put the \q{warn below here} line
1455 between the encryptions you consider secure and the ones you
1456 consider substandard. By default, PuTTY supplies a preference order
1457 intended to reflect a reasonable preference in terms of security and
1460 Single-DES is not supported natively in the SSH 2 draft protocol
1461 standards. One or two server implementations do support it, by a
1462 non-standard name. PuTTY can use single-DES to interoperate with
1463 these servers if you enable the \q{Enable non-standard single-DES in
1464 SSH 2} option; by default this is disabled and PuTTY will stick to
1467 \H{config-ssh-auth} The Auth panel
1469 The Auth panel allows you to configure authentication options for
1472 \S{config-ssh-tis} \q{Attempt TIS or CryptoCard authentication}
1474 \cfg{winhelp-topic}{ssh.auth.tis}
1476 TIS and CryptoCard authentication are simple challenge/response
1477 forms of authentication available in SSH protocol version 1 only.
1478 You might use them if you were using S/Key one-time passwords, for
1479 example, or if you had a physical security token that generated
1480 responses to authentication challenges.
1482 With this switch enabled, PuTTY will attempt these forms of
1483 authentication if the server is willing to try them. You will be
1484 presented with a challenge string (which will be different every
1485 time) and must supply the correct response in order to log in. If
1486 your server supports this, you should talk to your system
1487 administrator about precisely what form these challenges and
1490 \S{config-ssh-ki} \q{Attempt keyboard-interactive authentication}
1492 \cfg{winhelp-topic}{ssh.auth.ki}
1494 The SSH 2 equivalent of TIS authentication is called
1495 \q{keyboard-interactive}. It is a flexible authentication method
1496 using an arbitrary sequence of requests and responses; so it is not
1497 only useful for challenge/response mechanisms such as S/Key, but it
1498 can also be used for (for example) asking the user for a new
1499 password when the old one has expired.
1501 PuTTY leaves this option enabled by default, but supplies a switch
1502 to turn it off in case you should have trouble with it.
1504 \S{config-ssh-agentfwd} \q{Allow agent forwarding}
1506 \cfg{winhelp-topic}{ssh.auth.agentfwd}
1508 This option allows the SSH server to open forwarded connections back
1509 to your local copy of Pageant. If you are not running Pageant, this
1510 option will do nothing.
1512 See \k{pageant} for general information on Pageant, and
1513 \k{pageant-forward} for information on agent forwarding. Note that
1514 there is a security risk involved with enabling this option; see
1515 \k{pageant-security} for details.
1517 \S{config-ssh-changeuser} \q{Allow attempted changes of username in SSH2}
1519 \cfg{winhelp-topic}{ssh.auth.changeuser}
1521 In the SSH 1 protocol, it is impossible to change username after
1522 failing to authenticate. So if you mis-type your username at the
1523 PuTTY \q{login as:} prompt, you will not be able to change it except
1524 by restarting PuTTY.
1526 The SSH 2 protocol \e{does} allow changes of username, in principle,
1527 but does not make it mandatory for SSH 2 servers to accept them. In
1528 particular, OpenSSH does not accept a change of username; once you
1529 have sent one username, it will reject attempts to try to
1530 authenticate as another user. (Depending on the version of OpenSSH,
1531 it may quietly return failure for all login attempts, or it may send
1534 For this reason, PuTTY will by default not prompt you for your
1535 username more than once, in case the server complains. If you know
1536 your server can cope with it, you can enable the \q{Allow attempted
1537 changes of username} option to modify PuTTY's behaviour.
1539 \S{config-ssh-privkey} \q{Private key file for authentication}
1541 \cfg{winhelp-topic}{ssh.auth.privkey}
1543 This box is where you enter the name of your private key file if you
1544 are using public key authentication. See \k{pubkey} for information
1545 about public key authentication in SSH.
1547 \H{config-ssh-tunnels} The Tunnels panel
1549 The Tunnels panel allows you to configure tunnelling of other
1550 connection types through an SSH connection.
1552 \S{config-ssh-x11} X11 forwarding
1554 \cfg{winhelp-topic}{ssh.tunnels.x11}
1556 If your server lets you run X Window System applications, X11
1557 forwarding allows you to securely give those applications access to
1558 a local X display on your PC.
1560 To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
1561 If your X display is not the primary display on your local machine
1562 (which it almost certainly will be unless you have deliberately
1563 arranged otherwise), you need to enter its location in the \q{X
1564 display location} box.
1566 See \k{using-x-forwarding} for more information about X11
1569 \S{config-ssh-portfwd} Port forwarding
1571 \cfg{winhelp-topic}{ssh.tunnels.portfwd}
1573 Port forwarding allows you to tunnel other types of network
1574 connection down an SSH session. See \k{using-port-forwarding} for a
1575 general discussion of port forwarding and how it works.
1577 The port forwarding section in the Tunnels panel shows a list of all
1578 the port forwardings that PuTTY will try to set up when it connects
1579 to the server. By default no port forwardings are set up, so this
1582 To add a port forwarding:
1584 \b Set one of the \q{Local} or \q{Remote} radio buttons, depending
1585 on whether you want to forward a local port to a remote destination
1586 (\q{Local}) or forward a remote port to a local destination
1589 \b Enter a source port number into the \q{Source port} box. For
1590 local forwardings, PuTTY will listen on this port of your PC. For
1591 remote forwardings, your SSH server will listen on this port of the
1592 remote machine. Note that most servers will not allow you to listen
1593 on port numbers less than 1024.
1595 \b Enter a hostname and port number separated by a colon, in the
1596 \q{Destination} box. Connections received on the source port will be
1597 directed to this destination. For example, to connect to a POP-3
1598 server, you might enter \c{popserver.example.com:110}.
1600 \b Click the \q{Add} button. Your forwarding details should appear
1603 To remove a port forwarding, simply select its details in the list
1604 box, and click the \q{Remove} button.
1606 \S{config-ssh-portfwd-localhost} Controlling the visibility of
1609 \cfg{winhelp-topic}{ssh.tunnels.portfwd.localhost}
1611 The source port for a forwarded connection usually does not accept
1612 connections from any machine except the SSH client or server machine
1613 itself (for local and remote forwardings respectively). There are
1614 controls in the Tunnels panel to change this:
1616 \b The \q{Local ports accept connections from other hosts} option
1617 allows you to set up local-to-remote port forwardings in such a way
1618 that machines other than your client PC can connect to the forwarded
1621 \b The \q{Remote ports do the same} option does the same thing for
1622 remote-to-local port forwardings (so that machines other than the
1623 SSH server machine can connect to the forwarded port.) Note that
1624 this feature is only available in the SSH 2 protocol, and not all
1625 SSH 2 servers support it (OpenSSH 3.0 does not, for example).
1627 \H{config-file} Storing configuration in a file
1629 PuTTY does not currently support storing its configuration in a file
1630 instead of the Registry. However, you can work around this with a
1631 couple of batch files.
1633 You will need a file called (say) \c{PUTTY.BAT} which imports the
1634 contents of a file into the Registry, then runs PuTTY, exports the
1635 contents of the Registry back into the file, and deletes the
1636 Registry entries. This can all be done using the Regedit command
1637 line options, so it's all automatic. Here is what you need in
1641 \c regedit /s putty.reg
1642 \c regedit /s puttyrnd.reg
1643 \c start /w putty.exe
1644 \c regedit /e puttynew.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
1645 \c copy puttynew.reg putty.reg
1647 \c regedit /s puttydel.reg
1649 This batch file needs two auxiliary files: \c{PUTTYRND.REG} which
1650 sets up an initial safe location for the \c{PUTTY.RND} random seed
1651 file, and \c{PUTTYDEL.REG} which destroys everything in the Registry
1652 once it's been successfully saved back to the file.
1654 Here is \c{PUTTYDEL.REG}:
1658 \c [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
1660 Here is an example \c{PUTTYRND.REG} file:
1664 \c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
1665 \c "RandSeedFile"="a:\putty.rnd"
1667 You should replace \c{a:\\putty.rnd} with the location where you
1668 want to store your random number data. If the aim is to carry around
1669 PuTTY and its settings on one floppy, you probably want to store it