X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/5dce67f7b8609667d5328efd74d5acdd0de26946..d57f70afa40c24426e5f936c86f7640801d43f7a:/doc/config.but diff --git a/doc/config.but b/doc/config.but index 5498c6c0..f1258176 100644 --- a/doc/config.but +++ b/doc/config.but @@ -1,4 +1,4 @@ -\versionid $Id: config.but,v 1.96 2004/10/24 18:26:00 jacob Exp $ +\define{versionidconfig} \versionid $Id$ \C{config} Configuring PuTTY @@ -206,6 +206,22 @@ Finally (the default option), you might not want to have any 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. @@ -1389,6 +1405,40 @@ immediately. 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} @@ -1540,9 +1590,9 @@ To remove one from the list, select it in the list box and press \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 @@ -2048,6 +2098,111 @@ 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 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 server may +still initiate rekeys.) + \H{config-ssh-auth} The Auth panel The Auth panel allows you to configure authentication options for @@ -2405,23 +2560,6 @@ to talking to OpenSSH. 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}