X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/putty/blobdiff_plain/b44b307ac0fc00f2a61ef64d4681fe201ecb927c..46ccbe20eca983436c1869e0728f7049398b9342:/doc/config.but diff --git a/doc/config.but b/doc/config.but index 04dd0d01..c9bf6657 100644 --- a/doc/config.but +++ b/doc/config.but @@ -1,4 +1,4 @@ -\versionid $Id: config.but,v 1.29 2002/03/09 17:59:15 simon Exp $ +\versionid $Id: config.but,v 1.38 2002/09/10 12:30:45 jacob Exp $ \C{config} Configuring PuTTY @@ -335,6 +335,9 @@ typically use to determine your terminal type. That feature is the \q{Terminal-type string} in the Connection panel; see \k{config-termtype} for details. +You can include control characters in the answerback string using +\c{^C} notation. (Use \c{^~} to get a literal \c{^}.) + \S{config-localecho} \q{Local echo} \cfg{winhelp-topic}{terminal.localecho} @@ -566,9 +569,9 @@ an accented character. The choices of character are designed to be easy to remember; for example, composing \q{e} and \q{`} produces the \q{\u00e8{e-grave}} character. -If you enable the \q{Application and AltGr act as Compose key} -option, the Windows Application key and the AltGr key will both have -this behaviour. +If your keyboard has a Windows Application key, it acts as a Compose +key in PuTTY. Alternatively, if you enable the \q{AltGr acts as +Compose key} option, the AltGr key will become a Compose key. \S{config-ctrlalt} \q{Control-Alt is different from AltGr} @@ -589,6 +592,10 @@ If you uncheck this box, Ctrl-Alt will become a synonym for AltGr, so you can use it to type extra graphic characters if your keyboard has any. +(However, Ctrl-Alt will never act as a Compose key, regardless of the +setting of \q{AltGr acts as Compose key} described in +\k{config-compose}.) + \H{config-bell} The Bell panel The Bell panel controls the terminal bell feature: the server's @@ -1029,6 +1036,11 @@ the server is interpreted as being in the 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 code page which is not listed in +the drop-down list, such as code page 866, then you should be able +to enter its name manually (\c{CP866} for example) in the list box +and get the right result. + \S{config-cyr} \q{Caps Lock acts as Cyrillic switch} \cfg{winhelp-topic}{translation.cyrillic} @@ -1344,6 +1356,10 @@ server. Keepalives are only supported in Telnet and SSH; the Rlogin and Raw protocols offer no way of implementing them. +Note that if you are using SSH1 and the server has a bug that makes +it unable to deal with SSH1 ignore messages (see +\k{config-ssh-bug-ignore1}), enabling keepalives will have no effect. + \S{config-nodelay} \q{Disable Nagle's algorithm} \cfg{winhelp-topic}{connection.nodelay} @@ -1357,6 +1373,94 @@ types of server. The Nagle algorithm is disabled by default. +\H{config-proxy} The Proxy panel + +The Proxy panel allows you to configure PuTTY to use various types +of proxy in order to make its network connections. The settings in +this panel affect the primary network connection forming your PuTTY +session, but also any extra connections made as a result of SSH port +forwarding (see \k{using-port-forwarding}). + +\S{config-proxy-type} Setting the proxy type + +The \q{Proxy type} radio buttons allow you to configure what type of +proxy you want PuTTY to use for its network connections. The default +setting is \q{None}; in this mode no proxy is used for any +connection. + +\b Selecting \q{HTTP} allows you to proxy your connections through a +web server supporting the HTTP \cw{CONNECT} command, as documented +in \W{http://www.ietf.org/rfc/rfc2817.txt}{RFC 2817}. + +\b Selecting \q{SOCKS} allows you to proxy your connections through +a SOCKS server. + +\b Many firewalls implement a less formal type of proxy in which a +user can make a Telnet connection directly to the firewall machine +and enter a command such as \c{connect myhost.com 22} to connect +through to an external host. Selecting \q{Telnet} allows you to tell +PuTTY to use this type of proxy. + +\S{config-proxy-exclude} Excluding parts of the network from proxying + +Typically you will only need to use a proxy to connect to non-local +parts of your network; for example, your proxy might be required for +connections outside your company's internal network. In the +\q{Exclude Hosts/IPs} box you can enter ranges of IP addresses, or +ranges of DNS names, for which PuTTY will avoid using the proxy and +make a direct connection instead. + +The \q{Exclude Hosts/IPs} box may contain more than one exclusion +range, separated by commas. Each range can be an IP address or a DNS +name, with a \c{*} character allowing wildcards. For example: + +\c *.example.com + +This excludes any host with a name ending in \c{.example.com} from +proxying. + +\c 192.168.88.* + +This excludes any host with an IP address starting with 192.168.88 +from proxying. + +\c 192.168.88.*,*.example.com + +This excludes both of the above ranges at once. + +\S{config-proxy-auth} Username and password + +If your proxy requires authentication, you can enter a username and +a password in the \q{Username} and \q{Password} boxes. + +Currently only the \q{Username} box has any effect, and that only for +SOCKS 4 proxies. ( [FIXME] No forms of authentication are supported +for other types of proxy.) + +\S{config-proxy-command} Specifying the Telnet proxy command + +If you are using the Telnet proxy type, the usual command required +by the firewall's Telnet server is \c{connect}, followed by a host +name and a port number. If your proxy needs a different command, +you can enter an alternative here. + +In this string, you can use \c{\\n} to represent a new-line, \c{\\r} +to represent a carriage return, \c{\\t} to represent a tab +character, and \c{\\x} followed by two hex digits to represent any +other character. \c{\\\\} is used to encode the \c{\\} character +itself. + +Also, the special strings \c{%host} and \c{%port} will be replaced +by the host name and port number you want to connect to. To get a +literal \c{%} sign, enter \c{%%}. + +\S{config-proxy-socksver} Selecting the version of the SOCKS protocol + +SOCKS servers exist in two versions: version 5 +(\W{http://www.ietf.org/rfc/rfc1928.txt}{RFC 1928}) and the earlier +version 4. The \q{SOCKS Version} radio buttons allow you to select +which one to use, if you have selected the SOCKS proxy type. + \H{config-telnet} The Telnet panel The Telnet panel allows you to configure options that only apply to @@ -1558,19 +1662,9 @@ version 1 or 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. -\S{config-ssh-macbug} \q{Imitate SSH 2 MAC bug} - -\cfg{winhelp-topic}{ssh.buggymac} - -This option \e{should} now be unnecessary. It existed in order to -work around a bug in early versions (2.3.0 and below) of the SSH -server software from \cw{ssh.com}. The symptom of this problem would -be that PuTTY would die unexpectedly at the beginning of the -session, saying \q{Incorrect MAC received on packet}. - -Current versions of PuTTY attempt to detect these faulty servers and -enable the bug compatibility automatically, so you should never need -to use this option any more. +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} Encryption algorithm selection @@ -1599,6 +1693,12 @@ 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 supported natively in the SSH 2 draft protocol standards. One or two server implementations do support it, by a non-standard name. PuTTY can use single-DES to interoperate with @@ -1766,6 +1866,146 @@ 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). +\H{config-ssh-bugs} The Bugs panel + +Not all SSH servers work properly. Various existing servers have +bugs in them, which can make it impossible for a client to talk to +them unless it knows about the bug and works around it. + +Since most servers announce their software version number at the +beginning of the SSH connection, PuTTY will attempt to detect which +bugs it can expect to see in the server and automatically enable +workarounds. However, sometimes it will make mistakes; if the server +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: + +\b \q{Off}: PuTTY will assume the server does not have the bug. + +\b \q{On}: PuTTY will assume the server \e{does} have the bug. + +\b \q{Auto}: PuTTY will use the server's version number announcement +to try to guess whether or not the server has the bug. + +\S{config-ssh-bug-ignore1} \q{Chokes on SSH1 ignore messages} + +\cfg{winhelp-topic}{ssh.bugs.ignore1} + +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 to hide +the password packet in SSH1, so that a listener cannot tell the +length of the user's password; it also uses ignore messages for +connection keepalives (see \k{config-keepalive}). + +If this bug is detected, PuTTY will stop using ignore messages. This +means that keepalives will stop working, and PuTTY will have to fall +back to a secondary defence against SSH1 password-length +eavesdropping. See \k{config-ssh-bug-plainpw1}. 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 more +vulnerable to eavesdroppers than it could be. + +This is an SSH1-specific bug. No known SSH2 server fails to deal +with SSH2 ignore messages. + +\S{config-ssh-bug-plainpw1} \q{Refuses all SSH1 password camouflage} + +\cfg{winhelp-topic}{ssh.bugs.plainpw1} + +When talking to an SSH1 server which cannot deal with ignore +messages (see \k{config-ssh-bug-ignore1}), PuTTY will attempt to +disguise the length of the user's password by sending additional +padding \e{within} the password packet. This is technically a +violation of the SSH1 specification, and so PuTTY will only do it +when it cannot use standards-compliant ignore messages as +camouflage. In this sense, for a server to refuse to accept a padded +password packet is not really a bug, but it does make life +inconvenient if the server can also not handle ignore messages. + +If this \q{bug} is detected, PuTTY will have no choice but to send +the user's password with no form of camouflage, so that an +eavesdropping user will be easily able to find out the exact length +of the password. If this bug is enabled when talking to a correct +server, the session will succeed, but will be more vulnerable to +eavesdroppers than it could be. + +This is an SSH1-specific bug. SSH2 is secure against this type of +attack. + +\S{config-ssh-bug-rsa1} \q{Chokes on SSH1 RSA authentication} + +\cfg{winhelp-topic}{ssh.bugs.rsa1} + +Some SSH1 servers cannot deal with RSA authentication messages at +all. If Pageant is running and contains any SSH1 keys, PuTTY will +normally automatically try RSA authentication before falling back to +passwords, so these servers will crash when they see the RSA attempt. + +If this bug is detected, PuTTY will go straight to password +authentication. If this bug is enabled when talking to a correct +server, the session will succeed, but of course RSA authentication +will be impossible. + +This is an SSH1-specific bug. + +\S{config-ssh-bug-hmac2} \q{Miscomputes SSH2 HMAC keys} + +\cfg{winhelp-topic}{ssh.bugs.hmac2} + +Versions 2.3.0 and below of the SSH server software from +\cw{ssh.com} compute the keys for their HMAC message authentication +codes incorrectly. A typical symptom of this problem is that PuTTY +dies unexpectedly at the beginning of the session, saying +\q{Incorrect MAC received on packet}. + +If this bug is detected, PuTTY will compute its HMAC keys in the +same way as the buggy server, so that communication will still be +possible. If this bug is enabled when talking to a correct server, +communication will fail. + +This is an SSH2-specific bug. + +\S{config-ssh-bug-derivekey2} \q{Miscomputes SSH2 encryption keys} + +\cfg{winhelp-topic}{ssh.bugs.derivekey2} + +Versions below 2.1.0 of the SSH server software from \cw{ssh.com} +compute the keys for the session encryption incorrectly. This +problem can cause various error messages, such as \q{Incoming packet +was garbled on decryption}, or possibly even \q{Out of memory}. + +If this bug is detected, PuTTY will compute its encryption keys in +the same way as the buggy server, so that communication will still +be possible. If this bug is enabled when talking to a correct +server, communication will fail. + +This is an SSH2-specific bug. + +\S{config-ssh-bug-ssh} \q{Requires padding on SSH2 RSA signatures} + +\cfg{winhelp-topic}{ssh.bugs.rsapad2} + +Versions below 3.3 of OpenSSH require SSH2 RSA signatures to be +padded with zero bytes to the same length as the RSA key modulus. +The SSH2 draft specification says that an unpadded signature MUST be +accepted, so this is a bug. A typical symptom of this problem is +that PuTTY mysteriously fails RSA authentication once in every few +hundred attempts, and falls back to passwords. + +If this bug is detected, PuTTY will pad its signatures in the way +OpenSSH expects. If this bug is enabled when talking to a correct +server, it is likely that no damage will be done, since correct +servers usually still accept padded signatures because they're used +to talking to OpenSSH. + +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