-\define{versionidconfig} \versionid $Id$
-
\C{config} Configuring PuTTY
This chapter describes all the \i{configuration options} in PuTTY.
\b The \q{Host Name} box is where you type the name, or the \i{IP
address}, of the server you want to connect to.
-\b The \q{Protocol} radio buttons let you choose what type of
+\b The \q{Connection type} radio buttons let you choose what type of
connection you want to make: a \I{raw TCP connections}raw
-connection, a \i{Telnet} connection, an \i{Rlogin} connection
-or an \i{SSH} connection. (See \k{which-one} for a
-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 \i{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, you will almost certainly need to fill in the \q{Port} box.
+connection, a \i{Telnet} connection, an \i{Rlogin} connection, an
+\i{SSH} connection, or a connection to a local \i{serial line}. (See
+\k{which-one} for a summary of the differences between SSH, Telnet
+and rlogin; see \k{using-rawprot} for an explanation of \q{raw}
+connections; see \k{using-serial} for information about using a
+serial line.)
+
+\b The \q{Port} box lets you specify which \i{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, you will almost certainly need to fill in the \q{Port} box
+yourself.
+
+If you select \q{Serial} from the \q{Connection type} radio buttons,
+the \q{Host Name} and \q{Port} boxes are replaced by \q{Serial line}
+and \q{Speed}; see \k{config-serial} for more details of these.
\S{config-saving} \ii{Loading and storing saved sessions}
\q{\i{Default Settings}} entry in the saved sessions list, with a single
click. Then press the \q{Save} button.
-\lcont{
-Note that PuTTY does not allow you to save a host name into the
-Default Settings entry. This ensures that when PuTTY is started up,
-the host name box is always empty, so a user can always just type in
-a host name and connect.
-}
-
If there is a specific host you want to store the details of how to
connect to, you should create a saved session, which will be
separate from the Default Settings.
PuTTY sessions, for debugging, analysis or future reference.
The main option is a radio-button set that specifies whether PuTTY
-will log anything at all. The options are
+will log anything at all. The options are:
-\b \q{Logging turned off completely}. This is the default option; in
-this mode PuTTY will not create a log file at all.
+\b \q{None}. This is the default option; in this mode PuTTY will not
+create a log file at all.
-\b \q{Log printable output only}. In this mode, a log file will be
+\b \q{Printable output}. In this mode, a log file will be
created and written to, but only printable text will be saved into
it. The various terminal control codes that are typically sent down
an interactive session alongside the printable text will be omitted.
This might be a useful mode if you want to read a log file in a text
editor and hope to be able to make sense of it.
-\b \q{Log all session output}. In this mode, \e{everything} sent by
+\b \q{All session output}. In this mode, \e{everything} sent by
the server into your terminal session is logged. If you view the log
file in a text editor, therefore, you may well find it full of
strange control characters. This is a particularly useful mode if
else can replay the session later in slow motion and watch to see
what went wrong.
-\b \q{\i{Log SSH packet data}}. In this mode (which is only used by SSH
-connections), the SSH message packets sent over the encrypted
-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 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.
+\b \I{SSH packet log}\q{SSH packets}. In this mode (which is only used
+by SSH connections), the SSH message packets sent over the encrypted
+connection are written to the log file (as well as \i{Event Log}
+entries). 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 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.
+
+\b \q{SSH packets and raw data}. In this mode, as well as the
+decrypted packets (as in the previous mode), the \e{raw} (encrypted,
+compressed, etc) packets are \e{also} logged. This could be useful to
+diagnose corruption in transit. (The same caveats as the previous mode
+apply, of course.)
+
+Note that the non-SSH logging options (\q{Printable output} and
+\q{All session output}) only work with PuTTY proper; in programs
+without terminal emulation (such as Plink), they will have no effect,
+even if enabled via saved settings.
\S{config-logfilename} \q{Log file name}
\b \c{&H} will be replaced by the host name you are connecting to.
+\b \c{&P} will be replaced by the port number you are connecting to on
+the target host.
+
For example, if you enter the host name
\c{c:\\puttylogs\\log-&h-&y&m&d-&t.dat}, you will end up with files looking
like
\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.
+When checked, decrypted 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
\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.
+When checked, all decrypted \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.
\c Second line
\c Third line
+\S{config-lfcr} \q{Implicit LF in every CR}
+
+\cfg{winhelp-topic}{terminal.crhaslf}
+
+Most servers send two control characters, \i{CR} and \i{LF}, to start a
+\i{new line} of the screen. The CR character makes the cursor return to the
+left-hand side of the screen. The LF character makes the cursor move
+one line down (and might make the screen scroll).
+
+Some servers only send CR, and so the newly
+written line is overwritten by the following line. This option causes
+a line feed so that all lines are displayed.
+
\S{config-erase} \q{Use \i{background colour} to erase screen}
\cfg{winhelp-topic}{terminal.bce}
movement commands (\cw{hjklyubn}). The 5 key generates the \c{.}
command (do nothing).
-Better still, pressing Shift with the keypad keys generates the
-capital forms of the commands (\cw{HJKLYUBN}), which tells NetHack
-to keep moving you in the same direction until you encounter
-something interesting.
+In addition, pressing Shift or Ctrl with the keypad keys generate
+the Shift- or Ctrl-keys you would expect (e.g. keypad-7 generates
+\cq{y}, so Shift-keypad-7 generates \cq{Y} and Ctrl-keypad-7
+generates Ctrl-Y); these commands tell NetHack to keep moving you in
+the same direction until you encounter something interesting.
For some reason, this feature only works properly when \i{Num Lock} is
on. We don't know why.
unexpectedly or inconveniently, you can tell PuTTY not to respond to
those server commands.
-\S{config-features-qtitle} Disabling remote \i{window title} querying
+\S{config-features-qtitle} Response to remote \i{window title} querying
\cfg{winhelp-topic}{features.qtitle}
typed at the keyboard. This allows an attacker to fake keypresses
and potentially cause your server-side applications to do things you
didn't want. Therefore this feature is disabled by default, and we
-recommend you do not turn it on unless you \e{really} know what you
-are doing.
+recommend you do not set it to \q{Window title} unless you \e{really}
+know what you are doing.
+
+There are three settings for this option:
+
+\dt \q{None}
+
+\dd PuTTY makes no response whatsoever to the relevant escape
+sequence. This may upset server-side software that is expecting some
+sort of response.
+
+\dt \q{Empty string}
+
+\dd PuTTY makes a well-formed response, but leaves it blank. Thus,
+server-side software that expects a response is kept happy, but an
+attacker cannot influence the response string. This is probably the
+setting you want if you have no better ideas.
+
+\dt \q{Window title}
+
+\dd PuTTY responds with the actual window title. This is dangerous for
+the reasons described above.
+
+\S{config-features-clearscroll} Disabling remote \i{scrollback clearing}
+
+\cfg{winhelp-topic}{features.clearscroll}
+
+PuTTY has the ability to clear the terminal's scrollback buffer in
+response to a command from the server. If you find PuTTY is doing this
+unexpectedly or inconveniently, you can tell PuTTY not to respond to
+that server command.
\S{config-features-dbackspace} Disabling \i{destructive backspace}
PuTTY has the ability to change its character set configuration in
response to commands from the server. Some programs send these
-commands unexpectedly or inconveniently. In particular, \I{BitchX} (an
+commands unexpectedly or inconveniently. In particular, \i{BitchX} (an
IRC client) seems to have a habit of reconfiguring the character set
to something other than the user intended.
\cfg{winhelp-topic}{window.size}
-The \q{\ii{Rows}} and \q{\ii{Columns}} boxes let you set the PuTTY
+The \q{\ii{Columns}} and \q{\ii{Rows}} boxes let you set the PuTTY
window to a precise size. Of course you can also \I{window resizing}drag
the window to a new size while a session is running.
\b \q{Change font size when maximised}: when the window is resized,
the number of rows and columns will change, \e{except} when the window
-is \i{maximise}d (or restored), when the font size will change.
+is \i{maximise}d (or restored), when the font size will change. (In
+this mode, holding down the Alt key while resizing will also cause the
+font size to change.)
\b \q{Forbid resizing completely}: the terminal will refuse to be
resized at all.
\cfg{winhelp-topic}{appearance.font}
This option allows you to choose what font, in what \I{font size}size,
-the PuTTY terminal window uses to display the text in the session. You
-will be offered a choice from all the fixed-width fonts installed on the
-system. (VT100-style terminal handling can only deal with fixed-width
-fonts.)
+the PuTTY terminal window uses to display the text in the session.
+
+By default, you will be offered a choice from all the fixed-width
+fonts installed on the system, since VT100-style terminal handling
+expects a fixed-width font. If you tick the box marked \q{Allow
+selection of variable-pitch fonts}, however, PuTTY will offer
+variable-width fonts as well: if you select one of these, the font
+will be coerced into fixed-size character cells, which will probably
+not look very good (but can work OK with some fonts).
\S{config-mouseptr} \q{Hide \i{mouse pointer} when typing in window}
During an interactive session, PuTTY receives a stream of 8-bit
bytes from the server, and in order to display them on the screen it
-needs to know what character set to interpret them in.
+needs to know what character set to interpret them in. Similarly,
+PuTTY needs to know how to translate your keystrokes into the encoding
+the server expects. Unfortunately, there is no satisfactory
+mechanism for PuTTY and the server to communicate this information,
+so it must usually be manually configured.
+
+There are a lot of character sets to choose from. The \q{Remote
+character set} option lets you select one.
-There are a lot of character sets to choose from. The \q{Received
-data assumed to be in which character set} option lets you select
-one. By default PuTTY will attempt to choose a character set that is
-right for your \i{locale} as reported by Windows; if it gets it wrong,
-you can select a different one using this control.
+By default PuTTY will use the \i{UTF-8} encoding of \i{Unicode}, which
+can represent pretty much any character; data coming from the server
+is interpreted as UTF-8, and keystrokes are sent UTF-8 encoded. This
+is what most modern distributions of Linux will expect by default.
+However, if this is wrong for your server, you can select a different
+character set using this control.
-A few notable character sets are:
+A few other notable character sets are:
\b The \i{ISO-8859} series are all standard character sets that include
various accented characters appropriate for different sets of
\b If you want the old IBM PC character set with block graphics and
line-drawing characters, you can select \q{\i{CP437}}.
-\b PuTTY also supports \i{Unicode} mode, in which the data coming from
-the server is interpreted as being in the \i{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 \i{code page} which is not listed in
the drop-down list, such as code page 866, then you can try entering
its name manually (\c{\i{CP866}} for example) in the list box. If the
If you enable \q{Paste to clipboard in RTF as well as plain text},
PuTTY will write formatting information to the clipboard as well as
-the actual text you copy. Currently the only effect of this will be
+the actual text you copy. The effect of this is
that if you paste into (say) a word processor, the text will appear
-in the word processor in the same \i{font} PuTTY was using to display
-it. In future it is likely that other formatting information (bold,
-underline, colours) will be copied as well.
+in the word processor in the same \i{font}, \i{colour}, and style
+(e.g. bold, underline) PuTTY was using to display it.
This option can easily be inconvenient, so by default it is
disabled.
change your terminal setting. On modern Linux machines, you could
try \cq{xterm-256color}.
-\S{config-boldcolour} \q{Bolded text is a different colour}
+\S{config-boldcolour} \q{Indicate bolded text by changing...}
\cfg{winhelp-topic}{colours.bold}
When the server sends a \i{control sequence} indicating that some text
-should be displayed in \i{bold}, PuTTY can handle this two ways. It can
-either change the \i{font} for a bold version, or use the same font in a
-brighter colour. This control lets you choose which.
-
-By default the box is checked, so non-bold text is displayed in
-light grey and bold text is displayed in bright white (and similarly
-in other colours). If you uncheck the box, bold and non-bold text
-will be displayed in the same colour, and instead the font will
-change to indicate the difference.
+should be displayed in \i{bold}, PuTTY can handle this in several
+ways. It can either change the \i{font} for a bold version, or use the
+same font in a brighter colour, or it can do both (brighten the colour
+\e{and} embolden the font). This control lets you choose which.
+
+By default bold is indicated by colour, so non-bold text is displayed
+in light grey and bold text is displayed in bright white (and
+similarly in other colours). If you change the setting to \q{The font}
+box, bold and non-bold text will be displayed in the same colour, and
+instead the font will change to indicate the difference. If you select
+\q{Both}, the font and the colour will both change.
+
+Some applications rely on \q{\i{bold black}} being distinguishable
+from a black background; if you choose \q{The font}, their text may
+become invisible.
\S{config-logpalette} \q{Attempt to use \i{logical palettes}}
values} for that colour will appear on the right-hand side of the
list box. Now, if you press the \q{Modify} button, you will be
presented with a colour selector, in which you can choose a new
-colour to go in place of the old one.
+colour to go in place of the old one. (You may also edit the RGB
+values directly in the edit boxes, if you wish; each value is an
+integer from 0 to 255.)
PuTTY allows you to set the \i{cursor colour}, the \i{default foreground}
and \I{default background}background, and the precise shades of all the
\I{ANSI colours}ANSI configurable colours (black, red, green, yellow, blue,
magenta, cyan, and white). You can also modify the precise shades used for
the \i{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. (Note that \q{Default
-Bold Background} is \e{not} the background colour used for bold text;
-it is only used if the server specifically asks for a bold
+if you have chosen to indicate that by colour (see \k{config-boldcolour}),
+and can also be used if the server asks specifically to use them. (Note
+that \q{Default Bold Background} is \e{not} the background colour used for
+bold text; it is only used if the server specifically asks for a bold
background.)
\H{config-connection} The Connection panel
protocols offer no way of implementing them. (For an alternative, see
\k{config-tcp-keepalives}.)
-Note that if you are using \i{SSH-1} and the server has a bug that makes
+Note that if you are using SSH-1 and the server has a bug that makes
it unable to deal with SSH-1 ignore messages (see
\k{config-ssh-bug-ignore1}), enabling keepalives will have no effect.
\cfg{winhelp-topic}{connection.ipversion}
This option allows the user to select between the old and new
-Internet protocols and addressing schemes (\i{IPv4} and \i{IPv6}). The
-default setting is \q{Auto}, which means PuTTY will do something
+Internet protocols and addressing schemes (\i{IPv4} and \i{IPv6}).
+The selected protocol will be used for most outgoing network
+connections (including connections to \I{proxy}proxies); however,
+tunnels have their own configuration, for which see
+\k{config-ssh-portfwd-address-family}.
+
+The default setting is \q{Auto}, which means PuTTY will do something
sensible and try to guess which protocol you wanted. (If you specify
a literal \i{Internet address}, it will use whichever protocol that
address implies. If you provide a \i{hostname}, it will see what kinds
If you need to force PuTTY to use a particular protocol, you can
explicitly set this to \q{IPv4} or \q{IPv6}.
+\S{config-loghost} \I{logical host name}\q{Logical name of remote host}
+
+\cfg{winhelp-topic}{connection.loghost}
+
+This allows you to tell PuTTY that the host it will really end up
+connecting to is different from where it thinks it is making a
+network connection.
+
+You might use this, for instance, if you had set up an SSH port
+forwarding in one PuTTY session so that connections to some
+arbitrary port (say, \cw{localhost} port 10022) were forwarded to a
+second machine's SSH port (say, \cw{foovax} port 22), and then
+started a second PuTTY connecting to the forwarded port.
+
+In normal usage, the second PuTTY will access the \i{host key cache}
+under the host name and port it actually connected to (i.e.
+\cw{localhost} port 10022 in this example). Using the logical host
+name option, however, you can configure the second PuTTY to cache
+the host key under the name of the host \e{you} know that it's
+\e{really} going to end up talking to (here \c{foovax}).
+
+This can be useful if you expect to connect to the same actual
+server through many different channels (perhaps because your port
+forwarding arrangements keep changing): by consistently setting the
+logical host name, you can arrange that PuTTY will not keep asking
+you to reconfirm its host key. Conversely, if you expect to use the
+same local port number for port forwardings to lots of different
+servers, you probably didn't want any particular server's host key
+cached under that local port number. (For this latter case, you
+could instead explicitly configure host keys in the relevant sessions;
+see \k{config-ssh-kex-manual-hostkeys}.)
+
+If you just enter a host name for this option, PuTTY will cache the
+SSH host key under the default SSH port for that host, irrespective
+of the port you really connected to (since the typical scenario is
+like the above example: you connect to a silly real port number and
+your connection ends up forwarded to the normal port-22 SSH server
+of some other machine). To override this, you can append a port
+number to the logical host name, separated by a colon. E.g. entering
+\cq{foovax:2200} as the logical host name will cause the host key to
+be cached as if you had connected to port 2200 of \c{foovax}.
+
+If you provide a host name using this option, it is also displayed
+in other locations which contain the remote host name, such as the
+default window title and the default SSH password prompt. This
+reflects the fact that this is the host you're \e{really} connecting
+to, which is more important than the mere means you happen to be
+using to contact that host. (This applies even if you're using a
+protocol other than SSH.)
+
\H{config-data} The Data panel
The Data panel allows you to configure various pieces of data which
In this box you can type that user name.
+\S{config-username-from-env} Use of system username
+
+\cfg{winhelp-topic}{connection.usernamefromenv}
+
+When the previous box (\k{config-username}) is left blank, by default,
+PuTTY will prompt for a username at the time you make a connection.
+
+In some environments, such as the networks of large organisations
+implementing \i{single sign-on}, a more sensible default may be to use
+the name of the user logged in to the local operating system (if any);
+this is particularly likely to be useful with \i{GSSAPI} authentication
+(see \k{config-ssh-auth-gssapi}). This control allows you to change
+the default behaviour.
+
+The current system username is displayed in the dialog as a
+convenience. It is not saved in the configuration; if a saved session
+is later used by a different user, that user's name will be used.
+
\S{config-termtype} \q{\ii{Terminal-type} string}
\cfg{winhelp-topic}{connection.termtype}
The \ii{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 \i{port
+session, and also any extra connections made as a result of SSH \i{port
forwarding} (see \k{using-port-forwarding}).
+Note that unlike some software (such as web browsers), PuTTY does not
+attempt to automatically determine whether to use a proxy and (if so)
+which one to use for a given destination. If you need to use a proxy,
+it must always be explicitly configured.
+
\S{config-proxy-type} Setting the proxy type
\cfg{winhelp-topic}{proxy.type}
through to an external host. Selecting \I{Telnet proxy}\q{Telnet}
allows you to tell PuTTY to use this type of proxy.
+\b Selecting \I{Local proxy}\q{Local} allows you to specify an arbitrary
+command on the local machine to act as a proxy. When the session is
+started, instead of creating a TCP connection, PuTTY runs the command
+(specified in \k{config-proxy-command}), and uses its standard input and
+output streams.
+
+\lcont{
+This could be used, for instance, to talk to some kind of network proxy
+that PuTTY does not natively support; or you could tunnel a connection
+over something other than TCP/IP entirely.
+
+If you want your local proxy command to make a secondary SSH
+connection to a proxy host and then tunnel the primary connection
+over that, you might well want the \c{-nc} command-line option in
+Plink. See \k{using-cmdline-ncmode} for more information.
+
+You can also enable this mode on the command line; see
+\k{using-cmdline-proxycmd}.
+}
+
\S{config-proxy-exclude} Excluding parts of the network from proxying
\cfg{winhelp-topic}{proxy.exclude}
passwords.
\b You can specify a way to include a username and password in the
-Telnet proxy command (see \k{config-proxy-command}).
+Telnet/Local proxy command (see \k{config-proxy-command}).
-\S{config-proxy-command} Specifying the Telnet proxy command
+\S{config-proxy-command} Specifying the Telnet or Local proxy command
\cfg{winhelp-topic}{proxy.command}
name and a port number. If your proxy needs a different command,
you can enter an alternative here.
+If you are using the \i{Local proxy} type, the local command to run
+is specified 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
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{%%}.
+password you specify. The strings \c{%proxyhost} and \c{%proxyport}
+will be replaced by the host details specified on the \e{Proxy} panel,
+if any (this is most likely to be useful for the Local proxy type).
+To get a literal \c{%} sign, enter \c{%%}.
-If the Telnet proxy server prompts for a username and password
+If a 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
tokens in the Telnet command, then the \q{Username} and \q{Password}
configuration fields will be ignored.
+\S{config-proxy-logging} Controlling \i{proxy logging}
+
+\cfg{winhelp-topic}{proxy.logging}
+
+Often the proxy interaction has its own diagnostic output; this is
+particularly the case for local proxy commands.
+
+The setting \q{Print proxy diagnostics in the terminal window} lets
+you control how much of the proxy's diagnostics are printed to the main
+terminal window, along with output from your main session.
+
+By default (\q{No}), proxy diagnostics are only sent to the Event Log;
+with \q{Yes} they are also printed to the terminal, where they may get
+mixed up with your main session. \q{Only until session starts} is a
+compromise; proxy messages will go to the terminal window until the main
+session is deemed to have started (in a protocol-dependent way), which
+is when they're most likely to be interesting; any further proxy-related
+messages during the session will only go to the Event Log.
+
\H{config-telnet} The \i{Telnet} panel
The Telnet panel allows you to configure options that only apply to
first and the server decompresses it at the other end. This can help
make the most of a low-\i{bandwidth} connection.
-\S{config-ssh-prot} \q{Preferred \i{SSH protocol version}}
+\S{config-ssh-prot} \q{\i{SSH protocol version}}
\cfg{winhelp-topic}{ssh.protocol}
-This allows you to select whether you would like to use \i{SSH protocol
-version 1} or \I{SSH-2}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.
-
-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} \ii{Encryption} algorithm selection
-
-\cfg{winhelp-topic}{ssh.ciphers}
-
-PuTTY supports a variety of different \i{encryption algorithm}s, and
-allows you to choose which one you prefer to use. You can do this by
-dragging the algorithms up and down in the list box (or moving them
-using the Up and Down buttons) to specify a preference order. When
-you make an SSH connection, PuTTY will search down the list from the
-top until it finds an algorithm supported by the server, and then
-use that.
-
-PuTTY currently supports the following algorithms:
-
-\b \i{AES} (Rijndael) - 256, 192, or 128-bit SDCTR or CBC (SSH-2 only)
-
-\b \i{Arcfour} (RC4) - 256 or 128-bit stream cipher (SSH-2 only)
-
-\b \i{Blowfish} - 256-bit SDCTR (SSH-2 only) or 128-bit CBC
-
-\b \ii{Triple-DES} - 168-bit SDCTR (SSH-2 only) or CBC
-
-\b \ii{Single-DES} - 56-bit CBC (see below for SSH-2)
-
-If the algorithm PuTTY finds is below the \q{warn below here} line,
-you will see a warning box when you make the connection:
-
-\c The first cipher supported by the server
-\c is single-DES, which is below the configured
-\c warning threshold.
-\c Do you want to continue with this connection?
-
-This warns you that the first available encryption is not a very
-secure one. Typically you would put the \q{warn below here} line
-between the encryptions you consider secure and the ones you
-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 recommended in the SSH-2 draft protocol
-standards, but one or two server implementations do support it.
-PuTTY can use single-DES to interoperate with
-these servers if you enable the \q{Enable legacy use of single-DES in
-SSH-2} option; by default this is disabled and PuTTY will stick to
-recommended ciphers.
+This allows you to select whether to use \i{SSH protocol version 2}
+or the older \I{SSH-1}version 1.
+
+You should normally leave this at the default of \q{2}. As well as
+having fewer features, the older SSH-1 protocol is no longer
+developed, has many known cryptographic weaknesses, and is generally
+not considered to be secure. PuTTY's protocol 1 implementation is
+provided mainly for compatibility, and is no longer being enhanced.
+
+If a server offers both versions, prefer \q{2}. If you have some
+server or piece of equipment that only talks SSH-1, select \q{1}
+here, and do not treat the resulting connection as secure.
+
+PuTTY will not automatically fall back to the other version of the
+protocol if the server turns out not to match your selection here;
+instead, it will put up an error message and abort the connection.
+This prevents an active attacker downgrading an intended SSH-2
+connection to SSH-1.
+
+\S{config-ssh-sharing} Sharing an SSH connection between PuTTY tools
+
+\cfg{winhelp-topic}{ssh.sharing}
+
+The controls in this box allow you to configure PuTTY to reuse an
+existing SSH connection, where possible.
+
+The SSH-2 protocol permits you to run multiple data channels over the
+same SSH connection, so that you can log in just once (and do the
+expensive encryption setup just once) and then have more than one
+terminal window open.
+
+Each instance of PuTTY can still run at most one terminal session, but
+using the controls in this box, you can configure PuTTY to check if
+another instance of itself has already connected to the target host,
+and if so, share that instance's SSH connection instead of starting a
+separate new one.
+
+To enable this feature, just tick the box \q{Share SSH connections if
+possible}. Then, whenever you start up a PuTTY session connecting to a
+particular host, it will try to reuse an existing SSH connection if
+one is available. For example, selecting \q{Duplicate Session} from
+the system menu will launch another session on the same host, and if
+sharing is enabled then it will reuse the existing SSH connection.
+
+When this mode is in use, the first PuTTY that connected to a given
+server becomes the \q{upstream}, which means that it is the one
+managing the real SSH connection. All subsequent PuTTYs which reuse
+the connection are referred to as \q{downstreams}: they do not connect
+to the real server at all, but instead connect to the upstream PuTTY
+via local inter-process communication methods.
+
+For this system to be activated, \e{both} the upstream and downstream
+instances of PuTTY must have the sharing option enabled.
+
+The upstream PuTTY can therefore not terminate until all its
+downstreams have closed. This is similar to the effect you get with
+port forwarding or X11 forwarding, in which a PuTTY whose terminal
+session has already finished will still remain open so as to keep
+serving forwarded connections.
+
+In case you need to configure this system in more detail, there are
+two additional checkboxes which allow you to specify whether a
+particular PuTTY can act as an upstream or a downstream or both.
+(These boxes only take effect if the main \q{Share SSH connections if
+possible} box is also ticked.) By default both of these boxes are
+ticked, so that multiple PuTTYs started from the same configuration
+will designate one of themselves as the upstream and share a single
+connection; but if for some reason you need a particular PuTTY
+configuration \e{not} to be an upstream (e.g. because you definitely
+need it to close promptly) or not to be a downstream (e.g. because it
+needs to do its own authentication using a special private key) then
+you can untick one or the other of these boxes.
+
+I have referred to \q{PuTTY} throughout the above discussion, but all
+the other PuTTY tools which make SSH connections can use this
+mechanism too. For example, if PSCP or PSFTP loads a configuration
+with sharing enabled, then it can act as a downstream and use an
+existing SSH connection set up by an instance of GUI PuTTY. The one
+special case is that PSCP and PSFTP will \e{never} act as upstreams.
+
+It is possible to test programmatically for the existence of a live
+upstream using Plink. See \k{plink-option-shareexists}.
\H{config-ssh-kex} The Kex panel
-\# FIXME: This whole section is draft. Feel free to revise.
-
The Kex panel (short for \q{\i{key exchange}}) allows you to configure
options related to SSH-2 key exchange.
to choose which one you prefer to use; configuration is similar to
cipher selection (see \k{config-ssh-encryption}).
-PuTTY currently supports the following varieties of \i{Diffie-Hellman key
-exchange}:
+PuTTY currently supports the following key exchange methods:
+
+\b \q{ECDH}: \i{elliptic curve} \i{Diffie-Hellman key exchange}.
-\b \q{Group 14}: a well-known 2048-bit group.
+\b \q{Group 14}: Diffie-Hellman key exchange with a well-known
+2048-bit group.
-\b \q{Group 1}: a well-known 1024-bit group. This is less secure
-\#{FIXME better words} than group 14, but may be faster with slow
-client or server machines, and may be the only method supported by
-older server software.
+\b \q{Group 1}: Diffie-Hellman key exchange with a well-known
+1024-bit group. We no longer recommend using this method, and it's
+not used by default in new installations; however, it may be the
+only method supported by very old server software.
\b \q{\ii{Group exchange}}: with this method, instead of using a fixed
group, PuTTY requests that the server suggest a group to use for key
exchange; the server can avoid groups known to be weak, and possibly
invent new ones over time, without any changes required to PuTTY's
-configuration. We recommend use of this method, if possible.
+configuration. We recommend use of this method instead of the
+well-known groups, if possible.
+
+\b \q{\i{RSA key exchange}}: this requires much less computational
+effort on the part of the client, and somewhat less on the part of
+the server, than Diffie-Hellman key exchange.
If the first algorithm PuTTY finds is below the \q{warn below here}
line, you will see a warning box when you make the connection, similar
exchange (\q{rekey}). You can also force a key exchange at any time
from the Special Commands menu (see \k{using-specials}).
-\# FIXME: do we have any additions to the SSH-2 drafts' advice on
+\# FIXME: do we have any additions to the SSH-2 specs' advice on
these values? Do we want to enforce any limits?
\b \q{Max minutes before rekey} specifies the amount of time that is
problems. The SSH-1 protocol, incidentally, has even weaker integrity
protection than SSH-2 without rekeys.
+\H{config-ssh-hostkey} The Host Keys panel
+
+The Host Keys panel allows you to configure options related to SSH-2
+\i{host key management}.
+
+Host keys are used to prove the server's identity, and assure you that
+the server is not being spoofed (either by a man-in-the-middle attack
+or by completely replacing it on the network). See \k{gs-hostkey} for
+a basic introduction to host keys.
+
+This entire panel is only relevant to SSH protocol version 2; none of
+these settings affect SSH-1 at all.
+
+\S{config-ssh-hostkey-order} \ii{Host key type} selection
+
+\cfg{winhelp-topic}{ssh.hostkey.order}
+
+PuTTY supports a variety of SSH-2 host key types, and allows you to
+choose which one you prefer to use to identify the server.
+Configuration is similar to cipher selection (see
+\k{config-ssh-encryption}).
+
+PuTTY currently supports the following host key types:
+
+\b \q{Ed25519}: \i{Edwards-curve} \i{DSA} using a twisted Edwards
+curve with modulus \cw{2^255-19}.
+
+\b \q{ECDSA}: \i{elliptic curve} \i{DSA} using one of the
+NIST-standardised elliptic curves.
+
+\b \q{DSA}: straightforward \i{DSA} using modular exponentiation.
+
+\b \q{RSA}: the ordinary \i{RSA} algorithm.
+
+If PuTTY already has one or more host keys stored for the server,
+it will prefer to use one of those, even if the server has a key
+type that is higher in the preference order. You can add such a
+key to PuTTY's cache from within an existing session using the
+\q{Special Commands} menu; see \k{using-specials}.
+
+Otherwise, PuTTY will choose a key type based purely on the
+preference order you specify in the configuration.
+
+If the first key type PuTTY finds is below the \q{warn below here}
+line, you will see a warning box when you make the connection, similar
+to that for cipher selection (see \k{config-ssh-encryption}).
+
+\S{config-ssh-kex-manual-hostkeys} \ii{Manually configuring host keys}
+
+\cfg{winhelp-topic}{ssh.kex.manualhostkeys}
+
+In some situations, if PuTTY's automated host key management is not
+doing what you need, you might need to manually configure PuTTY to
+accept a specific host key, or one of a specific set of host keys.
+
+One reason why you might want to do this is because the host name
+PuTTY is connecting to is using round-robin DNS to return one of
+multiple actual servers, and they all have different host keys. In
+that situation, you might need to configure PuTTY to accept any of a
+list of host keys for the possible servers, while still rejecting any
+key not in that list.
+
+Another reason is if PuTTY's automated host key management is
+completely unavailable, e.g. because PuTTY (or Plink or PSFTP, etc) is
+running in a Windows environment without access to the Registry. In
+that situation, you will probably want to use the \cw{-hostkey}
+command-line option to configure the expected host key(s); see
+\k{using-cmdline-hostkey}.
+
+For situations where PuTTY's automated host key management simply
+picks the wrong host name to store a key under, you may want to
+consider setting a \q{logical host name} instead; see
+\k{config-loghost}.
+
+To configure manual host keys via the GUI, enter some text describing
+the host key into the edit box in the \q{Manually configure host keys
+for this connection} container, and press the \q{Add} button. The text
+will appear in the \q{Host keys or fingerprints to accept} list box.
+You can remove keys again with the \q{Remove} button.
+
+The text describing a host key can be in one of the following formats:
+
+\b An MD5-based host key fingerprint of the form displayed in PuTTY's
+Event Log and host key dialog boxes, i.e. sixteen 2-digit hex numbers
+separated by colons.
+
+\b A base64-encoded blob describing an SSH-2 public key in
+OpenSSH's one-line public key format. How you acquire a public key in
+this format is server-dependent; on an OpenSSH server it can typically
+be found in a location like \c{/etc/ssh/ssh_host_rsa_key.pub}.
+
+If this box contains at least one host key or fingerprint when PuTTY
+makes an SSH connection, then PuTTY's automated host key management is
+completely bypassed: the connection will be permitted if and only if
+the host key presented by the server is one of the keys listed in this
+box, and the \I{host key cache}host key store in the Registry will be
+neither read \e{nor written}, unless you explicitly do so.
+
+If the box is empty (as it usually is), then PuTTY's automated host
+key management will work as normal.
+
+\H{config-ssh-encryption} The Cipher panel
+
+\cfg{winhelp-topic}{ssh.ciphers}
+
+PuTTY supports a variety of different \i{encryption algorithm}s, and
+allows you to choose which one you prefer to use. You can do this by
+dragging the algorithms up and down in the list box (or moving them
+using the Up and Down buttons) to specify a preference order. When
+you make an SSH connection, PuTTY will search down the list from the
+top until it finds an algorithm supported by the server, and then
+use that.
+
+PuTTY currently supports the following algorithms:
+
+\b \i{ChaCha20-Poly1305}, a combined cipher and \i{MAC} (SSH-2 only)
+
+\b \i{AES} (Rijndael) - 256, 192, or 128-bit SDCTR or CBC (SSH-2 only)
+
+\b \i{Arcfour} (RC4) - 256 or 128-bit stream cipher (SSH-2 only)
+
+\b \i{Blowfish} - 256-bit SDCTR (SSH-2 only) or 128-bit CBC
+
+\b \ii{Triple-DES} - 168-bit SDCTR (SSH-2 only) or CBC
+
+\b \ii{Single-DES} - 56-bit CBC (see below for SSH-2)
+
+If the algorithm PuTTY finds is below the \q{warn below here} line,
+you will see a warning box when you make the connection:
+
+\c The first cipher supported by the server
+\c is single-DES, which is below the configured
+\c warning threshold.
+\c Do you want to continue with this connection?
+
+This warns you that the first available encryption is not a very
+secure one. Typically you would put the \q{warn below here} line
+between the encryptions you consider secure and the ones you
+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 recommended in the SSH-2 protocol
+standards, but one or two server implementations do support it.
+PuTTY can use single-DES to interoperate with
+these servers if you enable the \q{Enable legacy use of single-DES in
+SSH-2} option; by default this is disabled and PuTTY will stick to
+recommended ciphers.
+
\H{config-ssh-auth} The Auth panel
The Auth panel allows you to configure \i{authentication} options for
SSH sessions.
+\S{config-ssh-banner} \q{Display pre-authentication banner}
+
+\cfg{winhelp-topic}{ssh.auth.banner}
+
+SSH-2 servers can provide a message for clients to display to the
+prospective user before the user logs in; this is sometimes known as a
+pre-authentication \q{\i{banner}}. Typically this is used to provide
+information about the server and legal notices.
+
+By default, PuTTY displays this message before prompting for a
+password or similar credentials (although, unfortunately, not before
+prompting for a login name, due to the nature of the protocol design).
+By unchecking this option, display of the banner can be suppressed
+entirely.
+
\S{config-ssh-noauth} \q{Bypass authentication entirely}
\cfg{winhelp-topic}{ssh.auth.bypass}
-In SSH-2, it is possible to establish a connection without using SSH's
-mechanisms to identify or authenticate oneself to the server. Some
-servers may prefer to handle authentication in the data channel, for
-instance, or may simply require no authentication whatsoever.
-
-By default, PuTTY assumes the server requires authentication (most
-do), and thus must provide a username. If you find you are getting
-unwanted username prompts, you could try checking this option.
+In SSH-2, it is in principle possible to establish a connection
+without using SSH's mechanisms to identify or prove who you are
+to the server. An SSH server could prefer to handle authentication
+in the data channel, for instance, or simply require no user
+authentication whatsoever.
+
+By default, PuTTY assumes the server requires authentication (we've
+never heard of one that doesn't), and thus must start this process
+with a username. If you find you are getting username prompts that
+you cannot answer, you could try enabling this option. However,
+most SSH servers will reject this.
+
+This is not the option you want if you have a username and just want
+PuTTY to remember it; for that see \k{config-username}.
+It's also probably not what if you're trying to set up passwordless
+login to a mainstream SSH server; depending on the server, you
+probably wanted public-key authentication (\k{pubkey})
+or perhaps GSSAPI authentication (\k{config-ssh-auth-gssapi}).
+(These are still forms of authentication, even if you don't have to
+interact with them.)
This option only affects SSH-2 connections. SSH-1 connections always
require an authentication step.
+\S{config-ssh-tryagent} \q{Attempt authentication using Pageant}
+
+\cfg{winhelp-topic}{ssh.auth.pageant}
+
+If this option is enabled, then PuTTY will look for Pageant (the SSH
+private-key storage agent) and attempt to authenticate with any
+suitable public keys Pageant currently holds.
+
+This behaviour is almost always desirable, and is therefore enabled
+by default. In rare cases you might need to turn it off in order to
+force authentication by some non-public-key method such as
+passwords.
+
+This option can also be controlled using the \c{-noagent}
+command-line option. See \k{using-cmdline-agentauth}.
+
+See \k{pageant} for more information about Pageant in general.
+
\S{config-ssh-tis} \q{Attempt \I{TIS authentication}TIS or
\i{CryptoCard authentication}}
authentication available in SSH protocol version 1 only. You might use
them if you were using \i{S/Key} \i{one-time passwords}, for example,
or if you had a physical \i{security token} that generated responses
-to authentication challenges.
+to authentication challenges. They can even be used to prompt for
+simple passwords.
With this switch enabled, PuTTY will attempt these forms of
authentication if the server is willing to try them. You will be
-presented with a challenge string (which will be different every
+presented with a challenge string (which may be different every
time) and must supply the correct response in order to log in. If
your server supports this, you should talk to your system
administrator about precisely what form these challenges and
private key in another format that you want to use with PuTTY, see
\k{puttygen-conversions}.
+You can use the authentication agent \i{Pageant} so that you do not
+need to explicitly configure a key here; see \k{pageant}.
+
+If a private key file is specified here with Pageant running, PuTTY
+will first try asking Pageant to authenticate with that key, and
+ignore any other keys Pageant may have. If that fails, PuTTY will ask
+for a passphrase as normal. You can also specify a \e{public} key file
+in this case (in RFC 4716 or OpenSSH format), as that's sufficient to
+identify the key to Pageant, but of course if Pageant isn't present
+PuTTY can't fall back to using this file itself.
+
+\H{config-ssh-auth-gssapi} The \i{GSSAPI} panel
+
+\cfg{winhelp-topic}{ssh.auth.gssapi}
+
+The \q{GSSAPI} subpanel of the \q{Auth} panel controls the use of
+GSSAPI authentication. This is a mechanism which delegates the
+authentication exchange to a library elsewhere on the client
+machine, which in principle can authenticate in many different ways
+but in practice is usually used with the \i{Kerberos} \i{single sign-on}
+protocol to implement \i{passwordless login}.
+
+GSSAPI is only available in the SSH-2 protocol.
+
+The topmost control on the GSSAPI subpanel is the checkbox labelled
+\q{Attempt GSSAPI authentication}. If this is disabled, GSSAPI will
+not be attempted at all and the rest of this panel is unused. If it
+is enabled, GSSAPI authentication will be attempted, and (typically)
+if your client machine has valid Kerberos credentials loaded, then
+PuTTY should be able to authenticate automatically to servers that
+support Kerberos logins.
+
+\S{config-ssh-auth-gssapi-delegation} \q{Allow GSSAPI credential
+delegation}
+
+\cfg{winhelp-topic}{ssh.auth.gssapi.delegation}
+
+\i{GSSAPI credential delegation} is a mechanism for passing on your
+Kerberos (or other) identity to the session on the SSH server. If
+you enable this option, then not only will PuTTY be able to log in
+automatically to a server that accepts your Kerberos credentials,
+but also you will be able to connect out from that server to other
+Kerberos-supporting services and use the same credentials just as
+automatically.
+
+(This option is the Kerberos analogue of SSH agent forwarding; see
+\k{pageant-forward} for some information on that.)
+
+Note that, like SSH agent forwarding, there is a security
+implication in the use of this option: the administrator of the
+server you connect to, or anyone else who has cracked the
+administrator account on that server, could fake your identity when
+connecting to further Kerberos-supporting services. However,
+Kerberos sites are typically run by a central authority, so the
+administrator of one server is likely to already have access to the
+other services too; so this would typically be less of a risk than
+SSH agent forwarding.
+
+\S{config-ssh-auth-gssapi-libraries} Preference order for GSSAPI
+libraries
+
+\cfg{winhelp-topic}{ssh.auth.gssapi.libraries}
+
+GSSAPI is a mechanism which allows more than one authentication
+method to be accessed through the same interface. Therefore, more
+than one authentication library may exist on your system which can
+be accessed using GSSAPI.
+
+PuTTY contains native support for a few well-known such libraries,
+and will look for all of them on your system and use whichever it
+finds. If more than one exists on your system and you need to use a
+specific one, you can adjust the order in which it will search using
+this preference list control.
+
+One of the options in the preference list is to use a user-specified
+GSSAPI library. If the library you want to use is not mentioned by
+name in PuTTY's list of options, you can enter its full pathname in
+the \q{User-supplied GSSAPI library path} field, and move the
+\q{User-supplied GSSAPI library} option in the preference list to
+make sure it is selected before anything else.
+
\H{config-ssh-tty} The TTY panel
The TTY panel lets you configure the remote pseudo-terminal.
\lcont{
PuTTY proper will send modes that it has an opinion on (currently only
-the code for the Backspace key, \cw{ERASE}). Plink on Unix
-will propagate appropriate modes from the local terminal, if any.
+the code for the Backspace key, \cw{ERASE}, and whether the character
+set is UTF-8, \cw{IUTF8}). Plink on Unix will propagate appropriate
+modes from the local terminal, if any.
}
PuTTY in a variety of ways, such as \cw{true}/\cw{false},
\cw{yes}/\cw{no}, and \cw{0}/\cw{1}.
+\b The boolean mode \I{IUTF8 terminal mode}\cw{IUTF8} signals to the
+server whether the terminal character set is \i{UTF-8} or not.
+If this is set incorrectly, actions like backspace may behave
+incorrectly in some circumstances. However, setting this is not usually
+sufficient to cause servers to expect the terminal to be in UTF-8 mode;
+POSIX servers will generally require the locale to be set (by some
+server-dependent means), although many default to UTF-8. Also,
+\#{circa 2016} many servers (particularly older servers) do not honour
+this mode sent over SSH. When set to \q{Auto}, this follows the
+local configured character set (see \k{config-charset}).
+
\b Terminal speeds are configured elsewhere; see \k{config-termspeed}.
\H{config-ssh-x11} The X11 panel
The X11 panel allows you to configure \i{forwarding of X11} over an
SSH connection.
-If your server lets you run X Window System applications, X11
-forwarding allows you to securely give those applications access to
+If your server lets you run X Window System \i{graphical applications},
+X11 forwarding allows you to securely give those applications access to
a local X display on your PC.
To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
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-xauthority} X authority file for local display
+
+\cfg{winhelp-topic}{ssh.tunnels.xauthority}
+
+If you are using X11 forwarding, the local X server to which your
+forwarded connections are eventually directed may itself require
+authorisation.
+
+Some Windows X servers do not require this: they do authorisation by
+simpler means, such as accepting any connection from the local
+machine but not from anywhere else. However, if your X server does
+require authorisation, then PuTTY needs to know what authorisation
+is required.
+
+One way in which this data might be made available is for the X
+server to store it somewhere in a file which has the same format
+as the Unix \c{.Xauthority} file. If this is how your Windows X
+server works, then you can tell PuTTY where to find this file by
+configuring this option. By default, PuTTY will not attempt to find
+any authorisation for your local display.
+
\H{config-ssh-portfwd} \I{port forwarding}The Tunnels panel
\cfg{winhelp-topic}{ssh.tunnels.portfwd}
to a remote destination (\q{Local}) or \I{remote port forwarding}forward
a remote port to a local destination (\q{Remote}). Alternatively,
select \q{Dynamic} if you want PuTTY to \I{dynamic port forwarding}provide
-a local SOCKS 4/4A/5 proxy on a local port.
+a local SOCKS 4/4A/5 proxy on a local port (note that this proxy only
+supports TCP connections; the SSH protocol does not support forwarding
+\i{UDP}).
\b Enter a source \i{port number} into the \q{Source port} box. For
local forwardings, PuTTY will listen on this port of your PC. For
by a colon, in the \q{Destination} box. Connections received on the
source port will be directed to this destination. For example, to
connect to a POP-3 server, you might enter
-\c{popserver.example.com:110}.
+\c{popserver.example.com:110}. (If you need to enter a literal
+\i{IPv6 address}, enclose it in square brackets, for instance
+\cq{[::1]:2200}.)
\b Click the \q{Add} button. Your forwarding details should appear
in the list box.
known to the local system. For instance, in the \q{Destination} box,
you could enter \c{popserver.example.com:pop3}.
-You can modify the currently active set of port forwardings in
-mid-session using \q{Change Settings} (see \k{using-changesettings}).
-If you delete a local or dynamic port forwarding in mid-session, PuTTY
-will stop listening for connections on that port, so it can be re-used
-by another program. If you delete a remote port forwarding, note that:
+You can \I{port forwarding, changing mid-session}modify the currently
+active set of port forwardings in mid-session using \q{Change
+Settings} (see \k{using-changesettings}). If you delete a local or
+dynamic port forwarding in mid-session, PuTTY will stop listening for
+connections on that port, so it can be re-used by another program. If
+you delete a remote port forwarding, note that:
\b The SSH-1 protocol contains no mechanism for asking the server to
stop listening on a remote port.
such as \q{Local ports accept connections from other hosts} only take
effect on new forwardings.
+If the connection you are forwarding over SSH is itself a second SSH
+connection made by another copy of PuTTY, you might find the
+\q{logical host name} configuration option useful to warn PuTTY of
+which host key it should be expecting. See \k{config-loghost} for
+details of this.
+
\S{config-ssh-portfwd-localhost} Controlling the visibility of
forwarded ports
\b for a remote-to-local port forwarding, PuTTY will choose a
sensible protocol for the outgoing connection.
+This overrides the general Internet protocol version preference
+on the Connection panel (see \k{config-address-family}).
+
Note that some operating systems may listen for incoming connections
in IPv4 even if you specifically asked for IPv6, because their IPv4
and IPv6 protocol stacks are linked together. Apparently \i{Linux} does
ticking \q{Auto} should always give you a port which you can connect
to using either protocol.
-\H{config-ssh-bugs} \I{SSH server bugs}The Bugs panel
+\H{config-ssh-bugs} \I{SSH server bugs}The Bugs and More Bugs panels
Not all SSH servers work properly. Various existing servers have
bugs in them, which can make it impossible for a client to talk to
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:
+The Bugs and More Bugs panels (there are two because we have so many
+bug compatibility modes) allow 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.
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 SSH-1, 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}).
+message whenever it receives it. PuTTY uses ignore messages to
+\I{password camouflage}hide the password packet in SSH-1, so that
+a listener cannot tell the length of the user's password; it also
+uses ignore messages for connection \i{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
but keepalives will not work and the session might be more
vulnerable to eavesdroppers than it could be.
-This is an SSH-1-specific bug. No known SSH-2 server fails to deal
-with SSH-2 ignore messages.
-
\S{config-ssh-bug-plainpw1} \q{Refuses all SSH-1 \i{password camouflage}}
\cfg{winhelp-topic}{ssh.bugs.plainpw1}
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
+If this \q{bug} is detected, PuTTY will assume that neither ignore
+messages nor padding are acceptable, and that it thus has 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 SSH-1-specific bug.
+\S{config-ssh-bug-ignore2} \q{Chokes on SSH-2 \i{ignore message}s}
+
+\cfg{winhelp-topic}{ssh.bugs.ignore2}
+
+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 in SSH-2
+to confuse the encrypted data stream and make it harder to
+cryptanalyse. It also uses ignore messages for connection
+\i{keepalives} (see \k{config-keepalive}).
+
+If it believes the server to have this bug, PuTTY will stop using
+ignore messages. 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 less cryptographically secure than it could be.
+
+\S{config-ssh-bug-winadj} \q{Chokes on PuTTY's SSH-2 \cq{winadj} requests}
+
+\cfg{winhelp-topic}{ssh.bugs.winadj}
+
+PuTTY sometimes sends a special request to SSH servers in the middle
+of channel data, with the name \cw{winadj@putty.projects.tartarus.org}
+(see \k{sshnames-channel}). The purpose of this request is to measure
+the round-trip time to the server, which PuTTY uses to tune its flow
+control. The server does not actually have to \e{understand} the
+message; it is expected to send back a \cw{SSH_MSG_CHANNEL_FAILURE}
+message indicating that it didn't understand it. (All PuTTY needs for
+its timing calculations is \e{some} kind of response.)
+
+It has been known for some SSH servers to get confused by this message
+in one way or another \dash because it has a long name, or because
+they can't cope with unrecognised request names even to the extent of
+sending back the correct failure response, or because they handle it
+sensibly but fill up the server's log file with pointless spam, or
+whatever. PuTTY therefore supports this bug-compatibility flag: if it
+believes the server has this bug, it will never send its
+\cq{winadj@putty.projects.tartarus.org} request, and will make do
+without its timing data.
+
\S{config-ssh-bug-hmac2} \q{Miscomputes SSH-2 HMAC keys}
\cfg{winhelp-topic}{ssh.bugs.hmac2}
Versions below 3.3 of \i{OpenSSH} require SSH-2 RSA signatures to be
padded with zero bytes to the same length as the RSA key modulus.
-The SSH-2 draft specification says that an unpadded signature MUST be
+The SSH-2 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.
This is an SSH-2-specific bug.
+\S{config-ssh-bug-maxpkt2} \q{Ignores SSH-2 \i{maximum packet size}}
+
+\cfg{winhelp-topic}{ssh.bugs.maxpkt2}
+
+When an SSH-2 channel is set up, each end announces the maximum size
+of data packet that it is willing to receive for that channel. Some
+servers ignore PuTTY's announcement and send packets larger than PuTTY
+is willing to accept, causing it to report \q{Incoming packet was
+garbled on decryption}.
+
+If this bug is detected, PuTTY never allows the channel's
+\i{flow-control window} to grow large enough to allow the server to
+send an over-sized packet. If this bug is enabled when talking to a
+correct server, the session will work correctly, but download
+performance will be less than it could be.
+
+\S{config-ssh-bug-chanreq} \q{Replies to requests on closed channels}
+
+\cfg{winhelp-topic}{ssh.bugs.chanreq}
+
+The SSH protocol as published in RFC 4254 has an ambiguity which
+arises if one side of a connection tries to close a channel, while the
+other side simultaneously sends a request within the channel and asks
+for a reply. RFC 4254 leaves it unclear whether the closing side
+should reply to the channel request after having announced its
+intention to close the channel.
+
+Discussion on the \cw{ietf-ssh} mailing list in April 2014 formed a
+clear consensus that the right answer is no. However, because of the
+ambiguity in the specification, some SSH servers have implemented the
+other policy; for example,
+\W{https://bugzilla.mindrot.org/show_bug.cgi?id=1818}{OpenSSH used to}
+until it was fixed.
+
+Because PuTTY sends channel requests with the \q{want reply} flag
+throughout channels' lifetime (see \k{config-ssh-bug-winadj}), it's
+possible that when connecting to such a server it might receive a
+reply to a request after it thinks the channel has entirely closed,
+and terminate with an error along the lines of \q{Received
+\cw{SSH2_MSG_CHANNEL_FAILURE} for nonexistent channel 256}.
+
+\S{config-ssh-bug-oldgex2} \q{Only supports pre-RFC4419 SSH-2 DH GEX}
+
+\cfg{winhelp-topic}{ssh.bugs.oldgex2}
+
+The SSH key exchange method that uses Diffie-Hellman group exchange
+was redesigned after its original release, to use a slightly more
+sophisticated setup message. Almost all SSH implementations switched
+over to the new version. (PuTTY was one of the last.) A few old
+servers still only support the old one.
+
+If this bug is detected, and the client and server negotiate
+Diffie-Hellman group exchange, then PuTTY will send the old message
+now known as \cw{SSH2_MSG_KEX_DH_GEX_REQUEST_OLD} in place of the new
+\cw{SSH2_MSG_KEX_DH_GEX_REQUEST}.
+
+This is an SSH-2-specific bug.
+
+\H{config-serial} The Serial panel
+
+The \i{Serial} panel allows you to configure options that only apply
+when PuTTY is connecting to a local \I{serial port}\i{serial line}.
+
+\S{config-serial-line} Selecting a serial line to connect to
+
+\cfg{winhelp-topic}{serial.line}
+
+The \q{Serial line to connect to} box allows you to choose which
+serial line you want PuTTY to talk to, if your computer has more
+than one serial port.
+
+On Windows, the first serial line is called \i\cw{COM1}, and if there
+is a second it is called \cw{COM2}, and so on.
+
+This configuration setting is also visible on the Session panel,
+where it replaces the \q{Host Name} box (see \k{config-hostname}) if
+the connection type is set to \q{Serial}.
+
+\S{config-serial-speed} Selecting the speed of your serial line
+
+\cfg{winhelp-topic}{serial.speed}
+
+The \q{Speed} box allows you to choose the speed (or \q{baud rate})
+at which to talk to the serial line. Typical values might be 9600,
+19200, 38400 or 57600. Which one you need will depend on the device
+at the other end of the serial cable; consult the manual for that
+device if you are in doubt.
+
+This configuration setting is also visible on the Session panel,
+where it replaces the \q{Port} box (see \k{config-hostname}) if the
+connection type is set to \q{Serial}.
+
+\S{config-serial-databits} Selecting the number of data bits
+
+\cfg{winhelp-topic}{serial.databits}
+
+The \q{Data bits} box allows you to choose how many data bits are
+transmitted in each byte sent or received through the serial line.
+Typical values are 7 or 8.
+
+\S{config-serial-stopbits} Selecting the number of stop bits
+
+\cfg{winhelp-topic}{serial.stopbits}
+
+The \q{Stop bits} box allows you to choose how many stop bits are
+used in the serial line protocol. Typical values are 1, 1.5 or 2.
+
+\S{config-serial-parity} Selecting the serial parity checking scheme
+
+\cfg{winhelp-topic}{serial.parity}
+
+The \q{Parity} box allows you to choose what type of parity checking
+is used on the serial line. The settings are:
+
+\b \q{None}: no parity bit is sent at all.
+
+\b \q{Odd}: an extra parity bit is sent alongside each byte, and
+arranged so that the total number of 1 bits is odd.
+
+\b \q{Even}: an extra parity bit is sent alongside each byte, and
+arranged so that the total number of 1 bits is even.
+
+\b \q{Mark}: an extra parity bit is sent alongside each byte, and
+always set to 1.
+
+\b \q{Space}: an extra parity bit is sent alongside each byte, and
+always set to 0.
+
+\S{config-serial-flow} Selecting the serial flow control scheme
+
+\cfg{winhelp-topic}{serial.flow}
+
+The \q{Flow control} box allows you to choose what type of flow
+control checking is used on the serial line. The settings are:
+
+\b \q{None}: no flow control is done. Data may be lost if either
+side attempts to send faster than the serial line permits.
+
+\b \q{XON/XOFF}: flow control is done by sending XON and XOFF
+characters within the data stream.
+
+\b \q{RTS/CTS}: flow control is done using the RTS and CTS wires on
+the serial line.
+
+\b \q{DSR/DTR}: flow control is done using the DSR and DTR wires on
+the serial line.
+
\H{config-file} \ii{Storing configuration in a file}
PuTTY does not currently support storing its configuration in a file
You should replace \c{a:\\putty.rnd} with the location where you
want to store your random number data. If the aim is to carry around
-PuTTY and its settings on one floppy, you probably want to store it
-on the floppy.
+PuTTY and its settings on one USB stick, you probably want to store it
+on the USB stick.
projects / PuTTY.git / blobdiff