-\versionid $Id: config.but,v 1.29 2002/03/09 17:59:15 simon Exp $
+\versionid $Id: config.but,v 1.47 2002/12/18 16:23:10 simon Exp $
\C{config} Configuring PuTTY
\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}
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}
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
in to do so, and how much silent time is required before the
overload feature will deactivate itself.
+Bell overload mode is always deactivated by any keypress in the
+terminal. This means it can respond to large unexpected streams of
+data, but does not interfere with ordinary command-line activities
+that generate beeps (such as filename completion).
+
\H{config-features} The Features panel
PuTTY's terminal emulation is very highly featured, and can do a lot
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}
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}
The Nagle algorithm is disabled by default.
+\H{config-proxy} The Proxy panel
+
+\cfg{winhelp-topic}{proxy.main}
+
+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
+
+\cfg{winhelp-topic}{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
+
+\cfg{winhelp-topic}{proxy.exclude}
+
+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.
+
+Connections to the local host (the host name \c{localhost}, and any
+loopback IP address) are never proxied, even if the proxy exclude
+list does not explicitly contain them. It is very unlikely that this
+behaviour would ever cause problems, but if it does you can change
+it by enabling \q{Consider proxying local host connections}.
+
+Note that if you are doing DNS at the proxy (see
+\k{config-proxy-dns}), you should make sure that your proxy
+exclusion settings do not depend on knowing the IP address of a
+host. If the name is passed on to the proxy without PuTTY looking it
+up, it will never know the IP address and cannot check it against
+your list.
+
+\S{config-proxy-dns} Name resolution when using a proxy
+
+\cfg{winhelp-topic}{proxy.dns}
+
+If you are using a proxy to access a private network, it can make a
+difference whether DNS name resolution is performed by PuTTY itself
+(on the client machine) or performed by the proxy.
+
+The \q{Do DNS name lookup at proxy end} configuration option allows
+you to control this. If you set it to \q{No}, PuTTY will always do
+its own DNS, and will always pass an IP address to the proxy. If you
+set it to \q{Yes}, PuTTY will always pass host names straight to the
+proxy without trying to look them up first.
+
+If you set this option to \q{Auto} (the default), PuTTY will do
+something it considers appropriate for each type of proxy. Telnet
+and HTTP proxies will have host names passed straight to them; SOCKS
+proxies will not.
+
+Note that if you are doing DNS at the proxy, you should make sure
+that your proxy exclusion settings (see \k{config-proxy-exclude}) do
+not depend on knowing the IP address of a host. If the name is
+passed on to the proxy without PuTTY looking it up, it will never
+know the IP address and cannot check it against your list.
+
+The original SOCKS 4 protocol does not support proxy-side DNS. There
+is a protocol extension (SOCKS 4A) which does support it, but not
+all SOCKS 4 servers provide this extension. If you enable proxy DNS
+and your SOCKS 4 server cannot deal with it, this might be why.
+
+\S{config-proxy-auth} Username and password
+
+\cfg{winhelp-topic}{proxy.auth}
+
+If your proxy requires authentication, you can enter a username and
+a password in the \q{Username} and \q{Password} boxes.
+
+Authentication is not supported for all forms of proxy:
+
+\b Username and password authentication is supported for HTTP
+proxies and SOCKS 5 proxies.
+
+\b SOCKS 4 can use the \q{Username} field, but does not support
+passwords.
+
+\b You can specify a way to include a username and password in the
+Telnet proxy command (see \k{config-proxy-command}).
+
+\S{config-proxy-command} Specifying the Telnet proxy command
+
+\cfg{winhelp-topic}{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. The strings
+\c{%user} and \c{%pass} will be replaced by the proxy username and
+password you specify. To get a literal \c{%} sign, enter \c{%%}.
+
+If the Telnet proxy server prompts for a username and password
+before commands can be sent, you can use a command such as:
+
+\c %user\\n%pass\\nconnect %host %port\\n
+
+This will send your username and password as the first two lines to
+the proxy, followed by a command to connect to the desired host and
+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-socksver} Selecting the version of the SOCKS protocol
+
+\cfg{winhelp-topic}{proxy.socksver}
+
+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
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
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
To remove a port forwarding, simply select its details in the list
box, and click the \q{Remove} button.
+In the \q{Source port} box, you can also optionally enter an IP
+address to listen on. Typically a Windows machine can be asked to
+listen on any single IP address in the \cw{127.*.*.*} range, and all
+of these are loopback addresses available only to the local machine.
+So if you forward (for example) \c{127.0.0.5:79} to a remote
+machine's \cw{finger} port, then you should be able to run commands
+such as \c{finger fred@127.0.0.5}. This can be useful if the program
+connecting to the forwarded port doesn't allow you to change the
+port number it uses. This feature is available for local-to-remote
+forwarded ports; SSH1 is unable to support it for remote-to-local
+ports, while SSH2 can support it in theory but servers will not
+necessarily cooperate.
+
\S{config-ssh-portfwd-localhost} Controlling the visibility of
forwarded ports
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-sig} \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.
+
+\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.
+
\H{config-file} Storing configuration in a file
PuTTY does not currently support storing its configuration in a file
projects / u / mdw / putty / blobdiff