-\versionid $Id: config.but,v 1.81 2004/06/10 10:01:11 jacob Exp $
+\versionid $Id: config.but,v 1.94 2004/10/16 10:56:54 simon Exp $
\C{config} Configuring PuTTY
\b The \q{Protocol} radio buttons let you choose what type of
connection you want to make: a raw connection, a Telnet connection, an
rlogin connection or an SSH connection. (See \k{which-one} for a
-summary of the differences between SSH, Telnet and rlogin.)
+summary of the differences between SSH, Telnet and rlogin, and
+\k{using-rawprot} for an explanation of \q{raw} connections.)
\b The \q{Port} box lets you specify which port number on the server
to connect to. If you select Telnet, Rlogin, or SSH, this box will
be filled in automatically to the usual value, and you will only
need to change it if you have an unusual server. If you select Raw
-mode (see \k{using-rawprot}), you will almost certainly need to fill
-in the \q{Port} box.
+mode, you will almost certainly need to fill in the \q{Port} box.
\S{config-saving} Loading and storing saved sessions
connection are written to the log file. You might need this to debug
a network-level problem, or more likely to send to the PuTTY authors
as part of a bug report. \e{BE WARNED} that if you log in using a
-password, the password will appear in the log file, so be sure to
-edit it out before sending the log file to anyone else!
+password, the password can appear in the log file; see
+\k{config-logssh} for options that may help to remove sensitive
+material from the log file before you send it to anyone else.
\S{config-logfilename} \q{Log file name}
automatic behaviour, but to ask the user every time the problem
comes up.
+\S{config-logssh} Options specific to SSH packet logging
+
+These options only apply if SSH packet data is being logged.
+
+The following options allow particularly sensitive portions of
+unencrypted packets to be automatically left out of the log file.
+They are only intended to deter casual nosiness; an attacker could
+glean a lot of useful information from even these obfuscated logs
+(e.g., length of password).
+
+\S2{config-logssh-omitpw} \q{Omit known password fields}
+
+\cfg{winhelp-topic}{logging.ssh.omitpassword}
+
+When checked, password fields are removed from the log of transmitted
+packets. (This includes any user responses to challenge-response
+authentication methods such as \q{keyboard-interactive}.) This does
+not include X11 authentication data if using X11 forwarding.
+
+Note that this will only omit data that PuTTY \e{knows} to be a
+password. However, if you start another login session within your
+PuTTY session, for instance, any password used will appear in the
+clear in the packet log. The next option may be of use to protect
+against this.
+
+This option is enabled by default.
+
+\S2{config-logssh-omitdata} \q{Omit session data}
+
+\cfg{winhelp-topic}{logging.ssh.omitdata}
+
+When checked, all \q{session data} is omitted; this is defined as data
+in terminal sessions and in forwarded channels (TCP, X11, and
+authentication agent). This will usually substantially reduce the size
+of the resulting log file.
+
+This option is disabled by default.
+
\H{config-terminal} The Terminal panel
The Terminal configuration panel allows you to control the behaviour
this mode, when the server sends a Control-G, the whole PuTTY window
will flash white for a fraction of a second.
+\b \q{Beep using the PC speaker} is self-explanatory.
+
\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
individual PuTTY session. This allows you to distinguish your PuTTY
The \q{Lines of scrollback} box lets you configure how many lines of
text PuTTY keeps. The \q{Display scrollbar} options allow you to
hide the scrollbar (although you can still view the scrollback using
-Shift-PgUp and Shift-PgDn). You can separately configure whether the
-scrollbar is shown in full-screen mode and in normal modes.
+the keyboard as described in \k{using-scrollback}). You can separately
+configure whether the scrollbar is shown in full-screen mode and in
+normal modes.
If you are viewing part of the scrollback when the server sends more
text to PuTTY, the screen will revert to showing the current
The format is a pair of numbers separated by a comma, for instance,
\c{38400,38400}. The first number represents the output speed
-(\e{from} the server), and the second is the input speed (\e{to} the
-server). (Only the first is used in the Rlogin protocol.)
+(\e{from} the server) in bits per second, and the second is the input
+speed (\e{to} the server). (Only the first is used in the Rlogin
+protocol.)
This option has no effect on Raw connections.
In this box you can type that user name.
+\S{config-environ} Setting environment variables on the server
+
+\cfg{winhelp-topic}{telnet.environ}
+
+The Telnet protocol provides a means for the client to pass
+environment variables to the server. Many Telnet servers have
+stopped supporting this feature due to security flaws, but PuTTY
+still supports it for the benefit of any servers which have found
+other ways around the security problems than just disabling the
+whole mechanism.
+
+Version 2 of the SSH protocol also provides a similar mechanism,
+which is easier to implement without security flaws. Newer SSH2
+servers are more likely to support it than older ones.
+
+This configuration data is not used in the SSHv1, rlogin or raw
+protocols.
+
+To add an environment variable to the list transmitted down the
+connection, you enter the variable name in the \q{Variable} box,
+enter its value in the \q{Value} box, and press the \q{Add} button.
+To remove one from the list, select it in the list box and press
+\q{Remove}.
+
\S{config-keepalive} Using keepalives to prevent disconnection
\cfg{winhelp-topic}{connection.keepalive}
server.
Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
-protocols offer no way of implementing them.
+protocols offer no way of implementing them. (For an alternative, see
+\k{config-tcp-keepalives}.)
Note that if you are using SSH1 and the server has a bug that makes
it unable to deal with SSH1 ignore messages (see
The Nagle algorithm is disabled by default.
+\S{config-tcp-keepalives} \q{Enable TCP keepalives}
+
+\cfg{winhelp-topic}{connection.tcpkeepalive}
+
+\e{NOTE:} TCP keepalives should not be confused with the
+application-level keepalives described in \k{config-keepalive}. If in
+doubt, you probably want application-level keepalives; TCP keepalives
+are provided for completeness.
+
+The idea of TCP keepalives is similar to application-level keepalives,
+and the same caveats apply. The main differences are:
+
+\b TCP keepalives are available on \e{all} connection types, including
+Raw and Rlogin.
+
+\b The interval between TCP keepalives is usually much longer,
+typically two hours; this is set by the operating system, and cannot
+be configured within PuTTY.
+
+\b If the operating system does not receive a response to a keepalive,
+it may send out more in quick succession and if terminate the connection
+if no response is received.
+
+TCP keepalives may be more useful for ensuring that half-open connections
+are terminated than for keeping a connection alive.
+
+TCP keepalives are disabled by default.
+
\H{config-proxy} The Proxy panel
\cfg{winhelp-topic}{proxy.main}
\b Username and password authentication is supported for HTTP
proxies and SOCKS 5 proxies.
+\lcont{
+
+\b With SOCKS 5, authentication is via \i{CHAP} if the proxy
+supports it (this is not supported in \i{PuTTYtel}); otherwise the
+password is sent to the proxy in plain text.
+
+\b With HTTP proxying, the only currently supported authentication
+method is \q{basic}, where the password is sent to the proxy in plain
+text.
+
+}
+
\b SOCKS 4 can use the \q{Username} field, but does not support
passwords.
The Telnet panel allows you to configure options that only apply to
Telnet sessions.
-\S{config-environ} Setting environment variables on the server
-
-\cfg{winhelp-topic}{telnet.environ}
-
-The Telnet protocol provides a means for the client to pass
-environment variables to the server. Many Telnet servers have
-stopped supporting this feature due to security flaws, but PuTTY
-still supports it for the benefit of any servers which have found
-other ways around the security problems than just disabling the
-whole mechanism.
-
-To add an environment variable to the list transmitted down the
-connection, you enter the variable name in the \q{Variable} box,
-enter its value in the \q{Value} box, and press the \q{Add} button.
-To remove one from the list, select it in the list box and press
-\q{Remove}.
-
\S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}
\cfg{winhelp-topic}{telnet.oldenviron}
you have confusing trouble with a firewall, you could try enabling
passive mode to see if it helps.
-\S{config-telnetkey} \q{Keyboard sends telnet Backspace and Interrupt}
+\S{config-telnetkey} \q{Keyboard sends Telnet special commands}
\cfg{winhelp-topic}{telnet.specialkeys}
-If this box is checked, the Backspace key on the keyboard will send
-the Telnet special backspace code, and Control-C will send the
-Telnet special interrupt code. You probably shouldn't enable this
+If this box is checked, several key sequences will have their normal
+actions modified:
+
+\b the Backspace key on the keyboard will send the \I{Erase Character,
+Telnet special command}Telnet special backspace code;
+
+\b Control-C will send the Telnet special \I{Interrupt Process, Telnet
+special command}Interrupt Process code;
+
+\b Control-Z will send the Telnet special \I{Suspend Process, Telnet
+special command}Suspend Process code.
+
+You probably shouldn't enable this
unless you know what you're doing.
-\S{config-telnetnl} \q{Return key sends telnet New Line instead of ^M}
+\S{config-telnetnl} \q{Return key sends Telnet New Line instead of ^M}
\cfg{winhelp-topic}{telnet.newline}
very specialist purposes; although in Plink (see \k{plink}) it is
the usual way of working.
+\S{config-ssh-noshell} \q{Don't start a shell or command at all}
+
+\cfg{winhelp-topic}{ssh.noshell}
+
+If you tick this box, PuTTY will not attempt to run a shell or
+command after connecting to the remote server. You might want to use
+this option if you are only using the SSH connection for port
+forwarding, and your user account on the server does not have the
+ability to run a shell.
+
+This feature is only available in SSH protocol version 2 (since the
+version 1 protocol assumes you will always want to run a shell).
+
+This feature can also be enabled using the \c{-N} command-line
+option; see \k{using-cmdline-noshell}.
+
+If you use this feature in Plink, you will not be able to terminate
+the Plink process by any graceful means; the only way to kill it
+will be by pressing Control-C or sending a kill signal from another
+program.
+
\S{config-ssh-comp} \q{Enable compression}
\cfg{winhelp-topic}{ssh.compress}
a local X display on your PC.
To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
-If your X display is not the primary display on your local machine
-(which it almost certainly will be unless you have deliberately
-arranged otherwise), you need to enter its location in the \q{X
-display location} box.
+If your X display is somewhere unusual, you will need to enter its
+location in the \q{X display location} box; if this is left blank,
+PuTTY try to find a sensible default in the environment, or use the
+primary local display (\c{:0}) if that fails.
See \k{using-x-forwarding} for more information about X11
forwarding.
projects / u / mdw / putty / blobdiff