-\versionid $Id: config.but,v 1.95 2004/10/19 13:54:50 jacob Exp $
+\define{versionidconfig} \versionid $Id$
\C{config} Configuring PuTTY
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
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.
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}
\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 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 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
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
+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
\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
SSH 2} option; by default this is disabled and PuTTY will stick to
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}).
+
+\# [Repeat key exchange bumph when config is added:] 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 protocol specifies that a new key exchange should
+take place every so often.
+
+\# 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.
+
+\# [When options are added to frob how often this happens, we should
+hardcode the values recommended by the drafts -- 1 hour, 1GB -- in
+this documentation, in case PuTTY's defaults are obscured by Default
+Settings etc. Assuming we think they're good advice, that is.]
+
\H{config-ssh-auth} The Auth panel
The Auth panel allows you to configure authentication options for
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}
projects / u / mdw / putty / blobdiff