-\versionid $Id: config.but,v 1.93 2004/10/13 13:43:11 simon 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
\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.
-
\S{config-linedrawpaste} Controlling copy and paste of line drawing
characters
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 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
In this box you can type that user name.
+\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}.
+
\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
The Telnet panel allows you to configure options that only apply to
Telnet sessions.
-\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.
-
-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}
projects / u / mdw / putty / blobdiff