X-Git-Url: https://asedeno.scripts.mit.edu/gitweb/?a=blobdiff_plain;f=doc%2Fconfig.but;h=04c9cd7065d64294f8d71bed88899d75d03fc375;hb=359b5c8eb45ff56c62032cf147fcdb3723d54324;hp=16d158990ac5684e65c35462c03bbb8fcc864a95;hpb=822628246ebf0036c83f0f6eba4233e518433249;p=PuTTY.git diff --git a/doc/config.but b/doc/config.but index 16d15899..04c9cd70 100644 --- a/doc/config.but +++ b/doc/config.but @@ -1,5 +1,3 @@ -\define{versionidconfig} \versionid $Id$ - \C{config} Configuring PuTTY This chapter describes all the \i{configuration options} in PuTTY. @@ -209,6 +207,9 @@ digits. \b \c{&H} will be replaced by the host name you are connecting to. +\b \c{&P} will be replaced by the port number you are connecting to on +the target host. + For example, if you enter the host name \c{c:\\puttylogs\\log-&h-&y&m&d-&t.dat}, you will end up with files looking like @@ -933,6 +934,15 @@ setting you want if you have no better ideas. \dd PuTTY responds with the actual window title. This is dangerous for the reasons described above. +\S{config-features-clearscroll} Disabling remote \i{scrollback clearing} + +\cfg{winhelp-topic}{features.clearscroll} + +PuTTY has the ability to clear the terminal's scrollback buffer in +response to a command from the server. If you find PuTTY is doing this +unexpectedly or inconveniently, you can tell PuTTY not to respond to +that server command. + \S{config-features-dbackspace} Disabling \i{destructive backspace} \cfg{winhelp-topic}{features.dbackspace} @@ -951,7 +961,7 @@ configuration PuTTY has the ability to change its character set configuration in response to commands from the server. Some programs send these -commands unexpectedly or inconveniently. In particular, \I{BitchX} (an +commands unexpectedly or inconveniently. In particular, \i{BitchX} (an IRC client) seems to have a habit of reconfiguring the character set to something other than the user intended. @@ -1030,7 +1040,9 @@ the terminal will stay the same, and the \i{font size} will change. \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 \i{maximise}d (or restored), when the font size will change. +is \i{maximise}d (or restored), when the font size will change. (In +this mode, holding down the Alt key while resizing will also cause the +font size to change.) \b \q{Forbid resizing completely}: the terminal will refuse to be resized at all. @@ -1094,10 +1106,15 @@ works in any of the cursor modes. \cfg{winhelp-topic}{appearance.font} This option allows you to choose what font, in what \I{font size}size, -the PuTTY terminal window uses to display the text in the session. You -will be offered a choice from all the fixed-width fonts installed on the -system. (VT100-style terminal handling can only deal with fixed-width -fonts.) +the PuTTY terminal window uses to display the text in the session. + +By default, you will be offered a choice from all the fixed-width +fonts installed on the system, since VT100-style terminal handling +expects a fixed-width font. If you tick the box marked \q{Allow +selection of variable-pitch fonts}, however, PuTTY will offer +variable-width fonts as well: if you select one of these, the font +will be coerced into fixed-size character cells, which will probably +not look very good (but can work OK with some fonts). \S{config-mouseptr} \q{Hide \i{mouse pointer} when typing in window} @@ -1240,15 +1257,23 @@ the character set understood by PuTTY. During an interactive session, PuTTY receives a stream of 8-bit bytes from the server, and in order to display them on the screen it -needs to know what character set to interpret them in. +needs to know what character set to interpret them in. Similarly, +PuTTY needs to know how to translate your keystrokes into the encoding +the server expects. Unfortunately, there is no satisfactory +mechanism for PuTTY and the server to communicate this information, +so it must usually be manually configured. + +There are a lot of character sets to choose from. The \q{Remote +character set} option lets you select one. -There are a lot of character sets to choose from. The \q{Received -data assumed to be in which character set} option lets you select -one. By default PuTTY will attempt to choose a character set that is -right for your \i{locale} as reported by Windows; if it gets it wrong, -you can select a different one using this control. +By default PuTTY will use the \i{UTF-8} encoding of \i{Unicode}, which +can represent pretty much any character; data coming from the server +is interpreted as UTF-8, and keystrokes are sent UTF-8 encoded. This +is what most modern distributions of Linux will expect by default. +However, if this is wrong for your server, you can select a different +character set using this control. -A few notable character sets are: +A few other notable character sets are: \b The \i{ISO-8859} series are all standard character sets that include various accented characters appropriate for different sets of @@ -1262,11 +1287,6 @@ Euro symbol. \b If you want the old IBM PC character set with block graphics and line-drawing characters, you can select \q{\i{CP437}}. -\b PuTTY also supports \i{Unicode} mode, in which the data coming from -the server is interpreted as being in the \i{UTF-8} encoding of Unicode. -If you select \q{UTF-8} as a character set you can use this mode. -Not all server-side applications will support it. - If you need support for a numeric \i{code page} which is not listed in the drop-down list, such as code page 866, then you can try entering its name manually (\c{\i{CP866}} for example) in the list box. If the @@ -1529,20 +1549,26 @@ 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} +\S{config-boldcolour} \q{Indicate bolded text by changing...} \cfg{winhelp-topic}{colours.bold} When the server sends a \i{control sequence} indicating that some text -should be displayed in \i{bold}, PuTTY can handle this two ways. It can -either change the \i{font} for a bold version, or use the same font in a -brighter colour. This control lets you choose which. - -By default the box is checked, so non-bold text is displayed in -light grey and bold text is displayed in bright white (and similarly -in other colours). If you uncheck the box, bold and non-bold text -will be displayed in the same colour, and instead the font will -change to indicate the difference. +should be displayed in \i{bold}, PuTTY can handle this in several +ways. It can either change the \i{font} for a bold version, or use the +same font in a brighter colour, or it can do both (brighten the colour +\e{and} embolden the font). This control lets you choose which. + +By default bold is indicated by colour, so non-bold text is displayed +in light grey and bold text is displayed in bright white (and +similarly in other colours). If you change the setting to \q{The font} +box, bold and non-bold text will be displayed in the same colour, and +instead the font will change to indicate the difference. If you select +\q{Both}, the font and the colour will both change. + +Some applications rely on \q{\i{bold black}} being distinguishable +from a black background; if you choose \q{The font}, their text may +become invisible. \S{config-logpalette} \q{Attempt to use \i{logical palettes}} @@ -1588,10 +1614,10 @@ and \I{default background}background, and the precise shades of all the \I{ANSI colours}ANSI configurable colours (black, red, green, yellow, blue, magenta, cyan, and white). You can also modify the precise shades used for the \i{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. (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 +if you have chosen to indicate that by colour (see \k{config-boldcolour}), +and can also be used 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 @@ -1650,7 +1676,7 @@ Keepalives are only supported in Telnet and SSH; the Rlogin and Raw protocols offer no way of implementing them. (For an alternative, see \k{config-tcp-keepalives}.) -Note that if you are using \i{SSH-1} and the server has a bug that makes +Note that if you are using SSH-1 and the server has a bug that makes it unable to deal with SSH-1 ignore messages (see \k{config-ssh-bug-ignore1}), enabling keepalives will have no effect. @@ -1716,6 +1742,56 @@ 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}. +\S{config-loghost} \I{logical host name}\q{Logical name of remote host} + +\cfg{winhelp-topic}{connection.loghost} + +This allows you to tell PuTTY that the host it will really end up +connecting to is different from where it thinks it is making a +network connection. + +You might use this, for instance, if you had set up an SSH port +forwarding in one PuTTY session so that connections to some +arbitrary port (say, \cw{localhost} port 10022) were forwarded to a +second machine's SSH port (say, \cw{foovax} port 22), and then +started a second PuTTY connecting to the forwarded port. + +In normal usage, the second PuTTY will access the \i{host key cache} +under the host name and port it actually connected to (i.e. +\cw{localhost} port 10022 in this example). Using the logical host +name option, however, you can configure the second PuTTY to cache +the host key under the name of the host \e{you} know that it's +\e{really} going to end up talking to (here \c{foovax}). + +This can be useful if you expect to connect to the same actual +server through many different channels (perhaps because your port +forwarding arrangements keep changing): by consistently setting the +logical host name, you can arrange that PuTTY will not keep asking +you to reconfirm its host key. Conversely, if you expect to use the +same local port number for port forwardings to lots of different +servers, you probably didn't want any particular server's host key +cached under that local port number. (For this latter case, you +could instead explicitly configure host keys in the relevant sessions; +see \k{config-ssh-kex-manual-hostkeys}.) + +If you just enter a host name for this option, PuTTY will cache the +SSH host key under the default SSH port for that host, irrespective +of the port you really connected to (since the typical scenario is +like the above example: you connect to a silly real port number and +your connection ends up forwarded to the normal port-22 SSH server +of some other machine). To override this, you can append a port +number to the logical host name, separated by a colon. E.g. entering +\cq{foovax:2200} as the logical host name will cause the host key to +be cached as if you had connected to port 2200 of \c{foovax}. + +If you provide a host name using this option, it is also displayed +in other locations which contain the remote host name, such as the +default window title and the default SSH password prompt. This +reflects the fact that this is the host you're \e{really} connecting +to, which is more important than the mere means you happen to be +using to contact that host. (This applies even if you're using a +protocol other than SSH.) + \H{config-data} The Data panel The Data panel allows you to configure various pieces of data which @@ -1735,6 +1811,24 @@ it explicitly every time. (Some Telnet servers don't support this.) In this box you can type that user name. +\S{config-username-from-env} Use of system username + +\cfg{winhelp-topic}{connection.usernamefromenv} + +When the previous box (\k{config-username}) is left blank, by default, +PuTTY will prompt for a username at the time you make a connection. + +In some environments, such as the networks of large organisations +implementing \i{single sign-on}, a more sensible default may be to use +the name of the user logged in to the local operating system (if any); +this is particularly likely to be useful with \i{GSSAPI} authentication +(see \k{config-ssh-auth-gssapi}). This control allows you to change +the default behaviour. + +The current system username is displayed in the dialog as a +convenience. It is not saved in the configuration; if a saved session +is later used by a different user, that user's name will be used. + \S{config-termtype} \q{\ii{Terminal-type} string} \cfg{winhelp-topic}{connection.termtype} @@ -1861,6 +1955,9 @@ If you want your local proxy command to make a secondary SSH connection to a proxy host and then tunnel the primary connection over that, you might well want the \c{-nc} command-line option in Plink. See \k{using-cmdline-ncmode} for more information. + +You can also enable this mode on the command line; see +\k{using-cmdline-proxycmd}. } \S{config-proxy-exclude} Excluding parts of the network from proxying @@ -2006,6 +2103,25 @@ port. Note that if you do not include the \c{%user} or \c{%pass} tokens in the Telnet command, then the \q{Username} and \q{Password} configuration fields will be ignored. +\S{config-proxy-logging} Controlling \i{proxy logging} + +\cfg{winhelp-topic}{proxy.logging} + +Often the proxy interaction has its own diagnostic output; this is +particularly the case for local proxy commands. + +The setting \q{Print proxy diagnostics in the terminal window} lets +you control how much of the proxy's diagnostics are printed to the main +terminal window, along with output from your main session. + +By default (\q{No}), proxy diagnostics are only sent to the Event Log; +with \q{Yes} they are also printed to the terminal, where they may get +mixed up with your main session. \q{Only until session starts} is a +compromise; proxy messages will go to the terminal window until the main +session is deemed to have started (in a protocol-dependent way), which +is when they're most likely to be interesting; any further proxy-related +messages during the session will only go to the Event Log. + \H{config-telnet} The \i{Telnet} panel The Telnet panel allows you to configure options that only apply to @@ -2182,76 +2298,95 @@ client end. Likewise, data sent by PuTTY to the server is compressed first and the server decompresses it at the other end. This can help make the most of a low-\i{bandwidth} connection. -\S{config-ssh-prot} \q{Preferred \i{SSH protocol version}} +\S{config-ssh-prot} \q{\i{SSH protocol version}} \cfg{winhelp-topic}{ssh.protocol} -This allows you to select whether you would like to use \i{SSH protocol -version 1} or \I{SSH-2}version 2. \#{FIXME: say something about this elsewhere?} - -PuTTY will attempt to use protocol 1 if the server you connect to -does not offer protocol 2, and vice versa. - -If you select \q{1 only} or \q{2 only} here, PuTTY will only connect -if the server you connect to offers the SSH protocol version you -have specified. - -\S{config-ssh-encryption} \ii{Encryption} algorithm selection - -\cfg{winhelp-topic}{ssh.ciphers} - -PuTTY supports a variety of different \i{encryption algorithm}s, and -allows you to choose which one you prefer to use. You can do this by -dragging the algorithms up and down in the list box (or moving them -using the Up and Down buttons) to specify a preference order. When -you make an SSH connection, PuTTY will search down the list from the -top until it finds an algorithm supported by the server, and then -use that. - -PuTTY currently supports the following algorithms: - -\b \i{AES} (Rijndael) - 256, 192, or 128-bit SDCTR or CBC (SSH-2 only) - -\b \i{Arcfour} (RC4) - 256 or 128-bit stream cipher (SSH-2 only) - -\b \i{Blowfish} - 256-bit SDCTR (SSH-2 only) or 128-bit CBC - -\b \ii{Triple-DES} - 168-bit SDCTR (SSH-2 only) or CBC - -\b \ii{Single-DES} - 56-bit CBC (see below for SSH-2) - -If the algorithm PuTTY finds is below the \q{warn below here} line, -you will see a warning box when you make the connection: - -\c The first cipher supported by the server -\c is single-DES, which is below the configured -\c warning threshold. -\c Do you want to continue with this connection? - -This warns you that the first available encryption is not a very -secure one. Typically you would put the \q{warn below here} line -between the encryptions you consider secure and the ones you -consider substandard. By default, PuTTY supplies a preference order -intended to reflect a reasonable preference in terms of security and -speed. - -In SSH-2, the encryption algorithm is negotiated independently for -each direction of the connection, although PuTTY does not support -separate configuration of the preference orders. As a result you may -get two warnings similar to the one above, possibly with different -encryptions. - -Single-DES is not recommended in the SSH-2 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 -recommended ciphers. +This allows you to select whether to use \i{SSH protocol version 2} +or the older \I{SSH-1}version 1. + +You should normally leave this at the default of \q{2}. As well as +having fewer features, the older SSH-1 protocol is no longer +developed, has many known cryptographic weaknesses, and is generally +not considered to be secure. PuTTY's protocol 1 implementation is +provided mainly for compatibility, and is no longer being enhanced. + +If a server offers both versions, prefer \q{2}. If you have some +server or piece of equipment that only talks SSH-1, select \q{1} +here, and do not treat the resulting connection as secure. + +PuTTY will not automatically fall back to the other version of the +protocol if the server turns out not to match your selection here; +instead, it will put up an error message and abort the connection. +This prevents an active attacker downgrading an intended SSH-2 +connection to SSH-1. + +\S{config-ssh-sharing} Sharing an SSH connection between PuTTY tools + +\cfg{winhelp-topic}{ssh.sharing} + +The controls in this box allow you to configure PuTTY to reuse an +existing SSH connection, where possible. + +The SSH-2 protocol permits you to run multiple data channels over the +same SSH connection, so that you can log in just once (and do the +expensive encryption setup just once) and then have more than one +terminal window open. + +Each instance of PuTTY can still run at most one terminal session, but +using the controls in this box, you can configure PuTTY to check if +another instance of itself has already connected to the target host, +and if so, share that instance's SSH connection instead of starting a +separate new one. + +To enable this feature, just tick the box \q{Share SSH connections if +possible}. Then, whenever you start up a PuTTY session connecting to a +particular host, it will try to reuse an existing SSH connection if +one is available. For example, selecting \q{Duplicate Session} from +the system menu will launch another session on the same host, and if +sharing is enabled then it will reuse the existing SSH connection. + +When this mode is in use, the first PuTTY that connected to a given +server becomes the \q{upstream}, which means that it is the one +managing the real SSH connection. All subsequent PuTTYs which reuse +the connection are referred to as \q{downstreams}: they do not connect +to the real server at all, but instead connect to the upstream PuTTY +via local inter-process communication methods. + +For this system to be activated, \e{both} the upstream and downstream +instances of PuTTY must have the sharing option enabled. + +The upstream PuTTY can therefore not terminate until all its +downstreams have closed. This is similar to the effect you get with +port forwarding or X11 forwarding, in which a PuTTY whose terminal +session has already finished will still remain open so as to keep +serving forwarded connections. + +In case you need to configure this system in more detail, there are +two additional checkboxes which allow you to specify whether a +particular PuTTY can act as an upstream or a downstream or both. +(These boxes only take effect if the main \q{Share SSH connections if +possible} box is also ticked.) By default both of these boxes are +ticked, so that multiple PuTTYs started from the same configuration +will designate one of themselves as the upstream and share a single +connection; but if for some reason you need a particular PuTTY +configuration \e{not} to be an upstream (e.g. because you definitely +need it to close promptly) or not to be a downstream (e.g. because it +needs to do its own authentication using a special private key) then +you can untick one or the other of these boxes. + +I have referred to \q{PuTTY} throughout the above discussion, but all +the other PuTTY tools which make SSH connections can use this +mechanism too. For example, if PSCP or PSFTP loads a configuration +with sharing enabled, then it can act as a downstream and use an +existing SSH connection set up by an instance of GUI PuTTY. The one +special case is that PSCP and PSFTP will \e{never} act as upstreams. + +It is possible to test programmatically for the existence of a live +upstream using Plink. See \k{plink-option-shareexists}. \H{config-ssh-kex} The Kex panel -\# FIXME: This whole section is draft. Feel free to revise. - The Kex panel (short for \q{\i{key exchange}}) allows you to configure options related to SSH-2 key exchange. @@ -2282,25 +2417,28 @@ 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 \i{Diffie-Hellman key -exchange}: +PuTTY currently supports the following key exchange methods: + +\b \q{ECDH}: \i{elliptic curve} \i{Diffie-Hellman key exchange}. -\b \q{Group 14}: a well-known 2048-bit group. +\b \q{Group 14}: Diffie-Hellman key exchange with 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 1}: Diffie-Hellman key exchange with a well-known +1024-bit group. We no longer recommend using this method, and it's +not used by default in new installations; however, it may be the +only method supported by very old server software. \b \q{\ii{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. +configuration. We recommend use of this method instead of the +well-known groups, if possible. -In addition, PuTTY supports \i{RSA key exchange}, which requires much less -computational effort on the part of the client, and somewhat less on -the part of the server, than Diffie-Hellman key exchange. +\b \q{\i{RSA key exchange}}: this requires much less computational +effort on the part of the client, and somewhat less on the part of +the server, than Diffie-Hellman key exchange. 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 @@ -2375,23 +2513,205 @@ 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-hostkey} The Host Keys panel + +The Host Keys panel allows you to configure options related to SSH-2 +\i{host key management}. + +Host keys are used to prove the server's identity, and assure you that +the server is not being spoofed (either by a man-in-the-middle attack +or by completely replacing it on the network). See \k{gs-hostkey} for +a basic introduction to host keys. + +This entire panel is only relevant to SSH protocol version 2; none of +these settings affect SSH-1 at all. + +\S{config-ssh-hostkey-order} \ii{Host key type} selection + +\cfg{winhelp-topic}{ssh.hostkey.order} + +PuTTY supports a variety of SSH-2 host key types, and allows you to +choose which one you prefer to use to identify the server. +Configuration is similar to cipher selection (see +\k{config-ssh-encryption}). + +PuTTY currently supports the following host key types: + +\b \q{Ed25519}: \i{Edwards-curve} \i{DSA} using a twisted Edwards +curve with modulus \cw{2^255-19}. + +\b \q{ECDSA}: \i{elliptic curve} \i{DSA} using one of the +NIST-standardised elliptic curves. + +\b \q{DSA}: straightforward \i{DSA} using modular exponentiation. + +\b \q{RSA}: the ordinary \i{RSA} algorithm. + +If PuTTY already has one or more host keys stored for the server, +it will prefer to use one of those, even if the server has a key +type that is higher in the preference order. You can add such a +key to PuTTY's cache from within an existing session using the +\q{Special Commands} menu; see \k{using-specials}. + +Otherwise, PuTTY will choose a key type based purely on the +preference order you specify in the configuration. + +If the first key type 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-manual-hostkeys} \ii{Manually configuring host keys} + +\cfg{winhelp-topic}{ssh.kex.manualhostkeys} + +In some situations, if PuTTY's automated host key management is not +doing what you need, you might need to manually configure PuTTY to +accept a specific host key, or one of a specific set of host keys. + +One reason why you might want to do this is because the host name +PuTTY is connecting to is using round-robin DNS to return one of +multiple actual servers, and they all have different host keys. In +that situation, you might need to configure PuTTY to accept any of a +list of host keys for the possible servers, while still rejecting any +key not in that list. + +Another reason is if PuTTY's automated host key management is +completely unavailable, e.g. because PuTTY (or Plink or PSFTP, etc) is +running in a Windows environment without access to the Registry. In +that situation, you will probably want to use the \cw{-hostkey} +command-line option to configure the expected host key(s); see +\k{using-cmdline-hostkey}. + +For situations where PuTTY's automated host key management simply +picks the wrong host name to store a key under, you may want to +consider setting a \q{logical host name} instead; see +\k{config-loghost}. + +To configure manual host keys via the GUI, enter some text describing +the host key into the edit box in the \q{Manually configure host keys +for this connection} container, and press the \q{Add} button. The text +will appear in the \q{Host keys or fingerprints to accept} list box. +You can remove keys again with the \q{Remove} button. + +The text describing a host key can be in one of the following formats: + +\b An MD5-based host key fingerprint of the form displayed in PuTTY's +Event Log and host key dialog boxes, i.e. sixteen 2-digit hex numbers +separated by colons. + +\b A base64-encoded blob describing an SSH-2 public key in +OpenSSH's one-line public key format. How you acquire a public key in +this format is server-dependent; on an OpenSSH server it can typically +be found in a location like \c{/etc/ssh/ssh_host_rsa_key.pub}. + +If this box contains at least one host key or fingerprint when PuTTY +makes an SSH connection, then PuTTY's automated host key management is +completely bypassed: the connection will be permitted if and only if +the host key presented by the server is one of the keys listed in this +box, and the \I{host key cache}host key store in the Registry will be +neither read \e{nor written}, unless you explicitly do so. + +If the box is empty (as it usually is), then PuTTY's automated host +key management will work as normal. + +\H{config-ssh-encryption} The Cipher panel + +\cfg{winhelp-topic}{ssh.ciphers} + +PuTTY supports a variety of different \i{encryption algorithm}s, and +allows you to choose which one you prefer to use. You can do this by +dragging the algorithms up and down in the list box (or moving them +using the Up and Down buttons) to specify a preference order. When +you make an SSH connection, PuTTY will search down the list from the +top until it finds an algorithm supported by the server, and then +use that. + +PuTTY currently supports the following algorithms: + +\b \i{ChaCha20-Poly1305}, a combined cipher and \i{MAC} (SSH-2 only) + +\b \i{AES} (Rijndael) - 256, 192, or 128-bit SDCTR or CBC (SSH-2 only) + +\b \i{Arcfour} (RC4) - 256 or 128-bit stream cipher (SSH-2 only) + +\b \i{Blowfish} - 256-bit SDCTR (SSH-2 only) or 128-bit CBC + +\b \ii{Triple-DES} - 168-bit SDCTR (SSH-2 only) or CBC + +\b \ii{Single-DES} - 56-bit CBC (see below for SSH-2) + +If the algorithm PuTTY finds is below the \q{warn below here} line, +you will see a warning box when you make the connection: + +\c The first cipher supported by the server +\c is single-DES, which is below the configured +\c warning threshold. +\c Do you want to continue with this connection? + +This warns you that the first available encryption is not a very +secure one. Typically you would put the \q{warn below here} line +between the encryptions you consider secure and the ones you +consider substandard. By default, PuTTY supplies a preference order +intended to reflect a reasonable preference in terms of security and +speed. + +In SSH-2, the encryption algorithm is negotiated independently for +each direction of the connection, although PuTTY does not support +separate configuration of the preference orders. As a result you may +get two warnings similar to the one above, possibly with different +encryptions. + +Single-DES is not recommended in the SSH-2 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 +recommended ciphers. + \H{config-ssh-auth} The Auth panel The Auth panel allows you to configure \i{authentication} options for SSH sessions. +\S{config-ssh-banner} \q{Display pre-authentication banner} + +\cfg{winhelp-topic}{ssh.auth.banner} + +SSH-2 servers can provide a message for clients to display to the +prospective user before the user logs in; this is sometimes known as a +pre-authentication \q{\i{banner}}. Typically this is used to provide +information about the server and legal notices. + +By default, PuTTY displays this message before prompting for a +password or similar credentials (although, unfortunately, not before +prompting for a login name, due to the nature of the protocol design). +By unchecking this option, display of the banner can be suppressed +entirely. + \S{config-ssh-noauth} \q{Bypass authentication entirely} \cfg{winhelp-topic}{ssh.auth.bypass} -In SSH-2, it is possible to establish a connection without using SSH's -mechanisms to identify or authenticate oneself to the server. Some -servers may prefer to handle authentication in the data channel, for -instance, or may simply require no authentication whatsoever. - -By default, PuTTY assumes the server requires authentication (most -do), and thus must provide a username. If you find you are getting -unwanted username prompts, you could try checking this option. +In SSH-2, it is in principle possible to establish a connection +without using SSH's mechanisms to identify or prove who you are +to the server. An SSH server could prefer to handle authentication +in the data channel, for instance, or simply require no user +authentication whatsoever. + +By default, PuTTY assumes the server requires authentication (we've +never heard of one that doesn't), and thus must start this process +with a username. If you find you are getting username prompts that +you cannot answer, you could try enabling this option. However, +most SSH servers will reject this. + +This is not the option you want if you have a username and just want +PuTTY to remember it; for that see \k{config-username}. +It's also probably not what if you're trying to set up passwordless +login to a mainstream SSH server; depending on the server, you +probably wanted public-key authentication (\k{pubkey}) +or perhaps GSSAPI authentication (\k{config-ssh-auth-gssapi}). +(These are still forms of authentication, even if you don't have to +interact with them.) This option only affects SSH-2 connections. SSH-1 connections always require an authentication step. @@ -2497,10 +2817,93 @@ This key must be in PuTTY's native format (\c{*.\i{PPK}}). If you have a private key in another format that you want to use with PuTTY, see \k{puttygen-conversions}. -If a key file is specified here, and \i{Pageant} is running (see -\k{pageant}), PuTTY will first try asking Pageant to authenticate with -that key, and ignore any other keys Pageant may have. If that fails, -PuTTY will ask for a passphrase as normal. +You can use the authentication agent \i{Pageant} so that you do not +need to explicitly configure a key here; see \k{pageant}. + +If a private key file is specified here with Pageant running, PuTTY +will first try asking Pageant to authenticate with that key, and +ignore any other keys Pageant may have. If that fails, PuTTY will ask +for a passphrase as normal. You can also specify a \e{public} key file +in this case (in RFC 4716 or OpenSSH format), as that's sufficient to +identify the key to Pageant, but of course if Pageant isn't present +PuTTY can't fall back to using this file itself. + +\H{config-ssh-auth-gssapi} The \i{GSSAPI} panel + +\cfg{winhelp-topic}{ssh.auth.gssapi} + +The \q{GSSAPI} subpanel of the \q{Auth} panel controls the use of +GSSAPI authentication. This is a mechanism which delegates the +authentication exchange to a library elsewhere on the client +machine, which in principle can authenticate in many different ways +but in practice is usually used with the \i{Kerberos} \i{single sign-on} +protocol to implement \i{passwordless login}. + +GSSAPI is only available in the SSH-2 protocol. + +The topmost control on the GSSAPI subpanel is the checkbox labelled +\q{Attempt GSSAPI authentication}. If this is disabled, GSSAPI will +not be attempted at all and the rest of this panel is unused. If it +is enabled, GSSAPI authentication will be attempted, and (typically) +if your client machine has valid Kerberos credentials loaded, then +PuTTY should be able to authenticate automatically to servers that +support Kerberos logins. + +\S{config-ssh-auth-gssapi-delegation} \q{Allow GSSAPI credential +delegation} + +\cfg{winhelp-topic}{ssh.auth.gssapi.delegation} + +\i{GSSAPI credential delegation} is a mechanism for passing on your +Kerberos (or other) identity to the session on the SSH server. If +you enable this option, then not only will PuTTY be able to log in +automatically to a server that accepts your Kerberos credentials, +but also you will be able to connect out from that server to other +Kerberos-supporting services and use the same credentials just as +automatically. + +(This option is the Kerberos analogue of SSH agent forwarding; see +\k{pageant-forward} for some information on that.) + +Note that, like SSH agent forwarding, there is a security +implication in the use of this option: the administrator of the +server you connect to, or anyone else who has cracked the +administrator account on that server, could fake your identity when +connecting to further Kerberos-supporting services. However, +Kerberos sites are typically run by a central authority, so the +administrator of one server is likely to already have access to the +other services too; so this would typically be less of a risk than +SSH agent forwarding. + +\S{config-ssh-auth-gssapi-libraries} Preference order for GSSAPI +libraries + +\cfg{winhelp-topic}{ssh.auth.gssapi.libraries} + +GSSAPI is a mechanism which allows more than one authentication +method to be accessed through the same interface. Therefore, more +than one authentication library may exist on your system which can +be accessed using GSSAPI. + +PuTTY contains native support for a few well-known such libraries, +and will look for all of them on your system and use whichever it +finds. If more than one exists on your system and you need to use a +specific one, you can adjust the order in which it will search using +this preference list control. + +One of the options in the preference list is to use a user-specified +GSSAPI library. If the library you want to use is not mentioned by +name in PuTTY's list of options, you can enter its full pathname in +the \q{User-supplied GSSAPI library path} field, and move the +\q{User-supplied GSSAPI library} option in the preference list to +make sure it is selected before anything else. + +On Windows, such libraries are files with a \I{DLL}\cw{.dll} +extension, and must have been built in the same way as the PuTTY +executable you're running; if you have a 32-bit DLL, you must run a +32-bit version of PuTTY, and the same with 64-bit (see +\k{faq-32bit-64bit}). On Unix, shared libraries generally have a +\cw{.so} extension. \H{config-ssh-tty} The TTY panel @@ -2557,8 +2960,9 @@ a sensible value. \lcont{ PuTTY proper will send modes that it has an opinion on (currently only -the code for the Backspace key, \cw{ERASE}). Plink on Unix -will propagate appropriate modes from the local terminal, if any. +the code for the Backspace key, \cw{ERASE}, and whether the character +set is UTF-8, \cw{IUTF8}). Plink on Unix will propagate appropriate +modes from the local terminal, if any. } @@ -2606,6 +3010,17 @@ character or turn it off entirely. PuTTY in a variety of ways, such as \cw{true}/\cw{false}, \cw{yes}/\cw{no}, and \cw{0}/\cw{1}. +\b The boolean mode \I{IUTF8 terminal mode}\cw{IUTF8} signals to the +server whether the terminal character set is \i{UTF-8} or not. +If this is set incorrectly, actions like backspace may behave +incorrectly in some circumstances. However, setting this is not usually +sufficient to cause servers to expect the terminal to be in UTF-8 mode; +POSIX servers will generally require the locale to be set (by some +server-dependent means), although many default to UTF-8. Also, +\#{circa 2016} many servers (particularly older servers) do not honour +this mode sent over SSH. When set to \q{Auto}, this follows the +local configured character set (see \k{config-charset}). + \b Terminal speeds are configured elsewhere; see \k{config-termspeed}. \H{config-ssh-x11} The X11 panel @@ -2615,8 +3030,8 @@ PuTTY in a variety of ways, such as \cw{true}/\cw{false}, The X11 panel allows you to configure \i{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 +If your server lets you run X Window System \i{graphical 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. @@ -2675,6 +3090,27 @@ 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-xauthority} X authority file for local display + +\cfg{winhelp-topic}{ssh.tunnels.xauthority} + +If you are using X11 forwarding, the local X server to which your +forwarded connections are eventually directed may itself require +authorisation. + +Some Windows X servers do not require this: they do authorisation by +simpler means, such as accepting any connection from the local +machine but not from anywhere else. However, if your X server does +require authorisation, then PuTTY needs to know what authorisation +is required. + +One way in which this data might be made available is for the X +server to store it somewhere in a file which has the same format +as the Unix \c{.Xauthority} file. If this is how your Windows X +server works, then you can tell PuTTY where to find this file by +configuring this option. By default, PuTTY will not attempt to find +any authorisation for your local display. + \H{config-ssh-portfwd} \I{port forwarding}The Tunnels panel \cfg{winhelp-topic}{ssh.tunnels.portfwd} @@ -2713,7 +3149,9 @@ needed with \q{Dynamic}), enter a hostname and port number separated by a colon, in the \q{Destination} box. Connections received on the source port will be directed to this destination. For example, to connect to a POP-3 server, you might enter -\c{popserver.example.com:110}. +\c{popserver.example.com:110}. (If you need to enter a literal +\i{IPv6 address}, enclose it in square brackets, for instance +\cq{[::1]:2200}.) \b Click the \q{Add} button. Your forwarding details should appear in the list box. @@ -2757,6 +3195,12 @@ 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. +If the connection you are forwarding over SSH is itself a second SSH +connection made by another copy of PuTTY, you might find the +\q{logical host name} configuration option useful to warn PuTTY of +which host key it should be expecting. See \k{config-loghost} for +details of this. + \S{config-ssh-portfwd-localhost} Controlling the visibility of forwarded ports @@ -2806,7 +3250,7 @@ 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} \I{SSH server bugs}The Bugs panel +\H{config-ssh-bugs} \I{SSH server bugs}The Bugs and More Bugs panels Not all SSH servers work properly. Various existing servers have bugs in them, which can make it impossible for a client to talk to @@ -2820,9 +3264,10 @@ has been deliberately configured to conceal its version number, or if the server is a version which PuTTY's bug database does not know about, then PuTTY will not know what bugs to expect. -The Bugs panel allows you to manually configure the bugs PuTTY -expects to see in the server. Each bug can be configured in three -states: +The Bugs and More Bugs panels (there are two because we have so many +bug compatibility modes) allow you to manually configure the bugs +PuTTY expects to see in the server. Each bug can be configured in +three states: \b \q{Off}: PuTTY will assume the server does not have the bug. @@ -2852,9 +3297,6 @@ enabled when talking to a correct server, the session will succeed, but keepalives will not work and the session might be more vulnerable to eavesdroppers than it could be. -This is an SSH-1-specific bug. No known SSH-2 server fails to deal -with SSH-2 ignore messages. - \S{config-ssh-bug-plainpw1} \q{Refuses all SSH-1 \i{password camouflage}} \cfg{winhelp-topic}{ssh.bugs.plainpw1} @@ -2896,6 +3338,46 @@ will be impossible. This is an SSH-1-specific bug. +\S{config-ssh-bug-ignore2} \q{Chokes on SSH-2 \i{ignore message}s} + +\cfg{winhelp-topic}{ssh.bugs.ignore2} + +An ignore message (SSH_MSG_IGNORE) is a message in the SSH protocol +which can be sent from the client to the server, or from the server +to the client, at any time. Either side is required to ignore the +message whenever it receives it. PuTTY uses ignore messages in SSH-2 +to confuse the encrypted data stream and make it harder to +cryptanalyse. It also uses ignore messages for connection +\i{keepalives} (see \k{config-keepalive}). + +If it believes the server to have this bug, PuTTY will stop using +ignore messages. If this bug is enabled when talking to a correct +server, the session will succeed, but keepalives will not work and +the session might be less cryptographically secure than it could be. + +\S{config-ssh-bug-winadj} \q{Chokes on PuTTY's SSH-2 \cq{winadj} requests} + +\cfg{winhelp-topic}{ssh.bugs.winadj} + +PuTTY sometimes sends a special request to SSH servers in the middle +of channel data, with the name \cw{winadj@putty.projects.tartarus.org} +(see \k{sshnames-channel}). The purpose of this request is to measure +the round-trip time to the server, which PuTTY uses to tune its flow +control. The server does not actually have to \e{understand} the +message; it is expected to send back a \cw{SSH_MSG_CHANNEL_FAILURE} +message indicating that it didn't understand it. (All PuTTY needs for +its timing calculations is \e{some} kind of response.) + +It has been known for some SSH servers to get confused by this message +in one way or another \dash because it has a long name, or because +they can't cope with unrecognised request names even to the extent of +sending back the correct failure response, or because they handle it +sensibly but fill up the server's log file with pointless spam, or +whatever. PuTTY therefore supports this bug-compatibility flag: if it +believes the server has this bug, it will never send its +\cq{winadj@putty.projects.tartarus.org} request, and will make do +without its timing data. + \S{config-ssh-bug-hmac2} \q{Miscomputes SSH-2 HMAC keys} \cfg{winhelp-topic}{ssh.bugs.hmac2} @@ -3002,6 +3484,48 @@ send an over-sized packet. If this bug is enabled when talking to a correct server, the session will work correctly, but download performance will be less than it could be. +\S{config-ssh-bug-chanreq} \q{Replies to requests on closed channels} + +\cfg{winhelp-topic}{ssh.bugs.chanreq} + +The SSH protocol as published in RFC 4254 has an ambiguity which +arises if one side of a connection tries to close a channel, while the +other side simultaneously sends a request within the channel and asks +for a reply. RFC 4254 leaves it unclear whether the closing side +should reply to the channel request after having announced its +intention to close the channel. + +Discussion on the \cw{ietf-ssh} mailing list in April 2014 formed a +clear consensus that the right answer is no. However, because of the +ambiguity in the specification, some SSH servers have implemented the +other policy; for example, +\W{https://bugzilla.mindrot.org/show_bug.cgi?id=1818}{OpenSSH used to} +until it was fixed. + +Because PuTTY sends channel requests with the \q{want reply} flag +throughout channels' lifetime (see \k{config-ssh-bug-winadj}), it's +possible that when connecting to such a server it might receive a +reply to a request after it thinks the channel has entirely closed, +and terminate with an error along the lines of \q{Received +\cw{SSH2_MSG_CHANNEL_FAILURE} for nonexistent channel 256}. + +\S{config-ssh-bug-oldgex2} \q{Only supports pre-RFC4419 SSH-2 DH GEX} + +\cfg{winhelp-topic}{ssh.bugs.oldgex2} + +The SSH key exchange method that uses Diffie-Hellman group exchange +was redesigned after its original release, to use a slightly more +sophisticated setup message. Almost all SSH implementations switched +over to the new version. (PuTTY was one of the last.) A few old +servers still only support the old one. + +If this bug is detected, and the client and server negotiate +Diffie-Hellman group exchange, then PuTTY will send the old message +now known as \cw{SSH2_MSG_KEX_DH_GEX_REQUEST_OLD} in place of the new +\cw{SSH2_MSG_KEX_DH_GEX_REQUEST}. + +This is an SSH-2-specific bug. + \H{config-serial} The Serial panel The \i{Serial} panel allows you to configure options that only apply @@ -3133,5 +3657,5 @@ Here is an example \c{PUTTYRND.REG} file: 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 -PuTTY and its settings on one floppy, you probably want to store it -on the floppy. +PuTTY and its settings on one USB stick, you probably want to store it +on the USB stick.