Cleanups of the GSSAPI support. On Windows, standard GSS libraries
[u/mdw/putty] / doc / config.but
1 \define{versionidconfig} \versionid $Id$
2
3 \C{config} Configuring PuTTY
4
5 This chapter describes all the \i{configuration options} in PuTTY.
6
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.
10
11 \H{config-session} The Session panel
12
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.
16
17 \S{config-hostname} The \i{host name} section
18
19 \cfg{winhelp-topic}{session.hostname}
20
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.
24
25 \b The \q{Host Name} box is where you type the name, or the \i{IP
26 address}, of the server you want to connect to.
27
28 \b The \q{Connection type} radio buttons let you choose what type of
29 connection you want to make: a \I{raw TCP connections}raw
30 connection, a \i{Telnet} connection, an \i{Rlogin} connection, an
31 \i{SSH} connection, or a connection to a local \i{serial line}. (See
32 \k{which-one} for a summary of the differences between SSH, Telnet
33 and rlogin; see \k{using-rawprot} for an explanation of \q{raw}
34 connections; see \k{using-serial} for information about using a
35 serial line.)
36
37 \b The \q{Port} box lets you specify which \i{port number} on the
38 server to connect to. If you select Telnet, Rlogin, or SSH, this box
39 will be filled in automatically to the usual value, and you will
40 only need to change it if you have an unusual server. If you select
41 Raw mode, you will almost certainly need to fill in the \q{Port} box
42 yourself.
43
44 If you select \q{Serial} from the \q{Connection type} radio buttons,
45 the \q{Host Name} and \q{Port} boxes are replaced by \q{Serial line}
46 and \q{Speed}; see \k{config-serial} for more details of these.
47
48 \S{config-saving} \ii{Loading and storing saved sessions}
49
50 \cfg{winhelp-topic}{session.saved}
51
52 The next part of the Session configuration panel allows you to save
53 your preferred PuTTY options so they will appear automatically the
54 next time you start PuTTY. It also allows you to create \e{saved
55 sessions}, which contain a full set of configuration options plus a
56 host name and protocol. A saved session contains all the information
57 PuTTY needs to start exactly the session you want.
58
59 \b To save your default settings: first set up the settings the way
60 you want them saved. Then come back to the Session panel. Select the
61 \q{\i{Default Settings}} entry in the saved sessions list, with a single
62 click. Then press the \q{Save} button.
63
64 If there is a specific host you want to store the details of how to
65 connect to, you should create a saved session, which will be
66 separate from the Default Settings.
67
68 \b To save a session: first go through the rest of the configuration
69 box setting up all the options you want. Then come back to the
70 Session panel. Enter a name for the saved session in the \q{Saved
71 Sessions} input box. (The server name is often a good choice for a
72 saved session name.) Then press the \q{Save} button. Your saved
73 session name should now appear in the list box.
74
75 \lcont{
76 You can also save settings in mid-session, from the \q{Change Settings}
77 dialog. Settings changed since the start of the session will be saved
78 with their current values; as well as settings changed through the
79 dialog, this includes changes in window size, window title changes
80 sent by the server, and so on.
81 }
82
83 \b To reload a saved session: single-click to select the session
84 name in the list box, and then press the \q{Load} button. Your saved
85 settings should all appear in the configuration panel.
86
87 \b To modify a saved session: first load it as described above. Then
88 make the changes you want. Come back to the Session panel, and press
89 the \q{Save} button. The new settings will be saved over the top of
90 the old ones.
91
92 \lcont{
93 To save the new settings under a different name, you can enter the new
94 name in the \q{Saved Sessions} box, or single-click to select a
95 session name in the list box to overwrite that session. To save
96 \q{Default Settings}, you must single-click the name before saving.
97 }
98
99 \b To start a saved session immediately: double-click on the session
100 name in the list box.
101
102 \b To delete a saved session: single-click to select the session
103 name in the list box, and then press the \q{Delete} button.
104
105 Each saved session is independent of the Default Settings
106 configuration. If you change your preferences and update Default
107 Settings, you must also update every saved session separately.
108
109 Saved sessions are stored in the \i{Registry}, at the location
110
111 \c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\Sessions
112
113 If you need to store them in a file, you could try the method
114 described in \k{config-file}.
115
116 \S{config-closeonexit} \q{\ii{Close Window} on Exit}
117
118 \cfg{winhelp-topic}{session.coe}
119
120 Finally in the Session panel, there is an option labelled \q{Close
121 Window on Exit}. This controls whether the PuTTY \i{terminal window}
122 disappears as soon as the session inside it terminates. If you are
123 likely to want to copy and paste text out of the session after it
124 has terminated, or restart the session, you should arrange for this
125 option to be off.
126
127 \q{Close Window On Exit} has three settings. \q{Always} means always
128 close the window on exit; \q{Never} means never close on exit
129 (always leave the window open, but \I{inactive window}inactive). The
130 third setting, and the default one, is \q{Only on clean exit}. In this
131 mode, a session which terminates normally will cause its window to
132 close, but one which is aborted unexpectedly by network trouble or a
133 confusing message from the server will leave the window up.
134
135 \H{config-logging} The Logging panel
136
137 \cfg{winhelp-topic}{logging.main}
138
139 The Logging configuration panel allows you to save \i{log file}s of your
140 PuTTY sessions, for debugging, analysis or future reference.
141
142 The main option is a radio-button set that specifies whether PuTTY
143 will log anything at all. The options are:
144
145 \b \q{None}. This is the default option; in this mode PuTTY will not
146 create a log file at all.
147
148 \b \q{Printable output}. In this mode, a log file will be
149 created and written to, but only printable text will be saved into
150 it. The various terminal control codes that are typically sent down
151 an interactive session alongside the printable text will be omitted.
152 This might be a useful mode if you want to read a log file in a text
153 editor and hope to be able to make sense of it.
154
155 \b \q{All session output}. In this mode, \e{everything} sent by
156 the server into your terminal session is logged. If you view the log
157 file in a text editor, therefore, you may well find it full of
158 strange control characters. This is a particularly useful mode if
159 you are experiencing problems with PuTTY's terminal handling: you
160 can record everything that went to the terminal, so that someone
161 else can replay the session later in slow motion and watch to see
162 what went wrong.
163
164 \b \I{SSH packet log}\q{SSH packets}. In this mode (which is only used
165 by SSH connections), the SSH message packets sent over the encrypted
166 connection are written to the log file (as well as \i{Event Log}
167 entries). You might need this to debug a network-level problem, or
168 more likely to send to the PuTTY authors as part of a bug report.
169 \e{BE WARNED} that if you log in using a password, the password can
170 appear in the log file; see \k{config-logssh} for options that may
171 help to remove sensitive material from the log file before you send it
172 to anyone else.
173
174 \b \q{SSH packets and raw data}. In this mode, as well as the
175 decrypted packets (as in the previous mode), the \e{raw} (encrypted,
176 compressed, etc) packets are \e{also} logged. This could be useful to
177 diagnose corruption in transit. (The same caveats as the previous mode
178 apply, of course.)
179
180 Note that the non-SSH logging options (\q{Printable output} and
181 \q{All session output}) only work with PuTTY proper; in programs
182 without terminal emulation (such as Plink), they will have no effect,
183 even if enabled via saved settings.
184
185 \S{config-logfilename} \q{Log file name}
186
187 \cfg{winhelp-topic}{logging.filename}
188
189 In this edit box you enter the name of the file you want to log the
190 session to. The \q{Browse} button will let you look around your file
191 system to find the right place to put the file; or if you already
192 know exactly where you want it to go, you can just type a pathname
193 into the edit box.
194
195 There are a few special features in this box. If you use the \c{&}
196 character in the file name box, PuTTY will insert details of the
197 current session in the name of the file it actually opens. The
198 precise replacements it will do are:
199
200 \b \c{&Y} will be replaced by the current year, as four digits.
201
202 \b \c{&M} will be replaced by the current month, as two digits.
203
204 \b \c{&D} will be replaced by the current day of the month, as two
205 digits.
206
207 \b \c{&T} will be replaced by the current time, as six digits
208 (HHMMSS) with no punctuation.
209
210 \b \c{&H} will be replaced by the host name you are connecting to.
211
212 For example, if you enter the host name
213 \c{c:\\puttylogs\\log-&h-&y&m&d-&t.dat}, you will end up with files looking
214 like
215
216 \c log-server1.example.com-20010528-110859.dat
217 \c log-unixbox.somewhere.org-20010611-221001.dat
218
219 \S{config-logfileexists} \q{What to do if the log file already exists}
220
221 \cfg{winhelp-topic}{logging.exists}
222
223 This control allows you to specify what PuTTY should do if it tries
224 to start writing to a log file and it finds the file already exists.
225 You might want to automatically destroy the existing log file and
226 start a new one with the same name. Alternatively, you might want to
227 open the existing log file and add data to the \e{end} of it.
228 Finally (the default option), you might not want to have any
229 automatic behaviour, but to ask the user every time the problem
230 comes up.
231
232 \S{config-logflush} \I{log file, flushing}\q{Flush log file frequently}
233
234 \cfg{winhelp-topic}{logging.flush}
235
236 This option allows you to control how frequently logged data is
237 flushed to disc. By default, PuTTY will flush data as soon as it is
238 displayed, so that if you view the log file while a session is still
239 open, it will be up to date; and if the client system crashes, there's
240 a greater chance that the data will be preserved.
241
242 However, this can incur a performance penalty. If PuTTY is running
243 slowly with logging enabled, you could try unchecking this option. Be
244 warned that the log file may not always be up to date as a result
245 (although it will of course be flushed when it is closed, for instance
246 at the end of a session).
247
248 \S{config-logssh} Options specific to \i{SSH packet log}ging
249
250 These options only apply if SSH packet data is being logged.
251
252 The following options allow particularly sensitive portions of
253 unencrypted packets to be automatically left out of the log file.
254 They are only intended to deter casual nosiness; an attacker could
255 glean a lot of useful information from even these obfuscated logs
256 (e.g., length of password).
257
258 \S2{config-logssh-omitpw} \q{Omit known password fields}
259
260 \cfg{winhelp-topic}{logging.ssh.omitpassword}
261
262 When checked, decrypted password fields are removed from the log of
263 transmitted packets. (This includes any user responses to
264 challenge-response authentication methods such as
265 \q{keyboard-interactive}.) This does not include X11 authentication
266 data if using X11 forwarding.
267
268 Note that this will only omit data that PuTTY \e{knows} to be a
269 password. However, if you start another login session within your
270 PuTTY session, for instance, any password used will appear in the
271 clear in the packet log. The next option may be of use to protect
272 against this.
273
274 This option is enabled by default.
275
276 \S2{config-logssh-omitdata} \q{Omit session data}
277
278 \cfg{winhelp-topic}{logging.ssh.omitdata}
279
280 When checked, all decrypted \q{session data} is omitted; this is
281 defined as data in terminal sessions and in forwarded channels (TCP,
282 X11, and authentication agent). This will usually substantially reduce
283 the size of the resulting log file.
284
285 This option is disabled by default.
286
287 \H{config-terminal} The Terminal panel
288
289 The Terminal configuration panel allows you to control the behaviour
290 of PuTTY's \i{terminal emulation}.
291
292 \S{config-autowrap} \q{Auto wrap mode initially on}
293
294 \cfg{winhelp-topic}{terminal.autowrap}
295
296 \ii{Auto wrap mode} controls what happens when text printed in a PuTTY
297 window reaches the right-hand edge of the window.
298
299 With auto wrap mode on, if a long line of text reaches the
300 right-hand edge, it will wrap over on to the next line so you can
301 still see all the text. With auto wrap mode off, the cursor will
302 stay at the right-hand edge of the screen, and all the characters in
303 the line will be printed on top of each other.
304
305 If you are running a full-screen application and you occasionally
306 find the screen scrolling up when it looks as if it shouldn't, you
307 could try turning this option off.
308
309 Auto wrap mode can be turned on and off by \i{control sequence}s sent by
310 the server. This configuration option controls the \e{default}
311 state, which will be restored when you reset the terminal (see
312 \k{reset-terminal}). However, if you modify this option in
313 mid-session using \q{Change Settings}, it will take effect
314 immediately.
315
316 \S{config-decom} \q{DEC Origin Mode initially on}
317
318 \cfg{winhelp-topic}{terminal.decom}
319
320 \i{DEC Origin Mode} is a minor option which controls how PuTTY
321 interprets cursor-position \i{control sequence}s sent by the server.
322
323 The server can send a control sequence that restricts the \i{scrolling
324 region} of the display. For example, in an editor, the server might
325 reserve a line at the top of the screen and a line at the bottom,
326 and might send a control sequence that causes scrolling operations
327 to affect only the remaining lines.
328
329 With DEC Origin Mode on, \i{cursor coordinates} are counted from the top
330 of the scrolling region. With it turned off, cursor coordinates are
331 counted from the top of the whole screen regardless of the scrolling
332 region.
333
334 It is unlikely you would need to change this option, but if you find
335 a full-screen application is displaying pieces of text in what looks
336 like the wrong part of the screen, you could try turning DEC Origin
337 Mode on to see whether that helps.
338
339 DEC Origin Mode can be turned on and off by control sequences sent
340 by the server. This configuration option controls the \e{default}
341 state, which will be restored when you reset the terminal (see
342 \k{reset-terminal}). However, if you modify this option in
343 mid-session using \q{Change Settings}, it will take effect
344 immediately.
345
346 \S{config-crlf} \q{Implicit CR in every LF}
347
348 \cfg{winhelp-topic}{terminal.lfhascr}
349
350 Most servers send two control characters, \i{CR} and \i{LF}, to start a
351 \i{new line} of the screen. The CR character makes the cursor return to the
352 left-hand side of the screen. The LF character makes the cursor move
353 one line down (and might make the screen scroll).
354
355 Some servers only send LF, and expect the terminal to move the
356 cursor over to the left automatically. If you come across a server
357 that does this, you will see a \I{stair-stepping}stepped effect on the
358 screen, like this:
359
360 \c First line of text
361 \c Second line
362 \c Third line
363
364 If this happens to you, try enabling the \q{Implicit CR in every LF}
365 option, and things might go back to normal:
366
367 \c First line of text
368 \c Second line
369 \c Third line
370
371 \S{config-lfcr} \q{Implicit LF in every CR}
372
373 \cfg{winhelp-topic}{terminal.crhaslf}
374
375 Most servers send two control characters, \i{CR} and \i{LF}, to start a
376 \i{new line} of the screen. The CR character makes the cursor return to the
377 left-hand side of the screen. The LF character makes the cursor move
378 one line down (and might make the screen scroll).
379
380 Some servers only send CR, and so the newly
381 written line is overwritten by the following line. This option causes
382 a line feed so that all lines are displayed.
383
384 \S{config-erase} \q{Use \i{background colour} to erase screen}
385
386 \cfg{winhelp-topic}{terminal.bce}
387
388 Not all terminals agree on what colour to turn the screen when the
389 server sends a \q{\i{clear screen}} sequence. Some terminals believe the
390 screen should always be cleared to the \e{default} background
391 colour. Others believe the screen should be cleared to whatever the
392 server has selected as a background colour.
393
394 There exist applications that expect both kinds of behaviour.
395 Therefore, PuTTY can be configured to do either.
396
397 With this option disabled, screen clearing is always done in the
398 default background colour. With this option enabled, it is done in
399 the \e{current} background colour.
400
401 Background-colour erase can be turned on and off by \i{control
402 sequences} sent by the server. This configuration option controls the
403 \e{default} state, which will be restored when you reset the
404 terminal (see \k{reset-terminal}). However, if you modify this
405 option in mid-session using \q{Change Settings}, it will take effect
406 immediately.
407
408 \S{config-blink} \q{Enable \i{blinking text}}
409
410 \cfg{winhelp-topic}{terminal.blink}
411
412 The server can ask PuTTY to display text that blinks on and off.
413 This is very distracting, so PuTTY allows you to turn blinking text
414 off completely.
415
416 When blinking text is disabled and the server attempts to make some
417 text blink, PuTTY will instead display the text with a \I{background
418 colour, bright}bolded background colour.
419
420 Blinking text can be turned on and off by \i{control sequence}s sent by
421 the server. This configuration option controls the \e{default}
422 state, which will be restored when you reset the terminal (see
423 \k{reset-terminal}). However, if you modify this option in
424 mid-session using \q{Change Settings}, it will take effect
425 immediately.
426
427 \S{config-answerback} \q{\ii{Answerback} to ^E}
428
429 \cfg{winhelp-topic}{terminal.answerback}
430
431 This option controls what PuTTY will send back to the server if the
432 server sends it the ^E \i{enquiry character}. Normally it just sends
433 the string \q{PuTTY}.
434
435 If you accidentally write the contents of a binary file to your
436 terminal, you will probably find that it contains more than one ^E
437 character, and as a result your next command line will probably read
438 \q{PuTTYPuTTYPuTTY...} as if you had typed the answerback string
439 multiple times at the keyboard. If you set the answerback string to
440 be empty, this problem should go away, but doing so might cause
441 other problems.
442
443 Note that this is \e{not} the feature of PuTTY which the server will
444 typically use to determine your terminal type. That feature is the
445 \q{\ii{Terminal-type} string} in the Connection panel; see
446 \k{config-termtype} for details.
447
448 You can include control characters in the answerback string using
449 \c{^C} notation. (Use \c{^~} to get a literal \c{^}.)
450
451 \S{config-localecho} \q{\ii{Local echo}}
452
453 \cfg{winhelp-topic}{terminal.localecho}
454
455 With local echo disabled, characters you type into the PuTTY window
456 are not echoed in the window \e{by PuTTY}. They are simply sent to
457 the server. (The \e{server} might choose to \I{remote echo}echo them
458 back to you; this can't be controlled from the PuTTY control panel.)
459
460 Some types of session need local echo, and many do not. In its
461 default mode, PuTTY will automatically attempt to deduce whether or
462 not local echo is appropriate for the session you are working in. If
463 you find it has made the wrong decision, you can use this
464 configuration option to override its choice: you can force local
465 echo to be turned on, or force it to be turned off, instead of
466 relying on the automatic detection.
467
468 \S{config-localedit} \q{\ii{Local line editing}}
469
470 \cfg{winhelp-topic}{terminal.localedit}
471
472 Normally, every character you type into the PuTTY window is sent
473 immediately to the server the moment you type it.
474
475 If you enable local line editing, this changes. PuTTY will let you
476 edit a whole line at a time locally, and the line will only be sent
477 to the server when you press Return. If you make a mistake, you can
478 use the Backspace key to correct it before you press Return, and the
479 server will never see the mistake.
480
481 Since it is hard to edit a line locally without being able to see
482 it, local line editing is mostly used in conjunction with \i{local echo}
483 (\k{config-localecho}). This makes it ideal for use in raw mode
484 \#{FIXME} or when connecting to \i{MUD}s or \i{talker}s. (Although some more
485 advanced MUDs do occasionally turn local line editing on and turn
486 local echo off, in order to accept a password from the user.)
487
488 Some types of session need local line editing, and many do not. In
489 its default mode, PuTTY will automatically attempt to deduce whether
490 or not local line editing is appropriate for the session you are
491 working in. If you find it has made the wrong decision, you can use
492 this configuration option to override its choice: you can force
493 local line editing to be turned on, or force it to be turned off,
494 instead of relying on the automatic detection.
495
496 \S{config-printing} \ii{Remote-controlled printing}
497
498 \cfg{winhelp-topic}{terminal.printing}
499
500 A lot of VT100-compatible terminals support printing under control
501 of the remote server. PuTTY supports this feature as well, but it is
502 turned off by default.
503
504 To enable remote-controlled printing, choose a printer from the
505 \q{Printer to send ANSI printer output to} drop-down list box. This
506 should allow you to select from all the printers you have installed
507 drivers for on your computer. Alternatively, you can type the
508 network name of a networked printer (for example,
509 \c{\\\\printserver\\printer1}) even if you haven't already
510 installed a driver for it on your own machine.
511
512 When the remote server attempts to print some data, PuTTY will send
513 that data to the printer \e{raw} - without translating it,
514 attempting to format it, or doing anything else to it. It is up to
515 you to ensure your remote server knows what type of printer it is
516 talking to.
517
518 Since PuTTY sends data to the printer raw, it cannot offer options
519 such as portrait versus landscape, print quality, or paper tray
520 selection. All these things would be done by your PC printer driver
521 (which PuTTY bypasses); if you need them done, you will have to find
522 a way to configure your remote server to do them.
523
524 To disable remote printing again, choose \q{None (printing
525 disabled)} from the printer selection list. This is the default
526 state.
527
528 \H{config-keyboard} The Keyboard panel
529
530 The Keyboard configuration panel allows you to control the behaviour
531 of the \i{keyboard} in PuTTY. The correct state for many of these
532 settings depends on what the server to which PuTTY is connecting
533 expects. With a \i{Unix} server, this is likely to depend on the
534 \i\c{termcap} or \i\c{terminfo} entry it uses, which in turn is likely to
535 be controlled by the \q{\ii{Terminal-type} string} setting in the Connection
536 panel; see \k{config-termtype} for details. If none of the settings here
537 seems to help, you may find \k{faq-keyboard} to be useful.
538
539 \S{config-backspace} Changing the action of the \ii{Backspace key}
540
541 \cfg{winhelp-topic}{keyboard.backspace}
542
543 Some terminals believe that the Backspace key should send the same
544 thing to the server as \i{Control-H} (ASCII code 8). Other terminals
545 believe that the Backspace key should send ASCII code 127 (usually
546 known as \i{Control-?}) so that it can be distinguished from Control-H.
547 This option allows you to choose which code PuTTY generates when you
548 press Backspace.
549
550 If you are connecting over SSH, PuTTY by default tells the server
551 the value of this option (see \k{config-ttymodes}), so you may find
552 that the Backspace key does the right thing either way. Similarly,
553 if you are connecting to a \i{Unix} system, you will probably find that
554 the Unix \i\c{stty} command lets you configure which the server
555 expects to see, so again you might not need to change which one PuTTY
556 generates. On other systems, the server's expectation might be fixed
557 and you might have no choice but to configure PuTTY.
558
559 If you do have the choice, we recommend configuring PuTTY to
560 generate Control-? and configuring the server to expect it, because
561 that allows applications such as \c{emacs} to use Control-H for
562 help.
563
564 (Typing \i{Shift-Backspace} will cause PuTTY to send whichever code
565 isn't configured here as the default.)
566
567 \S{config-homeend} Changing the action of the \i{Home and End keys}
568
569 \cfg{winhelp-topic}{keyboard.homeend}
570
571 The Unix terminal emulator \i\c{rxvt} disagrees with the rest of the
572 world about what character sequences should be sent to the server by
573 the Home and End keys.
574
575 \i\c{xterm}, and other terminals, send \c{ESC [1~} for the Home key,
576 and \c{ESC [4~} for the End key. \c{rxvt} sends \c{ESC [H} for the
577 Home key and \c{ESC [Ow} for the End key.
578
579 If you find an application on which the Home and End keys aren't
580 working, you could try switching this option to see if it helps.
581
582 \S{config-funkeys} Changing the action of the \i{function keys} and
583 \i{keypad}
584
585 \cfg{winhelp-topic}{keyboard.funkeys}
586
587 This option affects the function keys (F1 to F12) and the top row of
588 the numeric keypad.
589
590 \b In the default mode, labelled \c{ESC [n~}, the function keys
591 generate sequences like \c{ESC [11~}, \c{ESC [12~} and so on. This
592 matches the general behaviour of Digital's terminals.
593
594 \b In Linux mode, F6 to F12 behave just like the default mode, but
595 F1 to F5 generate \c{ESC [[A} through to \c{ESC [[E}. This mimics the
596 \i{Linux virtual console}.
597
598 \b In \I{xterm}Xterm R6 mode, F5 to F12 behave like the default mode, but F1
599 to F4 generate \c{ESC OP} through to \c{ESC OS}, which are the
600 sequences produced by the top row of the \e{keypad} on Digital's
601 terminals.
602
603 \b In \i{VT400} mode, all the function keys behave like the default
604 mode, but the actual top row of the numeric keypad generates \c{ESC
605 OP} through to \c{ESC OS}.
606
607 \b In \i{VT100+} mode, the function keys generate \c{ESC OP} through to
608 \c{ESC O[}
609
610 \b In \i{SCO} mode, the function keys F1 to F12 generate \c{ESC [M}
611 through to \c{ESC [X}. Together with shift, they generate \c{ESC [Y}
612 through to \c{ESC [j}. With control they generate \c{ESC [k} through
613 to \c{ESC [v}, and with shift and control together they generate
614 \c{ESC [w} through to \c{ESC [\{}.
615
616 If you don't know what any of this means, you probably don't need to
617 fiddle with it.
618
619 \S{config-appcursor} Controlling \i{Application Cursor Keys} mode
620
621 \cfg{winhelp-topic}{keyboard.appcursor}
622
623 Application Cursor Keys mode is a way for the server to change the
624 control sequences sent by the arrow keys. In normal mode, the arrow
625 keys send \c{ESC [A} through to \c{ESC [D}. In application mode,
626 they send \c{ESC OA} through to \c{ESC OD}.
627
628 Application Cursor Keys mode can be turned on and off by the server,
629 depending on the application. PuTTY allows you to configure the
630 initial state.
631
632 You can also disable application cursor keys mode completely, using
633 the \q{Features} configuration panel; see
634 \k{config-features-application}.
635
636 \S{config-appkeypad} Controlling \i{Application Keypad} mode
637
638 \cfg{winhelp-topic}{keyboard.appkeypad}
639
640 Application Keypad mode is a way for the server to change the
641 behaviour of the numeric keypad.
642
643 In normal mode, the keypad behaves like a normal Windows keypad:
644 with \i{NumLock} on, the number keys generate numbers, and with NumLock
645 off they act like the arrow keys and Home, End etc.
646
647 In application mode, all the keypad keys send special control
648 sequences, \e{including} Num Lock. Num Lock stops behaving like Num
649 Lock and becomes another function key.
650
651 Depending on which version of Windows you run, you may find the Num
652 Lock light still flashes on and off every time you press Num Lock,
653 even when application mode is active and Num Lock is acting like a
654 function key. This is unavoidable.
655
656 Application keypad mode can be turned on and off by the server,
657 depending on the application. PuTTY allows you to configure the
658 initial state.
659
660 You can also disable application keypad mode completely, using the
661 \q{Features} configuration panel; see
662 \k{config-features-application}.
663
664 \S{config-nethack} Using \i{NetHack keypad mode}
665
666 \cfg{winhelp-topic}{keyboard.nethack}
667
668 PuTTY has a special mode for playing NetHack. You can enable it by
669 selecting \q{NetHack} in the \q{Initial state of numeric keypad}
670 control.
671
672 In this mode, the numeric keypad keys 1-9 generate the NetHack
673 movement commands (\cw{hjklyubn}). The 5 key generates the \c{.}
674 command (do nothing).
675
676 In addition, pressing Shift or Ctrl with the keypad keys generate
677 the Shift- or Ctrl-keys you would expect (e.g. keypad-7 generates
678 \cq{y}, so Shift-keypad-7 generates \cq{Y} and Ctrl-keypad-7
679 generates Ctrl-Y); these commands tell NetHack to keep moving you in
680 the same direction until you encounter something interesting.
681
682 For some reason, this feature only works properly when \i{Num Lock} is
683 on. We don't know why.
684
685 \S{config-compose} Enabling a DEC-like \ii{Compose key}
686
687 \cfg{winhelp-topic}{keyboard.compose}
688
689 DEC terminals have a Compose key, which provides an easy-to-remember
690 way of typing \i{accented characters}. You press Compose and then type
691 two more characters. The two characters are \q{combined} to produce
692 an accented character. The choices of character are designed to be
693 easy to remember; for example, composing \q{e} and \q{`} produces
694 the \q{\u00e8{e-grave}} character.
695
696 If your keyboard has a Windows \i{Application key}, it acts as a Compose
697 key in PuTTY. Alternatively, if you enable the \q{\i{AltGr} acts as
698 Compose key} option, the AltGr key will become a Compose key.
699
700 \S{config-ctrlalt} \q{Control-Alt is different from \i{AltGr}}
701
702 \cfg{winhelp-topic}{keyboard.ctrlalt}
703
704 Some old keyboards do not have an AltGr key, which can make it
705 difficult to type some characters. PuTTY can be configured to treat
706 the key combination Ctrl + Left Alt the same way as the AltGr key.
707
708 By default, this checkbox is checked, and the key combination Ctrl +
709 Left Alt does something completely different. PuTTY's usual handling
710 of the left Alt key is to prefix the Escape (Control-\cw{[})
711 character to whatever character sequence the rest of the keypress
712 would generate. For example, Alt-A generates Escape followed by
713 \c{a}. So Alt-Ctrl-A would generate Escape, followed by Control-A.
714
715 If you uncheck this box, Ctrl-Alt will become a synonym for AltGr,
716 so you can use it to type extra graphic characters if your keyboard
717 has any.
718
719 (However, Ctrl-Alt will never act as a Compose key, regardless of the
720 setting of \q{AltGr acts as Compose key} described in
721 \k{config-compose}.)
722
723 \H{config-bell} The Bell panel
724
725 The Bell panel controls the \i{terminal bell} feature: the server's
726 ability to cause PuTTY to beep at you.
727
728 In the default configuration, when the server sends the character
729 with ASCII code 7 (Control-G), PuTTY will play the \i{Windows Default
730 Beep} sound. This is not always what you want the terminal bell
731 feature to do; the Bell panel allows you to configure alternative
732 actions.
733
734 \S{config-bellstyle} \q{Set the style of bell}
735
736 \cfg{winhelp-topic}{bell.style}
737
738 This control allows you to select various different actions to occur
739 on a terminal bell:
740
741 \b Selecting \q{None} \I{terminal bell, disabling}disables the bell
742 completely. In this mode, the server can send as many Control-G
743 characters as it likes and nothing at all will happen.
744
745 \b \q{Make default system alert sound} is the default setting. It
746 causes the Windows \q{Default Beep} sound to be played. To change
747 what this sound is, or to test it if nothing seems to be happening,
748 use the Sound configurer in the Windows Control Panel.
749
750 \b \q{\ii{Visual bell}} is a silent alternative to a beeping computer. In
751 this mode, when the server sends a Control-G, the whole PuTTY window
752 will flash white for a fraction of a second.
753
754 \b \q{Beep using the \i{PC speaker}} is self-explanatory.
755
756 \b \q{Play a custom \i{sound file}} allows you to specify a particular
757 sound file to be used by PuTTY alone, or even by a particular
758 individual PuTTY session. This allows you to distinguish your PuTTY
759 beeps from any other beeps on the system. If you select this option,
760 you will also need to enter the name of your sound file in the edit
761 control \q{Custom sound file to play as a bell}.
762
763 \S{config-belltaskbar} \q{\ii{Taskbar}/\I{window caption}caption
764 indication on bell}
765
766 \cfg{winhelp-topic}{bell.taskbar}
767
768 This feature controls what happens to the PuTTY window's entry in
769 the Windows Taskbar if a bell occurs while the window does not have
770 the input focus.
771
772 In the default state (\q{Disabled}) nothing unusual happens.
773
774 If you select \q{Steady}, then when a bell occurs and the window is
775 not in focus, the window's Taskbar entry and its title bar will
776 change colour to let you know that PuTTY session is asking for your
777 attention. The change of colour will persist until you select the
778 window, so you can leave several PuTTY windows minimised in your
779 terminal, go away from your keyboard, and be sure not to have missed
780 any important beeps when you get back.
781
782 \q{Flashing} is even more eye-catching: the Taskbar entry will
783 continuously flash on and off until you select the window.
784
785 \S{config-bellovl} \q{Control the \i{bell overload} behaviour}
786
787 \cfg{winhelp-topic}{bell.overload}
788
789 A common user error in a terminal session is to accidentally run the
790 Unix command \c{cat} (or equivalent) on an inappropriate file type,
791 such as an executable, image file, or ZIP file. This produces a huge
792 stream of non-text characters sent to the terminal, which typically
793 includes a lot of bell characters. As a result of this the terminal
794 often doesn't stop beeping for ten minutes, and everybody else in
795 the office gets annoyed.
796
797 To try to avoid this behaviour, or any other cause of excessive
798 beeping, PuTTY includes a bell overload management feature. In the
799 default configuration, receiving more than five bell characters in a
800 two-second period will cause the overload feature to activate. Once
801 the overload feature is active, further bells will \I{terminal bell,
802 disabling} have no effect at all, so the rest of your binary file
803 will be sent to the screen in silence. After a period of five seconds
804 during which no further bells are received, the overload feature will
805 turn itself off again and bells will be re-enabled.
806
807 If you want this feature completely disabled, you can turn it off
808 using the checkbox \q{Bell is temporarily disabled when over-used}.
809
810 Alternatively, if you like the bell overload feature but don't agree
811 with the settings, you can configure the details: how many bells
812 constitute an overload, how short a time period they have to arrive
813 in to do so, and how much silent time is required before the
814 overload feature will deactivate itself.
815
816 Bell overload mode is always deactivated by any keypress in the
817 terminal. This means it can respond to large unexpected streams of
818 data, but does not interfere with ordinary command-line activities
819 that generate beeps (such as filename completion).
820
821 \H{config-features} The Features panel
822
823 PuTTY's \i{terminal emulation} is very highly featured, and can do a lot
824 of things under remote server control. Some of these features can
825 cause problems due to buggy or strangely configured server
826 applications.
827
828 The Features configuration panel allows you to disable some of
829 PuTTY's more advanced terminal features, in case they cause trouble.
830
831 \S{config-features-application} Disabling application keypad and cursor keys
832
833 \cfg{winhelp-topic}{features.application}
834
835 \I{Application Keypad}Application keypad mode (see
836 \k{config-appkeypad}) and \I{Application Cursor Keys}application
837 cursor keys mode (see \k{config-appcursor}) alter the behaviour of
838 the keypad and cursor keys. Some applications enable these modes but
839 then do not deal correctly with the modified keys. You can force
840 these modes to be permanently disabled no matter what the server
841 tries to do.
842
843 \S{config-features-mouse} Disabling \cw{xterm}-style \i{mouse reporting}
844
845 \cfg{winhelp-topic}{features.mouse}
846
847 PuTTY allows the server to send \i{control codes} that let it take over
848 the mouse and use it for purposes other than \i{copy and paste}.
849 Applications which use this feature include the text-mode web
850 browser \i\c{links}, the Usenet newsreader \i\c{trn} version 4, and the
851 file manager \i\c{mc} (Midnight Commander).
852
853 If you find this feature inconvenient, you can disable it using the
854 \q{Disable xterm-style mouse reporting} control. With this box
855 ticked, the mouse will \e{always} do copy and paste in the normal
856 way.
857
858 Note that even if the application takes over the mouse, you can
859 still manage PuTTY's copy and paste by holding down the Shift key
860 while you select and paste, unless you have deliberately turned this
861 feature off (see \k{config-mouseshift}).
862
863 \S{config-features-resize} Disabling remote \i{terminal resizing}
864
865 \cfg{winhelp-topic}{features.resize}
866
867 PuTTY has the ability to change the terminal's size and position in
868 response to commands from the server. If you find PuTTY is doing
869 this unexpectedly or inconveniently, you can tell PuTTY not to
870 respond to those server commands.
871
872 \S{config-features-altscreen} Disabling switching to the \i{alternate screen}
873
874 \cfg{winhelp-topic}{features.altscreen}
875
876 Many terminals, including PuTTY, support an \q{alternate screen}.
877 This is the same size as the ordinary terminal screen, but separate.
878 Typically a screen-based program such as a text editor might switch
879 the terminal to the alternate screen before starting up. Then at the
880 end of the run, it switches back to the primary screen, and you see
881 the screen contents just as they were before starting the editor.
882
883 Some people prefer this not to happen. If you want your editor to
884 run in the same screen as the rest of your terminal activity, you
885 can disable the alternate screen feature completely.
886
887 \S{config-features-retitle} Disabling remote \i{window title} changing
888
889 \cfg{winhelp-topic}{features.retitle}
890
891 PuTTY has the ability to change the window title in response to
892 commands from the server. If you find PuTTY is doing this
893 unexpectedly or inconveniently, you can tell PuTTY not to respond to
894 those server commands.
895
896 \S{config-features-qtitle} Response to remote \i{window title} querying
897
898 \cfg{winhelp-topic}{features.qtitle}
899
900 PuTTY can optionally provide the xterm service of allowing server
901 applications to find out the local window title. This feature is
902 disabled by default, but you can turn it on if you really want it.
903
904 NOTE that this feature is a \e{potential \i{security hazard}}. If a
905 malicious application can write data to your terminal (for example,
906 if you merely \c{cat} a file owned by someone else on the server
907 machine), it can change your window title (unless you have disabled
908 this as mentioned in \k{config-features-retitle}) and then use this
909 service to have the new window title sent back to the server as if
910 typed at the keyboard. This allows an attacker to fake keypresses
911 and potentially cause your server-side applications to do things you
912 didn't want. Therefore this feature is disabled by default, and we
913 recommend you do not set it to \q{Window title} unless you \e{really}
914 know what you are doing.
915
916 There are three settings for this option:
917
918 \dt \q{None}
919
920 \dd PuTTY makes no response whatsoever to the relevant escape
921 sequence. This may upset server-side software that is expecting some
922 sort of response.
923
924 \dt \q{Empty string}
925
926 \dd PuTTY makes a well-formed response, but leaves it blank. Thus,
927 server-side software that expects a response is kept happy, but an
928 attacker cannot influence the response string. This is probably the
929 setting you want if you have no better ideas.
930
931 \dt \q{Window title}
932
933 \dd PuTTY responds with the actual window title. This is dangerous for
934 the reasons described above.
935
936 \S{config-features-dbackspace} Disabling \i{destructive backspace}
937
938 \cfg{winhelp-topic}{features.dbackspace}
939
940 Normally, when PuTTY receives character 127 (^?) from the server, it
941 will perform a \q{destructive backspace}: move the cursor one space
942 left and delete the character under it. This can apparently cause
943 problems in some applications, so PuTTY provides the ability to
944 configure character 127 to perform a normal backspace (without
945 deleting a character) instead.
946
947 \S{config-features-charset} Disabling remote \i{character set}
948 configuration
949
950 \cfg{winhelp-topic}{features.charset}
951
952 PuTTY has the ability to change its character set configuration in
953 response to commands from the server. Some programs send these
954 commands unexpectedly or inconveniently. In particular, \i{BitchX} (an
955 IRC client) seems to have a habit of reconfiguring the character set
956 to something other than the user intended.
957
958 If you find that accented characters are not showing up the way you
959 expect them to, particularly if you're running BitchX, you could try
960 disabling the remote character set configuration commands.
961
962 \S{config-features-shaping} Disabling \i{Arabic text shaping}
963
964 \cfg{winhelp-topic}{features.arabicshaping}
965
966 PuTTY supports shaping of Arabic text, which means that if your
967 server sends text written in the basic \i{Unicode} Arabic alphabet then
968 it will convert it to the correct display forms before printing it
969 on the screen.
970
971 If you are using full-screen software which was not expecting this
972 to happen (especially if you are not an Arabic speaker and you
973 unexpectedly find yourself dealing with Arabic text files in
974 applications which are not Arabic-aware), you might find that the
975 \i{display becomes corrupted}. By ticking this box, you can disable
976 Arabic text shaping so that PuTTY displays precisely the characters
977 it is told to display.
978
979 You may also find you need to disable bidirectional text display;
980 see \k{config-features-bidi}.
981
982 \S{config-features-bidi} Disabling \i{bidirectional text} display
983
984 \cfg{winhelp-topic}{features.bidi}
985
986 PuTTY supports bidirectional text display, which means that if your
987 server sends text written in a language which is usually displayed
988 from right to left (such as \i{Arabic} or \i{Hebrew}) then PuTTY will
989 automatically flip it round so that it is displayed in the right
990 direction on the screen.
991
992 If you are using full-screen software which was not expecting this
993 to happen (especially if you are not an Arabic speaker and you
994 unexpectedly find yourself dealing with Arabic text files in
995 applications which are not Arabic-aware), you might find that the
996 \i{display becomes corrupted}. By ticking this box, you can disable
997 bidirectional text display, so that PuTTY displays text from left to
998 right in all situations.
999
1000 You may also find you need to disable Arabic text shaping;
1001 see \k{config-features-shaping}.
1002
1003 \H{config-window} The Window panel
1004
1005 The Window configuration panel allows you to control aspects of the
1006 \i{PuTTY window}.
1007
1008 \S{config-winsize} Setting the \I{window size}size of the PuTTY window
1009
1010 \cfg{winhelp-topic}{window.size}
1011
1012 The \q{\ii{Columns}} and \q{\ii{Rows}} boxes let you set the PuTTY
1013 window to a precise size. Of course you can also \I{window resizing}drag
1014 the window to a new size while a session is running.
1015
1016 \S{config-winsizelock} What to do when the window is resized
1017
1018 \cfg{winhelp-topic}{window.resize}
1019
1020 These options allow you to control what happens when the user tries
1021 to \I{window resizing}resize the PuTTY window using its window furniture.
1022
1023 There are four options here:
1024
1025 \b \q{Change the number of rows and columns}: the font size will not
1026 change. (This is the default.)
1027
1028 \b \q{Change the size of the font}: the number of rows and columns in
1029 the terminal will stay the same, and the \i{font size} will change.
1030
1031 \b \q{Change font size when maximised}: when the window is resized,
1032 the number of rows and columns will change, \e{except} when the window
1033 is \i{maximise}d (or restored), when the font size will change.
1034
1035 \b \q{Forbid resizing completely}: the terminal will refuse to be
1036 resized at all.
1037
1038 \S{config-scrollback} Controlling \i{scrollback}
1039
1040 \cfg{winhelp-topic}{window.scrollback}
1041
1042 These options let you configure the way PuTTY keeps text after it
1043 scrolls off the top of the screen (see \k{using-scrollback}).
1044
1045 The \q{Lines of scrollback} box lets you configure how many lines of
1046 text PuTTY keeps. The \q{Display scrollbar} options allow you to
1047 hide the \i{scrollbar} (although you can still view the scrollback using
1048 the keyboard as described in \k{using-scrollback}). You can separately
1049 configure whether the scrollbar is shown in \i{full-screen} mode and in
1050 normal modes.
1051
1052 If you are viewing part of the scrollback when the server sends more
1053 text to PuTTY, the screen will revert to showing the current
1054 terminal contents. You can disable this behaviour by turning off
1055 \q{Reset scrollback on display activity}. You can also make the
1056 screen revert when you press a key, by turning on \q{Reset
1057 scrollback on keypress}.
1058
1059 \S{config-erasetoscrollback} \q{Push erased text into scrollback}
1060
1061 \cfg{winhelp-topic}{window.erased}
1062
1063 When this option is enabled, the contents of the terminal screen
1064 will be pushed into the scrollback when a server-side application
1065 clears the screen, so that your scrollback will contain a better
1066 record of what was on your screen in the past.
1067
1068 If the application switches to the \i{alternate screen} (see
1069 \k{config-features-altscreen} for more about this), then the
1070 contents of the primary screen will be visible in the scrollback
1071 until the application switches back again.
1072
1073 This option is enabled by default.
1074
1075 \H{config-appearance} The Appearance panel
1076
1077 The Appearance configuration panel allows you to control aspects of
1078 the appearance of \I{PuTTY window}PuTTY's window.
1079
1080 \S{config-cursor} Controlling the appearance of the \i{cursor}
1081
1082 \cfg{winhelp-topic}{appearance.cursor}
1083
1084 The \q{Cursor appearance} option lets you configure the cursor to be
1085 a block, an underline, or a vertical line. A block cursor becomes an
1086 empty box when the window loses focus; an underline or a vertical
1087 line becomes dotted.
1088
1089 The \q{\ii{Cursor blinks}} option makes the cursor blink on and off. This
1090 works in any of the cursor modes.
1091
1092 \S{config-font} Controlling the \i{font} used in the terminal window
1093
1094 \cfg{winhelp-topic}{appearance.font}
1095
1096 This option allows you to choose what font, in what \I{font size}size,
1097 the PuTTY terminal window uses to display the text in the session. You
1098 will be offered a choice from all the fixed-width fonts installed on the
1099 system. (VT100-style terminal handling can only deal with fixed-width
1100 fonts.)
1101
1102 \S{config-mouseptr} \q{Hide \i{mouse pointer} when typing in window}
1103
1104 \cfg{winhelp-topic}{appearance.hidemouse}
1105
1106 If you enable this option, the mouse pointer will disappear if the
1107 PuTTY window is selected and you press a key. This way, it will not
1108 obscure any of the text in the window while you work in your
1109 session. As soon as you move the mouse, the pointer will reappear.
1110
1111 This option is disabled by default, so the mouse pointer remains
1112 visible at all times.
1113
1114 \S{config-winborder} Controlling the \i{window border}
1115
1116 \cfg{winhelp-topic}{appearance.border}
1117
1118 PuTTY allows you to configure the appearance of the window border to
1119 some extent.
1120
1121 The checkbox marked \q{Sunken-edge border} changes the appearance of
1122 the window border to something more like a DOS box: the inside edge
1123 of the border is highlighted as if it sank down to meet the surface
1124 inside the window. This makes the border a little bit thicker as
1125 well. It's hard to describe well. Try it and see if you like it.
1126
1127 You can also configure a completely blank gap between the text in
1128 the window and the border, using the \q{Gap between text and window
1129 edge} control. By default this is set at one pixel. You can reduce
1130 it to zero, or increase it further.
1131
1132 \H{config-behaviour} The Behaviour panel
1133
1134 The Behaviour configuration panel allows you to control aspects of
1135 the behaviour of \I{PuTTY window}PuTTY's window.
1136
1137 \S{config-title} Controlling the \i{window title}
1138
1139 \cfg{winhelp-topic}{appearance.title}
1140
1141 The \q{Window title} edit box allows you to set the title of the
1142 PuTTY window. By default the window title will contain the \i{host name}
1143 followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
1144 If you want a different window title, this is where to set it.
1145
1146 PuTTY allows the server to send \c{xterm} \i{control sequence}s which
1147 modify the title of the window in mid-session (unless this is disabled -
1148 see \k{config-features-retitle}); the title string set here
1149 is therefore only the \e{initial} window title.
1150
1151 As well as the \e{window} title, there is also an \c{xterm}
1152 sequence to modify the \I{icon title}title of the window's \e{icon}.
1153 This makes sense in a windowing system where the window becomes an
1154 icon when minimised, such as Windows 3.1 or most X Window System
1155 setups; but in the Windows 95-like user interface it isn't as
1156 applicable.
1157
1158 By default, PuTTY only uses the server-supplied \e{window} title, and
1159 ignores the icon title entirely. If for some reason you want to see
1160 both titles, check the box marked \q{Separate window and icon titles}.
1161 If you do this, PuTTY's window title and Taskbar \I{window caption}caption will
1162 change into the server-supplied icon title if you \i{minimise} the PuTTY
1163 window, and change back to the server-supplied window title if you
1164 restore it. (If the server has not bothered to supply a window or
1165 icon title, none of this will happen.)
1166
1167 \S{config-warnonclose} \q{Warn before \i{closing window}}
1168
1169 \cfg{winhelp-topic}{behaviour.closewarn}
1170
1171 If you press the \i{Close button} in a PuTTY window that contains a
1172 running session, PuTTY will put up a warning window asking if you
1173 really meant to close the window. A window whose session has already
1174 terminated can always be closed without a warning.
1175
1176 If you want to be able to close a window quickly, you can disable
1177 the \q{Warn before closing window} option.
1178
1179 \S{config-altf4} \q{Window closes on \i{ALT-F4}}
1180
1181 \cfg{winhelp-topic}{behaviour.altf4}
1182
1183 By default, pressing ALT-F4 causes the \I{closing window}window to
1184 close (or a warning box to appear; see \k{config-warnonclose}). If you
1185 disable the \q{Window closes on ALT-F4} option, then pressing ALT-F4
1186 will simply send a key sequence to the server.
1187
1188 \S{config-altspace} \q{\ii{System menu} appears on \i{ALT-Space}}
1189
1190 \cfg{winhelp-topic}{behaviour.altspace}
1191
1192 If this option is enabled, then pressing ALT-Space will bring up the
1193 PuTTY window's menu, like clicking on the top left corner. If it is
1194 disabled, then pressing ALT-Space will just send \c{ESC SPACE} to
1195 the server.
1196
1197 Some \i{accessibility} programs for Windows may need this option
1198 enabling to be able to control PuTTY's window successfully. For
1199 instance, \i{Dragon NaturallySpeaking} requires it both to open the
1200 system menu via voice, and to close, minimise, maximise and restore
1201 the window.
1202
1203 \S{config-altonly} \q{\ii{System menu} appears on \i{Alt} alone}
1204
1205 \cfg{winhelp-topic}{behaviour.altonly}
1206
1207 If this option is enabled, then pressing and releasing ALT will
1208 bring up the PuTTY window's menu, like clicking on the top left
1209 corner. If it is disabled, then pressing and releasing ALT will have
1210 no effect.
1211
1212 \S{config-alwaysontop} \q{Ensure window is \i{always on top}}
1213
1214 \cfg{winhelp-topic}{behaviour.alwaysontop}
1215
1216 If this option is enabled, the PuTTY window will stay on top of all
1217 other windows.
1218
1219 \S{config-fullscreen} \q{\ii{Full screen} on Alt-Enter}
1220
1221 \cfg{winhelp-topic}{behaviour.altenter}
1222
1223 If this option is enabled, then pressing Alt-Enter will cause the
1224 PuTTY window to become full-screen. Pressing Alt-Enter again will
1225 restore the previous window size.
1226
1227 The full-screen feature is also available from the \ii{System menu}, even
1228 when it is configured not to be available on the Alt-Enter key. See
1229 \k{using-fullscreen}.
1230
1231 \H{config-translation} The Translation panel
1232
1233 The Translation configuration panel allows you to control the
1234 translation between the \i{character set} understood by the server and
1235 the character set understood by PuTTY.
1236
1237 \S{config-charset} Controlling character set translation
1238
1239 \cfg{winhelp-topic}{translation.codepage}
1240
1241 During an interactive session, PuTTY receives a stream of 8-bit
1242 bytes from the server, and in order to display them on the screen it
1243 needs to know what character set to interpret them in. Similarly,
1244 PuTTY needs to know how to translate your keystrokes into the encoding
1245 the server expects. Unfortunately, there is no satisfactory
1246 mechanism for PuTTY and the server to communicate this information,
1247 so it must usually be manually configured.
1248
1249 There are a lot of character sets to choose from. The \q{Remote
1250 character set} option lets you select one. By default PuTTY will
1251 attempt to choose a character set that is right for your \i{locale} as
1252 reported by Windows; if it gets it wrong, you can select a different
1253 one using this control.
1254
1255 A few notable character sets are:
1256
1257 \b The \i{ISO-8859} series are all standard character sets that include
1258 various accented characters appropriate for different sets of
1259 languages.
1260
1261 \b The \i{Win125x} series are defined by Microsoft, for similar
1262 purposes. In particular Win1252 is almost equivalent to ISO-8859-1,
1263 but contains a few extra characters such as matched quotes and the
1264 Euro symbol.
1265
1266 \b If you want the old IBM PC character set with block graphics and
1267 line-drawing characters, you can select \q{\i{CP437}}.
1268
1269 \b PuTTY also supports \i{Unicode} mode, in which the data coming from
1270 the server is interpreted as being in the \i{UTF-8} encoding of Unicode,
1271 and keystrokes are sent UTF-8 encoded. If you select \q{UTF-8} as a
1272 character set you can use this mode. Not all server-side applications
1273 will support it.
1274
1275 If you need support for a numeric \i{code page} which is not listed in
1276 the drop-down list, such as code page 866, then you can try entering
1277 its name manually (\c{\i{CP866}} for example) in the list box. If the
1278 underlying version of Windows has the appropriate translation table
1279 installed, PuTTY will use it.
1280
1281 \S{config-cjk-ambig-wide} \q{Treat \i{CJK} ambiguous characters as wide}
1282
1283 \cfg{winhelp-topic}{translation.cjkambigwide}
1284
1285 There are \I{East Asian Ambiguous characters}some Unicode characters
1286 whose \I{character width}width is not well-defined. In most contexts, such
1287 characters should be treated as single-width for the purposes of \I{wrapping,
1288 terminal}wrapping and so on; however, in some CJK contexts, they are better
1289 treated as double-width for historical reasons, and some server-side
1290 applications may expect them to be displayed as such. Setting this option
1291 will cause PuTTY to take the double-width interpretation.
1292
1293 If you use legacy CJK applications, and you find your lines are
1294 wrapping in the wrong places, or you are having other display
1295 problems, you might want to play with this setting.
1296
1297 This option only has any effect in \i{UTF-8} mode (see \k{config-charset}).
1298
1299 \S{config-cyr} \q{\i{Caps Lock} acts as \i{Cyrillic} switch}
1300
1301 \cfg{winhelp-topic}{translation.cyrillic}
1302
1303 This feature allows you to switch between a US/UK keyboard layout
1304 and a Cyrillic keyboard layout by using the Caps Lock key, if you
1305 need to type (for example) \i{Russian} and English side by side in the
1306 same document.
1307
1308 Currently this feature is not expected to work properly if your
1309 native keyboard layout is not US or UK.
1310
1311 \S{config-linedraw} Controlling display of \i{line-drawing characters}
1312
1313 \cfg{winhelp-topic}{translation.linedraw}
1314
1315 VT100-series terminals allow the server to send \i{control sequence}s that
1316 shift temporarily into a separate character set for drawing simple
1317 lines and boxes. However, there are a variety of ways in which PuTTY
1318 can attempt to find appropriate characters, and the right one to use
1319 depends on the locally configured \i{font}. In general you should probably
1320 try lots of options until you find one that your particular font
1321 supports.
1322
1323 \b \q{Use Unicode line drawing code points} tries to use the box
1324 characters that are present in \i{Unicode}. For good Unicode-supporting
1325 fonts this is probably the most reliable and functional option.
1326
1327 \b \q{Poor man's line drawing} assumes that the font \e{cannot}
1328 generate the line and box characters at all, so it will use the
1329 \c{+}, \c{-} and \c{|} characters to draw approximations to boxes.
1330 You should use this option if none of the other options works.
1331
1332 \b \q{Font has XWindows encoding} is for use with fonts that have a
1333 special encoding, where the lowest 32 character positions (below the
1334 ASCII printable range) contain the line-drawing characters. This is
1335 unlikely to be the case with any standard Windows font; it will
1336 probably only apply to custom-built fonts or fonts that have been
1337 automatically converted from the X Window System.
1338
1339 \b \q{Use font in both ANSI and OEM modes} tries to use the same
1340 font in two different character sets, to obtain a wider range of
1341 characters. This doesn't always work; some fonts claim to be a
1342 different size depending on which character set you try to use.
1343
1344 \b \q{Use font in OEM mode only} is more reliable than that, but can
1345 miss out other characters from the main character set.
1346
1347 \S{config-linedrawpaste} Controlling \i{copy and paste} of line drawing
1348 characters
1349
1350 \cfg{winhelp-topic}{selection.linedraw}
1351
1352 By default, when you copy and paste a piece of the PuTTY screen that
1353 contains VT100 line and box drawing characters, PuTTY will paste
1354 them in the form they appear on the screen: either \i{Unicode} line
1355 drawing code points, or the \q{poor man's} line-drawing characters
1356 \c{+}, \c{-} and \c{|}. The checkbox \q{Copy and paste VT100 line
1357 drawing chars as lqqqk} disables this feature, so line-drawing
1358 characters will be pasted as the \i{ASCII} characters that were printed
1359 to produce them. This will typically mean they come out mostly as
1360 \c{q} and \c{x}, with a scattering of \c{jklmntuvw} at the corners.
1361 This might be useful if you were trying to recreate the same box
1362 layout in another program, for example.
1363
1364 Note that this option only applies to line-drawing characters which
1365 \e{were} printed by using the VT100 mechanism. Line-drawing
1366 characters that were received as Unicode code points will paste as
1367 Unicode always.
1368
1369 \H{config-selection} The Selection panel
1370
1371 The Selection panel allows you to control the way \i{copy and paste}
1372 work in the PuTTY window.
1373
1374 \S{config-rtfpaste} Pasting in \i{Rich Text Format}
1375
1376 \cfg{winhelp-topic}{selection.rtf}
1377
1378 If you enable \q{Paste to clipboard in RTF as well as plain text},
1379 PuTTY will write formatting information to the clipboard as well as
1380 the actual text you copy. The effect of this is
1381 that if you paste into (say) a word processor, the text will appear
1382 in the word processor in the same \i{font}, \i{colour}, and style
1383 (e.g. bold, underline) PuTTY was using to display it.
1384
1385 This option can easily be inconvenient, so by default it is
1386 disabled.
1387
1388 \S{config-mouse} Changing the actions of the mouse buttons
1389
1390 \cfg{winhelp-topic}{selection.buttons}
1391
1392 PuTTY's copy and paste mechanism is by default modelled on the Unix
1393 \c{xterm} application. The X Window System uses a three-button mouse,
1394 and the convention is that the \i{left button} \I{selecting text}selects,
1395 the \i{right button} extends an existing selection, and the
1396 \i{middle button} pastes.
1397
1398 Windows often only has two mouse buttons, so in PuTTY's default
1399 configuration (\q{Compromise}), the \e{right} button pastes, and the
1400 \e{middle} button (if you have one) \I{adjusting a selection}extends
1401 a selection.
1402
1403 If you have a \i{three-button mouse} and you are already used to the
1404 \c{xterm} arrangement, you can select it using the \q{Action of
1405 mouse buttons} control.
1406
1407 Alternatively, with the \q{Windows} option selected, the middle
1408 button extends, and the right button brings up a \i{context menu} (on
1409 which one of the options is \q{Paste}). (This context menu is always
1410 available by holding down Ctrl and right-clicking, regardless of the
1411 setting of this option.)
1412
1413 \S{config-mouseshift} \q{Shift overrides application's use of mouse}
1414
1415 \cfg{winhelp-topic}{selection.shiftdrag}
1416
1417 PuTTY allows the server to send \i{control codes} that let it
1418 \I{mouse reporting}take over the mouse and use it for purposes other
1419 than \i{copy and paste}.
1420 Applications which use this feature include the text-mode web
1421 browser \c{links}, the Usenet newsreader \c{trn} version 4, and the
1422 file manager \c{mc} (Midnight Commander).
1423
1424 When running one of these applications, pressing the mouse buttons
1425 no longer performs copy and paste. If you do need to copy and paste,
1426 you can still do so if you hold down Shift while you do your mouse
1427 clicks.
1428
1429 However, it is possible in theory for applications to even detect
1430 and make use of Shift + mouse clicks. We don't know of any
1431 applications that do this, but in case someone ever writes one,
1432 unchecking the \q{Shift overrides application's use of mouse}
1433 checkbox will cause Shift + mouse clicks to go to the server as well
1434 (so that mouse-driven copy and paste will be completely disabled).
1435
1436 If you want to prevent the application from taking over the mouse at
1437 all, you can do this using the Features control panel; see
1438 \k{config-features-mouse}.
1439
1440 \S{config-rectselect} Default selection mode
1441
1442 \cfg{winhelp-topic}{selection.rect}
1443
1444 As described in \k{using-selection}, PuTTY has two modes of
1445 selecting text to be copied to the clipboard. In the default mode
1446 (\q{Normal}), dragging the mouse from point A to point B selects to
1447 the end of the line containing A, all the lines in between, and from
1448 the very beginning of the line containing B. In the other mode
1449 (\q{Rectangular block}), dragging the mouse between two points
1450 defines a rectangle, and everything within that rectangle is copied.
1451
1452 Normally, you have to hold down Alt while dragging the mouse to
1453 select a rectangular block. Using the \q{Default selection mode}
1454 control, you can set \i{rectangular selection} as the default, and then
1455 you have to hold down Alt to get the \e{normal} behaviour.
1456
1457 \S{config-charclasses} Configuring \i{word-by-word selection}
1458
1459 \cfg{winhelp-topic}{selection.charclasses}
1460
1461 PuTTY will select a word at a time in the terminal window if you
1462 \i{double-click} to begin the drag. This panel allows you to control
1463 precisely what is considered to be a word.
1464
1465 Each character is given a \e{class}, which is a small number
1466 (typically 0, 1 or 2). PuTTY considers a single word to be any
1467 number of adjacent characters in the same class. So by modifying the
1468 assignment of characters to classes, you can modify the word-by-word
1469 selection behaviour.
1470
1471 In the default configuration, the \i{character classes} are:
1472
1473 \b Class 0 contains \i{white space} and control characters.
1474
1475 \b Class 1 contains most \i{punctuation}.
1476
1477 \b Class 2 contains letters, numbers and a few pieces of punctuation
1478 (the double quote, minus sign, period, forward slash and
1479 underscore).
1480
1481 So, for example, if you assign the \c{@} symbol into character class
1482 2, you will be able to select an e-mail address with just a double
1483 click.
1484
1485 In order to adjust these assignments, you start by selecting a group
1486 of characters in the list box. Then enter a class number in the edit
1487 box below, and press the \q{Set} button.
1488
1489 This mechanism currently only covers ASCII characters, because it
1490 isn't feasible to expand the list to cover the whole of Unicode.
1491
1492 Character class definitions can be modified by \i{control sequence}s
1493 sent by the server. This configuration option controls the
1494 \e{default} state, which will be restored when you reset the
1495 terminal (see \k{reset-terminal}). However, if you modify this
1496 option in mid-session using \q{Change Settings}, it will take effect
1497 immediately.
1498
1499 \H{config-colours} The Colours panel
1500
1501 The Colours panel allows you to control PuTTY's use of \i{colour}.
1502
1503 \S{config-ansicolour} \q{Allow terminal to specify \i{ANSI colours}}
1504
1505 \cfg{winhelp-topic}{colours.ansi}
1506
1507 This option is enabled by default. If it is disabled, PuTTY will
1508 ignore any \i{control sequence}s sent by the server to request coloured
1509 text.
1510
1511 If you have a particularly garish application, you might want to
1512 turn this option off and make PuTTY only use the default foreground
1513 and background colours.
1514
1515 \S{config-xtermcolour} \q{Allow terminal to use xterm \i{256-colour mode}}
1516
1517 \cfg{winhelp-topic}{colours.xterm256}
1518
1519 This option is enabled by default. If it is disabled, PuTTY will
1520 ignore any control sequences sent by the server which use the
1521 extended 256-colour mode supported by recent versions of \cw{xterm}.
1522
1523 If you have an application which is supposed to use 256-colour mode
1524 and it isn't working, you may find you need to tell your server that
1525 your terminal supports 256 colours. On Unix, you do this by ensuring
1526 that the setting of \i\cw{TERM} describes a 256-colour-capable
1527 terminal. You can check this using a command such as \c{infocmp}:
1528
1529 \c $ infocmp | grep colors
1530 \c colors#256, cols#80, it#8, lines#24, pairs#256,
1531 \e bbbbbbbbbb
1532
1533 If you do not see \cq{colors#256} in the output, you may need to
1534 change your terminal setting. On modern Linux machines, you could
1535 try \cq{xterm-256color}.
1536
1537 \S{config-boldcolour} \q{Bolded text is a different colour}
1538
1539 \cfg{winhelp-topic}{colours.bold}
1540
1541 When the server sends a \i{control sequence} indicating that some text
1542 should be displayed in \i{bold}, PuTTY can handle this two ways. It can
1543 either change the \i{font} for a bold version, or use the same font in a
1544 brighter colour. This control lets you choose which.
1545
1546 By default the box is checked, so non-bold text is displayed in
1547 light grey and bold text is displayed in bright white (and similarly
1548 in other colours). If you uncheck the box, bold and non-bold text
1549 will be displayed in the same colour, and instead the font will
1550 change to indicate the difference.
1551
1552 \S{config-logpalette} \q{Attempt to use \i{logical palettes}}
1553
1554 \cfg{winhelp-topic}{colours.logpal}
1555
1556 Logical palettes are a mechanism by which a Windows application
1557 running on an \i{8-bit colour} display can select precisely the colours
1558 it wants instead of going with the Windows standard defaults.
1559
1560 If you are not getting the colours you ask for on an 8-bit display,
1561 you can try enabling this option. However, be warned that it's never
1562 worked very well.
1563
1564 \S{config-syscolour} \q{Use \i{system colours}}
1565
1566 \cfg{winhelp-topic}{colours.system}
1567
1568 Enabling this option will cause PuTTY to ignore the configured colours
1569 for \I{default background}\I{default foreground}\q{Default
1570 Background/Foreground} and \I{cursor colour}\q{Cursor Colour/Text} (see
1571 \k{config-colourcfg}), instead going with the system-wide defaults.
1572
1573 Note that non-bold and \i{bold text} will be the same colour if this
1574 option is enabled. You might want to change to indicating bold text
1575 by font changes (see \k{config-boldcolour}).
1576
1577 \S{config-colourcfg} Adjusting the colours in the \i{terminal window}
1578
1579 \cfg{winhelp-topic}{colours.config}
1580
1581 The main colour control allows you to specify exactly what colours
1582 things should be displayed in. To modify one of the PuTTY colours,
1583 use the list box to select which colour you want to modify. The \i{RGB
1584 values} for that colour will appear on the right-hand side of the
1585 list box. Now, if you press the \q{Modify} button, you will be
1586 presented with a colour selector, in which you can choose a new
1587 colour to go in place of the old one. (You may also edit the RGB
1588 values directly in the edit boxes, if you wish; each value is an
1589 integer from 0 to 255.)
1590
1591 PuTTY allows you to set the \i{cursor colour}, the \i{default foreground}
1592 and \I{default background}background, and the precise shades of all the
1593 \I{ANSI colours}ANSI configurable colours (black, red, green, yellow, blue,
1594 magenta, cyan, and white). You can also modify the precise shades used for
1595 the \i{bold} versions of these colours; these are used to display bold text
1596 if you have selected \q{Bolded text is a different colour}, and can also be
1597 used if the server asks specifically to use them. (Note that \q{Default
1598 Bold Background} is \e{not} the background colour used for bold text;
1599 it is only used if the server specifically asks for a bold
1600 background.)
1601
1602 \H{config-connection} The Connection panel
1603
1604 The Connection panel allows you to configure options that apply to
1605 more than one type of \i{connection}.
1606
1607 \S{config-keepalive} Using \i{keepalives} to prevent disconnection
1608
1609 \cfg{winhelp-topic}{connection.keepalive}
1610
1611 If you find your sessions are closing unexpectedly (most often with
1612 \q{Connection reset by peer}) after they have been idle for a while,
1613 you might want to try using this option.
1614
1615 Some network \i{routers} and \i{firewalls} need to keep track of all
1616 connections through them. Usually, these firewalls will assume a
1617 connection is dead if no data is transferred in either direction
1618 after a certain time interval. This can cause PuTTY sessions to be
1619 unexpectedly closed by the firewall if no traffic is seen in the
1620 session for some time.
1621
1622 The keepalive option (\q{Seconds between keepalives}) allows you to
1623 configure PuTTY to send data through the session at regular
1624 intervals, in a way that does not disrupt the actual terminal
1625 session. If you find your firewall is cutting \i{idle connections} off,
1626 you can try entering a non-zero value in this field. The value is
1627 measured in seconds; so, for example, if your firewall cuts
1628 connections off after ten minutes then you might want to enter 300
1629 seconds (5 minutes) in the box.
1630
1631 Note that keepalives are not always helpful. They help if you have a
1632 firewall which drops your connection after an idle period; but if
1633 the network between you and the server suffers from \i{breaks in
1634 connectivity} then keepalives can actually make things worse. If a
1635 session is idle, and connectivity is temporarily lost between the
1636 endpoints, but the connectivity is restored before either side tries
1637 to send anything, then there will be no problem - neither endpoint
1638 will notice that anything was wrong. However, if one side does send
1639 something during the break, it will repeatedly try to re-send, and
1640 eventually give up and abandon the connection. Then when
1641 connectivity is restored, the other side will find that the first
1642 side doesn't believe there is an open connection any more.
1643 Keepalives can make this sort of problem worse, because they
1644 increase the probability that PuTTY will attempt to send data during
1645 a break in connectivity. (Other types of periodic network activity
1646 can cause this behaviour; in particular, SSH-2 re-keys can have
1647 this effect. See \k{config-ssh-kex-rekey}.)
1648
1649 Therefore, you might find that keepalives help
1650 connection loss, or you might find they make it worse, depending on
1651 what \e{kind} of network problems you have between you and the
1652 server.
1653
1654 Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
1655 protocols offer no way of implementing them. (For an alternative, see
1656 \k{config-tcp-keepalives}.)
1657
1658 Note that if you are using \i{SSH-1} and the server has a bug that makes
1659 it unable to deal with SSH-1 ignore messages (see
1660 \k{config-ssh-bug-ignore1}), enabling keepalives will have no effect.
1661
1662 \S{config-nodelay} \q{Disable \i{Nagle's algorithm}}
1663
1664 \cfg{winhelp-topic}{connection.nodelay}
1665
1666 Nagle's algorithm is a detail of TCP/IP implementations that tries
1667 to minimise the number of small data packets sent down a network
1668 connection. With Nagle's algorithm enabled, PuTTY's \i{bandwidth} usage
1669 will be slightly more efficient; with it disabled, you may find you
1670 get a faster response to your keystrokes when connecting to some
1671 types of server.
1672
1673 The Nagle algorithm is disabled by default for \i{interactive connections}.
1674
1675 \S{config-tcp-keepalives} \q{Enable \i{TCP keepalives}}
1676
1677 \cfg{winhelp-topic}{connection.tcpkeepalive}
1678
1679 \e{NOTE:} TCP keepalives should not be confused with the
1680 application-level keepalives described in \k{config-keepalive}. If in
1681 doubt, you probably want application-level keepalives; TCP keepalives
1682 are provided for completeness.
1683
1684 The idea of TCP keepalives is similar to application-level keepalives,
1685 and the same caveats apply. The main differences are:
1686
1687 \b TCP keepalives are available on \e{all} connection types, including
1688 Raw and Rlogin.
1689
1690 \b The interval between TCP keepalives is usually much longer,
1691 typically two hours; this is set by the operating system, and cannot
1692 be configured within PuTTY.
1693
1694 \b If the operating system does not receive a response to a keepalive,
1695 it may send out more in quick succession and terminate the connection
1696 if no response is received.
1697
1698 TCP keepalives may be more useful for ensuring that \i{half-open connections}
1699 are terminated than for keeping a connection alive.
1700
1701 TCP keepalives are disabled by default.
1702
1703 \S{config-address-family} \I{Internet protocol version}\q{Internet protocol}
1704
1705 \cfg{winhelp-topic}{connection.ipversion}
1706
1707 This option allows the user to select between the old and new
1708 Internet protocols and addressing schemes (\i{IPv4} and \i{IPv6}).
1709 The selected protocol will be used for most outgoing network
1710 connections (including connections to \I{proxy}proxies); however,
1711 tunnels have their own configuration, for which see
1712 \k{config-ssh-portfwd-address-family}.
1713
1714 The default setting is \q{Auto}, which means PuTTY will do something
1715 sensible and try to guess which protocol you wanted. (If you specify
1716 a literal \i{Internet address}, it will use whichever protocol that
1717 address implies. If you provide a \i{hostname}, it will see what kinds
1718 of address exist for that hostname; it will use IPv6 if there is an
1719 IPv6 address available, and fall back to IPv4 if not.)
1720
1721 If you need to force PuTTY to use a particular protocol, you can
1722 explicitly set this to \q{IPv4} or \q{IPv6}.
1723
1724 \S{config-loghost} \I{logical host name}\q{Logical name of remote host}
1725
1726 \cfg{winhelp-topic}{connection.loghost}
1727
1728 This allows you to tell PuTTY that the host it will really end up
1729 connecting to is different from where it thinks it is making a
1730 network connection.
1731
1732 You might use this, for instance, if you had set up an SSH port
1733 forwarding in one PuTTY session so that connections to some
1734 arbitrary port (say, \cw{localhost} port 10022) were forwarded to a
1735 second machine's SSH port (say, \cw{foovax} port 22), and then
1736 started a second PuTTY connecting to the forwarded port.
1737
1738 In normal usage, the second PuTTY will access the host key cache
1739 under the host name and port it actually connected to (i.e.
1740 \cw{localhost} port 10022 in this example). Using the logical host
1741 name option, however, you can configure the second PuTTY to cache
1742 the host key under the name of the host \e{you} know that it's
1743 \e{really} going to end up talking to (here \c{foovax}).
1744
1745 This can be useful if you expect to connect to the same actual
1746 server through many different channels (perhaps because your port
1747 forwarding arrangements keep changing): by consistently setting the
1748 logical host name, you can arrange that PuTTY will not keep asking
1749 you to reconfirm its host key. Conversely, if you expect to use the
1750 same local port number for port forwardings to lots of different
1751 servers, you probably didn't want any particular server's host key
1752 cached under that local port number.
1753
1754 If you just enter a host name for this option, PuTTY will cache the
1755 SSH host key under the default SSH port for that host, irrespective
1756 of the port you really connected to (since the typical scenario is
1757 like the above example: you connect to a silly real port number and
1758 your connection ends up forwarded to the normal port-22 SSH server
1759 of some other machine). To override this, you can append a port
1760 number to the logical host name, separated by a colon. E.g. entering
1761 \cq{foovax:2200} as the logical host name will cause the host key to
1762 be cached as if you had connected to port 2200 of \c{foovax}.
1763
1764 If you provide a host name using this option, it is also displayed
1765 in other locations which contain the remote host name, such as the
1766 default window title and the default SSH password prompt. This
1767 reflects the fact that this is the host you're \e{really} connecting
1768 to, which is more important than the mere means you happen to be
1769 using to contact that host. (This applies even if you're using a
1770 protocol other than SSH.)
1771
1772 \H{config-data} The Data panel
1773
1774 The Data panel allows you to configure various pieces of data which
1775 can be sent to the server to affect your connection at the far end.
1776
1777 Each option on this panel applies to more than one protocol.
1778 Options which apply to only one protocol appear on that protocol's
1779 configuration panels.
1780
1781 \S{config-username} \q{\ii{Auto-login username}}
1782
1783 \cfg{winhelp-topic}{connection.username}
1784
1785 All three of the SSH, Telnet and Rlogin protocols allow you to
1786 specify what user name you want to log in as, without having to type
1787 it explicitly every time. (Some Telnet servers don't support this.)
1788
1789 In this box you can type that user name.
1790
1791 \S{config-username-from-env} \q{Use of system username}
1792
1793 \cfg{winhelp-topic}{connection.usernamefromenv}
1794
1795 When the previous box (\k{config-username}) is left blank, by default,
1796 PuTTY will prompt for a username at the time you make a connection.
1797
1798 In some environments, such as large corporate networks with \i{single
1799 sign-on}, a more sensible default may be to use the name of the user
1800 logged in to the local operating system (if any). This control allows
1801 you to change the default behaviour.
1802
1803 The current system username is displayed in the dialog as a
1804 convenience. It is not saved in the configuration; if a saved session
1805 is later used by a different user, that user's name will be used.
1806
1807 \S{config-termtype} \q{\ii{Terminal-type} string}
1808
1809 \cfg{winhelp-topic}{connection.termtype}
1810
1811 Most servers you might connect to with PuTTY are designed to be
1812 connected to from lots of different types of terminal. In order to
1813 send the right \i{control sequence}s to each one, the server will need
1814 to know what type of terminal it is dealing with. Therefore, each of
1815 the SSH, Telnet and Rlogin protocols allow a text string to be sent
1816 down the connection describing the terminal. On a \i{Unix} server,
1817 this selects an entry from the \i\c{termcap} or \i\c{terminfo} database
1818 that tells applications what \i{control sequences} to send to the
1819 terminal, and what character sequences to expect the \i{keyboard}
1820 to generate.
1821
1822 PuTTY attempts to emulate the Unix \i\c{xterm} program, and by default
1823 it reflects this by sending \c{xterm} as a terminal-type string. If
1824 you find this is not doing what you want - perhaps the remote
1825 system reports \q{Unknown terminal type} - you could try setting
1826 this to something different, such as \i\c{vt220}.
1827
1828 If you're not sure whether a problem is due to the terminal type
1829 setting or not, you probably need to consult the manual for your
1830 application or your server.
1831
1832 \S{config-termspeed} \q{\ii{Terminal speed}s}
1833
1834 \cfg{winhelp-topic}{connection.termspeed}
1835
1836 The Telnet, Rlogin, and SSH protocols allow the client to specify
1837 terminal speeds to the server.
1838
1839 This parameter does \e{not} affect the actual speed of the connection,
1840 which is always \q{as fast as possible}; it is just a hint that is
1841 sometimes used by server software to modify its behaviour. For
1842 instance, if a slow speed is indicated, the server may switch to a
1843 less \i{bandwidth}-hungry display mode.
1844
1845 The value is usually meaningless in a network environment, but
1846 PuTTY lets you configure it, in case you find the server is reacting
1847 badly to the default value.
1848
1849 The format is a pair of numbers separated by a comma, for instance,
1850 \c{38400,38400}. The first number represents the output speed
1851 (\e{from} the server) in bits per second, and the second is the input
1852 speed (\e{to} the server). (Only the first is used in the Rlogin
1853 protocol.)
1854
1855 This option has no effect on Raw connections.
1856
1857 \S{config-environ} Setting \i{environment variables} on the server
1858
1859 \cfg{winhelp-topic}{telnet.environ}
1860
1861 The Telnet protocol provides a means for the client to pass
1862 environment variables to the server. Many Telnet servers have
1863 stopped supporting this feature due to security flaws, but PuTTY
1864 still supports it for the benefit of any servers which have found
1865 other ways around the security problems than just disabling the
1866 whole mechanism.
1867
1868 Version 2 of the SSH protocol also provides a similar mechanism,
1869 which is easier to implement without security flaws. Newer \i{SSH-2}
1870 servers are more likely to support it than older ones.
1871
1872 This configuration data is not used in the SSH-1, rlogin or raw
1873 protocols.
1874
1875 To add an environment variable to the list transmitted down the
1876 connection, you enter the variable name in the \q{Variable} box,
1877 enter its value in the \q{Value} box, and press the \q{Add} button.
1878 To remove one from the list, select it in the list box and press
1879 \q{Remove}.
1880
1881 \H{config-proxy} The Proxy panel
1882
1883 \cfg{winhelp-topic}{proxy.main}
1884
1885 The \ii{Proxy} panel allows you to configure PuTTY to use various types
1886 of proxy in order to make its network connections. The settings in
1887 this panel affect the primary network connection forming your PuTTY
1888 session, and also any extra connections made as a result of SSH \i{port
1889 forwarding} (see \k{using-port-forwarding}).
1890
1891 Note that unlike some software (such as web browsers), PuTTY does not
1892 attempt to automatically determine whether to use a proxy and (if so)
1893 which one to use for a given destination. If you need to use a proxy,
1894 it must always be explicitly configured.
1895
1896 \S{config-proxy-type} Setting the proxy type
1897
1898 \cfg{winhelp-topic}{proxy.type}
1899
1900 The \q{Proxy type} radio buttons allow you to configure what type of
1901 proxy you want PuTTY to use for its network connections. The default
1902 setting is \q{None}; in this mode no proxy is used for any
1903 connection.
1904
1905 \b Selecting \I{HTTP proxy}\q{HTTP} allows you to proxy your connections
1906 through a web server supporting the HTTP \cw{CONNECT} command, as documented
1907 in \W{http://www.ietf.org/rfc/rfc2817.txt}{RFC 2817}.
1908
1909 \b Selecting \q{SOCKS 4} or \q{SOCKS 5} allows you to proxy your
1910 connections through a \i{SOCKS server}.
1911
1912 \b Many firewalls implement a less formal type of proxy in which a
1913 user can make a Telnet connection directly to the firewall machine
1914 and enter a command such as \c{connect myhost.com 22} to connect
1915 through to an external host. Selecting \I{Telnet proxy}\q{Telnet}
1916 allows you to tell PuTTY to use this type of proxy.
1917
1918 \b Selecting \I{Local proxy}\q{Local} allows you to specify an arbitrary
1919 command on the local machine to act as a proxy. When the session is
1920 started, instead of creating a TCP connection, PuTTY runs the command
1921 (specified in \k{config-proxy-command}), and uses its standard input and
1922 output streams.
1923
1924 \lcont{
1925 This could be used, for instance, to talk to some kind of network proxy
1926 that PuTTY does not natively support; or you could tunnel a connection
1927 over something other than TCP/IP entirely.
1928
1929 If you want your local proxy command to make a secondary SSH
1930 connection to a proxy host and then tunnel the primary connection
1931 over that, you might well want the \c{-nc} command-line option in
1932 Plink. See \k{using-cmdline-ncmode} for more information.
1933 }
1934
1935 \S{config-proxy-exclude} Excluding parts of the network from proxying
1936
1937 \cfg{winhelp-topic}{proxy.exclude}
1938
1939 Typically you will only need to use a proxy to connect to non-local
1940 parts of your network; for example, your proxy might be required for
1941 connections outside your company's internal network. In the
1942 \q{Exclude Hosts/IPs} box you can enter ranges of IP addresses, or
1943 ranges of DNS names, for which PuTTY will avoid using the proxy and
1944 make a direct connection instead.
1945
1946 The \q{Exclude Hosts/IPs} box may contain more than one exclusion
1947 range, separated by commas. Each range can be an IP address or a DNS
1948 name, with a \c{*} character allowing wildcards. For example:
1949
1950 \c *.example.com
1951
1952 This excludes any host with a name ending in \c{.example.com} from
1953 proxying.
1954
1955 \c 192.168.88.*
1956
1957 This excludes any host with an IP address starting with 192.168.88
1958 from proxying.
1959
1960 \c 192.168.88.*,*.example.com
1961
1962 This excludes both of the above ranges at once.
1963
1964 Connections to the local host (the host name \i\c{localhost}, and any
1965 \i{loopback IP address}) are never proxied, even if the proxy exclude
1966 list does not explicitly contain them. It is very unlikely that this
1967 behaviour would ever cause problems, but if it does you can change
1968 it by enabling \q{Consider proxying local host connections}.
1969
1970 Note that if you are doing \I{proxy DNS}DNS at the proxy (see
1971 \k{config-proxy-dns}), you should make sure that your proxy
1972 exclusion settings do not depend on knowing the IP address of a
1973 host. If the name is passed on to the proxy without PuTTY looking it
1974 up, it will never know the IP address and cannot check it against
1975 your list.
1976
1977 \S{config-proxy-dns} \I{proxy DNS}\ii{Name resolution} when using a proxy
1978
1979 \cfg{winhelp-topic}{proxy.dns}
1980
1981 If you are using a proxy to access a private network, it can make a
1982 difference whether \i{DNS} name resolution is performed by PuTTY itself
1983 (on the client machine) or performed by the proxy.
1984
1985 The \q{Do DNS name lookup at proxy end} configuration option allows
1986 you to control this. If you set it to \q{No}, PuTTY will always do
1987 its own DNS, and will always pass an IP address to the proxy. If you
1988 set it to \q{Yes}, PuTTY will always pass host names straight to the
1989 proxy without trying to look them up first.
1990
1991 If you set this option to \q{Auto} (the default), PuTTY will do
1992 something it considers appropriate for each type of proxy. Telnet,
1993 HTTP, and SOCKS5 proxies will have host names passed straight to
1994 them; SOCKS4 proxies will not.
1995
1996 Note that if you are doing DNS at the proxy, you should make sure
1997 that your proxy exclusion settings (see \k{config-proxy-exclude}) do
1998 not depend on knowing the IP address of a host. If the name is
1999 passed on to the proxy without PuTTY looking it up, it will never
2000 know the IP address and cannot check it against your list.
2001
2002 The original SOCKS 4 protocol does not support proxy-side DNS. There
2003 is a protocol extension (SOCKS 4A) which does support it, but not
2004 all SOCKS 4 servers provide this extension. If you enable proxy DNS
2005 and your SOCKS 4 server cannot deal with it, this might be why.
2006
2007 \S{config-proxy-auth} \I{proxy username}Username and \I{proxy password}password
2008
2009 \cfg{winhelp-topic}{proxy.auth}
2010
2011 If your proxy requires \I{proxy authentication}authentication, you can
2012 enter a username and a password in the \q{Username} and \q{Password} boxes.
2013
2014 \I{security hazard}Note that if you save your session, the proxy
2015 password will be saved in plain text, so anyone who can access your PuTTY
2016 configuration data will be able to discover it.
2017
2018 Authentication is not fully supported for all forms of proxy:
2019
2020 \b Username and password authentication is supported for HTTP
2021 proxies and SOCKS 5 proxies.
2022
2023 \lcont{
2024
2025 \b With SOCKS 5, authentication is via \i{CHAP} if the proxy
2026 supports it (this is not supported in \i{PuTTYtel}); otherwise the
2027 password is sent to the proxy in \I{plaintext password}plain text.
2028
2029 \b With HTTP proxying, the only currently supported authentication
2030 method is \I{HTTP basic}\q{basic}, where the password is sent to the proxy
2031 in \I{plaintext password}plain text.
2032
2033 }
2034
2035 \b SOCKS 4 can use the \q{Username} field, but does not support
2036 passwords.
2037
2038 \b You can specify a way to include a username and password in the
2039 Telnet/Local proxy command (see \k{config-proxy-command}).
2040
2041 \S{config-proxy-command} Specifying the Telnet or Local proxy command
2042
2043 \cfg{winhelp-topic}{proxy.command}
2044
2045 If you are using the \i{Telnet proxy} type, the usual command required
2046 by the firewall's Telnet server is \c{connect}, followed by a host
2047 name and a port number. If your proxy needs a different command,
2048 you can enter an alternative here.
2049
2050 If you are using the \i{Local proxy} type, the local command to run
2051 is specified here.
2052
2053 In this string, you can use \c{\\n} to represent a new-line, \c{\\r}
2054 to represent a carriage return, \c{\\t} to represent a tab
2055 character, and \c{\\x} followed by two hex digits to represent any
2056 other character. \c{\\\\} is used to encode the \c{\\} character
2057 itself.
2058
2059 Also, the special strings \c{%host} and \c{%port} will be replaced
2060 by the host name and port number you want to connect to. The strings
2061 \c{%user} and \c{%pass} will be replaced by the proxy username and
2062 password you specify. The strings \c{%proxyhost} and \c{%proxyport}
2063 will be replaced by the host details specified on the \e{Proxy} panel,
2064 if any (this is most likely to be useful for the Local proxy type).
2065 To get a literal \c{%} sign, enter \c{%%}.
2066
2067 If a Telnet proxy server prompts for a username and password
2068 before commands can be sent, you can use a command such as:
2069
2070 \c %user\n%pass\nconnect %host %port\n
2071
2072 This will send your username and password as the first two lines to
2073 the proxy, followed by a command to connect to the desired host and
2074 port. Note that if you do not include the \c{%user} or \c{%pass}
2075 tokens in the Telnet command, then the \q{Username} and \q{Password}
2076 configuration fields will be ignored.
2077
2078 \H{config-telnet} The \i{Telnet} panel
2079
2080 The Telnet panel allows you to configure options that only apply to
2081 Telnet sessions.
2082
2083 \S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
2084
2085 \cfg{winhelp-topic}{telnet.oldenviron}
2086
2087 The original Telnet mechanism for passing \i{environment variables} was
2088 badly specified. At the time the standard (RFC 1408) was written,
2089 BSD telnet implementations were already supporting the feature, and
2090 the intention of the standard was to describe the behaviour the BSD
2091 implementations were already using.
2092
2093 Sadly there was a typing error in the standard when it was issued,
2094 and two vital function codes were specified the wrong way round. BSD
2095 implementations did not change, and the standard was not corrected.
2096 Therefore, it's possible you might find either \i{BSD} or \i{RFC}-compliant
2097 implementations out there. This switch allows you to choose which
2098 one PuTTY claims to be.
2099
2100 The problem was solved by issuing a second standard, defining a new
2101 Telnet mechanism called \i\cw{NEW_ENVIRON}, which behaved exactly like
2102 the original \i\cw{OLD_ENVIRON} but was not encumbered by existing
2103 implementations. Most Telnet servers now support this, and it's
2104 unambiguous. This feature should only be needed if you have trouble
2105 passing environment variables to quite an old server.
2106
2107 \S{config-ptelnet} Passive and active \i{Telnet negotiation} modes
2108
2109 \cfg{winhelp-topic}{telnet.passive}
2110
2111 In a Telnet connection, there are two types of data passed between
2112 the client and the server: actual text, and \e{negotiations} about
2113 which Telnet extra features to use.
2114
2115 PuTTY can use two different strategies for negotiation:
2116
2117 \b In \I{active Telnet negotiation}\e{active} mode, PuTTY starts to send
2118 negotiations as soon as the connection is opened.
2119
2120 \b In \I{passive Telnet negotiation}\e{passive} mode, PuTTY will wait to
2121 negotiate until it sees a negotiation from the server.
2122
2123 The obvious disadvantage of passive mode is that if the server is
2124 also operating in a passive mode, then negotiation will never begin
2125 at all. For this reason PuTTY defaults to active mode.
2126
2127 However, sometimes passive mode is required in order to successfully
2128 get through certain types of firewall and \i{Telnet proxy} server. If
2129 you have confusing trouble with a \i{firewall}, you could try enabling
2130 passive mode to see if it helps.
2131
2132 \S{config-telnetkey} \q{Keyboard sends \i{Telnet special commands}}
2133
2134 \cfg{winhelp-topic}{telnet.specialkeys}
2135
2136 If this box is checked, several key sequences will have their normal
2137 actions modified:
2138
2139 \b the Backspace key on the keyboard will send the \I{Erase Character,
2140 Telnet special command}Telnet special backspace code;
2141
2142 \b Control-C will send the Telnet special \I{Interrupt Process, Telnet
2143 special command}Interrupt Process code;
2144
2145 \b Control-Z will send the Telnet special \I{Suspend Process, Telnet
2146 special command}Suspend Process code.
2147
2148 You probably shouldn't enable this
2149 unless you know what you're doing.
2150
2151 \S{config-telnetnl} \q{Return key sends \i{Telnet New Line} instead of ^M}
2152
2153 \cfg{winhelp-topic}{telnet.newline}
2154
2155 Unlike most other remote login protocols, the Telnet protocol has a
2156 special \q{\i{new line}} code that is not the same as the usual line
2157 endings of Control-M or Control-J. By default, PuTTY sends the
2158 Telnet New Line code when you press Return, instead of sending
2159 Control-M as it does in most other protocols.
2160
2161 Most Unix-style Telnet servers don't mind whether they receive
2162 Telnet New Line or Control-M; some servers do expect New Line, and
2163 some servers prefer to see ^M. If you are seeing surprising
2164 behaviour when you press Return in a Telnet session, you might try
2165 turning this option off to see if it helps.
2166
2167 \H{config-rlogin} The Rlogin panel
2168
2169 The \i{Rlogin} panel allows you to configure options that only apply to
2170 Rlogin sessions.
2171
2172 \S{config-rlogin-localuser} \I{local username in Rlogin}\q{Local username}
2173
2174 \cfg{winhelp-topic}{rlogin.localuser}
2175
2176 Rlogin allows an automated (password-free) form of login by means of
2177 a file called \i\c{.rhosts} on the server. You put a line in your
2178 \c{.rhosts} file saying something like \c{jbloggs@pc1.example.com},
2179 and then when you make an Rlogin connection the client transmits the
2180 username of the user running the Rlogin client. The server checks
2181 the username and hostname against \c{.rhosts}, and if they match it
2182 \I{passwordless login}does not ask for a password.
2183
2184 This only works because Unix systems contain a safeguard to stop a
2185 user from pretending to be another user in an Rlogin connection.
2186 Rlogin connections have to come from \I{privileged port}port numbers below
2187 1024, and Unix systems prohibit this to unprivileged processes; so when the
2188 server sees a connection from a low-numbered port, it assumes the
2189 client end of the connection is held by a privileged (and therefore
2190 trusted) process, so it believes the claim of who the user is.
2191
2192 Windows does not have this restriction: \e{any} user can initiate an
2193 outgoing connection from a low-numbered port. Hence, the Rlogin
2194 \c{.rhosts} mechanism is completely useless for securely
2195 distinguishing several different users on a Windows machine. If you
2196 have a \c{.rhosts} entry pointing at a Windows PC, you should assume
2197 that \e{anyone} using that PC can \i{spoof} your username in
2198 an Rlogin connection and access your account on the server.
2199
2200 The \q{Local username} control allows you to specify what user name
2201 PuTTY should claim you have, in case it doesn't match your \i{Windows
2202 user name} (or in case you didn't bother to set up a Windows user
2203 name).
2204
2205 \H{config-ssh} The SSH panel
2206
2207 The \i{SSH} panel allows you to configure options that only apply to
2208 SSH sessions.
2209
2210 \S{config-command} Executing a specific command on the server
2211
2212 \cfg{winhelp-topic}{ssh.command}
2213
2214 In SSH, you don't have to run a general shell session on the server.
2215 Instead, you can choose to run a single specific command (such as a
2216 mail user agent, for example). If you want to do this, enter the
2217 command in the \q{\ii{Remote command}} box.
2218
2219 Note that most servers will close the session after executing the
2220 command.
2221
2222 \S{config-ssh-noshell} \q{Don't start a \I{remote shell}shell or
2223 \I{remote command}command at all}
2224
2225 \cfg{winhelp-topic}{ssh.noshell}
2226
2227 If you tick this box, PuTTY will not attempt to run a shell or
2228 command after connecting to the remote server. You might want to use
2229 this option if you are only using the SSH connection for \i{port
2230 forwarding}, and your user account on the server does not have the
2231 ability to run a shell.
2232
2233 This feature is only available in \i{SSH protocol version 2} (since the
2234 version 1 protocol assumes you will always want to run a shell).
2235
2236 This feature can also be enabled using the \c{-N} command-line
2237 option; see \k{using-cmdline-noshell}.
2238
2239 If you use this feature in Plink, you will not be able to terminate
2240 the Plink process by any graceful means; the only way to kill it
2241 will be by pressing Control-C or sending a kill signal from another
2242 program.
2243
2244 \S{config-ssh-comp} \q{Enable \i{compression}}
2245
2246 \cfg{winhelp-topic}{ssh.compress}
2247
2248 This enables data compression in the SSH connection: data sent by
2249 the server is compressed before sending, and decompressed at the
2250 client end. Likewise, data sent by PuTTY to the server is compressed
2251 first and the server decompresses it at the other end. This can help
2252 make the most of a low-\i{bandwidth} connection.
2253
2254 \S{config-ssh-prot} \q{Preferred \i{SSH protocol version}}
2255
2256 \cfg{winhelp-topic}{ssh.protocol}
2257
2258 This allows you to select whether you would like to use \i{SSH protocol
2259 version 1} or \I{SSH-2}version 2. \#{FIXME: say something about this elsewhere?}
2260
2261 PuTTY will attempt to use protocol 1 if the server you connect to
2262 does not offer protocol 2, and vice versa.
2263
2264 If you select \q{1 only} or \q{2 only} here, PuTTY will only connect
2265 if the server you connect to offers the SSH protocol version you
2266 have specified.
2267
2268 \S{config-ssh-encryption} \ii{Encryption} algorithm selection
2269
2270 \cfg{winhelp-topic}{ssh.ciphers}
2271
2272 PuTTY supports a variety of different \i{encryption algorithm}s, and
2273 allows you to choose which one you prefer to use. You can do this by
2274 dragging the algorithms up and down in the list box (or moving them
2275 using the Up and Down buttons) to specify a preference order. When
2276 you make an SSH connection, PuTTY will search down the list from the
2277 top until it finds an algorithm supported by the server, and then
2278 use that.
2279
2280 PuTTY currently supports the following algorithms:
2281
2282 \b \i{AES} (Rijndael) - 256, 192, or 128-bit SDCTR or CBC (SSH-2 only)
2283
2284 \b \i{Arcfour} (RC4) - 256 or 128-bit stream cipher (SSH-2 only)
2285
2286 \b \i{Blowfish} - 256-bit SDCTR (SSH-2 only) or 128-bit CBC
2287
2288 \b \ii{Triple-DES} - 168-bit SDCTR (SSH-2 only) or CBC
2289
2290 \b \ii{Single-DES} - 56-bit CBC (see below for SSH-2)
2291
2292 If the algorithm PuTTY finds is below the \q{warn below here} line,
2293 you will see a warning box when you make the connection:
2294
2295 \c The first cipher supported by the server
2296 \c is single-DES, which is below the configured
2297 \c warning threshold.
2298 \c Do you want to continue with this connection?
2299
2300 This warns you that the first available encryption is not a very
2301 secure one. Typically you would put the \q{warn below here} line
2302 between the encryptions you consider secure and the ones you
2303 consider substandard. By default, PuTTY supplies a preference order
2304 intended to reflect a reasonable preference in terms of security and
2305 speed.
2306
2307 In SSH-2, the encryption algorithm is negotiated independently for
2308 each direction of the connection, although PuTTY does not support
2309 separate configuration of the preference orders. As a result you may
2310 get two warnings similar to the one above, possibly with different
2311 encryptions.
2312
2313 Single-DES is not recommended in the SSH-2 protocol
2314 standards, but one or two server implementations do support it.
2315 PuTTY can use single-DES to interoperate with
2316 these servers if you enable the \q{Enable legacy use of single-DES in
2317 SSH-2} option; by default this is disabled and PuTTY will stick to
2318 recommended ciphers.
2319
2320 \H{config-ssh-kex} The Kex panel
2321
2322 \# FIXME: This whole section is draft. Feel free to revise.
2323
2324 The Kex panel (short for \q{\i{key exchange}}) allows you to configure
2325 options related to SSH-2 key exchange.
2326
2327 Key exchange occurs at the start of an SSH connection (and
2328 occasionally thereafter); it establishes a \i{shared secret} that is used
2329 as the basis for all of SSH's security features. It is therefore very
2330 important for the security of the connection that the key exchange is
2331 secure.
2332
2333 Key exchange is a cryptographically intensive process; if either the
2334 client or the server is a relatively slow machine, the slower methods
2335 may take several tens of seconds to complete.
2336
2337 If connection startup is too slow, or the connection hangs
2338 periodically, you may want to try changing these settings.
2339
2340 If you don't understand what any of this means, it's safe to leave
2341 these settings alone.
2342
2343 This entire panel is only relevant to SSH protocol version 2; none of
2344 these settings affect SSH-1 at all.
2345
2346 \S{config-ssh-kex-order} \ii{Key exchange algorithm} selection
2347
2348 \cfg{winhelp-topic}{ssh.kex.order}
2349
2350 PuTTY supports a variety of SSH-2 key exchange methods, and allows you
2351 to choose which one you prefer to use; configuration is similar to
2352 cipher selection (see \k{config-ssh-encryption}).
2353
2354 PuTTY currently supports the following varieties of \i{Diffie-Hellman key
2355 exchange}:
2356
2357 \b \q{Group 14}: a well-known 2048-bit group.
2358
2359 \b \q{Group 1}: a well-known 1024-bit group. This is less secure
2360 \#{FIXME better words} than group 14, but may be faster with slow
2361 client or server machines, and may be the only method supported by
2362 older server software.
2363
2364 \b \q{\ii{Group exchange}}: with this method, instead of using a fixed
2365 group, PuTTY requests that the server suggest a group to use for key
2366 exchange; the server can avoid groups known to be weak, and possibly
2367 invent new ones over time, without any changes required to PuTTY's
2368 configuration. We recommend use of this method, if possible.
2369
2370 In addition, PuTTY supports \i{RSA key exchange}, which requires much less
2371 computational effort on the part of the client, and somewhat less on
2372 the part of the server, than Diffie-Hellman key exchange.
2373
2374 If the first algorithm PuTTY finds is below the \q{warn below here}
2375 line, you will see a warning box when you make the connection, similar
2376 to that for cipher selection (see \k{config-ssh-encryption}).
2377
2378 \S{config-ssh-kex-rekey} \ii{Repeat key exchange}
2379
2380 \cfg{winhelp-topic}{ssh.kex.repeat}
2381
2382 If the session key negotiated at connection startup is used too much
2383 or for too long, it may become feasible to mount attacks against the
2384 SSH connection. Therefore, the SSH-2 protocol specifies that a new key
2385 exchange should take place every so often; this can be initiated by
2386 either the client or the server.
2387
2388 While this renegotiation is taking place, no data can pass through
2389 the SSH connection, so it may appear to \q{freeze}. (The occurrence of
2390 repeat key exchange is noted in the Event Log; see
2391 \k{using-eventlog}.) Usually the same algorithm is used as at the
2392 start of the connection, with a similar overhead.
2393
2394 These options control how often PuTTY will initiate a repeat key
2395 exchange (\q{rekey}). You can also force a key exchange at any time
2396 from the Special Commands menu (see \k{using-specials}).
2397
2398 \# FIXME: do we have any additions to the SSH-2 specs' advice on
2399 these values? Do we want to enforce any limits?
2400
2401 \b \q{Max minutes before rekey} specifies the amount of time that is
2402 allowed to elapse before a rekey is initiated. If this is set to zero,
2403 PuTTY will not rekey due to elapsed time. The SSH-2 protocol
2404 specification recommends a timeout of at most 60 minutes.
2405
2406 You might have a need to disable time-based rekeys completely for the same
2407 reasons that \i{keepalives} aren't always helpful. If you anticipate
2408 suffering a network dropout of several hours in the middle of an SSH
2409 connection, but were not actually planning to send \e{data} down
2410 that connection during those hours, then an attempted rekey in the
2411 middle of the dropout will probably cause the connection to be
2412 abandoned, whereas if rekeys are disabled then the connection should
2413 in principle survive (in the absence of interfering \i{firewalls}). See
2414 \k{config-keepalive} for more discussion of these issues; for these
2415 purposes, rekeys have much the same properties as keepalives.
2416 (Except that rekeys have cryptographic value in themselves, so you
2417 should bear that in mind when deciding whether to turn them off.)
2418 Note, however, the the SSH \e{server} can still initiate rekeys.
2419
2420 \b \q{Max data before rekey} specifies the amount of data (in bytes)
2421 that is permitted to flow in either direction before a rekey is
2422 initiated. If this is set to zero, PuTTY will not rekey due to
2423 transferred data. The SSH-2 protocol specification recommends a limit
2424 of at most 1 gigabyte.
2425
2426 \lcont{
2427
2428 As well as specifying a value in bytes, the following shorthand can be
2429 used:
2430
2431 \b \cq{1k} specifies 1 kilobyte (1024 bytes).
2432
2433 \b \cq{1M} specifies 1 megabyte (1024 kilobytes).
2434
2435 \b \cq{1G} specifies 1 gigabyte (1024 megabytes).
2436
2437 }
2438
2439 Disabling data-based rekeys entirely is a bad idea. The \i{integrity},
2440 and to a lesser extent, \i{confidentiality} of the SSH-2 protocol depend
2441 in part on rekeys occuring before a 32-bit packet sequence number
2442 wraps around. Unlike time-based rekeys, data-based rekeys won't occur
2443 when the SSH connection is idle, so they shouldn't cause the same
2444 problems. The SSH-1 protocol, incidentally, has even weaker integrity
2445 protection than SSH-2 without rekeys.
2446
2447 \H{config-ssh-auth} The Auth panel
2448
2449 The Auth panel allows you to configure \i{authentication} options for
2450 SSH sessions.
2451
2452 \S{config-ssh-noauth} \q{Bypass authentication entirely}
2453
2454 \cfg{winhelp-topic}{ssh.auth.bypass}
2455
2456 In SSH-2, it is possible to establish a connection without using SSH's
2457 mechanisms to identify or authenticate oneself to the server. Some
2458 servers may prefer to handle authentication in the data channel, for
2459 instance, or may simply require no authentication whatsoever.
2460
2461 By default, PuTTY assumes the server requires authentication (most
2462 do), and thus must provide a username. If you find you are getting
2463 unwanted username prompts, you could try checking this option.
2464
2465 This option only affects SSH-2 connections. SSH-1 connections always
2466 require an authentication step.
2467
2468 \S{config-ssh-tryagent} \q{Attempt authentication using Pageant}
2469
2470 \cfg{winhelp-topic}{ssh.auth.pageant}
2471
2472 If this option is enabled, then PuTTY will look for Pageant (the SSH
2473 private-key storage agent) and attempt to authenticate with any
2474 suitable public keys Pageant currently holds.
2475
2476 This behaviour is almost always desirable, and is therefore enabled
2477 by default. In rare cases you might need to turn it off in order to
2478 force authentication by some non-public-key method such as
2479 passwords.
2480
2481 This option can also be controlled using the \c{-noagent}
2482 command-line option. See \k{using-cmdline-agentauth}.
2483
2484 See \k{pageant} for more information about Pageant in general.
2485
2486 \S{config-ssh-tis} \q{Attempt \I{TIS authentication}TIS or
2487 \i{CryptoCard authentication}}
2488
2489 \cfg{winhelp-topic}{ssh.auth.tis}
2490
2491 TIS and CryptoCard authentication are (despite their names) generic
2492 forms of simple \I{challenge/response authentication}challenge/response
2493 authentication available in SSH protocol version 1 only. You might use
2494 them if you were using \i{S/Key} \i{one-time passwords}, for example,
2495 or if you had a physical \i{security token} that generated responses
2496 to authentication challenges. They can even be used to prompt for
2497 simple passwords.
2498
2499 With this switch enabled, PuTTY will attempt these forms of
2500 authentication if the server is willing to try them. You will be
2501 presented with a challenge string (which may be different every
2502 time) and must supply the correct response in order to log in. If
2503 your server supports this, you should talk to your system
2504 administrator about precisely what form these challenges and
2505 responses take.
2506
2507 \S{config-ssh-ki} \q{Attempt \i{keyboard-interactive authentication}}
2508
2509 \cfg{winhelp-topic}{ssh.auth.ki}
2510
2511 The SSH-2 equivalent of TIS authentication is called
2512 \q{keyboard-interactive}. It is a flexible authentication method
2513 using an arbitrary sequence of requests and responses; so it is not
2514 only useful for \I{challenge/response authentication}challenge/response
2515 mechanisms such as \i{S/Key}, but it can also be used for (for example)
2516 asking the user for a \I{password expiry}new password when the old one
2517 has expired.
2518
2519 PuTTY leaves this option enabled by default, but supplies a switch
2520 to turn it off in case you should have trouble with it.
2521
2522 \S{config-ssh-agentfwd} \q{Allow \i{agent forwarding}}
2523
2524 \cfg{winhelp-topic}{ssh.auth.agentfwd}
2525
2526 This option allows the SSH server to open forwarded connections back
2527 to your local copy of \i{Pageant}. If you are not running Pageant, this
2528 option will do nothing.
2529
2530 See \k{pageant} for general information on Pageant, and
2531 \k{pageant-forward} for information on agent forwarding. Note that
2532 there is a security risk involved with enabling this option; see
2533 \k{pageant-security} for details.
2534
2535 \S{config-ssh-changeuser} \q{Allow attempted \i{changes of username} in SSH-2}
2536
2537 \cfg{winhelp-topic}{ssh.auth.changeuser}
2538
2539 In the SSH-1 protocol, it is impossible to change username after
2540 failing to authenticate. So if you mis-type your username at the
2541 PuTTY \q{login as:} prompt, you will not be able to change it except
2542 by restarting PuTTY.
2543
2544 The SSH-2 protocol \e{does} allow changes of username, in principle,
2545 but does not make it mandatory for SSH-2 servers to accept them. In
2546 particular, \i{OpenSSH} does not accept a change of username; once you
2547 have sent one username, it will reject attempts to try to
2548 authenticate as another user. (Depending on the version of OpenSSH,
2549 it may quietly return failure for all login attempts, or it may send
2550 an error message.)
2551
2552 For this reason, PuTTY will by default not prompt you for your
2553 username more than once, in case the server complains. If you know
2554 your server can cope with it, you can enable the \q{Allow attempted
2555 changes of username} option to modify PuTTY's behaviour.
2556
2557 \S{config-ssh-privkey} \q{\ii{Private key} file for authentication}
2558
2559 \cfg{winhelp-topic}{ssh.auth.privkey}
2560
2561 This box is where you enter the name of your private key file if you
2562 are using \i{public key authentication}. See \k{pubkey} for information
2563 about public key authentication in SSH.
2564
2565 This key must be in PuTTY's native format (\c{*.\i{PPK}}). If you have a
2566 private key in another format that you want to use with PuTTY, see
2567 \k{puttygen-conversions}.
2568
2569 If a key file is specified here, and \i{Pageant} is running (see
2570 \k{pageant}), PuTTY will first try asking Pageant to authenticate with
2571 that key, and ignore any other keys Pageant may have. If that fails,
2572 PuTTY will ask for a passphrase as normal.
2573
2574 \H{config-ssh-auth-gssapi} The GSSAPI panel
2575
2576 \cfg{winhelp-topic}{ssh.auth.gssapi}
2577
2578 The \q{GSSAPI} subpanel of the \q{Auth} panel controls the use of
2579 GSSAPI authentication. This is a mechanism which delegates the
2580 authentication exchange to a library elsewhere on the client
2581 machine, which in principle can authenticate in many different ways
2582 but in practice is usually used with the Kerberos single-sign-on
2583 protocol.
2584
2585 GSSAPI is only available in the SSH-2 protocol.
2586
2587 The topmost control on the GSSAPI subpanel is the checkbox labelled
2588 \q{Attempt GSSAPI authentication}. If this is disabled, GSSAPI will
2589 not be attempted at all and the rest of this panel is unused. If it
2590 is enabled, GSSAPI authentication will be attempted, and (typically)
2591 if your client machine has valid Kerberos credentials loaded, then
2592 PuTTY should be able to authenticate automatically to servers that
2593 support Kerberos logins.
2594
2595 \S{config-ssh-auth-gssapi-delegation} \q{Allow GSSAPI credential
2596 delegation}
2597
2598 \cfg{winhelp-topic}{ssh.auth.gssapi.delegation}
2599
2600 GSSAPI credential delegation is a mechanism for passing on your
2601 Kerberos (or other) identity to the session on the SSH server. If
2602 you enable this option, then not only will PuTTY be able to log in
2603 automatically to a server that accepts your Kerberos credentials,
2604 but also you will be able to connect out from that server to other
2605 Kerberos-supporting services and use the same credentials just as
2606 automatically.
2607
2608 (This option is the Kerberos analogue of SSH agent forwarding; see
2609 \k{pageant-forward} for some information on that.)
2610
2611 Note that, like SSH agent forwarding, there is a security
2612 implication in the use of this option: the administrator of the
2613 server you connect to, or anyone else who has cracked the
2614 administrator account on that server, could fake your identity when
2615 connecting to further Kerberos-supporting services. However,
2616 Kerberos sites are typically run by a central authority, so the
2617 administrator of one server is likely to already have access to the
2618 other services too; so this would typically be less of a risk than
2619 SSH agent forwarding.
2620
2621 \S{config-ssh-auth-gssapi-libraries} Preference order for GSSAPI
2622 libraries
2623
2624 \cfg{winhelp-topic}{ssh.auth.gssapi.libraries}
2625
2626 GSSAPI is a mechanism which allows more than one authentication
2627 method to be accessed through the same interface. Therefore, more
2628 than one authentication library may exist on your system which can
2629 be accessed using GSSAPI.
2630
2631 PuTTY contains native support for a few well-known such libraries,
2632 and will look for all of them on your system and use whichever it
2633 finds. If more than one exists on your system and you need to use a
2634 specific one, you can adjust the order in which it will search using
2635 this preference list control.
2636
2637 One of the options in the preference list is to use a user-specified
2638 GSSAPI library. If the library you want to use is not mentioned by
2639 name in PuTTY's list of options, you can enter its full pathname in
2640 the \q{User-supplied GSSAPI library path} field, and move the
2641 \q{User-supplied GSSAPI library} option in the preference list to
2642 make sure it is selected before anything else.
2643
2644 \H{config-ssh-tty} The TTY panel
2645
2646 The TTY panel lets you configure the remote pseudo-terminal.
2647
2648 \S{config-ssh-pty} \I{pseudo-terminal allocation}\q{Don't allocate
2649 a pseudo-terminal}
2650
2651 \cfg{winhelp-topic}{ssh.nopty}
2652
2653 When connecting to a \i{Unix} system, most \I{interactive
2654 connections}interactive shell sessions are run in a \e{pseudo-terminal},
2655 which allows the Unix system to pretend it's talking to a real physical
2656 terminal device but allows the SSH server to catch all the data coming
2657 from that fake device and send it back to the client.
2658
2659 Occasionally you might find you have a need to run a session \e{not}
2660 in a pseudo-terminal. In PuTTY, this is generally only useful for
2661 very specialist purposes; although in Plink (see \k{plink}) it is
2662 the usual way of working.
2663
2664 \S{config-ttymodes} Sending \i{terminal modes}
2665
2666 \cfg{winhelp-topic}{ssh.ttymodes}
2667
2668 The SSH protocol allows the client to send \q{terminal modes} for
2669 the remote pseudo-terminal. These usually control the server's
2670 expectation of the local terminal's behaviour.
2671
2672 If your server does not have sensible defaults for these modes, you
2673 may find that changing them here helps. If you don't understand any of
2674 this, it's safe to leave these settings alone.
2675
2676 (None of these settings will have any effect if no pseudo-terminal
2677 is requested or allocated.)
2678
2679 You can add or modify a mode by selecting it from the drop-down list,
2680 choosing whether it's set automatically or to a specific value with
2681 the radio buttons and edit box, and hitting \q{Add}. A mode (or
2682 several) can be removed from the list by selecting them and hitting
2683 \q{Remove}. The effect of the mode list is as follows:
2684
2685 \b If a mode is not on the list, it will not be specified to the
2686 server under any circumstances.
2687
2688 \b If a mode is on the list:
2689
2690 \lcont{
2691
2692 \b If the \q{Auto} option is selected, the PuTTY tools will decide
2693 whether to specify that mode to the server, and if so, will send
2694 a sensible value.
2695
2696 \lcont{
2697
2698 PuTTY proper will send modes that it has an opinion on (currently only
2699 the code for the Backspace key, \cw{ERASE}). Plink on Unix
2700 will propagate appropriate modes from the local terminal, if any.
2701
2702 }
2703
2704 \b If a value is specified, it will be sent to the server under all
2705 circumstances. The precise syntax of the value box depends on the
2706 mode.
2707
2708 }
2709
2710 By default, all of the available modes are listed as \q{Auto},
2711 which should do the right thing in most circumstances.
2712
2713 The precise effect of each setting, if any, is up to the server. Their
2714 names come from \i{POSIX} and other Unix systems, and they are most
2715 likely to have a useful effect on such systems. (These are the same
2716 settings that can usually be changed using the \i\c{stty} command once
2717 logged in to such servers.)
2718
2719 Some notable modes are described below; for fuller explanations, see
2720 your server documentation.
2721
2722 \b \I{ERASE special character}\cw{ERASE} is the character that when typed
2723 by the user will delete one space to the left. When set to \q{Auto}
2724 (the default setting), this follows the setting of the local Backspace
2725 key in PuTTY (see \k{config-backspace}).
2726
2727 \lcont{
2728 This and other \i{special character}s are specified using \c{^C} notation
2729 for Ctrl-C, and so on. Use \c{^<27>} or \c{^<0x1B>} to specify a
2730 character numerically, and \c{^~} to get a literal \c{^}. Other
2731 non-control characters are denoted by themselves. Leaving the box
2732 entirely blank indicates that \e{no} character should be assigned to
2733 the specified function, although this may not be supported by all
2734 servers.
2735 }
2736
2737 \b \I{QUIT special character}\cw{QUIT} is a special character that
2738 usually forcefully ends the current process on the server
2739 (\cw{SIGQUIT}). On many servers its default setting is Ctrl-backslash
2740 (\c{^\\}), which is easy to accidentally invoke on many keyboards. If
2741 this is getting in your way, you may want to change it to another
2742 character or turn it off entirely.
2743
2744 \b Boolean modes such as \cw{ECHO} and \cw{ICANON} can be specified in
2745 PuTTY in a variety of ways, such as \cw{true}/\cw{false},
2746 \cw{yes}/\cw{no}, and \cw{0}/\cw{1}.
2747
2748 \b Terminal speeds are configured elsewhere; see \k{config-termspeed}.
2749
2750 \H{config-ssh-x11} The X11 panel
2751
2752 \cfg{winhelp-topic}{ssh.tunnels.x11}
2753
2754 The X11 panel allows you to configure \i{forwarding of X11} over an
2755 SSH connection.
2756
2757 If your server lets you run X Window System applications, X11
2758 forwarding allows you to securely give those applications access to
2759 a local X display on your PC.
2760
2761 To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
2762 If your X display is somewhere unusual, you will need to enter its
2763 location in the \q{X display location} box; if this is left blank,
2764 PuTTY will try to find a sensible default in the environment, or use the
2765 primary local display (\c{:0}) if that fails.
2766
2767 See \k{using-x-forwarding} for more information about X11
2768 forwarding.
2769
2770 \S{config-ssh-x11auth} Remote \i{X11 authentication}
2771
2772 \cfg{winhelp-topic}{ssh.tunnels.x11auth}
2773
2774 If you are using X11 forwarding, the virtual X server created on the
2775 SSH server machine will be protected by authorisation data. This
2776 data is invented, and checked, by PuTTY.
2777
2778 The usual authorisation method used for this is called
2779 \i\cw{MIT-MAGIC-COOKIE-1}. This is a simple password-style protocol:
2780 the X client sends some cookie data to the server, and the server
2781 checks that it matches the real cookie. The cookie data is sent over
2782 an unencrypted X11 connection; so if you allow a client on a third
2783 machine to access the virtual X server, then the cookie will be sent
2784 in the clear.
2785
2786 PuTTY offers the alternative protocol \i\cw{XDM-AUTHORIZATION-1}. This
2787 is a cryptographically authenticated protocol: the data sent by the
2788 X client is different every time, and it depends on the IP address
2789 and port of the client's end of the connection and is also stamped
2790 with the current time. So an eavesdropper who captures an
2791 \cw{XDM-AUTHORIZATION-1} string cannot immediately re-use it for
2792 their own X connection.
2793
2794 PuTTY's support for \cw{XDM-AUTHORIZATION-1} is a somewhat
2795 experimental feature, and may encounter several problems:
2796
2797 \b Some X clients probably do not even support
2798 \cw{XDM-AUTHORIZATION-1}, so they will not know what to do with the
2799 data PuTTY has provided.
2800
2801 \b This authentication mechanism will only work in SSH-2. In SSH-1,
2802 the SSH server does not tell the client the source address of
2803 a forwarded connection in a machine-readable format, so it's
2804 impossible to verify the \cw{XDM-AUTHORIZATION-1} data.
2805
2806 \b You may find this feature causes problems with some SSH servers,
2807 which will not clean up \cw{XDM-AUTHORIZATION-1} data after a
2808 session, so that if you then connect to the same server using
2809 a client which only does \cw{MIT-MAGIC-COOKIE-1} and are allocated
2810 the same remote display number, you might find that out-of-date
2811 authentication data is still present on your server and your X
2812 connections fail.
2813
2814 PuTTY's default is \cw{MIT-MAGIC-COOKIE-1}. If you change it, you
2815 should be sure you know what you're doing.
2816
2817 \S{config-ssh-xauthority} X authority file for local display
2818
2819 \cfg{winhelp-topic}{ssh.tunnels.xauthority}
2820
2821 If you are using X11 forwarding, the local X server to which your
2822 forwarded connections are eventually directed may itself require
2823 authorisation.
2824
2825 Some Windows X servers do not require this: they do authorisation by
2826 simpler means, such as accepting any connection from the local
2827 machine but not from anywhere else. However, if your X server does
2828 require authorisation, then PuTTY needs to know what authorisation
2829 is required.
2830
2831 One way in which this data might be made available is for the X
2832 server to store it somewhere in a file which has the same format
2833 as the Unix \c{.Xauthority} file. If this is how your Windows X
2834 server works, then you can tell PuTTY where to find this file by
2835 configuring this option. By default, PuTTY will not attempt to find
2836 any authorisation for your local display.
2837
2838 \H{config-ssh-portfwd} \I{port forwarding}The Tunnels panel
2839
2840 \cfg{winhelp-topic}{ssh.tunnels.portfwd}
2841
2842 The Tunnels panel allows you to configure tunnelling of arbitrary
2843 connection types through an SSH connection.
2844
2845 Port forwarding allows you to tunnel other types of \i{network
2846 connection} down an SSH session. See \k{using-port-forwarding} for a
2847 general discussion of port forwarding and how it works.
2848
2849 The port forwarding section in the Tunnels panel shows a list of all
2850 the port forwardings that PuTTY will try to set up when it connects
2851 to the server. By default no port forwardings are set up, so this
2852 list is empty.
2853
2854 To add a port forwarding:
2855
2856 \b Set one of the \q{Local} or \q{Remote} radio buttons, depending
2857 on whether you want to \I{local port forwarding}forward a local port
2858 to a remote destination (\q{Local}) or \I{remote port forwarding}forward
2859 a remote port to a local destination (\q{Remote}). Alternatively,
2860 select \q{Dynamic} if you want PuTTY to \I{dynamic port forwarding}provide
2861 a local SOCKS 4/4A/5 proxy on a local port (note that this proxy only
2862 supports TCP connections; the SSH protocol does not support forwarding
2863 \i{UDP}).
2864
2865 \b Enter a source \i{port number} into the \q{Source port} box. For
2866 local forwardings, PuTTY will listen on this port of your PC. For
2867 remote forwardings, your SSH server will listen on this port of the
2868 remote machine. Note that most servers will not allow you to listen
2869 on \I{privileged port}port numbers less than 1024.
2870
2871 \b If you have selected \q{Local} or \q{Remote} (this step is not
2872 needed with \q{Dynamic}), enter a hostname and port number separated
2873 by a colon, in the \q{Destination} box. Connections received on the
2874 source port will be directed to this destination. For example, to
2875 connect to a POP-3 server, you might enter
2876 \c{popserver.example.com:110}.
2877
2878 \b Click the \q{Add} button. Your forwarding details should appear
2879 in the list box.
2880
2881 To remove a port forwarding, simply select its details in the list
2882 box, and click the \q{Remove} button.
2883
2884 In the \q{Source port} box, you can also optionally enter an \I{listen
2885 address}IP address to listen on, by specifying (for instance)
2886 \c{127.0.0.5:79}.
2887 See \k{using-port-forwarding} for more information on how this
2888 works and its restrictions.
2889
2890 In place of port numbers, you can enter \i{service names}, if they are
2891 known to the local system. For instance, in the \q{Destination} box,
2892 you could enter \c{popserver.example.com:pop3}.
2893
2894 You can \I{port forwarding, changing mid-session}modify the currently
2895 active set of port forwardings in mid-session using \q{Change
2896 Settings} (see \k{using-changesettings}). If you delete a local or
2897 dynamic port forwarding in mid-session, PuTTY will stop listening for
2898 connections on that port, so it can be re-used by another program. If
2899 you delete a remote port forwarding, note that:
2900
2901 \b The SSH-1 protocol contains no mechanism for asking the server to
2902 stop listening on a remote port.
2903
2904 \b The SSH-2 protocol does contain such a mechanism, but not all SSH
2905 servers support it. (In particular, \i{OpenSSH} does not support it in
2906 any version earlier than 3.9.)
2907
2908 If you ask to delete a remote port forwarding and PuTTY cannot make
2909 the server actually stop listening on the port, it will instead just
2910 start refusing incoming connections on that port. Therefore,
2911 although the port cannot be reused by another program, you can at
2912 least be reasonably sure that server-side programs can no longer
2913 access the service at your end of the port forwarding.
2914
2915 If you delete a forwarding, any existing connections established using
2916 that forwarding remain open. Similarly, changes to global settings
2917 such as \q{Local ports accept connections from other hosts} only take
2918 effect on new forwardings.
2919
2920 If the connection you are forwarding over SSH is itself a second SSH
2921 connection made by another copy of PuTTY, you might find the
2922 \q{logical host name} configuration option useful to warn PuTTY of
2923 which host key it should be expecting. See \k{config-loghost} for
2924 details of this.
2925
2926 \S{config-ssh-portfwd-localhost} Controlling the visibility of
2927 forwarded ports
2928
2929 \cfg{winhelp-topic}{ssh.tunnels.portfwd.localhost}
2930
2931 The source port for a forwarded connection usually does not accept
2932 connections from any machine except the \I{localhost}SSH client or
2933 server machine itself (for local and remote forwardings respectively).
2934 There are controls in the Tunnels panel to change this:
2935
2936 \b The \q{Local ports accept connections from other hosts} option
2937 allows you to set up local-to-remote port forwardings in such a way
2938 that machines other than your client PC can connect to the forwarded
2939 port. (This also applies to dynamic SOCKS forwarding.)
2940
2941 \b The \q{Remote ports do the same} option does the same thing for
2942 remote-to-local port forwardings (so that machines other than the
2943 SSH server machine can connect to the forwarded port.) Note that
2944 this feature is only available in the SSH-2 protocol, and not all
2945 SSH-2 servers support it (\i{OpenSSH} 3.0 does not, for example).
2946
2947 \S{config-ssh-portfwd-address-family} Selecting \i{Internet protocol
2948 version} for forwarded ports
2949
2950 \cfg{winhelp-topic}{ssh.tunnels.portfwd.ipversion}
2951
2952 This switch allows you to select a specific Internet protocol (\i{IPv4}
2953 or \i{IPv6}) for the local end of a forwarded port. By default, it is
2954 set on \q{Auto}, which means that:
2955
2956 \b for a local-to-remote port forwarding, PuTTY will listen for
2957 incoming connections in both IPv4 and (if available) IPv6
2958
2959 \b for a remote-to-local port forwarding, PuTTY will choose a
2960 sensible protocol for the outgoing connection.
2961
2962 This overrides the general Internet protocol version preference
2963 on the Connection panel (see \k{config-address-family}).
2964
2965 Note that some operating systems may listen for incoming connections
2966 in IPv4 even if you specifically asked for IPv6, because their IPv4
2967 and IPv6 protocol stacks are linked together. Apparently \i{Linux} does
2968 this, and Windows does not. So if you're running PuTTY on Windows
2969 and you tick \q{IPv6} for a local or dynamic port forwarding, it
2970 will \e{only} be usable by connecting to it using IPv6; whereas if
2971 you do the same on Linux, you can also use it with IPv4. However,
2972 ticking \q{Auto} should always give you a port which you can connect
2973 to using either protocol.
2974
2975 \H{config-ssh-bugs} \I{SSH server bugs}The Bugs panel
2976
2977 Not all SSH servers work properly. Various existing servers have
2978 bugs in them, which can make it impossible for a client to talk to
2979 them unless it knows about the bug and works around it.
2980
2981 Since most servers announce their software version number at the
2982 beginning of the SSH connection, PuTTY will attempt to detect which
2983 bugs it can expect to see in the server and automatically enable
2984 workarounds. However, sometimes it will make mistakes; if the server
2985 has been deliberately configured to conceal its version number, or
2986 if the server is a version which PuTTY's bug database does not know
2987 about, then PuTTY will not know what bugs to expect.
2988
2989 The Bugs panel allows you to manually configure the bugs PuTTY
2990 expects to see in the server. Each bug can be configured in three
2991 states:
2992
2993 \b \q{Off}: PuTTY will assume the server does not have the bug.
2994
2995 \b \q{On}: PuTTY will assume the server \e{does} have the bug.
2996
2997 \b \q{Auto}: PuTTY will use the server's version number announcement
2998 to try to guess whether or not the server has the bug.
2999
3000 \S{config-ssh-bug-ignore1} \q{Chokes on SSH-1 \i{ignore message}s}
3001
3002 \cfg{winhelp-topic}{ssh.bugs.ignore1}
3003
3004 An ignore message (SSH_MSG_IGNORE) is a message in the SSH protocol
3005 which can be sent from the client to the server, or from the server
3006 to the client, at any time. Either side is required to ignore the
3007 message whenever it receives it. PuTTY uses ignore messages to
3008 \I{password camouflage}hide the password packet in SSH-1, so that
3009 a listener cannot tell the length of the user's password; it also
3010 uses ignore messages for connection \i{keepalives} (see
3011 \k{config-keepalive}).
3012
3013 If this bug is detected, PuTTY will stop using ignore messages. This
3014 means that keepalives will stop working, and PuTTY will have to fall
3015 back to a secondary defence against SSH-1 password-length
3016 eavesdropping. See \k{config-ssh-bug-plainpw1}. If this bug is
3017 enabled when talking to a correct server, the session will succeed,
3018 but keepalives will not work and the session might be more
3019 vulnerable to eavesdroppers than it could be.
3020
3021 \S{config-ssh-bug-plainpw1} \q{Refuses all SSH-1 \i{password camouflage}}
3022
3023 \cfg{winhelp-topic}{ssh.bugs.plainpw1}
3024
3025 When talking to an SSH-1 server which cannot deal with ignore
3026 messages (see \k{config-ssh-bug-ignore1}), PuTTY will attempt to
3027 disguise the length of the user's password by sending additional
3028 padding \e{within} the password packet. This is technically a
3029 violation of the SSH-1 specification, and so PuTTY will only do it
3030 when it cannot use standards-compliant ignore messages as
3031 camouflage. In this sense, for a server to refuse to accept a padded
3032 password packet is not really a bug, but it does make life
3033 inconvenient if the server can also not handle ignore messages.
3034
3035 If this \q{bug} is detected, PuTTY will assume that neither ignore
3036 messages nor padding are acceptable, and that it thus has no choice
3037 but to send the user's password with no form of camouflage, so that
3038 an eavesdropping user will be easily able to find out the exact length
3039 of the password. If this bug is enabled when talking to a correct
3040 server, the session will succeed, but will be more vulnerable to
3041 eavesdroppers than it could be.
3042
3043 This is an SSH-1-specific bug. SSH-2 is secure against this type of
3044 attack.
3045
3046 \S{config-ssh-bug-rsa1} \q{Chokes on SSH-1 \i{RSA} authentication}
3047
3048 \cfg{winhelp-topic}{ssh.bugs.rsa1}
3049
3050 Some SSH-1 servers cannot deal with RSA authentication messages at
3051 all. If \i{Pageant} is running and contains any SSH-1 keys, PuTTY will
3052 normally automatically try RSA authentication before falling back to
3053 passwords, so these servers will crash when they see the RSA attempt.
3054
3055 If this bug is detected, PuTTY will go straight to password
3056 authentication. If this bug is enabled when talking to a correct
3057 server, the session will succeed, but of course RSA authentication
3058 will be impossible.
3059
3060 This is an SSH-1-specific bug.
3061
3062 \S{config-ssh-bug-ignore2} \q{Chokes on SSH-2 \i{ignore message}s}
3063
3064 \cfg{winhelp-topic}{ssh.bugs.ignore2}
3065
3066 An ignore message (SSH_MSG_IGNORE) is a message in the SSH protocol
3067 which can be sent from the client to the server, or from the server
3068 to the client, at any time. Either side is required to ignore the
3069 message whenever it receives it. PuTTY uses ignore messages in SSH-2
3070 to confuse the encrypted data stream and make it harder to
3071 cryptanalyse. It also uses ignore messages for connection
3072 \i{keepalives} (see \k{config-keepalive}).
3073
3074 If it believes the server to have this bug, PuTTY will stop using
3075 ignore messages. If this bug is enabled when talking to a correct
3076 server, the session will succeed, but keepalives will not work and
3077 the session might be less cryptographically secure than it could be.
3078
3079 \S{config-ssh-bug-hmac2} \q{Miscomputes SSH-2 HMAC keys}
3080
3081 \cfg{winhelp-topic}{ssh.bugs.hmac2}
3082
3083 Versions 2.3.0 and below of the SSH server software from
3084 \cw{ssh.com} compute the keys for their \i{HMAC} \i{message authentication
3085 code}s incorrectly. A typical symptom of this problem is that PuTTY
3086 dies unexpectedly at the beginning of the session, saying
3087 \q{Incorrect MAC received on packet}.
3088
3089 If this bug is detected, PuTTY will compute its HMAC keys in the
3090 same way as the buggy server, so that communication will still be
3091 possible. If this bug is enabled when talking to a correct server,
3092 communication will fail.
3093
3094 This is an SSH-2-specific bug.
3095
3096 \S{config-ssh-bug-derivekey2} \q{Miscomputes SSH-2 \i{encryption} keys}
3097
3098 \cfg{winhelp-topic}{ssh.bugs.derivekey2}
3099
3100 Versions below 2.0.11 of the SSH server software from \i\cw{ssh.com}
3101 compute the keys for the session encryption incorrectly. This
3102 problem can cause various error messages, such as \q{Incoming packet
3103 was garbled on decryption}, or possibly even \q{Out of memory}.
3104
3105 If this bug is detected, PuTTY will compute its encryption keys in
3106 the same way as the buggy server, so that communication will still
3107 be possible. If this bug is enabled when talking to a correct
3108 server, communication will fail.
3109
3110 This is an SSH-2-specific bug.
3111
3112 \S{config-ssh-bug-sig} \q{Requires padding on SSH-2 \i{RSA} \i{signatures}}
3113
3114 \cfg{winhelp-topic}{ssh.bugs.rsapad2}
3115
3116 Versions below 3.3 of \i{OpenSSH} require SSH-2 RSA signatures to be
3117 padded with zero bytes to the same length as the RSA key modulus.
3118 The SSH-2 specification says that an unpadded signature MUST be
3119 accepted, so this is a bug. A typical symptom of this problem is
3120 that PuTTY mysteriously fails RSA authentication once in every few
3121 hundred attempts, and falls back to passwords.
3122
3123 If this bug is detected, PuTTY will pad its signatures in the way
3124 OpenSSH expects. If this bug is enabled when talking to a correct
3125 server, it is likely that no damage will be done, since correct
3126 servers usually still accept padded signatures because they're used
3127 to talking to OpenSSH.
3128
3129 This is an SSH-2-specific bug.
3130
3131 \S{config-ssh-bug-pksessid2} \q{Misuses the \i{session ID} in SSH-2 PK auth}
3132
3133 \cfg{winhelp-topic}{ssh.bugs.pksessid2}
3134
3135 Versions below 2.3 of \i{OpenSSH} require SSH-2 \i{public-key authentication}
3136 to be done slightly differently: the data to be signed by the client
3137 contains the session ID formatted in a different way. If public-key
3138 authentication mysteriously does not work but the Event Log (see
3139 \k{using-eventlog}) thinks it has successfully sent a signature, it
3140 might be worth enabling the workaround for this bug to see if it
3141 helps.
3142
3143 If this bug is detected, PuTTY will sign data in the way OpenSSH
3144 expects. If this bug is enabled when talking to a correct server,
3145 SSH-2 public-key authentication will fail.
3146
3147 This is an SSH-2-specific bug.
3148
3149 \S{config-ssh-bug-rekey} \q{Handles SSH-2 key re-exchange badly}
3150
3151 \cfg{winhelp-topic}{ssh.bugs.rekey2}
3152
3153 Some SSH servers cannot cope with \i{repeat key exchange} at
3154 all, and will ignore attempts by the client to start one. Since
3155 PuTTY pauses the session while performing a repeat key exchange, the
3156 effect of this would be to cause the session to hang after an hour
3157 (unless you have your rekey timeout set differently; see
3158 \k{config-ssh-kex-rekey} for more about rekeys).
3159 Other, very old, SSH servers handle repeat key exchange even more
3160 badly, and disconnect upon receiving a repeat key exchange request.
3161
3162 If this bug is detected, PuTTY will never initiate a repeat key
3163 exchange. If this bug is enabled when talking to a correct server,
3164 the session should still function, but may be less secure than you
3165 would expect.
3166
3167 This is an SSH-2-specific bug.
3168
3169 \S{config-ssh-bug-maxpkt2} \q{Ignores SSH-2 \i{maximum packet size}}
3170
3171 \cfg{winhelp-topic}{ssh.bugs.maxpkt2}
3172
3173 When an SSH-2 channel is set up, each end announces the maximum size
3174 of data packet that it is willing to receive for that channel. Some
3175 servers ignore PuTTY's announcement and send packets larger than PuTTY
3176 is willing to accept, causing it to report \q{Incoming packet was
3177 garbled on decryption}.
3178
3179 If this bug is detected, PuTTY never allows the channel's
3180 \i{flow-control window} to grow large enough to allow the server to
3181 send an over-sized packet. If this bug is enabled when talking to a
3182 correct server, the session will work correctly, but download
3183 performance will be less than it could be.
3184
3185 \H{config-serial} The Serial panel
3186
3187 The \i{Serial} panel allows you to configure options that only apply
3188 when PuTTY is connecting to a local \I{serial port}\i{serial line}.
3189
3190 \S{config-serial-line} Selecting a serial line to connect to
3191
3192 \cfg{winhelp-topic}{serial.line}
3193
3194 The \q{Serial line to connect to} box allows you to choose which
3195 serial line you want PuTTY to talk to, if your computer has more
3196 than one serial port.
3197
3198 On Windows, the first serial line is called \i\cw{COM1}, and if there
3199 is a second it is called \cw{COM2}, and so on.
3200
3201 This configuration setting is also visible on the Session panel,
3202 where it replaces the \q{Host Name} box (see \k{config-hostname}) if
3203 the connection type is set to \q{Serial}.
3204
3205 \S{config-serial-speed} Selecting the speed of your serial line
3206
3207 \cfg{winhelp-topic}{serial.speed}
3208
3209 The \q{Speed} box allows you to choose the speed (or \q{baud rate})
3210 at which to talk to the serial line. Typical values might be 9600,
3211 19200, 38400 or 57600. Which one you need will depend on the device
3212 at the other end of the serial cable; consult the manual for that
3213 device if you are in doubt.
3214
3215 This configuration setting is also visible on the Session panel,
3216 where it replaces the \q{Port} box (see \k{config-hostname}) if the
3217 connection type is set to \q{Serial}.
3218
3219 \S{config-serial-databits} Selecting the number of data bits
3220
3221 \cfg{winhelp-topic}{serial.databits}
3222
3223 The \q{Data bits} box allows you to choose how many data bits are
3224 transmitted in each byte sent or received through the serial line.
3225 Typical values are 7 or 8.
3226
3227 \S{config-serial-stopbits} Selecting the number of stop bits
3228
3229 \cfg{winhelp-topic}{serial.stopbits}
3230
3231 The \q{Stop bits} box allows you to choose how many stop bits are
3232 used in the serial line protocol. Typical values are 1, 1.5 or 2.
3233
3234 \S{config-serial-parity} Selecting the serial parity checking scheme
3235
3236 \cfg{winhelp-topic}{serial.parity}
3237
3238 The \q{Parity} box allows you to choose what type of parity checking
3239 is used on the serial line. The settings are:
3240
3241 \b \q{None}: no parity bit is sent at all.
3242
3243 \b \q{Odd}: an extra parity bit is sent alongside each byte, and
3244 arranged so that the total number of 1 bits is odd.
3245
3246 \b \q{Even}: an extra parity bit is sent alongside each byte, and
3247 arranged so that the total number of 1 bits is even.
3248
3249 \b \q{Mark}: an extra parity bit is sent alongside each byte, and
3250 always set to 1.
3251
3252 \b \q{Space}: an extra parity bit is sent alongside each byte, and
3253 always set to 0.
3254
3255 \S{config-serial-flow} Selecting the serial flow control scheme
3256
3257 \cfg{winhelp-topic}{serial.flow}
3258
3259 The \q{Flow control} box allows you to choose what type of flow
3260 control checking is used on the serial line. The settings are:
3261
3262 \b \q{None}: no flow control is done. Data may be lost if either
3263 side attempts to send faster than the serial line permits.
3264
3265 \b \q{XON/XOFF}: flow control is done by sending XON and XOFF
3266 characters within the data stream.
3267
3268 \b \q{RTS/CTS}: flow control is done using the RTS and CTS wires on
3269 the serial line.
3270
3271 \b \q{DSR/DTR}: flow control is done using the DSR and DTR wires on
3272 the serial line.
3273
3274 \H{config-file} \ii{Storing configuration in a file}
3275
3276 PuTTY does not currently support storing its configuration in a file
3277 instead of the \i{Registry}. However, you can work around this with a
3278 couple of \i{batch file}s.
3279
3280 You will need a file called (say) \c{PUTTY.BAT} which imports the
3281 contents of a file into the Registry, then runs PuTTY, exports the
3282 contents of the Registry back into the file, and deletes the
3283 Registry entries. This can all be done using the Regedit command
3284 line options, so it's all automatic. Here is what you need in
3285 \c{PUTTY.BAT}:
3286
3287 \c @ECHO OFF
3288 \c regedit /s putty.reg
3289 \c regedit /s puttyrnd.reg
3290 \c start /w putty.exe
3291 \c regedit /ea new.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
3292 \c copy new.reg putty.reg
3293 \c del new.reg
3294 \c regedit /s puttydel.reg
3295
3296 This batch file needs two auxiliary files: \c{PUTTYRND.REG} which
3297 sets up an initial safe location for the \c{PUTTY.RND} random seed
3298 file, and \c{PUTTYDEL.REG} which destroys everything in the Registry
3299 once it's been successfully saved back to the file.
3300
3301 Here is \c{PUTTYDEL.REG}:
3302
3303 \c REGEDIT4
3304 \c
3305 \c [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
3306
3307 Here is an example \c{PUTTYRND.REG} file:
3308
3309 \c REGEDIT4
3310 \c
3311 \c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
3312 \c "RandSeedFile"="a:\\putty.rnd"
3313
3314 You should replace \c{a:\\putty.rnd} with the location where you
3315 want to store your random number data. If the aim is to carry around
3316 PuTTY and its settings on one floppy, you probably want to store it
3317 on the floppy.