-\versionid $Id: config.but,v 1.66 2003/06/25 15:52:29 jacob 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.
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
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}
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
individual PuTTY session. This allows you to distinguish your PuTTY
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.
-
-When you resize the PuTTY window, one of four things can happen:
+to resize the PuTTY window using its window furniture.
-\b Nothing (if you have completely disabled resizes).
+There are four options here:
-\b The font size can stay the same and the number of rows and
-columns in the terminal can change.
+\b \q{Change the number of rows and columns}: the font size will not
+change. (This is the default.)
-\b The number of rows and columns in the terminal can stay the same,
-and the font size 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 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.
+\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.
-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
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
+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
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.
-
-\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.
-
-\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
+\S{config-linedrawpaste} Controlling copy and paste of line drawing
characters
\cfg{winhelp-topic}{selection.linedraw}
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{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.
+\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 displayed using Unicode will paste as Unicode always.
+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-rtfpaste} Pasting in Rich Text Format
\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}
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}
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.
+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}
If your proxy requires authentication, you can enter a username and
a password in the \q{Username} and \q{Password} boxes.
+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.
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}
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
This key must be in PuTTY's native format (\c{*.PPK}).
-\H{config-ssh-tunnels} The Tunnels panel
-
-The Tunnels panel allows you to configure tunnelling of other
-connection types through an SSH connection.
-
-\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.
-\S2{config-ssh-x11auth} Remote X11 authentication
+\S{config-ssh-x11auth} Remote X11 authentication
\cfg{winhelp-topic}{ssh.tunnels.x11auth}
PuTTY's default is \cw{MIT-MAGIC-COOKIE-1}. If you change it, you
should be sure you know what you're doing.
-\S{config-ssh-portfwd} Port forwarding
+\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.
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}). Alternatively, select \q{Dynamic} if you want PuTTY to
-provide a local SOCKS proxy on a local port.
+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
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
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
This is an SSH2-specific bug.
-\S{config-ssh-bug-dhgex} \q{Chokes on Diffie-Hellman group exchange}
-
-\cfg{winhelp-topic}{ssh.bugs.dhgex2}
-
-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.
-
-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.
-
-This is an SSH2-specific bug.
-
\S{config-ssh-bug-pksessid2} \q{Misuses the session ID in PK auth}
\cfg{winhelp-topic}{ssh.bugs.pksessid2}
\c regedit /s putty.reg
\c regedit /s puttyrnd.reg
\c start /w putty.exe
-\c regedit /ea 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