X-Git-Url: https://git.distorted.org.uk/u/mdw/putty/blobdiff_plain/cecb13f6928246c1fc9f49c5613938b97b86da3d..77603464f5b4231df69eb20ca278062bd7aae9fb:/doc/config.but diff --git a/doc/config.but b/doc/config.but index db0369b6..53622989 100644 --- a/doc/config.but +++ b/doc/config.but @@ -53,10 +53,12 @@ you want them saved. Then come back to the Session panel. Select the \q{Default Settings} entry in the saved sessions list, with a single click. Then press the \q{Save} button. +\lcont{ Note that PuTTY does not allow you to save a host name into the Default Settings entry. This ensures that when PuTTY is started up, the host name box is always empty, so a user can always just type in a host name and connect. +} If there is a specific host you want to store the details of how to connect to, you should create a saved session, which will be @@ -69,6 +71,14 @@ Sessions} input box. (The server name is often a good choice for a saved session name.) Then press the \q{Save} button. Your saved session name should now appear in the list box. +\lcont{ +You can also save settings in mid-session, from the \q{Change Settings} +dialog. Settings changed since the start of the session will be saved +with their current values; as well as settings changed through the +dialog, this includes changes in window size, window title changes +sent by the server, and so on. +} + \b To reload a saved session: single-click to select the session name in the list box, and then press the \q{Load} button. Your saved settings should all appear in the configuration panel. @@ -76,7 +86,7 @@ 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, 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 @@ -206,6 +216,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. @@ -1409,6 +1435,20 @@ 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} @@ -1476,86 +1516,6 @@ background.) 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 -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-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-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} @@ -1648,6 +1608,111 @@ 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} @@ -2068,6 +2133,129 @@ 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. + +You might have a need to disable time-based 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.) +Note, however, the the SSH \e{server} can still initiate rekeys. + +\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). + +} + +Disabling data-based rekeys entirely is a bad idea. The integrity, +and to a lesser extent, confidentiality of the SSH-2 protocol depend +in part on rekeys occuring before a 32-bit packet sequence number +wraps around. Unlike time-based rekeys, data-based rekeys won't occur +when the SSH connection is idle, so they shouldn't cause the same +problems. The SSH-1 protocol, incidentally, has even weaker integrity +protection than SSH-2 without rekeys. + \H{config-ssh-auth} The Auth panel The Auth panel allows you to configure authentication options for @@ -2150,15 +2338,13 @@ about public key authentication in SSH. 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. @@ -2172,7 +2358,7 @@ 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} @@ -2219,10 +2405,13 @@ 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. -\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. @@ -2264,6 +2453,35 @@ 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. +In place of port numbers, you can enter service names, if they are +known to the local system. For instance, in the \q{Destination} box, +you could enter \c{popserver.example.com:pop3}. + +You can modify the currently active set of port forwardings in +mid-session using \q{Change Settings} (see \k{using-changesettings}). +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. + +If you delete a forwarding, any existing connections established using +that forwarding remain open. Similarly, changes to global settings +such as \q{Local ports accept connections from other hosts} only take +effect on new forwardings. + \S{config-ssh-portfwd-localhost} Controlling the visibility of forwarded ports @@ -2285,6 +2503,31 @@ SSH server machine can connect to the forwarded port.) Note that 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. + +Note that some operating systems may listen for incoming connections +in IPv4 even if you specifically asked for IPv6, because their IPv4 +and IPv6 protocol stacks are linked together. Apparently Linux does +this, and Windows does not. So if you're running PuTTY on Windows +and you tick \q{IPv6} for a local or dynamic port forwarding, it +will \e{only} be usable by connecting to it using IPv6; whereas if +you do the same on Linux, you can also use it with IPv4. However, +ticking \q{Auto} should always give you a port which you can connect +to using either protocol. + \H{config-ssh-bugs} The Bugs panel Not all SSH servers work properly. Various existing servers have @@ -2425,23 +2668,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} @@ -2460,6 +2686,26 @@ SSH2 public-key authentication will fail. This is an SSH2-specific bug. +\S{config-ssh-bug-rekey} \q{Handles key re-exchange badly} + +\cfg{winhelp-topic}{ssh.bugs.rekey2} + +Some SSH servers cannot cope with repeat key exchange at +all, and will ignore attempts by the client to start one. Since +PuTTY pauses the session while performing a repeat key exchange, the +effect of this would be to cause the session to hang after an hour +(unless you have your rekey timeout set differently; see +\k{config-ssh-kex-rekey} for more about rekeys). +Other, very old, SSH servers handle repeat key exchange even more +badly, and disconnect upon receiving a repeat key exchange request. + +If this bug is detected, PuTTY will never initiate a repeat key +exchange. If this bug is enabled when talking to a correct server, +the session should still function, but may be less secure than you +would expect. + +This is an SSH2-specific bug. + \H{config-file} Storing configuration in a file PuTTY does not currently support storing its configuration in a file