\C{config} Configuring PuTTY
-\# Walk the user through the whole config box explaining all the
-\# options.
+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,
+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 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}.
+
+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-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.
+
+\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
+
+\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.
projects / u / mdw / putty / blobdiff