X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/putty/blobdiff_plain/e5b0d077dd2623867702f2e76afb776856eb77b4..486f54de20259904c873cdd0369efcd247f40940:/doc/config.but diff --git a/doc/config.but b/doc/config.but index 6c5d64f6..12ac02bd 100644 --- a/doc/config.but +++ b/doc/config.but @@ -1,4 +1,646 @@ \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, 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.