-\versionid $Id: config.but,v 1.45 2002/12/18 11:39:25 simon Exp $
+\define{versionidconfig} \versionid $Id$
\C{config} Configuring PuTTY
\b The \q{Protocol} radio buttons let you choose what type of
connection you want to make: a raw connection, a Telnet connection, an
rlogin connection or an SSH connection. (See \k{which-one} for a
-summary of the differences between SSH, Telnet and rlogin.)
+summary of the differences between SSH, Telnet and rlogin, and
+\k{using-rawprot} for an explanation of \q{raw} connections.)
\b The \q{Port} box lets you specify which port number on the server
to connect to. If you select Telnet, Rlogin, or SSH, this box will
be filled in automatically to the usual value, and you will only
need to change it if you have an unusual server. If you select Raw
-mode (see \k{using-rawprot}), you will almost certainly need to fill
-in the \q{Port} box.
+mode, you will almost certainly need to fill in the \q{Port} box.
\S{config-saving} Loading and storing saved sessions
settings should all appear in the configuration panel.
\b To modify a saved session: first load it as described above. Then
-make the changes you want. Come back to the Session panel,
-single-click to select the session name in the list box, and press
+make the changes you want. Come back to the Session panel, and press
the \q{Save} button. The new settings will be saved over the top of
-the old ones.
+the old ones
+
+\lcont{
+To save the new settings under a different name, you can enter the new
+name in the \q{Saved Sessions} box, or single-click to select a
+session name in the list box to overwrite that session. To save
+\q{Default Settings}, you must single-click the name before saving.
+}
\b To start a saved session immediately: double-click on the session
name in the list box.
configuration. If you change your preferences and update Default
Settings, you must also update every saved session separately.
+Saved sessions are stored in the Registry, at the location
+
+\c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\Sessions
+
+If you need to store them in a file, you could try the method
+described in \k{config-file}.
+
\S{config-closeonexit} \q{Close Window on Exit}
\cfg{winhelp-topic}{session.coe}
Window on Exit}. This controls whether the PuTTY session window
disappears as soon as the session inside it terminates. If you are
likely to want to copy and paste text out of the session after it
-has terminated, you should arrange this option to be off.
+has terminated, or restart the session, you should arrange for this
+option to be off.
\q{Close Window On Exit} has three settings. \q{Always} means always
close the window on exit; \q{Never} means never close on exit
-(always leave the window open). The third setting, and the default
-one, is \q{Only on clean exit}. In this mode, a session which
-terminates normally will cause its window to close, but one which is
-aborted unexpectedly by network trouble or a confusing message from
-the server will leave the window up.
+(always leave the window open, but \I{inactive window}inactive). The
+third setting, and the default one, is \q{Only on clean exit}. In this
+mode, a session which terminates normally will cause its window to
+close, but one which is aborted unexpectedly by network trouble or a
+confusing message from the server will leave the window up.
\H{config-logging} The Logging panel
connection are written to the log file. You might need this to debug
a network-level problem, or more likely to send to the PuTTY authors
as part of a bug report. \e{BE WARNED} that if you log in using a
-password, the password will appear in the log file, so be sure to
-edit it out before sending the log file to anyone else!
+password, the password can appear in the log file; see
+\k{config-logssh} for options that may help to remove sensitive
+material from the log file before you send it to anyone else.
\S{config-logfilename} \q{Log file name}
automatic behaviour, but to ask the user every time the problem
comes up.
+\S{config-logflush} \q{Flush log file frequently}
+
+\cfg{winhelp-topic}{logging.flush}
+
+This option allows you to control how frequently logged data is
+flushed to disc. By default, PuTTY will flush data as soon as it is
+displayed, so that if you view the log file while a session is still
+open, it will be up to date; and if the client system crashes, there's
+a greater chance that the data will be preserved.
+
+However, this can incur a performance penalty. If PuTTY is running
+slowly with logging enabled, you could try unchecking this option. Be
+warned that the log file may not always be up to date as a result
+(although it will of course be flushed when it is closed, for instance
+at the end of a session).
+
+\S{config-logssh} Options specific to SSH packet logging
+
+These options only apply if SSH packet data is being logged.
+
+The following options allow particularly sensitive portions of
+unencrypted packets to be automatically left out of the log file.
+They are only intended to deter casual nosiness; an attacker could
+glean a lot of useful information from even these obfuscated logs
+(e.g., length of password).
+
+\S2{config-logssh-omitpw} \q{Omit known password fields}
+
+\cfg{winhelp-topic}{logging.ssh.omitpassword}
+
+When checked, password fields are removed from the log of transmitted
+packets. (This includes any user responses to challenge-response
+authentication methods such as \q{keyboard-interactive}.) This does
+not include X11 authentication data if using X11 forwarding.
+
+Note that this will only omit data that PuTTY \e{knows} to be a
+password. However, if you start another login session within your
+PuTTY session, for instance, any password used will appear in the
+clear in the packet log. The next option may be of use to protect
+against this.
+
+This option is enabled by default.
+
+\S2{config-logssh-omitdata} \q{Omit session data}
+
+\cfg{winhelp-topic}{logging.ssh.omitdata}
+
+When checked, all \q{session data} is omitted; this is defined as data
+in terminal sessions and in forwarded channels (TCP, X11, and
+authentication agent). This will usually substantially reduce the size
+of the resulting log file.
+
+This option is disabled by default.
+
\H{config-terminal} The Terminal panel
The Terminal configuration panel allows you to control the behaviour
could try turning this option off.
Auto wrap mode can be turned on and off by control sequences sent by
-the server. This configuration option only controls the \e{default}
-state. If you modify this option in mid-session using \q{Change
-Settings}, you will need to reset the terminal (see
-\k{reset-terminal}) before the change takes effect.
+the server. This configuration option controls the \e{default}
+state, which will be restored when you reset the terminal (see
+\k{reset-terminal}). However, if you modify this option in
+mid-session using \q{Change Settings}, it will take effect
+immediately.
\S{config-decom} \q{DEC Origin Mode initially on}
Mode on to see whether that helps.
DEC Origin Mode can be turned on and off by control sequences sent
-by the server. This configuration option only controls the
-\e{default} state. If you modify this option in mid-session using
-\q{Change Settings}, you will need to reset the terminal (see
-\k{reset-terminal}) before the change takes effect.
+by the server. This configuration option controls the \e{default}
+state, which will be restored when you reset the terminal (see
+\k{reset-terminal}). However, if you modify this option in
+mid-session using \q{Change Settings}, it will take effect
+immediately.
\S{config-crlf} \q{Implicit CR in every LF}
the \e{current} background colour.
Background-colour erase can be turned on and off by control
-sequences sent by the server. This configuration option only
-controls the \e{default} state. If you modify this option in
-mid-session using \q{Change Settings}, you will need to reset the
-terminal (see \k{reset-terminal}) before the change takes effect.
+sequences sent by the server. This configuration option controls the
+\e{default} state, which will be restored when you reset the
+terminal (see \k{reset-terminal}). However, if you modify this
+option in mid-session using \q{Change Settings}, it will take effect
+immediately.
\S{config-blink} \q{Enable blinking text}
background colour.
Blinking text can be turned on and off by control sequences sent by
-the server. This configuration option only controls the \e{default}
-state. If you modify this option in mid-session using \q{Change
-Settings}, you will need to reset the terminal (see
-\k{reset-terminal}) before the change takes effect.
+the server. This configuration option controls the \e{default}
+state, which will be restored when you reset the terminal (see
+\k{reset-terminal}). However, if you modify this option in
+mid-session using \q{Change Settings}, it will take effect
+immediately.
\S{config-answerback} \q{Answerback to ^E}
that allows applications such as \c{emacs} to use Control-H for
help.
+(Typing \i{Shift-Backspace} will cause PuTTY to send whichever code
+isn't configured here as the default.)
+
\S{config-homeend} Changing the action of the Home and End keys
\cfg{winhelp-topic}{keyboard.homeend}
the server can send as many Control-G characters as it likes and
nothing at all will happen.
-\b \q{Play Windows Default Sound} is the default setting. It causes
-the Windows \q{Default Beep} sound to be played. To change what this
-sound is, or to test it if nothing seems to be happening, use the
-Sound configurer in the Windows Control Panel.
+\b \q{Make default system alert sound} is the default setting. It
+causes the Windows \q{Default Beep} sound to be played. To change
+what this sound is, or to test it if nothing seems to be happening,
+use the Sound configurer in the Windows Control Panel.
+
+\b \q{Visual bell} is a silent alternative to a beeping computer. In
+this mode, when the server sends a Control-G, the whole PuTTY window
+will flash white for a fraction of a second.
+
+\b \q{Beep using the PC speaker} is self-explanatory.
\b \q{Play a custom sound file} allows you to specify a particular
sound file to be used by PuTTY alone, or even by a particular
you will also need to enter the name of your sound file in the edit
control \q{Custom sound file to play as a bell}.
-\b \q{Visual bell} is a silent alternative to a beeping computer. In
-this mode, when the server sends a Control-G, the whole PuTTY window
-will flash white for a fraction of a second.
-
\S{config-belltaskbar} \q{Taskbar/caption indication on bell}
\cfg{winhelp-topic}{bell.taskbar}
unexpectedly or inconveniently, you can tell PuTTY not to respond to
those server commands.
+\S{config-features-qtitle} Disabling remote window title querying
+
+\cfg{winhelp-topic}{features.qtitle}
+
+PuTTY can optionally provide the xterm service of allowing server
+applications to find out the local window title. This feature is
+disabled by default, but you can turn it on if you really want it.
+
+NOTE that this feature is a \e{potential security hazard}. If a
+malicious application can write data to your terminal (for example,
+if you merely \c{cat} a file owned by someone else on the server
+machine), it can change your window title (unless you have disabled
+this as mentioned in \k{config-features-retitle}) and then use this
+service to have the new window title sent back to the server as if
+typed at the keyboard. This allows an attacker to fake keypresses
+and potentially cause your server-side applications to do things you
+didn't want. Therefore this feature is disabled by default, and we
+recommend you do not turn it on unless you \e{really} know what you
+are doing.
+
\S{config-features-dbackspace} Disabling destructive backspace
\cfg{winhelp-topic}{features.dbackspace}
expect them to, particularly if you're running BitchX, you could try
disabling the remote character set configuration commands.
+\S{config-features-shaping} Disabling Arabic text shaping
+
+\cfg{winhelp-topic}{features.arabicshaping}
+
+PuTTY supports shaping of Arabic text, which means that if your
+server sends text written in the basic Unicode Arabic alphabet then
+it will convert it to the correct display forms before printing it
+on the screen.
+
+If you are using full-screen software which was not expecting this
+to happen (especially if you are not an Arabic speaker and you
+unexpectedly find yourself dealing with Arabic text files in
+applications which are not Arabic-aware), you might find that the
+display becomes corrupted. By ticking this box, you can disable
+Arabic text shaping so that PuTTY displays precisely the characters
+it is told to display.
+
+You may also find you need to disable bidirectional text display;
+see \k{config-features-bidi}.
+
+\S{config-features-bidi} Disabling bidirectional text display
+
+\cfg{winhelp-topic}{features.bidi}
+
+PuTTY supports bidirectional text display, which means that if your
+server sends text written in a language which is usually displayed
+from right to left (such as Arabic or Hebrew) then PuTTY will
+automatically flip it round so that it is displayed in the right
+direction on the screen.
+
+If you are using full-screen software which was not expecting this
+to happen (especially if you are not an Arabic speaker and you
+unexpectedly find yourself dealing with Arabic text files in
+applications which are not Arabic-aware), you might find that the
+display becomes corrupted. By ticking this box, you can disable
+bidirectional text display, so that PuTTY displays text from left to
+right in all situations.
+
+You may also find you need to disable Arabic text shaping;
+see \k{config-features-shaping}.
+
\H{config-window} The Window panel
The Window configuration panel allows you to control aspects of the
\cfg{winhelp-topic}{window.resize}
These options allow you to control what happens when the user tries
-to resize the PuTTY window.
+to resize the PuTTY window using its window furniture.
-When you resize the PuTTY window, one of four things can happen:
+There are four options here:
-\b Nothing (if you have completely disabled resizes).
+\b \q{Change the number of rows and columns}: the font size will not
+change. (This is the default.)
-\b The font size can stay the same and the number of rows and
-columns in the terminal can change.
+\b \q{Change the size of the font}: the number of rows and columns in
+the terminal will stay the same, and the font size will change.
-\b The number of rows and columns in the terminal can stay the same,
-and the font size can change.
+\b \q{Change font size when maximised}: when the window is resized,
+the number of rows and columns will change, \e{except} when the window
+is maximised (or restored), when the font size will change.
-\b You can allow PuTTY to change \e{either} the terminal size or the
-font size. In this mode it will change the terminal size most of the
-time, but enlarge the font when you maximise the window.
-
-You can control which of these happens using the \q{Lock terminal
-size against resizing} and \q{Lock font size against resizing}
-options. If you lock both, the window will refuse to be resized at
-all. If you lock just the terminal size, the font size will change
-when you resize the window. If you lock just the font size, the
-terminal size will change when you resize the window.
+\b \q{Forbid resizing completely}: the terminal will refuse to be
+resized at all.
\S{config-scrollback} Controlling scrollback
The \q{Lines of scrollback} box lets you configure how many lines of
text PuTTY keeps. The \q{Display scrollbar} options allow you to
hide the scrollbar (although you can still view the scrollback using
-Shift-PgUp and Shift-PgDn). You can separately configure whether the
-scrollbar is shown in full-screen mode and in normal modes.
+the keyboard as described in \k{using-scrollback}). You can separately
+configure whether the scrollbar is shown in full-screen mode and in
+normal modes.
If you are viewing part of the scrollback when the server sends more
text to PuTTY, the screen will revert to showing the current
screen revert when you press a key, by turning on \q{Reset
scrollback on keypress}.
+\S{config-erasetoscrollback} \q{Push erased text into scrollback}
+
+\cfg{winhelp-topic}{window.erased}
+
+When this option is enabled, the contents of the terminal screen
+will be pushed into the scrollback when a server-side application
+clears the screen, so that your scrollback will contain a better
+record of what was on your screen in the past.
+
+If the application switches to the alternate screen (see
+\k{config-features-altscreen} for more about this), then the
+contents of the primary screen will be visible in the scrollback
+until the application switches back again.
+
+This option is enabled by default.
+
\H{config-appearance} The Appearance panel
The Appearance configuration panel allows you to control aspects of
system. (VT100-style terminal handling can only deal with fixed-
width fonts.)
-\S{config-title} Controlling the window title
-
-\cfg{winhelp-topic}{appearance.title}
-
-The \q{Window title} edit box allows you to set the title of the
-PuTTY window. By default the window title will contain the host name
-followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
-If you want a different window title, this is where to set it.
-
-PuTTY allows the server to send \c{xterm} control sequences which
-modify the title of the window in mid-session. There is also an
-\c{xterm} sequence to modify the title of the window's \e{icon}.
-This makes sense in a windowing system where the window becomes an
-icon when minimised, such as Windows 3.1 or most X Window System
-setups; but in the Windows 95-like user interface it isn't as
-applicable. By default PuTTY's window title and Taskbar caption will
-change into the server-supplied icon title if you minimise the PuTTY
-window, and change back to the server-supplied window title if you
-restore it. (If the server has not bothered to supply a window or
-icon title, none of this will happen.) By checking the box marked
-\q{Avoid ever using icon title}, you can arrange that PuTTY will
-always display the window title, and completely ignore any icon
-titles the server sends it.
-
\S{config-mouseptr} \q{Hide mouse pointer when typing in window}
\cfg{winhelp-topic}{appearance.hidemouse}
The Behaviour configuration panel allows you to control aspects of
the behaviour of PuTTY's window.
+\S{config-title} Controlling the window title
+
+\cfg{winhelp-topic}{appearance.title}
+
+The \q{Window title} edit box allows you to set the title of the
+PuTTY window. By default the window title will contain the host name
+followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
+If you want a different window title, this is where to set it.
+
+PuTTY allows the server to send \c{xterm} control sequences which
+modify the title of the window in mid-session (unless this is disabled -
+see \k{config-features-retitle}); the title string set here
+is therefore only the \e{initial} window title.
+
+As well as the \e{window} title, there is also an
+\c{xterm} sequence to modify the title of the window's \e{icon}.
+This makes sense in a windowing system where the window becomes an
+icon when minimised, such as Windows 3.1 or most X Window System
+setups; but in the Windows 95-like user interface it isn't as
+applicable.
+
+By default, PuTTY only uses the server-supplied \e{window} title, and
+ignores the icon title entirely. If for some reason you want to see
+both titles, check the box marked \q{Separate window and icon titles}.
+If you do this, PuTTY's window title and Taskbar caption will
+change into the server-supplied icon title if you minimise the PuTTY
+window, and change back to the server-supplied window title if you
+restore it. (If the server has not bothered to supply a window or
+icon title, none of this will happen.)
+
\S{config-warnonclose} \q{Warn before closing window}
\cfg{winhelp-topic}{behaviour.closewarn}
Not all server-side applications will support it.
If you need support for a numeric code page which is not listed in
-the drop-down list, such as code page 866, then you should be able
-to enter its name manually (\c{CP866} for example) in the list box
-and get the right result.
+the drop-down list, such as code page 866, then you can try entering
+its name manually (\c{CP866} for example) in the list box. If the
+underlying version of Windows has the appropriate translation table
+installed, PuTTY will use it.
\S{config-cyr} \q{Caps Lock acts as Cyrillic switch}
\cfg{winhelp-topic}{translation.linedraw}
-VT100-series terminals allow the server to send control sequences
-that shift temporarily into a separate character set for drawing
-lines and boxes. PuTTY has a variety of ways to support this
-capability. In general you should probably try lots of options until
-you find one that your particular font supports.
+VT100-series terminals allow the server to send control sequences that
+shift temporarily into a separate character set for drawing simple
+lines and boxes. However, there are a variety of ways in which PuTTY
+can attempt to find appropriate characters, and the right one to use
+depends on the locally configured font. In general you should probably
+try lots of options until you find one that your particular font
+supports.
+
+\b \q{Use Unicode line drawing code points} tries to use the box
+characters that are present in Unicode. For good Unicode-supporting
+fonts this is probably the most reliable and functional option.
+
+\b \q{Poor man's line drawing} assumes that the font \e{cannot}
+generate the line and box characters at all, so it will use the
+\c{+}, \c{-} and \c{|} characters to draw approximations to boxes.
+You should use this option if none of the other options works.
\b \q{Font has XWindows encoding} is for use with fonts that have a
special encoding, where the lowest 32 character positions (below the
\b \q{Use font in OEM mode only} is more reliable than that, but can
miss out other characters from the main character set.
-\b \q{Poor man's line drawing} assumes that the font \e{cannot}
-generate the line and box characters at all, so it will use the
-\c{+}, \c{-} and \c{|} characters to draw approximations to boxes.
-You should use this option if none of the other options works.
+\S{config-linedrawpaste} Controlling copy and paste of line drawing
+characters
-\b \q{Unicode mode} tries to use the box characters that are present
-in Unicode. For good Unicode-supporting fonts this is probably the
-most reliable and functional option.
+\cfg{winhelp-topic}{selection.linedraw}
+
+By default, when you copy and paste a piece of the PuTTY screen that
+contains VT100 line and box drawing characters, PuTTY will paste
+them in the form they appear on the screen: either Unicode line
+drawing code points, or the \q{poor man's} line-drawing characters
+\c{+}, \c{-} and \c{|}. The checkbox \q{Copy and paste VT100 line
+drawing chars as lqqqk} disables this feature, so line-drawing
+characters will be pasted as the ASCII characters that were printed
+to produce them. This will typically mean they come out mostly as
+\c{q} and \c{x}, with a scattering of \c{jklmntuvw} at the corners.
+This might be useful if you were trying to recreate the same box
+layout in another program, for example.
+
+Note that this option only applies to line-drawing characters which
+\e{were} printed by using the VT100 mechanism. Line-drawing
+characters that were received as Unicode code points will paste as
+Unicode always.
\H{config-selection} The Selection panel
The Selection panel allows you to control the way copy and paste
work in the PuTTY window.
-\S{config-linedrawpaste} Controlling the pasting of line drawing
-characters
-
-\cfg{winhelp-topic}{selection.linedraw}
-
-By default, when you copy and paste a piece of the PuTTY screen that
-contains VT100 line and box drawing characters, PuTTY will translate
-them into the \q{poor man's} line-drawing characters \c{+}, \c{-}
-and \c{|}. The checkbox \q{Don't translate line drawing chars}
-disables this feature, so line-drawing characters will be pasted as
-if they were in the normal character set. This will typically mean
-they come out mostly as \c{q} and \c{x}, with a scattering of
-\c{jklmntuvw} at the corners. This might be useful if you were
-trying to recreate the same box layout in another program, for
-example.
-
\S{config-rtfpaste} Pasting in Rich Text Format
\cfg{winhelp-topic}{selection.rtf}
\cfg{winhelp-topic}{selection.buttons}
-PuTTY's copy and paste mechanism is modelled on the Unix \c{xterm}
-application. The X Window System uses a three-button mouse, and the
-convention is that the left button selects, the right button extends
-an existing selection, and the middle button pastes.
+PuTTY's copy and paste mechanism is by default modelled on the Unix
+\c{xterm} application. The X Window System uses a three-button mouse,
+and the convention is that the left button selects, the right button
+extends an existing selection, and the middle button pastes.
-Windows typically only has two mouse buttons, so in PuTTY's default
-configuration, the \e{right} button pastes, and the \e{middle}
-button (if you have one) extends a selection.
+Windows often only has two mouse buttons, so in PuTTY's default
+configuration (\q{Compromise}), the \e{right} button pastes, and the
+\e{middle} button (if you have one) extends a selection.
If you have a three-button mouse and you are already used to the
\c{xterm} arrangement, you can select it using the \q{Action of
mouse buttons} control.
+Alternatively, with the \q{Windows} option selected, the middle
+button extends, and the right button brings up a context menu (on
+which one of the options is \q{Paste}). (This context menu is always
+available by holding down Ctrl and right-clicking, regardless of the
+setting of this option.)
+
\S{config-mouseshift} \q{Shift overrides application's use of mouse}
\cfg{winhelp-topic}{selection.shiftdrag}
isn't feasible to expand the list to cover the whole of Unicode.
Character class definitions can be modified by control sequences
-sent by the server. This configuration option only controls the
-\e{default} state. If you modify this option in mid-session using
-\q{Change Settings}, you will need to reset the terminal (see
-\k{reset-terminal}) before the change takes effect.
+sent by the server. This configuration option controls the
+\e{default} state, which will be restored when you reset the
+terminal (see \k{reset-terminal}). However, if you modify this
+option in mid-session using \q{Change Settings}, it will take effect
+immediately.
\H{config-colours} The Colours panel
The Colours panel allows you to control PuTTY's use of colour.
+\S{config-ansicolour} \q{Allow terminal to specify ANSI colours}
+
+\cfg{winhelp-topic}{colours.ansi}
+
+This option is enabled by default. If it is disabled, PuTTY will
+ignore any control sequences sent by the server to request coloured
+text.
+
+If you have a particularly garish application, you might want to
+turn this option off and make PuTTY only use the default foreground
+and background colours.
+
+\S{config-xtermcolour} \q{Allow terminal to use xterm 256-colour mode}
+
+\cfg{winhelp-topic}{colours.xterm256}
+
+This option is enabled by default. If it is disabled, PuTTY will
+ignore any control sequences sent by the server which use the
+extended 256-colour mode supported by recent versions of \cw{xterm}.
+
+If you have an application which is supposed to use 256-colour mode
+and it isn't working, you may find you need to tell your server that
+your terminal supports 256 colours. On Unix, you do this by ensuring
+that the setting of \cw{TERM} describes a 256-colour-capable
+terminal. You can check this using a command such as \c{infocmp}:
+
+\c $ infocmp | grep colors
+\c colors#256, cols#80, it#8, lines#24, pairs#256,
+\e bbbbbbbbbb
+
+If you do not see \cq{colors#256} in the output, you may need to
+change your terminal setting. On modern Linux machines, you could
+try \cq{xterm-256color}.
+
\S{config-boldcolour} \q{Bolded text is a different colour}
\cfg{winhelp-topic}{colours.bold}
you can try enabling this option. However, be warned that it's never
worked very well.
+\S{config-syscolour} \q{Use system colours}
+
+\cfg{winhelp-topic}{colours.system}
+
+Enabling this option will cause PuTTY to ignore the configured colours
+for \q{Default Background/Foreground} and \q{Cursor Colour/Text} (see
+\k{config-colourcfg}), instead going with the system-wide defaults.
+
+Note that non-bold and bold text will be the same colour if this
+option is enabled. You might want to change to indicating bold text
+by font changes (see \k{config-boldcolour}).
+
\S{config-colourcfg} Adjusting the colours in the terminal window
\cfg{winhelp-topic}{colours.config}
PuTTY allows you to set the cursor colour, the default foreground
and background, and the precise shades of all the ANSI configurable
colours (black, red, green, yellow, blue, magenta, cyan, and white).
-In addition, if you have selected \q{Bolded text is a different
-colour}, you can also modify the precise shades used for the bold
-versions of these colours.
+You can also modify the precise shades used for the bold versions of
+these colours; these are used to display bold text if you have
+selected \q{Bolded text is a different colour}, and can also be used
+if the server asks specifically to use them. (Note that \q{Default
+Bold Background} is \e{not} the background colour used for bold text;
+it is only used if the server specifically asks for a bold
+background.)
\H{config-connection} The Connection panel
The Connection panel allows you to configure options that apply to
more than one type of connection.
-\S{config-termtype} \q{Terminal-type string}
-
-\cfg{winhelp-topic}{connection.termtype}
-
-Most servers you might connect to with PuTTY are designed to be
-connected to from lots of different types of terminal. In order to
-send the right control sequences to each one, the server will need
-to know what type of terminal it is dealing with. Therefore, each of
-the SSH, Telnet and Rlogin protocols allow a text string to be sent
-down the connection describing the terminal.
-
-PuTTY attempts to emulate the Unix \c{xterm} program, and by default
-it reflects this by sending \c{xterm} as a terminal-type string. If
-you find this is not doing what you want - perhaps the remote
-terminal reports \q{Unknown terminal type} - you could try setting
-this to something different, such as \c{vt220}.
-
-If you're not sure whether a problem is due to the terminal type
-setting or not, you probably need to consult the manual for your
-application or your server.
-
-\S{config-username} \q{Auto-login username}
-
-\cfg{winhelp-topic}{connection.username}
-
-All three of the SSH, Telnet and Rlogin protocols allow you to
-specify what user name you want to log in as, without having to type
-it explicitly every time. (Some Telnet servers don't support this.)
-
-In this box you can type that user name.
-
\S{config-keepalive} Using keepalives to prevent disconnection
\cfg{winhelp-topic}{connection.keepalive}
-If you find your sessions are closing unexpectedly (\q{Connection
-reset by peer}) after they have been idle for a while, you might
-want to try using this option.
+If you find your sessions are closing unexpectedly (most often with
+\q{Connection reset by peer}) after they have been idle for a while,
+you might want to try using this option.
Some network routers and firewalls need to keep track of all
connections through them. Usually, these firewalls will assume a
server.
Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
-protocols offer no way of implementing them.
+protocols offer no way of implementing them. (For an alternative, see
+\k{config-tcp-keepalives}.)
Note that if you are using SSH1 and the server has a bug that makes
it unable to deal with SSH1 ignore messages (see
The Nagle algorithm is disabled by default.
+\S{config-tcp-keepalives} \q{Enable TCP keepalives}
+
+\cfg{winhelp-topic}{connection.tcpkeepalive}
+
+\e{NOTE:} TCP keepalives should not be confused with the
+application-level keepalives described in \k{config-keepalive}. If in
+doubt, you probably want application-level keepalives; TCP keepalives
+are provided for completeness.
+
+The idea of TCP keepalives is similar to application-level keepalives,
+and the same caveats apply. The main differences are:
+
+\b TCP keepalives are available on \e{all} connection types, including
+Raw and Rlogin.
+
+\b The interval between TCP keepalives is usually much longer,
+typically two hours; this is set by the operating system, and cannot
+be configured within PuTTY.
+
+\b If the operating system does not receive a response to a keepalive,
+it may send out more in quick succession and if terminate the connection
+if no response is received.
+
+TCP keepalives may be more useful for ensuring that half-open connections
+are terminated than for keeping a connection alive.
+
+TCP keepalives are disabled by default.
+
+\S{config-address-family} \q{Internet protocol}
+
+\cfg{winhelp-topic}{connection.ipversion}
+
+This option allows the user to select between the old and new
+Internet protocols and addressing schemes (IPv4 and IPv6). The
+default setting is \q{Auto}, which means PuTTY will do something
+sensible and try to guess which protocol you wanted. (If you specify
+a literal Internet address, it will use whichever protocol that
+address implies. If you provide a hostname, it will see what kinds
+of address exist for that hostname; it will use IPv6 if there is an
+IPv6 address available, and fall back to IPv4 if not.)
+
+If you need to force PuTTY to use a particular protocol, you can
+explicitly set this to \q{IPv4} or \q{IPv6}.
+
+\H{config-data} The Data panel
+
+The Data panel allows you to configure various pieces of data which
+can be sent to the server to affect your connection at the far end.
+
+Each options on this panel applies to more than one protocol.
+Options which apply to only one protocol appear on that protocol's
+configuration panels.
+
+\S{config-username} \q{Auto-login username}
+
+\cfg{winhelp-topic}{connection.username}
+
+All three of the SSH, Telnet and Rlogin protocols allow you to
+specify what user name you want to log in as, without having to type
+it explicitly every time. (Some Telnet servers don't support this.)
+
+In this box you can type that user name.
+
+\S{config-termtype} \q{Terminal-type string}
+
+\cfg{winhelp-topic}{connection.termtype}
+
+Most servers you might connect to with PuTTY are designed to be
+connected to from lots of different types of terminal. In order to
+send the right control sequences to each one, the server will need
+to know what type of terminal it is dealing with. Therefore, each of
+the SSH, Telnet and Rlogin protocols allow a text string to be sent
+down the connection describing the terminal.
+
+PuTTY attempts to emulate the Unix \c{xterm} program, and by default
+it reflects this by sending \c{xterm} as a terminal-type string. If
+you find this is not doing what you want - perhaps the remote
+system reports \q{Unknown terminal type} - you could try setting
+this to something different, such as \c{vt220}.
+
+If you're not sure whether a problem is due to the terminal type
+setting or not, you probably need to consult the manual for your
+application or your server.
+
+\S{config-termspeed} \q{Terminal speeds}
+
+\cfg{winhelp-topic}{connection.termspeed}
+
+The Telnet, Rlogin, and SSH protocols allow the client to specify
+terminal speeds to the server.
+
+This parameter does \e{not} affect the actual speed of the connection,
+which is always \q{as fast as possible}; it is just a hint that is
+sometimes used by server software to modify its behaviour. For
+instance, if a slow speed is indicated, the server may switch to a
+less bandwidth-hungry display mode.
+
+The value is usually meaningless in a network environment, but
+PuTTY lets you configure it, in case you find the server is reacting
+badly to the default value.
+
+The format is a pair of numbers separated by a comma, for instance,
+\c{38400,38400}. The first number represents the output speed
+(\e{from} the server) in bits per second, and the second is the input
+speed (\e{to} the server). (Only the first is used in the Rlogin
+protocol.)
+
+This option has no effect on Raw connections.
+
+\S{config-environ} Setting environment variables on the server
+
+\cfg{winhelp-topic}{telnet.environ}
+
+The Telnet protocol provides a means for the client to pass
+environment variables to the server. Many Telnet servers have
+stopped supporting this feature due to security flaws, but PuTTY
+still supports it for the benefit of any servers which have found
+other ways around the security problems than just disabling the
+whole mechanism.
+
+Version 2 of the SSH protocol also provides a similar mechanism,
+which is easier to implement without security flaws. Newer SSH2
+servers are more likely to support it than older ones.
+
+This configuration data is not used in the SSHv1, rlogin or raw
+protocols.
+
+To add an environment variable to the list transmitted down the
+connection, you enter the variable name in the \q{Variable} box,
+enter its value in the \q{Value} box, and press the \q{Add} button.
+To remove one from the list, select it in the list box and press
+\q{Remove}.
+
\H{config-proxy} The Proxy panel
\cfg{winhelp-topic}{proxy.main}
web server supporting the HTTP \cw{CONNECT} command, as documented
in \W{http://www.ietf.org/rfc/rfc2817.txt}{RFC 2817}.
-\b Selecting \q{SOCKS} allows you to proxy your connections through
-a SOCKS server.
+\b Selecting \q{SOCKS 4} or \q{SOCKS 5} allows you to proxy your
+connections through a SOCKS server.
\b Many firewalls implement a less formal type of proxy in which a
user can make a Telnet connection directly to the firewall machine
This excludes both of the above ranges at once.
+Connections to the local host (the host name \c{localhost}, and any
+loopback IP address) are never proxied, even if the proxy exclude
+list does not explicitly contain them. It is very unlikely that this
+behaviour would ever cause problems, but if it does you can change
+it by enabling \q{Consider proxying local host connections}.
+
+Note that if you are doing DNS at the proxy (see
+\k{config-proxy-dns}), you should make sure that your proxy
+exclusion settings do not depend on knowing the IP address of a
+host. If the name is passed on to the proxy without PuTTY looking it
+up, it will never know the IP address and cannot check it against
+your list.
+
+\S{config-proxy-dns} Name resolution when using a proxy
+
+\cfg{winhelp-topic}{proxy.dns}
+
+If you are using a proxy to access a private network, it can make a
+difference whether DNS name resolution is performed by PuTTY itself
+(on the client machine) or performed by the proxy.
+
+The \q{Do DNS name lookup at proxy end} configuration option allows
+you to control this. If you set it to \q{No}, PuTTY will always do
+its own DNS, and will always pass an IP address to the proxy. If you
+set it to \q{Yes}, PuTTY will always pass host names straight to the
+proxy without trying to look them up first.
+
+If you set this option to \q{Auto} (the default), PuTTY will do
+something it considers appropriate for each type of proxy. Telnet
+and HTTP proxies will have host names passed straight to them; SOCKS
+proxies will not.
+
+Note that if you are doing DNS at the proxy, you should make sure
+that your proxy exclusion settings (see \k{config-proxy-exclude}) do
+not depend on knowing the IP address of a host. If the name is
+passed on to the proxy without PuTTY looking it up, it will never
+know the IP address and cannot check it against your list.
+
+The original SOCKS 4 protocol does not support proxy-side DNS. There
+is a protocol extension (SOCKS 4A) which does support it, but not
+all SOCKS 4 servers provide this extension. If you enable proxy DNS
+and your SOCKS 4 server cannot deal with it, this might be why.
+
\S{config-proxy-auth} Username and password
\cfg{winhelp-topic}{proxy.auth}
If your proxy requires authentication, you can enter a username and
a password in the \q{Username} and \q{Password} boxes.
-Authentication is not supported for all forms of proxy:
+Note that if you save your session, the proxy password will be
+saved in plain text, so anyone who can access your PuTTY
+configuration data will be able to discover it.
+
+Authentication is not fully supported for all forms of proxy:
\b Username and password authentication is supported for HTTP
proxies and SOCKS 5 proxies.
+\lcont{
+
+\b With SOCKS 5, authentication is via \i{CHAP} if the proxy
+supports it (this is not supported in \i{PuTTYtel}); otherwise the
+password is sent to the proxy in plain text.
+
+\b With HTTP proxying, the only currently supported authentication
+method is \q{basic}, where the password is sent to the proxy in plain
+text.
+
+}
+
\b SOCKS 4 can use the \q{Username} field, but does not support
passwords.
If the Telnet proxy server prompts for a username and password
before commands can be sent, you can use a command such as:
-\c %user\\n%pass\\nconnect %host %port\\n
+\c %user\n%pass\nconnect %host %port\n
This will send your username and password as the first two lines to
the proxy, followed by a command to connect to the desired host and
tokens in the Telnet command, then the \q{Username} and \q{Password}
configuration fields will be ignored.
-\S{config-proxy-socksver} Selecting the version of the SOCKS protocol
-
-\cfg{winhelp-topic}{proxy.socksver}
-
-SOCKS servers exist in two versions: version 5
-(\W{http://www.ietf.org/rfc/rfc1928.txt}{RFC 1928}) and the earlier
-version 4. The \q{SOCKS Version} radio buttons allow you to select
-which one to use, if you have selected the SOCKS proxy type.
-
\H{config-telnet} The Telnet panel
The Telnet panel allows you to configure options that only apply to
Telnet sessions.
-\S{config-termspeed} \q{Terminal-speed string}
-
-\cfg{winhelp-topic}{telnet.termspeed}
-
-Telnet allows the client to send a text string that describes the
-terminal speed. PuTTY lets you configure this, in case you find the
-server is reacting badly to the default value. (I'm not aware of any
-servers that do have a problem with it.)
-
-\S{config-environ} Setting environment variables on the server
-
-\cfg{winhelp-topic}{telnet.environ}
-
-The Telnet protocol also provides a means for the client to pass
-environment variables to the server. Many Telnet servers have
-stopped supporting this feature due to security flaws, but PuTTY
-still supports it for the benefit of any servers which have found
-other ways around the security problems than just disabling the
-whole mechanism.
-
-To add an environment variable to the list transmitted down the
-connection, you enter the variable name in the \q{Variable} box,
-enter its value in the \q{Value} box, and press the \q{Add} button.
-To remove one from the list, select it in the list box and press
-\q{Remove}.
-
\S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
\cfg{winhelp-topic}{telnet.oldenviron}
you have confusing trouble with a firewall, you could try enabling
passive mode to see if it helps.
-\S{config-telnetkey} \q{Keyboard sends telnet Backspace and Interrupt}
+\S{config-telnetkey} \q{Keyboard sends Telnet special commands}
\cfg{winhelp-topic}{telnet.specialkeys}
-If this box is checked, the Backspace key on the keyboard will send
-the Telnet special backspace code, and Control-C will send the
-Telnet special interrupt code. You probably shouldn't enable this
+If this box is checked, several key sequences will have their normal
+actions modified:
+
+\b the Backspace key on the keyboard will send the \I{Erase Character,
+Telnet special command}Telnet special backspace code;
+
+\b Control-C will send the Telnet special \I{Interrupt Process, Telnet
+special command}Interrupt Process code;
+
+\b Control-Z will send the Telnet special \I{Suspend Process, Telnet
+special command}Suspend Process code.
+
+You probably shouldn't enable this
unless you know what you're doing.
-\S{config-telnetnl} \q{Return key sends telnet New Line instead of ^M}
+\S{config-telnetnl} \q{Return key sends Telnet New Line instead of ^M}
\cfg{winhelp-topic}{telnet.newline}
The Rlogin panel allows you to configure options that only apply to
Rlogin sessions.
-\S{config-rlogin-termspeed} \q{Terminal-speed string}
-
-\cfg{winhelp-topic}{rlogin.termspeed}
-
-Like Telnet, Rlogin allows the client to send a text string that
-describes the terminal speed. PuTTY lets you configure this, in case
-you find the server is reacting badly to the default value. (I'm not
-aware of any servers that do have a problem with it.)
-
\S{config-rlogin-localuser} \q{Local username}
\cfg{winhelp-topic}{rlogin.localuser}
very specialist purposes; although in Plink (see \k{plink}) it is
the usual way of working.
+\S{config-ssh-noshell} \q{Don't start a shell or command at all}
+
+\cfg{winhelp-topic}{ssh.noshell}
+
+If you tick this box, PuTTY will not attempt to run a shell or
+command after connecting to the remote server. You might want to use
+this option if you are only using the SSH connection for port
+forwarding, and your user account on the server does not have the
+ability to run a shell.
+
+This feature is only available in SSH protocol version 2 (since the
+version 1 protocol assumes you will always want to run a shell).
+
+This feature can also be enabled using the \c{-N} command-line
+option; see \k{using-cmdline-noshell}.
+
+If you use this feature in Plink, you will not be able to terminate
+the Plink process by any graceful means; the only way to kill it
+will be by pressing Control-C or sending a kill signal from another
+program.
+
\S{config-ssh-comp} \q{Enable compression}
\cfg{winhelp-topic}{ssh.compress}
top until it finds an algorithm supported by the server, and then
use that.
+PuTTY currently supports the following algorithms:
+
+\b AES (Rijndael) - 256, 192, or 128-bit CBC (SSH-2 only)
+
+\b Blowfish - 128-bit CBC
+
+\b Triple-DES - 168-bit CBC
+
+\b Single-DES - 56-bit CBC (see below for SSH-2)
+
If the algorithm PuTTY finds is below the \q{warn below here} line,
you will see a warning box when you make the connection:
get two warnings similar to the one above, possibly with different
encryptions.
-Single-DES is not supported natively in the SSH 2 draft protocol
-standards. One or two server implementations do support it, by a
-non-standard name. PuTTY can use single-DES to interoperate with
-these servers if you enable the \q{Enable non-standard single-DES in
+Single-DES is not recommended in the SSH 2 draft protocol
+standards, but one or two server implementations do support it.
+PuTTY can use single-DES to interoperate with
+these servers if you enable the \q{Enable legacy use of single-DES in
SSH 2} option; by default this is disabled and PuTTY will stick to
-the standard.
+recommended ciphers.
+
+\H{config-ssh-kex} The Kex panel
+
+\# FIXME: This whole section is draft. Feel free to revise.
+
+The Kex panel (short for \q{key exchange}) allows you to configure
+options related to SSH-2 key exchange.
+
+Key exchange occurs at the start of an SSH connection (and
+occasionally thereafter); it establishes a shared secret that is used
+as the basis for all of SSH's security features. It is therefore very
+important for the security of the connection that the key exchange is
+secure.
+
+Key exchange is a cryptographically intensive process; if either the
+client or the server is a relatively slow machine, the slower methods
+may take several tens of seconds to complete.
+
+If connection startup is too slow, or the connection hangs
+periodically, you may want to try changing these settings.
+
+If you don't understand what any of this means, it's safe to leave
+these settings alone.
+
+This entire panel is only relevant to SSH protocol version 2; none of
+these settings affect SSH-1 at all.
+
+\S{config-ssh-kex-order} Key exchange algorithm selection
+
+\cfg{winhelp-topic}{ssh.kex.order}
+
+PuTTY supports a variety of SSH-2 key exchange methods, and allows you
+to choose which one you prefer to use; configuration is similar to
+cipher selection (see \k{config-ssh-encryption}).
+
+PuTTY currently supports the following varieties of Diffie-Hellman key
+exchange:
+
+\b \q{Group 14}: a well-known 2048-bit group.
+
+\b \q{Group 1}: a well-known 1024-bit group. This is less secure
+\#{FIXME better words} than group 14, but may be faster with slow
+client or server machines, and may be the only method supported by
+older server software.
+
+\b \q{Group exchange}: with this method, instead of using a fixed
+group, PuTTY requests that the server suggest a group to use for key
+exchange; the server can avoid groups known to be weak, and possibly
+invent new ones over time, without any changes required to PuTTY's
+configuration. We recommend use of this method, if possible.
+
+If the first algorithm PuTTY finds is below the \q{warn below here}
+line, you will see a warning box when you make the connection, similar
+to that for cipher selection (see \k{config-ssh-encryption}).
+
+\S{config-ssh-kex-rekey} Repeat key exchange
+
+\cfg{winhelp-topic}{ssh.kex.repeat}
+
+If the session key negotiated at connection startup is used too much
+or for too long, it may become feasible to mount attacks against the
+SSH connection. Therefore, the SSH-2 protocol specifies that a new key
+exchange should take place every so often; this can be initiated by
+either the client or the server.
+
+While this renegotiation is taking place, no data can pass through
+the SSH connection, so it may appear to \q{freeze}. (The occurrence of
+repeat key exchange is noted in the Event Log; see
+\k{using-eventlog}.) Usually the same algorithm is used as at the
+start of the connection, with a similar overhead.
+
+These options control how often PuTTY will initiate a repeat key
+exchange (\q{rekey}). You can also force a key exchange at any time
+from the Special Commands menu (see \k{using-specials}).
+
+\# FIXME: do we have any additions to the SSH-2 drafts' advice on
+these values? Do we want to enforce any limits?
+
+\b \q{Max minutes before rekey} specifies the amount of time that is
+allowed to elapse before a rekey is initiated. If this is set to zero,
+PuTTY will not rekey due to elapsed time. The SSH-2 protocol
+specification recommends a timeout of at most 60 minutes.
+
+\b \q{Max data before rekey} specifies the amount of data (in bytes)
+that is permitted to flow in either direction before a rekey is
+initiated. If this is set to zero, PuTTY will not rekey due to
+transferred data. The SSH-2 protocol specification recommends a limit
+of at most 1 gigabyte.
+
+\lcont{
+
+As well as specifying a value in bytes, the following shorthand can be
+used:
+
+\b \cq{1k} specifies 1 kilobyte (1024 bytes).
+
+\b \cq{1M} specifies 1 megabyte (1024 kilobytes).
+
+\b \cq{1G} specifies 1 gigabyte (1024 megabytes).
+
+}
+
+PuTTY can be prevented from initiating a rekey entirely by setting
+both of these values to zero. (Note, however, that the SSH
+\e{server} may still initiate rekeys.)
+
+You might have a need to disable rekeys completely for the same
+reasons that keepalives aren't always helpful. If you anticipate
+suffering a network dropout of several hours in the middle of an SSH
+connection, but were not actually planning to send \e{data} down
+that connection during those hours, then an attempted rekey in the
+middle of the dropout will probably cause the connection to be
+abandoned, whereas if rekeys are disabled then the connection should
+in principle survive (in the absence of interfering firewalls). See
+\k{config-keepalive} for more discussion of these issues; for these
+purposes, rekeys have much the same properties as keepalives.
+(Except that rekeys have cryptographic value in themselves, so you
+should bear that in mind when deciding whether to turn them off.)
\H{config-ssh-auth} The Auth panel
are using public key authentication. See \k{pubkey} for information
about public key authentication in SSH.
-\H{config-ssh-tunnels} The Tunnels panel
-
-The Tunnels panel allows you to configure tunnelling of other
-connection types through an SSH connection.
+This key must be in PuTTY's native format (\c{*.PPK}).
-\S{config-ssh-x11} X11 forwarding
+\H{config-ssh-x11} The X11 panel
\cfg{winhelp-topic}{ssh.tunnels.x11}
+The X11 panel allows you to configure forwarding of X11 over an
+SSH connection.
+
If your server lets you run X Window System applications, X11
forwarding allows you to securely give those applications access to
a local X display on your PC.
To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
-If your X display is not the primary display on your local machine
-(which it almost certainly will be unless you have deliberately
-arranged otherwise), you need to enter its location in the \q{X
-display location} box.
+If your X display is somewhere unusual, you will need to enter its
+location in the \q{X display location} box; if this is left blank,
+PuTTY try to find a sensible default in the environment, or use the
+primary local display (\c{:0}) if that fails.
See \k{using-x-forwarding} for more information about X11
forwarding.
-\S{config-ssh-portfwd} Port forwarding
+\S{config-ssh-x11auth} Remote X11 authentication
+
+\cfg{winhelp-topic}{ssh.tunnels.x11auth}
+
+If you are using X11 forwarding, the virtual X server created on the
+SSH server machine will be protected by authorisation data. This
+data is invented, and checked, by PuTTY.
+
+The usual authorisation method used for this is called
+\cw{MIT-MAGIC-COOKIE-1}. This is a simple password-style protocol:
+the X client sends some cookie data to the server, and the server
+checks that it matches the real cookie. The cookie data is sent over
+an unencrypted X11 connection; so if you allow a client on a third
+machine to access the virtual X server, then the cookie will be sent
+in the clear.
+
+PuTTY offers the alternative protocol \cw{XDM-AUTHORIZATION-1}. This
+is a cryptographically authenticated protocol: the data sent by the
+X client is different every time, and it depends on the IP address
+and port of the client's end of the connection and is also stamped
+with the current time. So an eavesdropper who captures an
+\cw{XDM-AUTHORIZATION-1} string cannot immediately re-use it for
+their own X connection.
+
+PuTTY's support for \cw{XDM-AUTHORIZATION-1} is a somewhat
+experimental feature, and may encounter several problems:
+
+\b Some X clients probably do not even support
+\cw{XDM-AUTHORIZATION-1}, so they will not know what to do with the
+data PuTTY has provided.
+
+\b This authentication mechanism will only work in SSH v2. In SSH
+v1, the SSH server does not tell the client the source address of
+a forwarded connection in a machine-readable format, so it's
+impossible to verify the \cw{XDM-AUTHORIZATION-1} data.
+
+\b You may find this feature causes problems with some SSH servers,
+which will not clean up \cw{XDM-AUTHORIZATION-1} data after a
+session, so that if you then connect to the same server using
+a client which only does \cw{MIT-MAGIC-COOKIE-1} and are allocated
+the same remote display number, you might find that out-of-date
+authentication data is still present on your server and your X
+connections fail.
+
+PuTTY's default is \cw{MIT-MAGIC-COOKIE-1}. If you change it, you
+should be sure you know what you're doing.
+
+\H{config-ssh-portfwd} The Tunnels panel
\cfg{winhelp-topic}{ssh.tunnels.portfwd}
+The Tunnels panel allows you to configure tunnelling of arbitrary
+connection types through an SSH connection.
+
Port forwarding allows you to tunnel other types of network
connection down an SSH session. See \k{using-port-forwarding} for a
general discussion of port forwarding and how it works.
\b Set one of the \q{Local} or \q{Remote} radio buttons, depending
on whether you want to forward a local port to a remote destination
(\q{Local}) or forward a remote port to a local destination
-(\q{Remote}).
+(\q{Remote}). Alternatively, select \q{Dynamic} if you want PuTTY to
+provide a local SOCKS 4/4A/5 proxy on a local port.
\b Enter a source port number into the \q{Source port} box. For
local forwardings, PuTTY will listen on this port of your PC. For
remote machine. Note that most servers will not allow you to listen
on port numbers less than 1024.
-\b Enter a hostname and port number separated by a colon, in the
-\q{Destination} box. Connections received on the source port will be
-directed to this destination. For example, to connect to a POP-3
-server, you might enter \c{popserver.example.com:110}.
+\b If you have selected \q{Local} or \q{Remote} (this step is not
+needed with \q{Dynamic}), enter a hostname and port number separated
+by a colon, in the \q{Destination} box. Connections received on the
+source port will be directed to this destination. For example, to
+connect to a POP-3 server, you might enter
+\c{popserver.example.com:110}.
\b Click the \q{Add} button. Your forwarding details should appear
in the list box.
box, and click the \q{Remove} button.
In the \q{Source port} box, you can also optionally enter an IP
-address to listen on. Typically a Windows machine can be asked to
-listen on any single IP address in the \cw{127.*.*.*} range, and all
-of these are loopback addresses available only to the local machine.
-So if you forward (for example) \c{127.0.0.5:79} to a remote
-machine's \cw{finger} port, then you should be able to run commands
-such as \c{finger fred@127.0.0.5}. This can be useful if the program
-connecting to the forwarded port doesn't allow you to change the
-port number it uses. This feature is available for local-to-remote
-forwarded ports; SSH1 is unable to support it for remote-to-local
-ports, while SSH2 can support it in theory but servers will not
-necessarily cooperate.
+address to listen on, by specifying (for instance) \c{127.0.0.5:79}.
+See \k{using-port-forwarding} for more information on how this
+works and its restrictions.
+
+You can modify the currently active set of port forwardings in
+mid-session using \q{Change Settings}. If you delete a local or
+dynamic port forwarding in mid-session, PuTTY will stop listening
+for connections on that port, so it can be re-used by another
+program. If you delete a remote port forwarding, note that:
+
+\b The SSHv1 protocol contains no mechanism for asking the server to
+stop listening on a remote port.
+
+\b The SSHv2 protocol does contain such a mechanism, but not all SSH
+servers support it. (In particular, OpenSSH does not support it in
+any version earlier than 3.9.)
+
+If you ask to delete a remote port forwarding and PuTTY cannot make
+the server actually stop listening on the port, it will instead just
+start refusing incoming connections on that port. Therefore,
+although the port cannot be reused by another program, you can at
+least be reasonably sure that server-side programs can no longer
+access the service at your end of the port forwarding.
\S{config-ssh-portfwd-localhost} Controlling the visibility of
forwarded ports
\b The \q{Local ports accept connections from other hosts} option
allows you to set up local-to-remote port forwardings in such a way
that machines other than your client PC can connect to the forwarded
-port.
+port. (This also applies to dynamic SOCKS forwarding.)
\b The \q{Remote ports do the same} option does the same thing for
remote-to-local port forwardings (so that machines other than the
this feature is only available in the SSH 2 protocol, and not all
SSH 2 servers support it (OpenSSH 3.0 does not, for example).
+\S{config-ssh-portfwd-address-family} Selecting Internet protocol
+version for forwarded ports
+
+\cfg{winhelp-topic}{ssh.tunnels.portfwd.ipversion}
+
+This switch allows you to select a specific Internet protocol (IPv4
+or IPv6) for the local end of a forwarded port. By default, it is
+set on \q{Auto}, which means that:
+
+\b for a local-to-remote port forwarding, PuTTY will listen for
+incoming connections in both IPv4 and (if available) IPv6
+
+\b for a remote-to-local port forwarding, PuTTY will choose a
+sensible protocol for the outgoing connection.
+
+\# FIXME: work out what this paragraph means, reword it for clarity,
+\# and reinstate it.
+Note that on Windows the address space for IPv4 and IPv6 is
+completely disjunct, so listening on IPv6 won't make PuTTY listen on
+IPv4. This behaviour may be different on most remote hosts when they
+are not operating Windows.
+
\H{config-ssh-bugs} The Bugs panel
Not all SSH servers work properly. Various existing servers have
\cfg{winhelp-topic}{ssh.bugs.derivekey2}
-Versions below 2.1.0 of the SSH server software from \cw{ssh.com}
+Versions below 2.0.11 of the SSH server software from \cw{ssh.com}
compute the keys for the session encryption incorrectly. This
problem can cause various error messages, such as \q{Incoming packet
was garbled on decryption}, or possibly even \q{Out of memory}.
This is an SSH2-specific bug.
-\S{config-ssh-bug-dhgex} \q{Chokes on Diffie-Hellman group exchange}
+\S{config-ssh-bug-pksessid2} \q{Misuses the session ID in PK auth}
-\cfg{winhelp-topic}{ssh.bugs.dhgex2}
+\cfg{winhelp-topic}{ssh.bugs.pksessid2}
-We have anecdotal evidence that some SSH servers claim to be able to
-perform Diffie-Hellman group exchange, but fail to actually do so
-when PuTTY tries to. If your SSH2 sessions spontaneously close
-immediately after opening the PuTTY window, it might be worth
-enabling the workaround for this bug to see if it helps.
+Versions below 2.3 of OpenSSH require SSH2 public-key authentication
+to be done slightly differently: the data to be signed by the client
+contains the session ID formatted in a different way. If public-key
+authentication mysteriously does not work but the Event Log (see
+\k{using-eventlog}) thinks it has successfully sent a signature, it
+might be worth enabling the workaround for this bug to see if it
+helps.
-We have no hard evidence that any specific version of specific
-server software reliably demonstrates this bug. Therefore, PuTTY
-will never \e{assume} a server has this bug; if you want the
-workaround, you need to enable it manually.
+If this bug is detected, PuTTY will sign data in the way OpenSSH
+expects. If this bug is enabled when talking to a correct server,
+SSH2 public-key authentication will fail.
This is an SSH2-specific bug.
\c regedit /s putty.reg
\c regedit /s puttyrnd.reg
\c start /w putty.exe
-\c regedit /e puttynew.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
-\c copy puttynew.reg putty.reg
-\c del puttynew.reg
+\c regedit /ea new.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
+\c copy new.reg putty.reg
+\c del new.reg
\c regedit /s puttydel.reg
This batch file needs two auxiliary files: \c{PUTTYRND.REG} which
\c REGEDIT4
\c
\c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
-\c "RandSeedFile"="a:\putty.rnd"
+\c "RandSeedFile"="a:\\putty.rnd"
You should replace \c{a:\\putty.rnd} with the location where you
want to store your random number data. If the aim is to carry around
projects / u / mdw / putty / blobdiff