X-Git-Url: https://asedeno.scripts.mit.edu/gitweb/?a=blobdiff_plain;f=doc%2Fconfig.but;h=49c0ff6eb8a15ff1c4933283cc0bdf2fb57a53d7;hb=6f6e9db932589470975ecc23261cd57eb9e710be;hp=96f5dbe4cf2958380e0a8d899a69f0ba1b995439;hpb=ca6fc3a4daf51166a15693feffc967bee9e3f59a;p=PuTTY.git diff --git a/doc/config.but b/doc/config.but index 96f5dbe4..49c0ff6e 100644 --- a/doc/config.but +++ b/doc/config.but @@ -1030,7 +1030,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 +1096,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} @@ -1247,12 +1254,16 @@ 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. 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. +character set} option lets you select one. + +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 @@ -1266,12 +1277,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, -and keystrokes are sent UTF-8 encoded. 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 @@ -1534,20 +1539,22 @@ 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. \S{config-logpalette} \q{Attempt to use \i{logical palettes}} @@ -1788,6 +1795,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} @@ -2249,57 +2274,6 @@ 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. \H{config-ssh-kex} The Kex panel @@ -2428,6 +2402,58 @@ 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-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{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 @@ -2449,6 +2475,21 @@ unwanted username prompts, you could try checking this option. This option only affects SSH-2 connections. SSH-1 connections always require an authentication step. +\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-tryagent} \q{Attempt authentication using Pageant} \cfg{winhelp-topic}{ssh.auth.pageant} @@ -2555,6 +2596,76 @@ If a key file is specified here, and \i{Pageant} is running (see that key, and ignore any other keys Pageant may have. If that fails, PuTTY will ask for a passphrase as normal. +\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. + +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. + \H{config-ssh-tty} The TTY panel The TTY panel lets you configure the remote pseudo-terminal. @@ -2932,9 +3043,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} @@ -2976,6 +3084,23 @@ 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-hmac2} \q{Miscomputes SSH-2 HMAC keys} \cfg{winhelp-topic}{ssh.bugs.hmac2} @@ -3082,6 +3207,29 @@ 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-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. + \H{config-serial} The Serial panel The \i{Serial} panel allows you to configure options that only apply