-\versionid $Id: config.but,v 1.43 2002/10/20 13:23:30 simon Exp $
+\versionid $Id: config.but,v 1.58 2003/03/06 12:51:12 simon Exp $
\C{config} Configuring PuTTY
could try turning this option off.
Auto wrap mode can be turned on and off by control sequences sent by
-the server. This configuration option only controls the \e{default}
-state. If you modify this option in mid-session using \q{Change
-Settings}, you will need to reset the terminal (see
-\k{reset-terminal}) before the change takes effect.
+the server. This configuration option controls the \e{default}
+state, which will be restored when you reset the terminal (see
+\k{reset-terminal}). However, if you modify this option in
+mid-session using \q{Change Settings}, it will take effect
+immediately.
\S{config-decom} \q{DEC Origin Mode initially on}
Mode on to see whether that helps.
DEC Origin Mode can be turned on and off by control sequences sent
-by the server. This configuration option only controls the
-\e{default} state. If you modify this option in mid-session using
-\q{Change Settings}, you will need to reset the terminal (see
-\k{reset-terminal}) before the change takes effect.
+by the server. This configuration option controls the \e{default}
+state, which will be restored when you reset the terminal (see
+\k{reset-terminal}). However, if you modify this option in
+mid-session using \q{Change Settings}, it will take effect
+immediately.
\S{config-crlf} \q{Implicit CR in every LF}
the \e{current} background colour.
Background-colour erase can be turned on and off by control
-sequences sent by the server. This configuration option only
-controls the \e{default} state. If you modify this option in
-mid-session using \q{Change Settings}, you will need to reset the
-terminal (see \k{reset-terminal}) before the change takes effect.
+sequences sent by the server. This configuration option controls the
+\e{default} state, which will be restored when you reset the
+terminal (see \k{reset-terminal}). However, if you modify this
+option in mid-session using \q{Change Settings}, it will take effect
+immediately.
\S{config-blink} \q{Enable blinking text}
background colour.
Blinking text can be turned on and off by control sequences sent by
-the server. This configuration option only controls the \e{default}
-state. If you modify this option in mid-session using \q{Change
-Settings}, you will need to reset the terminal (see
-\k{reset-terminal}) before the change takes effect.
+the server. This configuration option controls the \e{default}
+state, which will be restored when you reset the terminal (see
+\k{reset-terminal}). However, if you modify this option in
+mid-session using \q{Change Settings}, it will take effect
+immediately.
\S{config-answerback} \q{Answerback to ^E}
the server can send as many Control-G characters as it likes and
nothing at all will happen.
-\b \q{Play Windows Default Sound} is the default setting. It causes
-the Windows \q{Default Beep} sound to be played. To change what this
-sound is, or to test it if nothing seems to be happening, use the
-Sound configurer in the Windows Control Panel.
+\b \q{Make default system alert sound} is the default setting. It
+causes the Windows \q{Default Beep} sound to be played. To change
+what this sound is, or to test it if nothing seems to be happening,
+use the Sound configurer in the Windows Control Panel.
+
+\b \q{Visual bell} is a silent alternative to a beeping computer. In
+this mode, when the server sends a Control-G, the whole PuTTY window
+will flash white for a fraction of a second.
\b \q{Play a custom sound file} allows you to specify a particular
sound file to be used by PuTTY alone, or even by a particular
you will also need to enter the name of your sound file in the edit
control \q{Custom sound file to play as a bell}.
-\b \q{Visual bell} is a silent alternative to a beeping computer. In
-this mode, when the server sends a Control-G, the whole PuTTY window
-will flash white for a fraction of a second.
-
\S{config-belltaskbar} \q{Taskbar/caption indication on bell}
\cfg{winhelp-topic}{bell.taskbar}
screen revert when you press a key, by turning on \q{Reset
scrollback on keypress}.
+\S{config-scrollback} \q{Push erased text into scrollback}
+
+\cfg{winhelp-topic}{window.erased}
+
+When this option is enabled, the contents of the terminal screen
+will be pushed into the scrollback when a server-side application
+clears the screen, so that your scrollback will contain a better
+record of what was on your screen in the past.
+
+If the application switches to the alternate screen (see
+\k{config-features-altscreen} for more about this), then the
+contents of the primary screen will be visible in the scrollback
+until the application switches back again.
+
+This option is enabled by default.
+
\H{config-appearance} The Appearance panel
The Appearance configuration panel allows you to control aspects of
system. (VT100-style terminal handling can only deal with fixed-
width fonts.)
-\S{config-title} Controlling the window title
-
-\cfg{winhelp-topic}{appearance.title}
-
-The \q{Window title} edit box allows you to set the title of the
-PuTTY window. By default the window title will contain the host name
-followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
-If you want a different window title, this is where to set it.
-
-PuTTY allows the server to send \c{xterm} control sequences which
-modify the title of the window in mid-session. There is also an
-\c{xterm} sequence to modify the title of the window's \e{icon}.
-This makes sense in a windowing system where the window becomes an
-icon when minimised, such as Windows 3.1 or most X Window System
-setups; but in the Windows 95-like user interface it isn't as
-applicable. By default PuTTY's window title and Taskbar caption will
-change into the server-supplied icon title if you minimise the PuTTY
-window, and change back to the server-supplied window title if you
-restore it. (If the server has not bothered to supply a window or
-icon title, none of this will happen.) By checking the box marked
-\q{Avoid ever using icon title}, you can arrange that PuTTY will
-always display the window title, and completely ignore any icon
-titles the server sends it.
-
\S{config-mouseptr} \q{Hide mouse pointer when typing in window}
\cfg{winhelp-topic}{appearance.hidemouse}
The Behaviour configuration panel allows you to control aspects of
the behaviour of PuTTY's window.
+\S{config-title} Controlling the window title
+
+\cfg{winhelp-topic}{appearance.title}
+
+The \q{Window title} edit box allows you to set the title of the
+PuTTY window. By default the window title will contain the host name
+followed by \q{PuTTY}, for example \c{server1.example.com - PuTTY}.
+If you want a different window title, this is where to set it.
+
+PuTTY allows the server to send \c{xterm} control sequences which
+modify the title of the window in mid-session. There is also an
+\c{xterm} sequence to modify the title of the window's \e{icon}.
+This makes sense in a windowing system where the window becomes an
+icon when minimised, such as Windows 3.1 or most X Window System
+setups; but in the Windows 95-like user interface it isn't as
+applicable.
+
+By default, PuTTY only uses the server-supplied \e{window} title, and
+ignores the icon title entirely. If for some reason you want to see
+both titles, check the box marked \q{Separate window and icon titles}.
+If you do this, PuTTY's window title and Taskbar caption will
+change into the server-supplied icon title if you minimise the PuTTY
+window, and change back to the server-supplied window title if you
+restore it. (If the server has not bothered to supply a window or
+icon title, none of this will happen.)
+
\S{config-warnonclose} \q{Warn before closing window}
\cfg{winhelp-topic}{behaviour.closewarn}
isn't feasible to expand the list to cover the whole of Unicode.
Character class definitions can be modified by control sequences
-sent by the server. This configuration option only controls the
-\e{default} state. If you modify this option in mid-session using
-\q{Change Settings}, you will need to reset the terminal (see
-\k{reset-terminal}) before the change takes effect.
+sent by the server. This configuration option controls the
+\e{default} state, which will be restored when you reset the
+terminal (see \k{reset-terminal}). However, if you modify this
+option in mid-session using \q{Change Settings}, it will take effect
+immediately.
\H{config-colours} The Colours panel
PuTTY allows you to set the cursor colour, the default foreground
and background, and the precise shades of all the ANSI configurable
colours (black, red, green, yellow, blue, magenta, cyan, and white).
-In addition, if you have selected \q{Bolded text is a different
-colour}, you can also modify the precise shades used for the bold
-versions of these colours.
+You can also modify the precise shades used for the 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.
\H{config-connection} The Connection panel
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:
+Authentication is not fully 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 Authentication is meaningless in Telnet proxies.
+\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
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
are using public key authentication. See \k{pubkey} for information
about public key authentication in SSH.
+This key must be in PuTTY's native format (\c{*.PPK}).
+
\H{config-ssh-tunnels} The Tunnels panel
The Tunnels panel allows you to configure tunnelling of other
See \k{using-x-forwarding} for more information about X11
forwarding.
+\S2{config-ssh-x11auth} Remote X11 authentication
+
+\cfg{winhelp-topic}{ssh.tunnels.x11auth}
+
+If you are using X11 forwarding, the virtual X server created on the
+SSH server machine will be protected by authorisation data. This
+data is invented, and checked, by PuTTY.
+
+The usual authorisation method used for this is called
+\cw{MIT-MAGIC-COOKIE-1}. This is a simple password-style protocol:
+the X client sends some cookie data to the server, and the server
+checks that it matches the real cookie. The cookie data is sent over
+an unencrypted X11 connection; so if you allow a client on a third
+machine to access the virtual X server, then the cookie will be sent
+in the clear.
+
+PuTTY offers the alternative protocol \cw{XDM-AUTHORIZATION-1}. This
+is a cryptographically authenticated protocol: the data sent by the
+X client is different every time, and it depends on the IP address
+and port of the client's end of the connection and is also stamped
+with the current time. So an eavesdropper who captures an
+\cw{XDM-AUTHORIZATION-1} string cannot immediately re-use it for
+their own X connection.
+
+PuTTY's support for \cw{XDM-AUTHORIZATION-1} is a somewhat
+experimental feature, and may encounter several problems:
+
+\b Some X clients probably do not even support
+\cw{XDM-AUTHORIZATION-1}, so they will not know what to do with the
+data PuTTY has provided.
+
+\b This authentication mechanism will only work in SSH v2. In SSH
+v1, the SSH server does not tell the client the source address of
+a forwarded connection in a machine-readable format, so it's
+impossible to verify the \cw{XDM-AUTHORIZATION-1} data.
+
+\b You may find this feature causes problems with some SSH servers,
+which will not clean up \cw{XDM-AUTHORIZATION-1} data after a
+session, so that if you then connect to the same server using
+a client which only does \cw{MIT-MAGIC-COOKIE-1} and are allocated
+the same remote display number, you might find that out-of-date
+authentication data is still present on your server and your X
+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-portfwd} Port forwarding
\cfg{winhelp-topic}{ssh.tunnels.portfwd}
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
\cfg{winhelp-topic}{ssh.bugs.derivekey2}
-Versions below 2.1.0 of the SSH server software from \cw{ssh.com}
+Versions below 2.0.11 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}.
This is an SSH2-specific bug.
+\S{config-ssh-bug-pksessid2} \q{Misuses the session ID in PK auth}
+
+\cfg{winhelp-topic}{ssh.bugs.pksessid2}
+
+Versions below 2.3 of OpenSSH require SSH2 public-key authentication
+to be done slightly differently: the data to be signed by the client
+contains the session ID formatted in a different way. If public-key
+authentication mysteriously does not work but the Event Log (see
+\k{using-eventlog}) thinks it has successfully sent a signature, it
+might be worth enabling the workaround for this bug to see if it
+helps.
+
+If this bug is detected, PuTTY will sign data in the way OpenSSH
+expects. If this bug is enabled when talking to a correct server,
+SSH2 public-key authentication will fail.
+
+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
~mdw / sgt / putty / blobdiff