Fix Makefile dependencies.
[u/mdw/putty] / doc / config.but
CommitLineData
c0d36a72 1\versionid $Id: config.but,v 1.28 2002/03/09 11:47:39 simon Exp $
8f1529bc 2
e5b0d077 3\C{config} Configuring PuTTY
4
55ba634a 5This chapter describes all the configuration options in PuTTY.
6
7PuTTY is configured using the control panel that comes up before you
8start a session. Some options can also be changed in the middle of a
d60c975d 9session, by selecting \q{Change Settings} from the window menu.
55ba634a 10
11\H{config-session} The Session panel
12
13The Session configuration panel contains the basic options you need
14to specify in order to open a session at all, and also allows you to
15save your settings to be reloaded later.
16
17\S{config-hostname} The host name section
18
70133c0e 19\cfg{winhelp-topic}{session.hostname}
20
55ba634a 21The top box on the Session panel, labelled \q{Specify your
22connection by host name}, contains the details that need to be
23filled in before PuTTY can open a session at all.
24
d60c975d 25\b The \q{Host Name} box is where you type the name, or the IP
55ba634a 26address, of the server you want to connect to.
27
d60c975d 28\b The \q{Protocol} radio buttons let you choose what type of
350ee898 29connection you want to make: a raw connection, a Telnet connection, an
add788fc 30rlogin connection or an SSH connection. (See \k{which-one} for a
31summary of the differences between SSH, Telnet and rlogin.)
55ba634a 32
d60c975d 33\b The \q{Port} box lets you specify which port number on the server
2f8d6d43 34to connect to. If you select Telnet, Rlogin, or SSH, this box will
35be filled in automatically to the usual value, and you will only
36need to change it if you have an unusual server. If you select Raw
37mode (see \k{using-rawprot}), you will almost certainly need to fill
38in the \q{Port} box.
55ba634a 39
40\S{config-saving} Loading and storing saved sessions
41
70133c0e 42\cfg{winhelp-topic}{session.saved}
43
55ba634a 44The next part of the Session configuration panel allows you to save
45your preferred PuTTY options so they will appear automatically the
46next time you start PuTTY. It also allows you to create \e{saved
47sessions}, which contain a full set of configuration options plus a
48host name and protocol. A saved session contains all the information
49PuTTY needs to start exactly the session you want.
50
51\b To save your default settings: first set up the settings the way
52you 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
d60c975d 54click. Then press the \q{Save} button.
55ba634a 55
e0cff44d 56Note that PuTTY does not allow you to save a host name into the
57Default Settings entry. This ensures that when PuTTY is started up,
58the host name box is always empty, so a user can always just type in
59a host name and connect.
60
61If there is a specific host you want to store the details of how to
62connect to, you should create a saved session, which will be
63separate from the Default Settings.
64
55ba634a 65\b To save a session: first go through the rest of the configuration
66box setting up all the options you want. Then come back to the
d60c975d 67Session panel. Enter a name for the saved session in the \q{Saved
55ba634a 68Sessions} input box. (The server name is often a good choice for a
d60c975d 69saved session name.) Then press the \q{Save} button. Your saved
55ba634a 70session name should now appear in the list box.
71
72\b To reload a saved session: single-click to select the session
d60c975d 73name in the list box, and then press the \q{Load} button. Your saved
55ba634a 74settings should all appear in the configuration panel.
75
76\b To modify a saved session: first load it as described above. Then
77make the changes you want. Come back to the Session panel,
78single-click to select the session name in the list box, and press
d60c975d 79the \q{Save} button. The new settings will be saved over the top of
55ba634a 80the old ones.
81
82\b To start a saved session immediately: double-click on the session
83name in the list box.
84
85\b To delete a saved session: single-click to select the session
d60c975d 86name in the list box, and then press the \q{Delete} button.
55ba634a 87
88Each saved session is independent of the Default Settings
89configuration. If you change your preferences and update Default
90Settings, you must also update every saved session separately.
91
92\S{config-closeonexit} \q{Close Window on Exit}
93
70133c0e 94\cfg{winhelp-topic}{session.coe}
95
add788fc 96Finally in the Session panel, there is an option labelled \q{Close
97Window on Exit}. This controls whether the PuTTY session window
98disappears as soon as the session inside it terminates. If you are
99likely to want to copy and paste text out of the session after it
100has terminated, you should arrange this option to be off.
101
102\q{Close Window On Exit} has three settings. \q{Always} means always
103close the window on exit; \q{Never} means never close on exit
104(always leave the window open). The third setting, and the default
105one, is \q{Only on clean exit}. In this mode, a session which
106terminates normally will cause its window to close, but one which is
107aborted unexpectedly by network trouble or a confusing message from
108the server will leave the window up.
109
110\H{config-logging} The Logging panel
111
70133c0e 112\cfg{winhelp-topic}{logging.main}
113
add788fc 114The Logging configuration panel allows you to save log files of your
115PuTTY sessions, for debugging, analysis or future reference.
116
117The main option is a radio-button set that specifies whether PuTTY
118will log anything at all. The options are
119
120\b \q{Logging turned off completely}. This is the default option; in
121this mode PuTTY will not create a log file at all.
122
123\b \q{Log printable output only}. In this mode, a log file will be
124created and written to, but only printable text will be saved into
125it. The various terminal control codes that are typically sent down
126an interactive session alongside the printable text will be omitted.
127This might be a useful mode if you want to read a log file in a text
128editor and hope to be able to make sense of it.
129
130\b \q{Log all session output}. In this mode, \e{everything} sent by
131the server into your terminal session is logged. If you view the log
132file in a text editor, therefore, you may well find it full of
133strange control characters. This is a particularly useful mode if
134you are experiencing problems with PuTTY's terminal handling: you
135can record everything that went to the terminal, so that someone
136else can replay the session later in slow motion and watch to see
137what went wrong.
138
00db133f 139\b \q{Log SSH packet data}. In this mode (which is only used by SSH
140connections), the SSH message packets sent over the encrypted
141connection are written to the log file. You might need this to debug
142a network-level problem, or more likely to send to the PuTTY authors
143as part of a bug report. \e{BE WARNED} that if you log in using a
144password, the password will appear in the log file, so be sure to
145edit it out before sending the log file to anyone else!
146
add788fc 147\S{config-logfilename} \q{Log file name}
148
70133c0e 149\cfg{winhelp-topic}{logging.filename}
150
add788fc 151In this edit box you enter the name of the file you want to log the
152session to. The \q{Browse} button will let you look around your file
153system to find the right place to put the file; or if you already
154know exactly where you want it to go, you can just type a pathname
155into the edit box.
156
157There are a few special features in this box. If you use the \c{&}
158character in the file name box, PuTTY will insert details of the
159current session in the name of the file it actually opens. The
160precise replacements it will do are:
161
162\b \c{&Y} will be replaced by the current year, as four digits.
163
164\b \c{&M} will be replaced by the current month, as two digits.
165
166\b \c{&D} will be replaced by the current day of the month, as two
167digits.
168
169\b \c{&T} will be replaced by the current time, as six digits
170(HHMMSS) with no punctuation.
171
172\b \c{&H} will be replaced by the host name you are connecting to.
173
174For 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
176like
177
178\c log-server1.example.com-20010528-110859.dat
179\c log-unixbox.somewhere.org-20010611-221001.dat
180
181\S{config-logfileexists} \q{What to do if the log file already exists}
182
70133c0e 183\cfg{winhelp-topic}{logging.exists}
184
add788fc 185This control allows you to specify what PuTTY should do if it tries
186to start writing to a log file and it finds the file already exists.
187You might want to automatically destroy the existing log file and
188start a new one with the same name. Alternatively, you might want to
189open the existing log file and add data to the \e{end} of it.
190Finally (the default option), you might not want to have any
191automatic behaviour, but to ask the user every time the problem
192comes up.
55ba634a 193
194\H{config-terminal} The Terminal panel
195
196The Terminal configuration panel allows you to control the behaviour
197of PuTTY's terminal emulation.
198
199\S{config-autowrap} \q{Auto wrap mode initially on}
200
70133c0e 201\cfg{winhelp-topic}{terminal.autowrap}
202
55ba634a 203Auto wrap mode controls what happens when text printed in a PuTTY
204window reaches the right-hand edge of the window.
205
206With auto wrap mode on, if a long line of text reaches the
207right-hand edge, it will wrap over on to the next line so you can
208still see all the text. With auto wrap mode off, the cursor will
209stay at the right-hand edge of the screen, and all the characters in
210the line will be printed on top of each other.
211
212If you are running a full-screen application and you occasionally
213find the screen scrolling up when it looks as if it shouldn't, you
214could try turning this option off.
215
216Auto wrap mode can be turned on and off by control sequences sent by
217the server. This configuration option only controls the \e{default}
d60c975d 218state. If you modify this option in mid-session using \q{Change
2f8d6d43 219Settings}, you will need to reset the terminal (see
220\k{reset-terminal}) before the change takes effect.
55ba634a 221
222\S{config-decom} \q{DEC Origin Mode initially on}
223
70133c0e 224\cfg{winhelp-topic}{terminal.decom}
225
55ba634a 226DEC Origin Mode is a minor option which controls how PuTTY
227interprets cursor-position control sequences sent by the server.
228
229The server can send a control sequence that restricts the scrolling
230region of the display. For example, in an editor, the server might
231reserve a line at the top of the screen and a line at the bottom,
232and might send a control sequence that causes scrolling operations
233to affect only the remaining lines.
234
235With DEC Origin Mode on, cursor coordinates are counted from the top
236of the scrolling region. With it turned off, cursor coordinates are
237counted from the top of the whole screen regardless of the scrolling
238region.
239
240It is unlikely you would need to change this option, but if you find
241a full-screen application is displaying pieces of text in what looks
242like the wrong part of the screen, you could try turning DEC Origin
243Mode on to see whether that helps.
244
2f8d6d43 245DEC Origin Mode can be turned on and off by control sequences sent
246by 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.
55ba634a 250
251\S{config-crlf} \q{Implicit CR in every LF}
252
70133c0e 253\cfg{winhelp-topic}{terminal.lfhascr}
254
55ba634a 255Most servers send two control characters, CR and LF, to start a new
256line of the screen. The CR character makes the cursor return to the
257left-hand side of the screen. The LF character makes the cursor move
258one line down (and might make the screen scroll).
259
260Some servers only send LF, and expect the terminal to move the
261cursor over to the left automatically. If you come across a server
262that does this, you will see a stepped effect on the screen, like
263this:
264
265\c First line of text
266\c Second line
267\c Third line
268
269If this happens to you, try enabling the \q{Implicit CR in every LF}
270option, and things might go back to normal:
271
272\c First line of text
273\c Second line
274\c Third line
275
55ba634a 276\S{config-erase} \q{Use background colour to erase screen}
277
70133c0e 278\cfg{winhelp-topic}{terminal.bce}
279
55ba634a 280Not all terminals agree on what colour to turn the screen when the
281server sends a \q{clear screen} sequence. Some terminals believe the
282screen should always be cleared to the \e{default} background
283colour. Others believe the screen should be cleared to whatever the
284server has selected as a background colour.
285
286There exist applications that expect both kinds of behaviour.
287Therefore, PuTTY can be configured to do either.
288
289With this option disabled, screen clearing is always done in the
290default background colour. With this option enabled, it is done in
291the \e{current} background colour.
292
2f8d6d43 293Background-colour erase can be turned on and off by control
294sequences sent by the server. This configuration option only
295controls the \e{default} state. If you modify this option in
296mid-session using \q{Change Settings}, you will need to reset the
297terminal (see \k{reset-terminal}) before the change takes effect.
298
55ba634a 299\S{config-blink} \q{Enable blinking text}
300
70133c0e 301\cfg{winhelp-topic}{terminal.blink}
302
55ba634a 303The server can ask PuTTY to display text that blinks on and off.
304This is very distracting, so PuTTY allows you to turn blinking text
305off completely.
306
2f8d6d43 307When blinking text is disabled and the server attempts to make some
308text blink, PuTTY will instead display the text with a bolded
309background colour.
310
311Blinking text can be turned on and off by control sequences sent by
312the server. This configuration option only controls the \e{default}
313state. If you modify this option in mid-session using \q{Change
314Settings}, you will need to reset the terminal (see
315\k{reset-terminal}) before the change takes effect.
316
a5a6cb30 317\S{config-answerback} \q{Answerback to ^E}
318
70133c0e 319\cfg{winhelp-topic}{terminal.answerback}
320
a5a6cb30 321This option controls what PuTTY will send back to the server if the
322server sends it the ^E enquiry character. Normally it just sends
323the string \q{PuTTY}.
324
2f8d6d43 325If you accidentally write the contents of a binary file to your
326terminal, you will probably find that it contains more than one ^E
327character, and as a result your next command line will probably read
328\q{PuTTYPuTTYPuTTY...} as if you had typed the answerback string
329multiple times at the keyboard. If you set the answerback string to
330be empty, this problem should go away, but doing so might cause
331other problems.
332
fa5d6e5e 333Note that this is \e{not} the feature of PuTTY which the server will
334typically 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.
337
add788fc 338\S{config-localecho} \q{Local echo}
55ba634a 339
70133c0e 340\cfg{winhelp-topic}{terminal.localecho}
341
add788fc 342With local echo disabled, characters you type into the PuTTY window
343are not echoed in the window \e{by PuTTY}. They are simply sent to
344the server. (The \e{server} might choose to echo them back to you;
345this can't be controlled from the PuTTY control panel.)
55ba634a 346
add788fc 347Some types of session need local echo, and many do not. In its
348default mode, PuTTY will automatically attempt to deduce whether or
349not local echo is appropriate for the session you are working in. If
350you find it has made the wrong decision, you can use this
351configuration option to override its choice: you can force local
352echo to be turned on, or force it to be turned off, instead of
353relying on the automatic detection.
55ba634a 354
add788fc 355\S{config-localedit} \q{Local line editing}
55ba634a 356
70133c0e 357\cfg{winhelp-topic}{terminal.localedit}
358
add788fc 359Normally, every character you type into the PuTTY window is sent
360immediately to the server the moment you type it.
361
362If you enable local line editing, this changes. PuTTY will let you
363edit a whole line at a time locally, and the line will only be sent
364to the server when you press Return. If you make a mistake, you can
365use the Backspace key to correct it before you press Return, and the
366server will never see the mistake.
367
368Since it is hard to edit a line locally without being able to see
369it, 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
372advanced MUDs do occasionally turn local line editing on and turn
373local echo off, in order to accept a password from the user.)
374
375Some types of session need local line editing, and many do not. In
376its default mode, PuTTY will automatically attempt to deduce whether
377or not local line editing is appropriate for the session you are
378working in. If you find it has made the wrong decision, you can use
379this configuration option to override its choice: you can force
380local line editing to be turned on, or force it to be turned off,
381instead of relying on the automatic detection.
55ba634a 382
55ba634a 383\H{config-keyboard} The Keyboard panel
384
1630bb61 385The Keyboard configuration panel allows you to control the behaviour
386of the keyboard in PuTTY.
387
55ba634a 388\S{config-backspace} Changing the action of the Backspace key
389
70133c0e 390\cfg{winhelp-topic}{keyboard.backspace}
391
1630bb61 392Some terminals believe that the Backspace key should send the same
393thing to the server as Control-H (ASCII code 8). Other terminals
394believe that the Backspace key should send ASCII code 127 (usually
395known as Control-?) so that it can be distinguished from Control-H.
396This option allows you to choose which code PuTTY generates when you
397press Backspace.
398
399If you are connecting to a Unix system, you will probably find that
400the Unix \c{stty} command lets you configure which the server
401expects to see, so you might not need to change which one PuTTY
402generates. On other systems, the server's expectation might be fixed
403and you might have no choice but to configure PuTTY.
404
405If you do have the choice, we recommend configuring PuTTY to
406generate Control-? and configuring the server to expect it, because
407that allows applications such as \c{emacs} to use Control-H for
408help.
409
55ba634a 410\S{config-homeend} Changing the action of the Home and End keys
411
70133c0e 412\cfg{winhelp-topic}{keyboard.homeend}
413
1630bb61 414The Unix terminal emulator \c{rxvt} disagrees with the rest of the
415world about what character sequences should be sent to the server by
416the Home and End keys.
417
418\c{xterm}, and other terminals, send \c{ESC [1~} for the Home key,
419and \c{ESC [4~} for the End key. \c{rxvt} sends \c{ESC [H} for the
420Home key and \c{ESC [Ow} for the End key.
421
422If you find an application on which the Home and End keys aren't
423working, you could try switching this option to see if it helps.
424
55ba634a 425\S{config-funkeys} Changing the action of the function keys and keypad
426
70133c0e 427\cfg{winhelp-topic}{keyboard.funkeys}
428
1630bb61 429This option affects the function keys (F1 to F12) and the top row of
430the numeric keypad.
431
432\b In the default mode, labelled \c{ESC [n~}, the function keys
433generate sequences like \c{ESC [11~}, \c{ESC [12~} and so on. This
434matches the general behaviour of Digital's terminals.
435
436\b In Linux mode, F6 to F12 behave just like the default mode, but
437F1 to F5 generate \c{ESC [[A} through to \c{ESC [[E}. This mimics the
438Linux virtual console.
439
440\b In Xterm R6 mode, F5 to F12 behave like the default mode, but F1
441to F4 generate \c{ESC OP} through to \c{ESC OS}, which are the
442sequences produced by the top row of the \e{keypad} on Digital's
443terminals.
444
445\b In VT400 mode, all the function keys behave like the default
446mode, but the actual top row of the numeric keypad generates \c{ESC
447OP} through to \c{ESC OS}.
448
350ee898 449\b In VT100+ mode, the function keys generate \c{ESC OP} through to
450\c{ESC O[}
451
452\b In SCO mode, the function keys F1 to F12 generate \c{ESC [M}
453through to \c{ESC [X}. Together with shift, they generate \c{ESC [Y}
454through to \c{ESC [j}. With control they generate \c{ESC [k} through
455to \c{ESC [v}, and with shift and control together they generate
456\c{ESC [w} through to \c{ESC [\{}.
457
1630bb61 458If you don't know what any of this means, you probably don't need to
459fiddle with it.
460
55ba634a 461\S{config-appcursor} Controlling Application Cursor Keys mode
462
70133c0e 463\cfg{winhelp-topic}{keyboard.appcursor}
464
1630bb61 465Application Cursor Keys mode is a way for the server to change the
466control sequences sent by the arrow keys. In normal mode, the arrow
467keys send \c{ESC [A} through to \c{ESC [D}. In application mode,
468they send \c{ESC OA} through to \c{ESC OD}.
469
470Application Cursor Keys mode can be turned on and off by the server,
471depending on the application. PuTTY allows you to configure the
0d2086c5 472initial state.
473
474You can also disable application cursor keys mode completely, using
475the \q{Features} configuration panel; see
476\k{config-features-application}.
1630bb61 477
55ba634a 478\S{config-appkeypad} Controlling Application Keypad mode
479
70133c0e 480\cfg{winhelp-topic}{keyboard.appkeypad}
481
1630bb61 482Application Keypad mode is a way for the server to change the
483behaviour of the numeric keypad.
484
485In normal mode, the keypad behaves like a normal Windows keypad:
486with NumLock on, the number keys generate numbers, and with NumLock
487off they act like the arrow keys and Home, End etc.
488
489In application mode, all the keypad keys send special control
490sequences, \e{including} Num Lock. Num Lock stops behaving like Num
491Lock and becomes another function key.
492
493Depending on which version of Windows you run, you may find the Num
494Lock light still flashes on and off every time you press Num Lock,
495even when application mode is active and Num Lock is acting like a
496function key. This is unavoidable.
497
498Application keypad mode can be turned on and off by the server,
499depending on the application. PuTTY allows you to configure the
0d2086c5 500initial state.
501
502You can also disable application keypad mode completely, using the
503\q{Features} configuration panel; see
504\k{config-features-application}.
1630bb61 505
55ba634a 506\S{config-nethack} Using NetHack keypad mode
507
70133c0e 508\cfg{winhelp-topic}{keyboard.nethack}
509
1630bb61 510PuTTY has a special mode for playing NetHack. You can enable it by
511selecting \q{NetHack} in the \q{Initial state of numeric keypad}
512control.
513
514In this mode, the numeric keypad keys 1-9 generate the NetHack
515movement commands (\cw{hjklyubn}). The 5 key generates the \c{.}
516command (do nothing).
517
518Better still, pressing Shift with the keypad keys generates the
519capital forms of the commands (\cw{HJKLYUBN}), which tells NetHack
520to keep moving you in the same direction until you encounter
521something interesting.
522
523For some reason, this feature only works properly when Num Lock is
524on. We don't know why.
525
55ba634a 526\S{config-compose} Enabling a DEC-like Compose key
527
70133c0e 528\cfg{winhelp-topic}{keyboard.compose}
529
1630bb61 530DEC terminals have a Compose key, which provides an easy-to-remember
531way of typing accented characters. You press Compose and then type
532two more characters. The two characters are \q{combined} to produce
533an accented character. The choices of character are designed to be
534easy to remember; for example, composing \q{e} and \q{`} produces
535the \q{\u00e8{e-grave}} character.
536
537If you enable the \q{Application and AltGr act as Compose key}
538option, the Windows Application key and the AltGr key will both have
539this behaviour.
540
add788fc 541\S{config-ctrlalt} \q{Control-Alt is different from AltGr}
b5752f1b 542
70133c0e 543\cfg{winhelp-topic}{keyboard.ctrlalt}
544
add788fc 545Some old keyboards do not have an AltGr key, which can make it
546difficult to type some characters. PuTTY can be configured to treat
547the key combination Ctrl + Left Alt the same way as the AltGr key.
b5752f1b 548
add788fc 549By default, this checkbox is checked, and the key combination Ctrl +
550Left Alt does something completely different. PuTTY's usual handling
551of the left Alt key is to prefix the Escape (Control-\cw{[})
552character to whatever character sequence the rest of the keypress
553would generate. For example, Alt-A generates Escape followed by
554\c{a}. So Alt-Ctrl-A would generate Escape, followed by Control-A.
b5752f1b 555
add788fc 556If you uncheck this box, Ctrl-Alt will become a synonym for AltGr,
557so you can use it to type extra graphic characters if your keyboard
558has any.
b5752f1b 559
a5a6cb30 560\H{config-bell} The Bell panel
561
562The Bell panel controls the terminal bell feature: the server's
563ability to cause PuTTY to beep at you.
564
565In the default configuration, when the server sends the character
566with ASCII code 7 (Control-G), PuTTY will play the Windows Default
567Beep sound. This is not always what you want the terminal bell
568feature to do; the Bell panel allows you to configure alternative
569actions.
570
571\S{config-bellstyle} \q{Set the style of bell}
572
70133c0e 573\cfg{winhelp-topic}{bell.style}
574
a5a6cb30 575This control allows you to select various different actions to occur
576on a terminal bell:
577
578\b Selecting \q{None} disables the bell completely. In this mode,
579the server can send as many Control-G characters as it likes and
580nothing at all will happen.
581
582\b \q{Play Windows Default Sound} is the default setting. It causes
583the Windows \q{Default Beep} sound to be played. To change what this
584sound is, or to test it if nothing seems to be happening, use the
585Sound configurer in the Windows Control Panel.
586
587\b \q{Play a custom sound file} allows you to specify a particular
588sound file to be used by PuTTY alone, or even by a particular
589individual PuTTY session. This allows you to distinguish your PuTTY
590beeps from any other beeps on the system. If you select this option,
591you will also need to enter the name of your sound file in the edit
592control \q{Custom sound file to play as a bell}.
593
594\b \q{Visual bell} is a silent alternative to a beeping computer. In
595this mode, when the server sends a Control-G, the whole PuTTY window
596will flash white for a fraction of a second.
597
598\S{config-belltaskbar} \q{Taskbar/caption indication on bell}
599
70133c0e 600\cfg{winhelp-topic}{bell.taskbar}
601
a5a6cb30 602This feature controls what happens to the PuTTY window's entry in
603the Windows Taskbar if a bell occurs while the window does not have
604the input focus.
605
606In the default state (\q{Disabled}) nothing unusual happens.
607
608If you select \q{Steady}, then when a bell occurs and the window is
609not in focus, the window's Taskbar entry and its title bar will
610change colour to let you know that PuTTY session is asking for your
611attention. The change of colour will persist until you select the
612window, so you can leave several PuTTY windows minimised in your
613terminal, go away from your keyboard, and be sure not to have missed
614any important beeps when you get back.
615
616\q{Flashing} is even more eye-catching: the Taskbar entry will
617continuously flash on and off until you select the window.
618
619\S{config-bellovl} \q{Control the bell overload behaviour}
620
70133c0e 621\cfg{winhelp-topic}{bell.overload}
622
a5a6cb30 623A common user error in a terminal session is to accidentally run the
624Unix command \c{cat} (or equivalent) on an inappropriate file type,
625such as an executable, image file, or ZIP file. This produces a huge
626stream of non-text characters sent to the terminal, which typically
627includes a lot of bell characters. As a result of this the terminal
628often doesn't stop beeping for ten minutes, and everybody else in
629the office gets annoyed.
630
631To try to avoid this behaviour, or any other cause of excessive
632beeping, PuTTY includes a bell overload management feature. In the
633default configuration, receiving more than five bell characters in a
634two-second period will cause the overload feature to activate. Once
635the overload feature is active, further bells will have no effect at
636all, so the rest of your binary file will be sent to the screen in
637silence. After a period of five seconds during which no further
638bells are received, the overload feature will turn itself off again
639and bells will be re-enabled.
640
641If you want this feature completely disabled, you can turn it off
642using the checkbox \q{Bell is temporarily disabled when over-used}.
643
644Alternatively, if you like the bell overload feature but don't agree
645with the settings, you can configure the details: how many bells
646constitute an overload, how short a time period they have to arrive
647in to do so, and how much silent time is required before the
648overload feature will deactivate itself.
649
0d2086c5 650\H{config-features} The Features panel
651
652PuTTY's terminal emulation is very highly featured, and can do a lot
653of things under remote server control. Some of these features can
654cause problems due to buggy or strangely configured server
655applications.
656
657The Features configuration panel allows you to disable some of
658PuTTY's more advanced terminal features, in case they cause trouble.
659
660\S{config-features-application} Disabling application keypad and cursor keys
661
662\cfg{winhelp-topic}{features.application}
663
664Application keypad mode (see \k{config-appkeypad}) and application
665cursor keys mode (see \k{config-appcursor}) alter the behaviour of
666the keypad and cursor keys. Some applications enable these modes but
667then do not deal correctly with the modified keys. You can force
668these modes to be permanently disabled no matter what the server
669tries to do.
670
c0d36a72 671\S{config-features-mouse} Disabling \cw{xterm}-style mouse reporting
672
673\cfg{winhelp-topic}{features.mouse}
674
675PuTTY allows the server to send control codes that let it take over
676the mouse and use it for purposes other than copy and paste.
677Applications which use this feature include the text-mode web
678browser \c{links}, the Usenet newsreader \c{trn} version 4, and the
679file manager \c{mc} (Midnight Commander).
680
681If you find this feature inconvenient, you can disable it using the
682\q{Disable xterm-style mouse reporting} control. With this box
683ticked, the mouse will \e{always} do copy and paste in the normal
684way.
685
686Note that even if the application takes over the mouse, you can
687still manage PuTTY's copy and paste by holding down the Shift key
688while you select and paste, unless you have deliberately turned this
689feature off (see \k{config-mouseshift}).
690
0d2086c5 691\S{config-features-resize} Disabling remote terminal resizing
692
693\cfg{winhelp-topic}{features.resize}
694
695PuTTY has the ability to change the terminal's size and position in
696response to commands from the server. If you find PuTTY is doing
697this unexpectedly or inconveniently, you can tell PuTTY not to
698respond to those server commands.
699
700\S{config-features-altscreen} Disabling switching to the alternate screen
701
702\cfg{winhelp-topic}{features.altscreen}
703
704Many terminals, including PuTTY, support an \q{alternate screen}.
705This is the same size as the ordinary terminal screen, but separate.
706Typically a screen-based program such as a text editor might switch
707the terminal to the alternate screen before starting up. Then at the
708end of the run, it switches back to the primary screen, and you see
709the screen contents just as they were before starting the editor.
710
711Some people prefer this not to happen. If you want your editor to
712run in the same screen as the rest of your terminal activity, you
713can disable the alternate screen feature completely.
714
715\S{config-features-retitle} Disabling remote window title changing
716
717\cfg{winhelp-topic}{features.retitle}
718
719PuTTY has the ability to change the window title in response to
720commands from the server. If you find PuTTY is doing this
721unexpectedly or inconveniently, you can tell PuTTY not to respond to
722those server commands.
723
724\S{config-features-dbackspace} Disabling destructive backspace
725
726\cfg{winhelp-topic}{features.dbackspace}
727
728Normally, when PuTTY receives character 127 (^?) from the server, it
729will perform a \q{destructive backspace}: move the cursor one space
730left and delete the character under it. This can apparently cause
731problems in some applications, so PuTTY provides the ability to
732configure character 127 to perform a normal backspace (without
733deleting a character) instead.
734
735\S{config-features-charset} Disabling remote character set
736configuration
737
738\cfg{winhelp-topic}{features.charset}
739
740PuTTY has the ability to change its character set configuration in
741response to commands from the server. Some programs send these
742commands unexpectedly or inconveniently. In particular, BitchX (an
743IRC client) seems to have a habit of reconfiguring the character set
744to something other than the user intended.
745
746If you find that accented characters are not showing up the way you
747expect them to, particularly if you're running BitchX, you could try
748disabling the remote character set configuration commands.
749
55ba634a 750\H{config-window} The Window panel
751
1630bb61 752The Window configuration panel allows you to control aspects of the
a5a6cb30 753PuTTY window.
1630bb61 754
55ba634a 755\S{config-winsize} Setting the size of the PuTTY window
756
70133c0e 757\cfg{winhelp-topic}{window.size}
758
d60c975d 759The \q{Rows} and \q{Columns} boxes let you set the PuTTY window to a
1630bb61 760precise size. Of course you can also drag the window to a new size
761while a session is running.
762
a5a6cb30 763\S{config-winsizelock} What to do when the window is resized
add788fc 764
70133c0e 765\cfg{winhelp-topic}{window.resize}
766
add788fc 767These options allow you to control what happens when the user tries
768to resize the PuTTY window.
769
a5a6cb30 770When you resize the PuTTY window, one of four things can happen:
add788fc 771
772\b Nothing (if you have completely disabled resizes).
773
774\b The font size can stay the same and the number of rows and
775columns in the terminal can change.
776
777\b The number of rows and columns in the terminal can stay the same,
778and the font size can change.
779
a5a6cb30 780\b You can allow PuTTY to change \e{either} the terminal size or the
781font size. In this mode it will change the terminal size most of the
782time, but enlarge the font when you maximise the window.
783
add788fc 784You can control which of these happens using the \q{Lock terminal
785size against resizing} and \q{Lock font size against resizing}
786options. If you lock both, the window will refuse to be resized at
787all. If you lock just the terminal size, the font size will change
788when you resize the window. If you lock just the font size, the
789terminal size will change when you resize the window.
1630bb61 790
55ba634a 791\S{config-scrollback} Controlling scrollback
792
70133c0e 793\cfg{winhelp-topic}{window.scrollback}
794
fc5a8711 795These options let you configure the way PuTTY keeps text after it
796scrolls off the top of the screen (see \k{using-scrollback}).
1630bb61 797
798The \q{Lines of scrollback} box lets you configure how many lines of
a5a6cb30 799text PuTTY keeps. The \q{Display scrollbar} options allow you to
1630bb61 800hide the scrollbar (although you can still view the scrollback using
a5a6cb30 801Shift-PgUp and Shift-PgDn). You can separately configure whether the
802scrollbar is shown in full-screen mode and in normal modes.
1630bb61 803
804If you are viewing part of the scrollback when the server sends more
805text to PuTTY, the screen will revert to showing the current
806terminal contents. You can disable this behaviour by turning off
807\q{Reset scrollback on display activity}. You can also make the
808screen revert when you press a key, by turning on \q{Reset
809scrollback on keypress}.
810
55ba634a 811\H{config-appearance} The Appearance panel
812
1630bb61 813The Appearance configuration panel allows you to control aspects of
a5a6cb30 814the appearance of PuTTY's window.
1630bb61 815
55ba634a 816\S{config-cursor} Controlling the appearance of the cursor
817
70133c0e 818\cfg{winhelp-topic}{appearance.cursor}
819
26c8f51a 820The \q{Cursor appearance} option lets you configure the cursor to be
821a block, an underline, or a vertical line. A block cursor becomes an
822empty box when the window loses focus; an underline or a vertical
823line becomes dotted.
824
825The \q{Cursor blinks} option makes the cursor blink on and off. This
826works in any of the cursor modes.
55ba634a 827
828\S{config-font} Controlling the font used in the terminal window
829
70133c0e 830\cfg{winhelp-topic}{appearance.font}
831
add788fc 832This option allows you to choose what font, in what size, the PuTTY
833terminal window uses to display the text in the session. You will be
834offered a choice from all the fixed-width fonts installed on the
835system. (VT100-style terminal handling can only deal with fixed-
836width fonts.)
26c8f51a 837
55ba634a 838\S{config-title} Controlling the window title
839
70133c0e 840\cfg{winhelp-topic}{appearance.title}
841
add788fc 842The \q{Window title} edit box allows you to set the title of the
843PuTTY window. By default the window title will contain the host name
844followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
845If you want a different window title, this is where to set it.
846
847PuTTY allows the server to send \c{xterm} control sequences which
848modify the title of the window in mid-session. There is also an
849\c{xterm} sequence to modify the title of the window's \e{icon}.
850This makes sense in a windowing system where the window becomes an
851icon when minimised, such as Windows 3.1 or most X Window System
852setups; but in the Windows 95-like user interface it isn't as
853applicable. By default PuTTY's window title and Taskbar caption will
854change into the server-supplied icon title if you minimise the PuTTY
855window, and change back to the server-supplied window title if you
856restore it. (If the server has not bothered to supply a window or
857icon title, none of this will happen.) By checking the box marked
858\q{Avoid ever using icon title}, you can arrange that PuTTY will
859always display the window title, and completely ignore any icon
860titles the server sends it.
861
862\S{config-mouseptr} \q{Hide mouse pointer when typing in window}
863
70133c0e 864\cfg{winhelp-topic}{appearance.hidemouse}
865
add788fc 866If you enable this option, the mouse pointer will disappear if the
867PuTTY window is selected and you press a key. This way, it will not
868obscure any of the text in the window while you work in your
869session. As soon as you move the mouse, the pointer will reappear.
870
871This option is disabled by default, so the mouse pointer remains
872visible at all times.
873
874\S{config-winborder} Controlling the window border
875
70133c0e 876\cfg{winhelp-topic}{appearance.border}
877
add788fc 878PuTTY allows you to configure the appearance of the window border to
879some extent.
880
881The checkbox marked \q{Sunken-edge border} changes the appearance of
882the window border to something more like a DOS box: the inside edge
883of the border is highlighted as if it sank down to meet the surface
884inside the window. This makes the border a little bit thicker as
885well. It's hard to describe well. Try it and see if you like it.
886
887You can also configure a completely blank gap between the text in
888the window and the border, using the \q{Gap between text and window
889edge} control. By default this is set at one pixel. You can reduce
890it to zero, or increase it further.
891
a5a6cb30 892\H{config-behaviour} The Behaviour panel
893
894The Behaviour configuration panel allows you to control aspects of
895the behaviour of PuTTY's window.
896
897\S{config-warnonclose} \q{Warn before closing window}
898
70133c0e 899\cfg{winhelp-topic}{behaviour.closewarn}
900
a5a6cb30 901If you press the Close button in a PuTTY window that contains a
902running session, PuTTY will put up a warning window asking if you
903really meant to close the window. A window whose session has already
904terminated can always be closed without a warning.
905
906If you want to be able to close a window quickly, you can disable
907the \q{Warn before closing window} option.
908
909\S{config-altf4} \q{Window closes on ALT-F4}
910
70133c0e 911\cfg{winhelp-topic}{behaviour.altf4}
912
a5a6cb30 913By default, pressing ALT-F4 causes the window to close (or a warning
914box to appear; see \k{config-warnonclose}). If you disable the
915\q{Window closes on ALT-F4} option, then pressing ALT-F4 will simply
916send a key sequence to the server.
917
918\S{config-altspace} \q{System menu appears on ALT-Space}
919
70133c0e 920\cfg{winhelp-topic}{behaviour.altspace}
921
a5a6cb30 922If this option is enabled, then pressing ALT-Space will bring up the
923PuTTY window's menu, like clicking on the top left corner. If it is
924disabled, then pressing ALT-Space will just send \c{ESC SPACE} to
925the server.
926
927Some accessibility programs for Windows may need this option
928enabling to be able to control PuTTY's window successfully. For
929instance, Dragon NaturallySpeaking requires it both to open the
930system menu via voice, and to close, minimise, maximise and restore
931the window.
932
933\S{config-altonly} \q{System menu appears on Alt alone}
934
70133c0e 935\cfg{winhelp-topic}{behaviour.altonly}
936
a5a6cb30 937If this option is enabled, then pressing and releasing ALT will
938bring up the PuTTY window's menu, like clicking on the top left
939corner. If it is disabled, then pressing and releasing ALT will have
940no effect.
941
942\S{config-alwaysontop} \q{Ensure window is always on top}
943
70133c0e 944\cfg{winhelp-topic}{behaviour.alwaysontop}
945
a5a6cb30 946If this option is enabled, the PuTTY window will stay on top of all
947other windows.
948
949\S{config-fullscreen} \q{Full screen on Alt-Enter}
950
70133c0e 951\cfg{winhelp-topic}{behaviour.altenter}
952
a5a6cb30 953If this option is enabled, then pressing Alt-Enter will cause the
2f8d6d43 954PuTTY window to become full-screen. Pressing Alt-Enter again will
955restore the previous window size.
956
957The full-screen feature is also available from the System menu, even
958when it is configured not to be available on the Alt-Enter key. See
959\k{using-fullscreen}.
a5a6cb30 960
55ba634a 961\H{config-translation} The Translation panel
962
1630bb61 963The Translation configuration panel allows you to control the
964translation between the character set understood by the server and
965the character set understood by PuTTY.
966
add788fc 967\S{config-charset} Controlling character set translation
968
70133c0e 969\cfg{winhelp-topic}{translation.codepage}
970
add788fc 971During an interactive session, PuTTY receives a stream of 8-bit
972bytes from the server, and in order to display them on the screen it
973needs to know what character set to interpret them in.
974
975There are a lot of character sets to choose from. The \q{Received
976data assumed to be in which character set} option lets you select
977one. By default PuTTY will attempt to choose a character set that is
978right for your locale as reported by Windows; if it gets it wrong,
979you can select a different one using this control.
980
981A few notable character sets are:
982
983\b The ISO-8859 series are all standard character sets that include
984various accented characters appropriate for different sets of
985languages.
55ba634a 986
add788fc 987\b The Win125x series are defined by Microsoft, for similar
988purposes. In particular Win1252 is almost equivalent to ISO-8859-1,
989but contains a few extra characters such as matched quotes and the
990Euro symbol.
55ba634a 991
add788fc 992\b If you want the old IBM PC character set with block graphics and
993line-drawing characters, you can select \q{CP437}.
994
995\b PuTTY also supports Unicode mode, in which the data coming from
996the server is interpreted as being in the UTF-8 encoding of Unicode.
997If you select \q{UTF-8} as a character set you can use this mode.
998Not all server-side applications will support it.
999
1000\S{config-cyr} \q{Caps Lock acts as Cyrillic switch}
1001
70133c0e 1002\cfg{winhelp-topic}{translation.cyrillic}
1003
add788fc 1004This feature allows you to switch between a US/UK keyboard layout
1005and a Cyrillic keyboard layout by using the Caps Lock key, if you
1006need to type (for example) Russian and English side by side in the
1007same document.
1008
1009Currently this feature is not expected to work properly if your
1010native keyboard layout is not US or UK.
1011
1012\S{config-linedraw} Controlling display of line drawing characters
1013
70133c0e 1014\cfg{winhelp-topic}{translation.linedraw}
1015
add788fc 1016VT100-series terminals allow the server to send control sequences
1017that shift temporarily into a separate character set for drawing
1018lines and boxes. PuTTY has a variety of ways to support this
1019capability. In general you should probably try lots of options until
1020you find one that your particular font supports.
1021
1022\b \q{Font has XWindows encoding} is for use with fonts that have a
1023special encoding, where the lowest 32 character positions (below the
1024ASCII printable range) contain the line-drawing characters. This is
1025unlikely to be the case with any standard Windows font; it will
1026probably only apply to custom-built fonts or fonts that have been
1027automatically converted from the X Window System.
1028
1029\b \q{Use font in both ANSI and OEM modes} tries to use the same
1030font in two different character sets, to obtain a wider range of
1031characters. This doesn't always work; some fonts claim to be a
1032different size depending on which character set you try to use.
1033
1034\b \q{Use font in OEM mode only} is more reliable than that, but can
1035miss out other characters from the main character set.
1036
1037\b \q{Poor man's line drawing} assumes that the font \e{cannot}
1038generate the line and box characters at all, so it will use the
1039\c{+}, \c{-} and \c{|} characters to draw approximations to boxes.
1040You should use this option if none of the other options works.
1041
1042\b \q{Unicode mode} tries to use the box characters that are present
1043in Unicode. For good Unicode-supporting fonts this is probably the
1044most reliable and functional option.
55ba634a 1045
1046\H{config-selection} The Selection panel
1047
1630bb61 1048The Selection panel allows you to control the way copy and paste
1049work in the PuTTY window.
1050
add788fc 1051\S{config-linedrawpaste} Controlling the pasting of line drawing
1052characters
1053
70133c0e 1054\cfg{winhelp-topic}{selection.linedraw}
1055
add788fc 1056By default, when you copy and paste a piece of the PuTTY screen that
1057contains VT100 line and box drawing characters, PuTTY will translate
1058them into the \q{poor man's} line-drawing characters \c{+}, \c{-}
1059and \c{|}. The checkbox \q{Don't translate line drawing chars}
1060disables this feature, so line-drawing characters will be pasted as
1061if they were in the normal character set. This will typically mean
1062they come out mostly as \c{q} and \c{x}, with a scattering of
1063\c{jklmntuvw} at the corners. This might be useful if you were
1064trying to recreate the same box layout in another program, for
1065example.
1066
a5a6cb30 1067\S{config-rtfpaste} Pasting in Rich Text Format
1068
70133c0e 1069\cfg{winhelp-topic}{selection.rtf}
1070
a5a6cb30 1071If you enable \q{Paste to clipboard in RTF as well as plain text},
1072PuTTY will write formatting information to the clipboard as well as
1073the actual text you copy. Currently the only effect of this will be
1074that if you paste into (say) a word processor, the text will appear
1075in the word processor in the same font PuTTY was using to display
1076it. In future it is likely that other formatting information (bold,
1077underline, colours) will be copied as well.
1078
1079This option can easily be inconvenient, so by default it is
1080disabled.
1081
55ba634a 1082\S{config-mouse} Changing the actions of the mouse buttons
1083
70133c0e 1084\cfg{winhelp-topic}{selection.buttons}
1085
add788fc 1086PuTTY's copy and paste mechanism is modelled on the Unix \c{xterm}
1087application. The X Window System uses a three-button mouse, and the
1088convention is that the left button selects, the right button extends
1089an existing selection, and the middle button pastes.
1090
1091Windows typically only has two mouse buttons, so in PuTTY's default
1092configuration, the \e{right} button pastes, and the \e{middle}
1093button (if you have one) extends a selection.
1094
1095If you have a three-button mouse and you are already used to the
1096\c{xterm} arrangement, you can select it using the \q{Action of
1097mouse buttons} control.
1098
1099\S{config-mouseshift} \q{Shift overrides application's use of mouse}
1100
70133c0e 1101\cfg{winhelp-topic}{selection.shiftdrag}
1102
add788fc 1103PuTTY allows the server to send control codes that let it take over
1104the mouse and use it for purposes other than copy and paste.
1105Applications which use this feature include the text-mode web
1106browser \c{links}, the Usenet newsreader \c{trn} version 4, and the
1107file manager \c{mc} (Midnight Commander).
1108
1109When running one of these applications, pressing the mouse buttons
1110no longer performs copy and paste. If you do need to copy and paste,
1111you can still do so if you hold down Shift while you do your mouse
1112clicks.
1113
1114However, it is possible in theory for applications to even detect
1115and make use of Shift + mouse clicks. We don't know of any
1116applications that do this, but in case someone ever writes one,
1117unchecking the \q{Shift overrides application's use of mouse}
1118checkbox will cause Shift + mouse clicks to go to the server as well
1119(so that mouse-driven copy and paste will be completely disabled).
1120
c0d36a72 1121If you want to prevent the application from taking over the mouse at
1122all, you can do this using the Features control panel; see
1123\k{config-features-mouse}.
1124
a5a6cb30 1125\S{config-rectselect} Default selection mode
1126
70133c0e 1127\cfg{winhelp-topic}{selection.rect}
1128
a5a6cb30 1129As described in \k{using-selection}, PuTTY has two modes of
1130selecting text to be copied to the clipboard. In the default mode
1131(\q{Normal}), dragging the mouse from point A to point B selects to
1132the end of the line containing A, all the lines in between, and from
1133the very beginning of the line containing B. In the other mode
1134(\q{Rectangular block}), dragging the mouse between two points
1135defines a rectangle, and everything within that rectangle is copied.
1136
1137Normally, you have to hold down Alt while dragging the mouse to
1138select a rectangular block. Using the \q{Default selection mode}
1139control, you can set rectangular selection as the default, and then
1140you have to hold down Alt to get the \e{normal} behaviour.
1141
55ba634a 1142\S{config-charclasses} Configuring word-by-word selection
1143
70133c0e 1144\cfg{winhelp-topic}{selection.charclasses}
1145
add788fc 1146PuTTY will select a word at a time in the terminal window if you
1147double-click to begin the drag. This panel allows you to control
1148precisely what is considered to be a word.
1149
1150Each character is given a \e{class}, which is a small number
1151(typically 0, 1 or 2). PuTTY considers a single word to be any
1152number of adjacent characters in the same class. So by modifying the
1153assignment of characters to classes, you can modify the word-by-word
1154selection behaviour.
1155
1156In the default configuration, the character classes are:
1157
1158\b Class 0 contains white space and control characters.
1159
1160\b Class 1 contains most punctuation.
1161
1162\b Class 2 contains letters, numbers and a few pieces of punctuation
1163(the double quote, minus sign, period, forward slash and
1164underscore).
1165
1166So, for example, if you assign the \c{@} symbol into character class
11672, you will be able to select an e-mail address with just a double
1168click.
1169
1170In order to adjust these assignments, you start by selecting a group
1171of characters in the list box. Then enter a class number in the edit
1172box below, and press the \q{Set} button.
1173
1174This mechanism currently only covers ASCII characters, because it
1175isn't feasible to expand the list to cover the whole of Unicode.
1176
7b74af11 1177Character class definitions can be modified by control sequences
1178sent by the server. This configuration option only controls the
1179\e{default} state. If you modify this option in mid-session using
1180\q{Change Settings}, you will need to reset the terminal (see
1181\k{reset-terminal}) before the change takes effect.
1182
55ba634a 1183\H{config-colours} The Colours panel
1184
1630bb61 1185The Colours panel allows you to control PuTTY's use of colour.
1186
55ba634a 1187\S{config-boldcolour} \q{Bolded text is a different colour}
1188
70133c0e 1189\cfg{winhelp-topic}{colours.bold}
1190
add788fc 1191When the server sends a control sequence indicating that some text
1192should be displayed in bold, PuTTY can handle this two ways. It can
1193either change the font for a bold version, or use the same font in a
1194brighter colour. This control lets you choose which.
1195
1196By default the box is checked, so non-bold text is displayed in
1197light grey and bold text is displayed in bright white (and similarly
1198in other colours). If you uncheck the box, bold and non-bold text
1199will be displayed in the same colour, and instead the font will
1200change to indicate the difference.
1201
55ba634a 1202\S{config-logpalette} \q{Attempt to use logical palettes}
1203
70133c0e 1204\cfg{winhelp-topic}{colours.logpal}
1205
add788fc 1206Logical palettes are a mechanism by which a Windows application
1207running on an 8-bit colour display can select precisely the colours
1208it wants instead of going with the Windows standard defaults.
1209
1210If you are not getting the colours you ask for on an 8-bit display,
1211you can try enabling this option. However, be warned that it's never
1212worked very well.
1213
55ba634a 1214\S{config-colourcfg} Adjusting the colours in the terminal window
1215
70133c0e 1216\cfg{winhelp-topic}{colours.config}
1217
add788fc 1218The main colour control allows you to specify exactly what colours
1219things should be displayed in. To modify one of the PuTTY colours,
1220use the list box to select which colour you want to modify. The RGB
1221values for that colour will appear on the right-hand side of the
1222list box. Now, if you press the \q{Modify} button, you will be
1223presented with a colour selector, in which you can choose a new
1224colour to go in place of the old one.
1225
1226PuTTY allows you to set the cursor colour, the default foreground
1227and background, and the precise shades of all the ANSI configurable
1228colours (black, red, green, yellow, blue, magenta, cyan, and white).
1229In addition, if you have selected \q{Bolded text is a different
1230colour}, you can also modify the precise shades used for the bold
1231versions of these colours.
1232
55ba634a 1233\H{config-connection} The Connection panel
1234
1630bb61 1235The Connection panel allows you to configure options that apply to
1236more than one type of connection.
1237
55ba634a 1238\S{config-termtype} \q{Terminal-type string}
1239
70133c0e 1240\cfg{winhelp-topic}{connection.termtype}
1241
add788fc 1242Most servers you might connect to with PuTTY are designed to be
1243connected to from lots of different types of terminal. In order to
1244send the right control sequences to each one, the server will need
1245to know what type of terminal it is dealing with. Therefore, each of
1246the SSH, Telnet and Rlogin protocols allow a text string to be sent
1247down the connection describing the terminal.
1248
1249PuTTY attempts to emulate the Unix \c{xterm} program, and by default
1250it reflects this by sending \c{xterm} as a terminal-type string. If
1251you find this is not doing what you want - perhaps the remote
1252terminal reports \q{Unknown terminal type} - you could try setting
1253this to something different, such as \c{vt220}.
1254
1255If you're not sure whether a problem is due to the terminal type
1256setting or not, you probably need to consult the manual for your
1257application or your server.
1258
55ba634a 1259\S{config-username} \q{Auto-login username}
1260
70133c0e 1261\cfg{winhelp-topic}{connection.username}
1262
add788fc 1263All three of the SSH, Telnet and Rlogin protocols allow you to
1264specify what user name you want to log in as, without having to type
1265it explicitly every time. (Some Telnet servers don't support this.)
1266
1267In this box you can type that user name.
1268
55ba634a 1269\S{config-keepalive} Using keepalives to prevent disconnection
1270
70133c0e 1271\cfg{winhelp-topic}{connection.keepalive}
1272
c33f3243 1273If you find your sessions are closing unexpectedly (\q{Connection
1274reset by peer}) after they have been idle for a while, you might
1275want to try using this option.
1276
add788fc 1277Some network routers and firewalls need to keep track of all
c33f3243 1278connections through them. Usually, these firewalls will assume a
1279connection is dead if no data is transferred in either direction
1280after a certain time interval. This can cause PuTTY sessions to be
1281unexpectedly closed by the firewall if no traffic is seen in the
1282session for some time.
1283
1284The keepalive option (\q{Seconds between keepalives}) allows you to
1285configure PuTTY to send data through the session at regular
1286intervals, in a way that does not disrupt the actual terminal
1287session. If you find your firewall is cutting idle connections off,
1288you can try entering a non-zero value in this field. The value is
1289measured in seconds; so, for example, if your firewall cuts
1290connections off after ten minutes then you might want to enter 300
1291seconds (5 minutes) in the box.
1292
1293Note that keepalives are not always helpful. They help if you have a
1294firewall which drops your connection after an idle period; but if
1295the network between you and the server suffers from breaks in
1296connectivity then keepalives can actually make things worse. If a
1297session is idle, and connectivity is temporarily lost between the
1298endpoints, but the connectivity is restored before either side tries
1299to send anything, then there will be no problem - neither endpoint
1300will notice that anything was wrong. However, if one side does send
1301something during the break, it will repeatedly try to re-send, and
1302eventually give up and abandon the connection. Then when
1303connectivity is restored, the other side will find that the first
1304side doesn't believe there is an open connection any more.
1305Keepalives can make this sort of problem worse, because they
1306increase the probability that PuTTY will attempt to send data during
1307a break in connectivity. Therefore, you might find they help
1308connection loss, or you might find they make it worse, depending on
1309what \e{kind} of network problems you have between you and the
1310server.
1311
1312Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
1313protocols offer no way of implementing them.
1314
81e8bb1b 1315\S{config-nodelay} \q{Disable Nagle's algorithm}
1316
70133c0e 1317\cfg{winhelp-topic}{connection.nodelay}
1318
81e8bb1b 1319Nagle's algorithm is a detail of TCP/IP implementations that tries
1320to minimise the number of small data packets sent down a network
1321connection. With Nagle's algorithm enabled, PuTTY's bandwidth usage
1322will be slightly more efficient; with it disabled, you may find you
1323get a faster response to your keystrokes when connecting to some
1324types of server.
1325
1326The Nagle algorithm is disabled by default.
1327
55ba634a 1328\H{config-telnet} The Telnet panel
1329
1630bb61 1330The Telnet panel allows you to configure options that only apply to
1331Telnet sessions.
1332
55ba634a 1333\S{config-termspeed} \q{Terminal-speed string}
1334
70133c0e 1335\cfg{winhelp-topic}{telnet.termspeed}
1336
add788fc 1337Telnet allows the client to send a text string that describes the
1338terminal speed. PuTTY lets you configure this, in case you find the
1339server is reacting badly to the default value. (I'm not aware of any
1340servers that do have a problem with it.)
1341
55ba634a 1342\S{config-environ} Setting environment variables on the server
1343
70133c0e 1344\cfg{winhelp-topic}{telnet.environ}
1345
add788fc 1346The Telnet protocol also provides a means for the client to pass
1347environment variables to the server. Many Telnet servers have
1348stopped supporting this feature due to security flaws, but PuTTY
1349still supports it for the benefit of any servers which have found
1350other ways around the security problems than just disabling the
1351whole mechanism.
1352
1353To add an environment variable to the list transmitted down the
1354connection, you enter the variable name in the \q{Variable} box,
1355enter its value in the \q{Value} box, and press the \q{Add} button.
1356To remove one from the list, select it in the list box and press
1357\q{Remove}.
1358
55ba634a 1359\S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
1360
70133c0e 1361\cfg{winhelp-topic}{telnet.oldenviron}
1362
add788fc 1363The original Telnet mechanism for passing environment variables was
1364badly specified. At the time the standard (RFC 1408) was written,
1365BSD telnet implementations were already supporting the feature, and
1366the intention of the standard was to describe the behaviour the BSD
1367implementations were already using.
1368
1369Sadly there was a typing error in the standard when it was issued,
1370and two vital function codes were specified the wrong way round. BSD
1371implementations did not change, and the standard was not corrected.
1372Therefore, it's possible you might find either BSD or RFC-compliant
1373implementations out there. This switch allows you to choose which
1374one PuTTY claims to be.
1375
1376The problem was solved by issuing a second standard, defining a new
1377Telnet mechanism called \cw{NEW_ENVIRON}, which behaved exactly like
1378the original \cw{OLD_ENVIRON} but was not encumbered by existing
1379implementations. Most Telnet servers now support this, and it's
1380unambiguous. This feature should only be needed if you have trouble
1381passing environment variables to quite an old server.
1382
1383\S{config-ptelnet} Passive and active Telnet negotiation modes
1384
70133c0e 1385\cfg{winhelp-topic}{telnet.passive}
1386
add788fc 1387In a Telnet connection, there are two types of data passed between
1388the client and the server: actual text, and \e{negotiations} about
1389which Telnet extra features to use.
1390
1391PuTTY can use two different strategies for negotiation:
1392
1393\b In \e{active} mode, PuTTY starts to send negotiations as soon as
1394the connection is opened.
1395
1396\b In \e{passive} mode, PuTTY will wait to negotiate until it sees a
1397negotiation from the server.
1398
1399The obvious disadvantage of passive mode is that if the server is
1400also operating in a passive mode, then negotiation will never begin
1401at all. For this reason PuTTY defaults to active mode.
1402
1403However, sometimes passive mode is required in order to successfully
1404get through certain types of firewall and Telnet proxy server. If
1405you have confusing trouble with a firewall, you could try enabling
1406passive mode to see if it helps.
1407
1408\S{config-telnetkey} \q{Keyboard sends telnet Backspace and Interrupt}
1409
70133c0e 1410\cfg{winhelp-topic}{telnet.specialkeys}
1411
add788fc 1412If this box is checked, the Backspace key on the keyboard will send
1413the Telnet special backspace code, and Control-C will send the
1414Telnet special interrupt code. You probably shouldn't enable this
1415unless you know what you're doing.
1416
e81b578d 1417\S{config-telnetnl} \q{Return key sends telnet New Line instead of ^M}
eee63b77 1418
1419\cfg{winhelp-topic}{telnet.newline}
1420
1421Unlike most other remote login protocols, the Telnet protocol has a
e81b578d 1422special \q{new line} code that is not the same as the usual line
eee63b77 1423endings of Control-M or Control-J. By default, PuTTY sends the
1424Telnet New Line code when you press Return, instead of sending
1425Control-M as it does in most other protocols.
1426
1427Most Unix-style Telnet servers don't mind whether they receive
1428Telnet New Line or Control-M; some servers do expect New Line, and
1429some servers prefer to see ^M. If you are seeing surprising
1430behaviour when you press Return in a Telnet session, you might try
1431turning this option off to see if it helps.
1432
add788fc 1433\H{config-rlogin} The Rlogin panel
1434
1435The Rlogin panel allows you to configure options that only apply to
1436Rlogin sessions.
1437
1438\S{config-rlogin-termspeed} \q{Terminal-speed string}
1439
70133c0e 1440\cfg{winhelp-topic}{rlogin.termspeed}
1441
add788fc 1442Like Telnet, Rlogin allows the client to send a text string that
1443describes the terminal speed. PuTTY lets you configure this, in case
1444you find the server is reacting badly to the default value. (I'm not
1445aware of any servers that do have a problem with it.)
1446
1447\S{config-rlogin-localuser} \q{Local username}
1448
70133c0e 1449\cfg{winhelp-topic}{rlogin.localuser}
1450
add788fc 1451Rlogin allows an automated (password-free) form of login by means of
1452a file called \c{.rhosts} on the server. You put a line in your
1453\c{.rhosts} file saying something like \c{jbloggs@pc1.example.com},
1454and then when you make an Rlogin connection the client transmits the
1455username of the user running the Rlogin client. The server checks
1456the username and hostname against \c{.rhosts}, and if they match it
1457does not ask for a password.
1458
1459This only works because Unix systems contain a safeguard to stop a
1460user from pretending to be another user in an Rlogin connection.
1461Rlogin connections have to come from port numbers below 1024, and
1462Unix systems prohibit this to unprivileged processes; so when the
1463server sees a connection from a low-numbered port, it assumes the
1464client end of the connection is held by a privileged (and therefore
1465trusted) process, so it believes the claim of who the user is.
1466
1467Windows does not have this restriction: \e{any} user can initiate an
1468outgoing connection from a low-numbered port. Hence, the Rlogin
1469\c{.rhosts} mechanism is completely useless for securely
1470distinguishing several different users on a Windows machine. If you
1471have a \c{.rhosts} entry pointing at a Windows PC, you should assume
1472that \e{anyone} using that PC can spoof your username in an Rlogin
1473connection and access your account on the server.
1474
1475The \q{Local username} control allows you to specify what user name
1476PuTTY should claim you have, in case it doesn't match your Windows
1477user name (or in case you didn't bother to set up a Windows user
1478name).
1479
55ba634a 1480\H{config-ssh} The SSH panel
1481
1630bb61 1482The SSH panel allows you to configure options that only apply to
1483SSH sessions.
1484
55ba634a 1485\S{config-command} Executing a specific command on the server
1486
70133c0e 1487\cfg{winhelp-topic}{ssh.command}
1488
add788fc 1489In SSH, you don't have to run a general shell session on the server.
1490Instead, you can choose to run a single specific command (such as a
1491mail user agent, for example). If you want to do this, enter the
1492command in the \q{Remote command} box.
1493
1494\S{config-ssh-pty} \q{Don't allocate a pseudo-terminal}
1495
70133c0e 1496\cfg{winhelp-topic}{ssh.nopty}
1497
add788fc 1498When connecting to a Unix system, most interactive shell sessions
1499are run in a \e{pseudo-terminal}, which allows the Unix system to
1500pretend it's talking to a real physical terminal device but allows
1501the SSH server to catch all the data coming from that fake device
1502and send it back to the client.
1503
1504Occasionally you might find you have a need to run a session \e{not}
1505in a pseudo-terminal. In PuTTY, this is generally only useful for
1506very specialist purposes; although in Plink (see \k{plink}) it is
1507the usual way of working.
1508
1509\S{config-ssh-comp} \q{Enable compression}
1510
70133c0e 1511\cfg{winhelp-topic}{ssh.compress}
1512
add788fc 1513This enables data compression in the SSH connection: data sent by
1514the server is compressed before sending, and decompressed at the
1515client end. Likewise, data sent by PuTTY to the server is compressed
1516first and the server decompresses it at the other end. This can help
1517make the most of a low-bandwidth connection.
1518
1519\S{config-ssh-prot} \q{Preferred SSH protocol version}
1520
70133c0e 1521\cfg{winhelp-topic}{ssh.protocol}
1522
add788fc 1523This allows you to select whether you would like to use SSH protocol
1524version 1 or version 2. \#{FIXME: say something about this elsewhere?}
1525
1526PuTTY will attempt to use protocol 1 if the server you connect to
1527does not offer protocol 2, and vice versa.
1528
1529\S{config-ssh-macbug} \q{Imitate SSH 2 MAC bug}
1530
70133c0e 1531\cfg{winhelp-topic}{ssh.buggymac}
1532
add788fc 1533This option \e{should} now be unnecessary. It existed in order to
1534work around a bug in early versions (2.3.0 and below) of the SSH
1535server software from \cw{ssh.com}. The symptom of this problem would
1536be that PuTTY would die unexpectedly at the beginning of the
1537session, saying \q{Incorrect MAC received on packet}.
1538
1539Current versions of PuTTY attempt to detect these faulty servers and
1540enable the bug compatibility automatically, so you should never need
1541to use this option any more.
1542
1543\S{config-ssh-encryption} Encryption algorithm selection
1544
70133c0e 1545\cfg{winhelp-topic}{ssh.ciphers}
1546
add788fc 1547PuTTY supports a variety of different encryption algorithms, and
1548allows you to choose which one you prefer to use. You can do this by
a5a6cb30 1549dragging the algorithms up and down in the list box (or moving them
1550using the Up and Down buttons) to specify a preference order. When
1551you make an SSH connection, PuTTY will search down the list from the
1552top until it finds an algorithm supported by the server, and then
1553use that.
add788fc 1554
1555If the algorithm PuTTY finds is below the \q{warn below here} line,
1556you will see a warning box when you make the connection:
1557
1558\c The first cipher supported by the server
1559\c is single-DES, which is below the configured
1560\c warning threshold.
1561\c Do you want to continue with this connection?
1562
1563This warns you that the first available encryption is not a very
1564secure one. Typically you would put the \q{warn below here} line
1565between the encryptions you consider secure and the ones you
a5a6cb30 1566consider substandard. By default, PuTTY supplies a preference order
1567intended to reflect a reasonable preference in terms of security and
1568speed.
add788fc 1569
81e8bb1b 1570Single-DES is not supported natively in the SSH 2 draft protocol
1571standards. One or two server implementations do support it, by a
1572non-standard name. PuTTY can use single-DES to interoperate with
1573these servers if you enable the \q{Enable non-standard single-DES in
1574SSH 2} option; by default this is disabled and PuTTY will stick to
1575the standard.
1576
add788fc 1577\H{config-ssh-auth} The Auth panel
1578
1579The Auth panel allows you to configure authentication options for
1580SSH sessions.
1581
1582\S{config-ssh-tis} \q{Attempt TIS or CryptoCard authentication}
1583
70133c0e 1584\cfg{winhelp-topic}{ssh.auth.tis}
1585
add788fc 1586TIS and CryptoCard authentication are simple challenge/response
1587forms of authentication available in SSH protocol version 1 only.
1588You might use them if you were using S/Key one-time passwords, for
1589example, or if you had a physical security token that generated
1590responses to authentication challenges.
1591
1592With this switch enabled, PuTTY will attempt these forms of
1593authentication if the server is willing to try them. You will be
1594presented with a challenge string (which will be different every
1595time) and must supply the correct response in order to log in. If
1596your server supports this, you should talk to your system
1597administrator about precisely what form these challenges and
1598responses take.
1599
babac7bd 1600\S{config-ssh-ki} \q{Attempt keyboard-interactive authentication}
81e8bb1b 1601
70133c0e 1602\cfg{winhelp-topic}{ssh.auth.ki}
1603
81e8bb1b 1604The SSH 2 equivalent of TIS authentication is called
1605\q{keyboard-interactive}. It is a flexible authentication method
1606using an arbitrary sequence of requests and responses; so it is not
1607only useful for challenge/response mechanisms such as S/Key, but it
1608can also be used for (for example) asking the user for a new
1609password when the old one has expired.
1610
1611PuTTY leaves this option enabled by default, but supplies a switch
1612to turn it off in case you should have trouble with it.
1613
add788fc 1614\S{config-ssh-agentfwd} \q{Allow agent forwarding}
1615
70133c0e 1616\cfg{winhelp-topic}{ssh.auth.agentfwd}
1617
add788fc 1618This option allows the SSH server to open forwarded connections back
1619to your local copy of Pageant. If you are not running Pageant, this
1620option will do nothing.
1621
1622See \k{pageant} for general information on Pageant, and
1623\k{pageant-forward} for information on agent forwarding. Note that
1624there is a security risk involved with enabling this option; see
1625\k{pageant-security} for details.
1626
babac7bd 1627\S{config-ssh-changeuser} \q{Allow attempted changes of username in SSH2}
5bb641e1 1628
1629\cfg{winhelp-topic}{ssh.auth.changeuser}
1630
1631In the SSH 1 protocol, it is impossible to change username after
1632failing to authenticate. So if you mis-type your username at the
1633PuTTY \q{login as:} prompt, you will not be able to change it except
1634by restarting PuTTY.
1635
1636The SSH 2 protocol \e{does} allow changes of username, in principle,
1637but does not make it mandatory for SSH 2 servers to accept them. In
1638particular, OpenSSH does not accept a change of username; once you
1639have sent one username, it will reject attempts to try to
1640authenticate as another user. (Depending on the version of OpenSSH,
1641it may quietly return failure for all login attempts, or it may send
1642an error message.)
1643
1644For this reason, PuTTY will by default not prompt you for your
1645username more than once, in case the server complains. If you know
1646your server can cope with it, you can enable the \q{Allow attempted
1647changes of username} option to modify PuTTY's behaviour.
1648
add788fc 1649\S{config-ssh-privkey} \q{Private key file for authentication}
1650
70133c0e 1651\cfg{winhelp-topic}{ssh.auth.privkey}
1652
add788fc 1653This box is where you enter the name of your private key file if you
1654are using public key authentication. See \k{pubkey} for information
1655about public key authentication in SSH.
1656
1657\H{config-ssh-tunnels} The Tunnels panel
1658
1659The Tunnels panel allows you to configure tunnelling of other
1660connection types through an SSH connection.
1661
1662\S{config-ssh-x11} X11 forwarding
1663
70133c0e 1664\cfg{winhelp-topic}{ssh.tunnels.x11}
1665
add788fc 1666If your server lets you run X Window System applications, X11
1667forwarding allows you to securely give those applications access to
1668a local X display on your PC.
1669
add788fc 1670To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
1671If your X display is not the primary display on your local machine
1672(which it almost certainly will be unless you have deliberately
1673arranged otherwise), you need to enter its location in the \q{X
1674display location} box.
1675
2f8d6d43 1676See \k{using-x-forwarding} for more information about X11
1677forwarding.
add788fc 1678
1679\S{config-ssh-portfwd} Port forwarding
1680
70133c0e 1681\cfg{winhelp-topic}{ssh.tunnels.portfwd}
1682
add788fc 1683Port forwarding allows you to tunnel other types of network
2f8d6d43 1684connection down an SSH session. See \k{using-port-forwarding} for a
1685general discussion of port forwarding and how it works.
1686
1687The port forwarding section in the Tunnels panel shows a list of all
1688the port forwardings that PuTTY will try to set up when it connects
1689to the server. By default no port forwardings are set up, so this
1690list is empty.
1691
1692To add a port forwarding:
1693
1694\b Set one of the \q{Local} or \q{Remote} radio buttons, depending
1695on whether you want to forward a local port to a remote destination
1696(\q{Local}) or forward a remote port to a local destination
1697(\q{Remote}).
1698
1699\b Enter a source port number into the \q{Source port} box. For
1700local forwardings, PuTTY will listen on this port of your PC. For
1701remote forwardings, your SSH server will listen on this port of the
1702remote machine. Note that most servers will not allow you to listen
1703on port numbers less than 1024.
1704
1705\b Enter a hostname and port number separated by a colon, in the
1706\q{Destination} box. Connections received on the source port will be
1707directed to this destination. For example, to connect to a POP-3
1708server, you might enter \c{popserver.example.com:110}.
1709
1710\b Click the \q{Add} button. Your forwarding details should appear
1711in the list box.
1712
1713To remove a port forwarding, simply select its details in the list
1714box, and click the \q{Remove} button.
37c6fce1 1715
beefa433 1716\S{config-ssh-portfwd-localhost} Controlling the visibility of
1717forwarded ports
1718
1719\cfg{winhelp-topic}{ssh.tunnels.portfwd.localhost}
1720
1721The source port for a forwarded connection usually does not accept
1722connections from any machine except the SSH client or server machine
1723itself (for local and remote forwardings respectively). There are
1724controls in the Tunnels panel to change this:
1725
1726\b The \q{Local ports accept connections from other hosts} option
1727allows you to set up local-to-remote port forwardings in such a way
1728that machines other than your client PC can connect to the forwarded
1729port.
1730
1731\b The \q{Remote ports do the same} option does the same thing for
1732remote-to-local port forwardings (so that machines other than the
1733SSH server machine can connect to the forwarded port.) Note that
1734this feature is only available in the SSH 2 protocol, and not all
1735SSH 2 servers support it (OpenSSH 3.0 does not, for example).
1736
37c6fce1 1737\H{config-file} Storing configuration in a file
1738
1739PuTTY does not currently support storing its configuration in a file
1740instead of the Registry. However, you can work around this with a
1741couple of batch files.
1742
1743You will need a file called (say) \c{PUTTY.BAT} which imports the
1744contents of a file into the Registry, then runs PuTTY, exports the
1745contents of the Registry back into the file, and deletes the
1746Registry entries. This can all be done using the Regedit command
1747line options, so it's all automatic. Here is what you need in
1748\c{PUTTY.BAT}:
1749
1750\c @ECHO OFF
1751\c regedit /s putty.reg
1752\c regedit /s puttyrnd.reg
1753\c start /w putty.exe
1754\c regedit /e puttynew.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
1755\c copy puttynew.reg putty.reg
1756\c del puttynew.reg
1757\c regedit /s puttydel.reg
1758
1759This batch file needs two auxiliary files: \c{PUTTYRND.REG} which
1760sets up an initial safe location for the \c{PUTTY.RND} random seed
1761file, and \c{PUTTYDEL.REG} which destroys everything in the Registry
1762once it's been successfully saved back to the file.
1763
1764Here is \c{PUTTYDEL.REG}:
1765
1766\c REGEDIT4
1767\c
1768\c [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
1769
1770Here is an example \c{PUTTYRND.REG} file:
1771
1772\c REGEDIT4
1773\c
1774\c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
1775\c "RandSeedFile"="a:\putty.rnd"
1776
1777You should replace \c{a:\\putty.rnd} with the location where you
1778want to store your random number data. If the aim is to carry around
1779PuTTY and its settings on one floppy, you probably want to store it
1780on the floppy.