config.but

putty

\define{versionidconfig} \versionid $Id: config.but 7345 2007-02-28 21:30:06Z jacob $

\C{config} Configuring PuTTY

This chapter describes all the \i{configuration options} in PuTTY.

PuTTY is configured using the control panel that comes up before you
start a session. Some options can also be changed in the middle of a
session, by selecting \q{Change Settings} from the window menu.

\H{config-session} The Session panel

The Session configuration panel contains the basic options you need
to specify in order to open a session at all, and also allows you to
save your settings to be reloaded later.

\S{config-hostname} The \i{host name} section

\cfg{winhelp-topic}{session.hostname}

The top box on the Session panel, labelled \q{Specify your
connection by host name}, contains the details that need to be
filled in before PuTTY can open a session at all.

\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{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, 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}

\cfg{winhelp-topic}{session.saved}

The next part of the Session configuration panel allows you to save
your preferred PuTTY options so they will appear automatically the
next time you start PuTTY. It also allows you to create \e{saved
sessions}, which contain a full set of configuration options plus a
host name and protocol. A saved session contains all the information
PuTTY needs to start exactly the session you want.

\b To save your default settings: first set up the settings the way
you want them saved. Then come back to the Session panel. Select the
\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.

\b To save a session: first go through the rest of the configuration
box setting up all the options you want. Then come back to the
Session panel. Enter a name for the saved session in the \q{Saved
Sessions} input box. (The server name is often a good choice for a
saved session name.) Then press the \q{Save} button. Your saved
session name should now appear in the list box.

\lcont{
You can also save settings in mid-session, from the \q{Change Settings}
dialog. Settings changed since the start of the session will be saved
with their current values; as well as settings changed through the
dialog, this includes changes in window size, window title changes
sent by the server, and so on.
}

\b To reload a saved session: single-click to select the session
name in the list box, and then press the \q{Load} button. Your saved
settings should all appear in the configuration panel.

\b To modify a saved session: first load it as described above. Then
make the changes you want. Come back to the Session panel, and press
the \q{Save} button. The new settings will be saved over the top of
the old ones.

\lcont{
To save the new settings under a different name, you can enter the new
name in the \q{Saved Sessions} box, or single-click to select a
session name in the list box to overwrite that session. To save
\q{Default Settings}, you must single-click the name before saving.
}

\b To start a saved session immediately: double-click on the session
name in the list box.

\b To delete a saved session: single-click to select the session
name in the list box, and then press the \q{Delete} button.

Each saved session is independent of the Default Settings
configuration. If you change your preferences and update Default
Settings, you must also update every saved session separately.

Saved sessions are stored in the \i{Registry}, at the location

\c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\Sessions

If you need to store them in a file, you could try the method
described in \k{config-file}.

\S{config-closeonexit} \q{\ii{Close Window} on Exit}

\cfg{winhelp-topic}{session.coe}

Finally in the Session panel, there is an option labelled \q{Close
Window on Exit}. This controls whether the PuTTY \i{terminal window}
disappears as soon as the session inside it terminates. If you are
likely to want to copy and paste text out of the session after it
has terminated, or restart the session, you should arrange for this
option to be off.

\q{Close Window On Exit} has three settings. \q{Always} means always
close the window on exit; \q{Never} means never close on exit
(always leave the window open, but \I{inactive window}inactive). The
third setting, and the default one, is \q{Only on clean exit}. In this
mode, a session which terminates normally will cause its window to
close, but one which is aborted unexpectedly by network trouble or a
confusing message from the server will leave the window up.

\H{config-logging} The Logging panel

\cfg{winhelp-topic}{logging.main}

The Logging configuration panel allows you to save \i{log file}s of your
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:

\b \q{None}. This is the default option; in this mode PuTTY will not
create a log file at all.

\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{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
you are experiencing problems with PuTTY's terminal handling: you
can record everything that went to the terminal, so that someone
else can replay the session later in slow motion and watch to see
what went wrong.

\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}

\cfg{winhelp-topic}{logging.filename}

In this edit box you enter the name of the file you want to log the
session to. The \q{Browse} button will let you look around your file
system to find the right place to put the file; or if you already
know exactly where you want it to go, you can just type a pathname
into the edit box.

There are a few special features in this box. If you use the \c{&}
character in the file name box, PuTTY will insert details of the
current session in the name of the file it actually opens. The
precise replacements it will do are:

\b \c{&Y} will be replaced by the current year, as four digits.

\b \c{&M} will be replaced by the current month, as two digits.

\b \c{&D} will be replaced by the current day of the month, as two
digits.

\b \c{&T} will be replaced by the current time, as six digits
(HHMMSS) with no punctuation.

\b \c{&H} will be replaced by the host name you are connecting to.

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

\c log-server1.example.com-20010528-110859.dat
\c log-unixbox.somewhere.org-20010611-221001.dat

\S{config-logfileexists} \q{What to do if the log file already exists}

\cfg{winhelp-topic}{logging.exists}

This control allows you to specify what PuTTY should do if it tries
to start writing to a log file and it finds the file already exists.
You might want to automatically destroy the existing log file and
start a new one with the same name. Alternatively, you might want to
open the existing log file and add data to the \e{end} of it.
Finally (the default option), you might not want to have any
automatic behaviour, but to ask the user every time the problem
comes up.

\S{config-logflush} \I{log file, flushing}\q{Flush log file frequently}

\cfg{winhelp-topic}{logging.flush}

This option allows you to control how frequently logged data is
flushed to disc. By default, PuTTY will flush data as soon as it is
displayed, so that if you view the log file while a session is still
open, it will be up to date; and if the client system crashes, there's
a greater chance that the data will be preserved.

However, this can incur a performance penalty. If PuTTY is running
slowly with logging enabled, you could try unchecking this option. Be
warned that the log file may not always be up to date as a result
(although it will of course be flushed when it is closed, for instance
at the end of a session).

\S{config-logssh} Options specific to \i{SSH packet log}ging

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, 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
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 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.

\H{config-terminal} The Terminal panel

The Terminal configuration panel allows you to control the behaviour
of PuTTY's \i{terminal emulation}.

\S{config-autowrap} \q{Auto wrap mode initially on}

\cfg{winhelp-topic}{terminal.autowrap}

\ii{Auto wrap mode} controls what happens when text printed in a PuTTY
window reaches the right-hand edge of the window.