Oops - that tweak had bad Buttress syntax. D'oh!

[u/mdw/putty] / doc / config.but

\C{config} Configuring PuTTY

This chapter describes all the 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 \e{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 host name section

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 \e{Host Name} box is where you type the name, or the IP
address, of the server you want to connect to.

\b The \e{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. \#{ FIXME: link to sections on
these? }

\b The \e{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, you
will almost certainly need to fill in the \e{Port} box.

\S{config-saving} Loading and storing saved sessions

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{Default Settings} entry in the saved sessions list, with a single
click. Then press the \e{Save} button.

\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 \e{Saved
Sessions} input box. (The server name is often a good choice for a
saved session name.) Then press the \e{Save} button. Your saved
session name should now appear in the list box.

\b To reload a saved session: single-click to select the session
name in the list box, and then press the \e{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,
single-click to select the session name in the list box, and press
the \e{Save} button. The new settings will be saved over the top of
the old ones.

\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 \e{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.

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

Finally in the Session panel, there is a check box labelled \q{Close
Window on Exit}. If this is turned on, the PuTTY session window will
disappear as soon as the session inside it terminates. Otherwise,
the window will remain on the desktop until you close it yourself,
so you can still read and copy text out of it.

\H{config-terminal} The Terminal panel

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

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

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

With auto wrap mode on, if a long line of text reaches the
right-hand edge, it will wrap over on to the next line so you can
still see all the text. With auto wrap mode off, the cursor will
stay at the right-hand edge of the screen, and all the characters in
the line will be printed on top of each other.

If you are running a full-screen application and you occasionally
find the screen scrolling up when it looks as if it shouldn't, you
could try turning this option off.

Auto wrap mode can be turned on and off by control sequences sent by
the server. This configuration option only controls the \e{default}
state. If you modify this option in mid-session using \e{Change
Settings}, you will need to reset the terminal \#{ FIXME } before
the change takes effect.

\S{config-decom} \q{DEC Origin Mode initially on}

DEC Origin Mode is a minor option which controls how PuTTY
interprets cursor-position control sequences sent by the server.

The server can send a control sequence that restricts the scrolling
region of the display. For example, in an editor, the server might
reserve a line at the top of the screen and a line at the bottom,
and might send a control sequence that causes scrolling operations
to affect only the remaining lines.

With DEC Origin Mode on, cursor coordinates are counted from the top
of the scrolling region. With it turned off, cursor coordinates are
counted from the top of the whole screen regardless of the scrolling
region.

It is unlikely you would need to change this option, but if you find
a full-screen application is displaying pieces of text in what looks
like the wrong part of the screen, you could try turning DEC Origin
Mode on to see whether that helps.

DEC Origin Mode can be turned on and off by control sequences sent by
the server. This configuration option only controls the \e{default}
state. If you modify this option in mid-session using \e{Change
Settings}, you will need to reset the terminal \#{ FIXME } before
the change takes effect.

\S{config-crlf} \q{Implicit CR in every LF}

Most servers send two control characters, CR and LF, to start a 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 LF, and expect the terminal to move the
cursor over to the left automatically. If you come across a server
that does this, you will see a stepped effect on the screen, like
this:

\c First line of text
\c                   Second line
\c                              Third line

If this happens to you, try enabling the \q{Implicit CR in every LF}
option, and things might go back to normal:

\c First line of text
\c Second line
\c Third line

\S{config-beep} \q{Beep enabled}

This option lets you turn off beeps in PuTTY. If your server is
beeping too much or attracting unwelcome attention, you can turn the
beeps off.

\S{config-erase} \q{Use background colour to erase screen}

Not all terminals agree on what colour to turn the screen when the
server sends a \q{clear screen} sequence. Some terminals believe the
screen should always be cleared to the \e{default} background
colour. Others believe the screen should be cleared to whatever the
server has selected as a background colour.

There exist applications that expect both kinds of behaviour.
Therefore, PuTTY can be configured to do either.

With this option disabled, screen clearing is always done in the
default background colour. With this option enabled, it is done in
the \e{current} background colour.

\S{config-blink} \q{Enable blinking text}

The server can ask PuTTY to display text that blinks on and off.
This is very distracting, so PuTTY allows you to turn blinking text
off completely.

\S{config-localterm} \q{Use local terminal line discipline}

Normally, every character you type into the PuTTY window is sent
straight to the server.

If you enable local terminal line discipline, this changes. PuTTY
will let you edit a whole line at a time locally, and the line will
only be sent to the server when you press Return. If you make a
mistake, you can use the Backspace key to correct it before you
press Return, and the server will never see the mistake.

Since it would be hard to edit a line locally without being able to
see it, local terminal line discipline also makes PuTTY echo what
you type. This makes it ideal for use in raw mode \#{ FIXME } or
when connecting to MUDs or talkers.

\S{config-logging} Controlling session logging

PuTTY has the ability to log the output from your session into a
file. You might want this if you were saving a particular piece of
output to mail to somebody, for example in a bug report.

You can choose between:

\b not logging anything (the default)

\b logging only the printable characters in a session (ignoring
control sequences to change colours or clear the screen)

\b logging everything sent to the terminal by the server.

You can turn logging on and off in mid-session using \e{Change
Settings}.

\H{config-keyboard} The Keyboard panel

The Keyboard configuration panel allows you to control the behaviour
of the keyboard in PuTTY.

\S{config-backspace} Changing the action of the Backspace key

Some terminals believe that the Backspace key should send the same
thing to the server as Control-H (ASCII code 8). Other terminals
believe that the Backspace key should send ASCII code 127 (usually
known as Control-?) so that it can be distinguished from Control-H.
This option allows you to choose which code PuTTY generates when you
press Backspace.

If you are connecting to a Unix system, you will probably find that
the Unix \c{stty} command lets you configure which the server
expects to see, so you might not need to change which one PuTTY
generates. On other systems, the server's expectation might be fixed
and you might have no choice but to configure PuTTY.

If you do have the choice, we recommend configuring PuTTY to
generate Control-? and configuring the server to expect it, because
that allows applications such as \c{emacs} to use Control-H for
help.

\S{config-homeend} Changing the action of the Home and End keys

The Unix terminal emulator \c{rxvt} disagrees with the rest of the
world about what character sequences should be sent to the server by
the Home and End keys.

\c{xterm}, and other terminals, send \c{ESC [1~} for the Home key,
and \c{ESC [4~} for the End key. \c{rxvt} sends \c{ESC [H} for the
Home key and \c{ESC [Ow} for the End key.

If you find an application on which the Home and End keys aren't
working, you could try switching this option to see if it helps.

\S{config-funkeys} Changing the action of the function keys and keypad

This option affects the function keys (F1 to F12) and the top row of
the numeric keypad.

\b In the default mode, labelled \c{ESC [n~}, the function keys
generate sequences like \c{ESC [11~}, \c{ESC [12~} and so on. This
matches the general behaviour of Digital's terminals.

\b In Linux mode, F6 to F12 behave just like the default mode, but
F1 to F5 generate \c{ESC [[A} through to \c{ESC [[E}. This mimics the
Linux virtual console.

\b In Xterm R6 mode, F5 to F12 behave like the default mode, but F1
to F4 generate \c{ESC OP} through to \c{ESC OS}, which are the
sequences produced by the top row of the \e{keypad} on Digital's
terminals.

\b In VT400 mode, all the function keys behave like the default
mode, but the actual top row of the numeric keypad generates \c{ESC
OP} through to \c{ESC OS}.

\b In VT100+ mode, the function keys generate \c{ESC OP} through to
\c{ESC O[}

\b In SCO mode, the function keys F1 to F12 generate \c{ESC [M}
through to \c{ESC [X}.  Together with shift, they generate \c{ESC [Y}
through to \c{ESC [j}.  With control they generate \c{ESC [k} through
to \c{ESC [v}, and with shift and control together they generate
\c{ESC [w} through to \c{ESC [\{}.

If you don't know what any of this means, you probably don't need to
fiddle with it.

\S{config-appcursor} Controlling Application Cursor Keys mode

Application Cursor Keys mode is a way for the server to change the
control sequences sent by the arrow keys. In normal mode, the arrow
keys send \c{ESC [A} through to \c{ESC [D}. In application mode,
they send \c{ESC OA} through to \c{ESC OD}.

Application Cursor Keys mode can be turned on and off by the server,
depending on the application. PuTTY allows you to configure the
initial state, and also allows you to disable application mode
completely.

\S{config-appkeypad} Controlling Application Keypad mode

Application Keypad mode is a way for the server to change the
behaviour of the numeric keypad.

In normal mode, the keypad behaves like a normal Windows keypad:
with NumLock on, the number keys generate numbers, and with NumLock
off they act like the arrow keys and Home, End etc.

In application mode, all the keypad keys send special control
sequences, \e{including} Num Lock. Num Lock stops behaving like Num
Lock and becomes another function key.

Depending on which version of Windows you run, you may find the Num
Lock light still flashes on and off every time you press Num Lock,
even when application mode is active and Num Lock is acting like a
function key. This is unavoidable.

Application keypad mode can be turned on and off by the server,
depending on the application. PuTTY allows you to configure the
initial state, and also allows you to disable application mode
completely.

\S{config-nethack} Using NetHack keypad mode

PuTTY has a special mode for playing NetHack. You can enable it by
selecting \q{NetHack} in the \q{Initial state of numeric keypad}
control.

In this mode, the numeric keypad keys 1-9 generate the NetHack
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.

For some reason, this feature only works properly when Num Lock is
on. We don't know why.

\S{config-compose} Enabling a DEC-like Compose key

DEC terminals have a Compose key, which provides an easy-to-remember
way of typing accented characters. You press Compose and then type
two more characters. The two characters are \q{combined} to produce
an accented character. The choices of character are designed to be
easy to remember; for example, composing \q{e} and \q{`} produces
the \q{\u00e8{e-grave}} character.

If you enable the \q{Application and AltGr act as Compose key}
option, the Windows Application key and the AltGr key will both have
this behaviour.

\H{config-bell} The Bell panel

The Bell configuration panel allows you to control how PuTTY should
respond to a terminal bell.

\S{config-bellstyle} Set the style of bell

When a terminal bell occurs, PuTTY can do one of the following things:

\b Nothing.  The bell is disabled.  Taskbar bell indication still
works, however.

\b Play Windows Default Sound.  The Windows Default Sound (which can
be configured from the Sounds control panel) will be played.

\b Play a custom sound file.  Select a \c{.wav} sound file using the
\e{Custom sound file to play as a bell} text box, or browse for the
file to play using the \e{Browse...} button.

\b Flash the terminal window as a visual bell.  No sound will be
played.

In addition, the PuTTY window's title bar and its entry in the taskbar
can be configured to flash or invert to indicate that a terminal bell
has occurred.

\S{config-belloverload} Control the bell overload behaviour

Sometimes mistakes, for example trying to \c{cat} a binary file on a
Unix machine, can lead to a large number of terminal bells being
received by PuTTY.  It might take a long time for PuTTY to catch up
with reacting to these bells, and the noise or flashing could be very
irritating for the user.

PuTTY's bell overload handling is designed to avoid this problem.  If
turned on using the \e{Bell is temporarily disabled when over-used}
tick box, the bell will be disabled if it occurs more than a specified 
number of times in a specified number of seconds.  When no bells have
occurred for a number of seconds, PuTTY re-enables the bell.

\H{config-window} The Window panel

The Window configuration panel allows you to control aspects of the
PuTTY window and its behaviour.

\S{config-winsize} Setting the size of the PuTTY window

The \e{Rows} and \e{Columns} boxes let you set the PuTTY window to a
precise size. Of course you can also drag the window to a new size
while a session is running.

If you are running an application which is unable to deal with
changes in window size, you might want to enable the \q{Lock window
size against resizing} option, which prevents the user from
accidentally changing the size of the window.

\S{config-scrollback} Controlling scrollback

Text that scrolls off the top of the PuTTY terminal window is kept
for reference. The scrollbar on the right of the window lets you
view the scrolled-off text. You can also page through the scrollback
using the keyboard, by pressing Shift-PgUp and Shift-PgDn.

The \q{Lines of scrollback} box lets you configure how many lines of
text PuTTY keeps. The \q{Display scrollbar} option allows you to
hide the scrollbar (although you can still view the scrollback using
Shift-PgUp and Shift-PgDn).

If you are viewing part of the scrollback when the server sends more
text to PuTTY, the screen will revert to showing the current
terminal contents. You can disable this behaviour by turning off
\q{Reset scrollback on display activity}. You can also make the
screen revert when you press a key, by turning on \q{Reset
scrollback on keypress}.

\S{config-warnonclose} \q{Warn before closing window}

If you press the Close button in a PuTTY window that contains a
running session, PuTTY will put up a warning window asking if you
really meant to close the window. A window whose session has already
terminated can always be closed without a warning.

If you want to be able to close a window quickly, you can disable
the \q{Warn before closing window} option.

\S{config-altf4} \q{Window closes on ALT-F4}

By default, pressing ALT-F4 causes the window to close (or a warning
box to appear; see \k{config-warnonclose}). If you disable the
\q{Window closes on ALT-F4} option, then pressing ALT-F4 will simply
send a key sequence to the server.

\S{config-altspace} \q{System menu appears on ALT-Space}

If this option is enabled, then pressing ALT-Space will bring up the
PuTTY window's menu, like clicking on the top left corner. If it is
disabled, then pressing ALT-Space will just send \c{ESC SPACE} to
the server.

Some accessibility programs for Windows may need this option
enabling to be able to control PuTTY's window successfully. For
instance, Dragon NaturallySpeaking requires it both to open the
system menu via voice, and to close, minimise, maximise and restore
the window.

\S{config-altonly} \q{System menu appears on Alt alone}

If this option is enabled, then pressing and releasing ALT will
bring up the PuTTY window's menu, like clicking on the top left
corner. If it is disabled, then pressing and releasing ALT will have
no effect.

\S{config-alwaysontop} \q{Ensure window is always on top}

If this option is enabled, the PuTTY window will stay on top of all
other windows.

\H{config-appearance} The Appearance panel

The Appearance configuration panel allows you to control aspects of
PuTTY's appearance.

\S{config-cursor} Controlling the appearance of the cursor

The \q{Cursor appearance} option lets you configure the cursor to be
a block, an underline, or a vertical line. A block cursor becomes an
empty box when the window loses focus; an underline or a vertical
line becomes dotted.

The \q{Cursor blinks} option makes the cursor blink on and off. This
works in any of the cursor modes.

\S{config-font} Controlling the font used in the terminal window



\S{config-title} Controlling the window title

\H{config-translation} The Translation panel

The Translation configuration panel allows you to control the
translation between the character set understood by the server and
the character set understood by PuTTY.

\S{config-linedraw} Line drawing characters

\S{config-outputtrans} Character set translation of output data

\S{config-inputtrans} Character set translation of input data

\H{config-selection} The Selection panel

The Selection panel allows you to control the way copy and paste
work in the PuTTY window.

\S{config-mouse} Changing the actions of the mouse buttons

\S{config-charclasses} Configuring word-by-word selection

\H{config-colours} The Colours panel

The Colours panel allows you to control PuTTY's use of colour.

\S{config-boldcolour} \q{Bolded text is a different colour}

\S{config-logpalette} \q{Attempt to use logical palettes}

\S{config-colourcfg} Adjusting the colours in the terminal window

\H{config-connection} The Connection panel

The Connection panel allows you to configure options that apply to
more than one type of connection.

\S{config-termtype} \q{Terminal-type string}

\S{config-username} \q{Auto-login username}

\S{config-keepalive} Using keepalives to prevent disconnection

If you find your sessions are closing unexpectedly (\q{Connection
reset by peer}) after they have been idle for a while, you might
want to try using this option.

Some network routers and firewalls need keep track of all
connections through them. Usually, these firewalls will assume a
connection is dead if no data is transferred in either direction
after a certain time interval. This can cause PuTTY sessions to be
unexpectedly closed by the firewall if no traffic is seen in the
session for some time.

The keepalive option (\q{Seconds between keepalives}) allows you to
configure PuTTY to send data through the session at regular
intervals, in a way that does not disrupt the actual terminal
session. If you find your firewall is cutting idle connections off,
you can try entering a non-zero value in this field. The value is
measured in seconds; so, for example, if your firewall cuts
connections off after ten minutes then you might want to enter 300
seconds (5 minutes) in the box.

Note that keepalives are not always helpful. They help if you have a
firewall which drops your connection after an idle period; but if
the network between you and the server suffers from breaks in
connectivity then keepalives can actually make things worse. If a
session is idle, and connectivity is temporarily lost between the
endpoints, but the connectivity is restored before either side tries
to send anything, then there will be no problem - neither endpoint
will notice that anything was wrong. However, if one side does send
something during the break, it will repeatedly try to re-send, and
eventually give up and abandon the connection. Then when
connectivity is restored, the other side will find that the first
side doesn't believe there is an open connection any more.
Keepalives can make this sort of problem worse, because they
increase the probability that PuTTY will attempt to send data during
a break in connectivity. Therefore, you might find they help
connection loss, or you might find they make it worse, depending on
what \e{kind} of network problems you have between you and the
server.

Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
protocols offer no way of implementing them.

\H{config-telnet} The Telnet panel

The Telnet panel allows you to configure options that only apply to
Telnet sessions.

\S{config-termspeed} \q{Terminal-speed string}

\S{config-environ} Setting environment variables on the server

\S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity}

\H{config-ssh} The SSH panel

The SSH panel allows you to configure options that only apply to
SSH sessions.

\S{config-command} Executing a specific command on the server

\S{config-auth} SSH authentication options

\S{config-protocol} SSH protocol options

\H{config-file} Storing configuration in a file

PuTTY does not currently support storing its configuration in a file
instead of the Registry. However, you can work around this with a
couple of batch files.

You will need a file called (say) \c{PUTTY.BAT} which imports the
contents of a file into the Registry, then runs PuTTY, exports the
contents of the Registry back into the file, and deletes the
Registry entries. This can all be done using the Regedit command
line options, so it's all automatic. Here is what you need in
\c{PUTTY.BAT}:

\c @ECHO OFF
\c regedit /s putty.reg
\c regedit /s puttyrnd.reg
\c start /w putty.exe
\c regedit /e puttynew.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
\c copy puttynew.reg putty.reg
\c del puttynew.reg
\c regedit /s puttydel.reg

This batch file needs two auxiliary files: \c{PUTTYRND.REG} which
sets up an initial safe location for the \c{PUTTY.RND} random seed
file, and \c{PUTTYDEL.REG} which destroys everything in the Registry
once it's been successfully saved back to the file.

Here is \c{PUTTYDEL.REG}:

\c REGEDIT4
\c  
\c [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]

Here is an example \c{PUTTYRND.REG} file:

\c REGEDIT4
\c  
\c [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
\c "RandSeedFile"="a:\putty.rnd"

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.