-\versionid $Id: config.but,v 1.32 2002/05/11 13:03:47 owen 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
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}
\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
\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
through to an external host. Selecting \q{Telnet} allows you to tell
PuTTY to use this type of proxy.
-Note [FIXME] that SOCKS is not yet supported, although it should be
-by the time we make our next release.
-
\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
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.
-Currently these boxes have no effect ( [FIXME] presumably they're
-for SOCKS only).
+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,
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{%%}.
+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
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{2 only} here, PuTTY will only connect if the server
-you connect to offers SSH protocol version 2.
-
-\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