| 1 | \C{config} Configuring PuTTY |
| 2 | |
| 3 | This chapter describes all the configuration options in PuTTY. |
| 4 | |
| 5 | PuTTY is configured using the control panel that comes up before you |
| 6 | start a session. Some options can also be changed in the middle of a |
| 7 | session, by selecting \e{Change Settings} from the window menu. |
| 8 | |
| 9 | \H{config-session} The Session panel |
| 10 | |
| 11 | The Session configuration panel contains the basic options you need |
| 12 | to specify in order to open a session at all, and also allows you to |
| 13 | save your settings to be reloaded later. |
| 14 | |
| 15 | \S{config-hostname} The host name section |
| 16 | |
| 17 | The top box on the Session panel, labelled \q{Specify your |
| 18 | connection by host name}, contains the details that need to be |
| 19 | filled in before PuTTY can open a session at all. |
| 20 | |
| 21 | \b The \e{Host Name} box is where you type the name, or the IP |
| 22 | address, of the server you want to connect to. |
| 23 | |
| 24 | \b The \e{Protocol} radio buttons let you choose what type of |
| 25 | connection you want to make: a raw connection, a Telnet connection, |
| 26 | or an SSH connection. \#{ FIXME: link to sections on these? } |
| 27 | |
| 28 | \b The \e{Port} box lets you specify which port number on the server |
| 29 | to connect to. If you select Telnet or SSH, this box will be filled |
| 30 | in automatically to the usual value, and you will only need to |
| 31 | change it if you have an unusual server. If you select Raw mode, you |
| 32 | will almost certainly need to fill in the \e{Port} box. |
| 33 | |
| 34 | \S{config-saving} Loading and storing saved sessions |
| 35 | |
| 36 | The next part of the Session configuration panel allows you to save |
| 37 | your preferred PuTTY options so they will appear automatically the |
| 38 | next time you start PuTTY. It also allows you to create \e{saved |
| 39 | sessions}, which contain a full set of configuration options plus a |
| 40 | host name and protocol. A saved session contains all the information |
| 41 | PuTTY needs to start exactly the session you want. |
| 42 | |
| 43 | \b To save your default settings: first set up the settings the way |
| 44 | you want them saved. Then come back to the Session panel. Select the |
| 45 | \q{Default Settings} entry in the saved sessions list, with a single |
| 46 | click. Then press the \e{Save} button. |
| 47 | |
| 48 | \b To save a session: first go through the rest of the configuration |
| 49 | box setting up all the options you want. Then come back to the |
| 50 | Session panel. Enter a name for the saved session in the \e{Saved |
| 51 | Sessions} input box. (The server name is often a good choice for a |
| 52 | saved session name.) Then press the \e{Save} button. Your saved |
| 53 | session name should now appear in the list box. |
| 54 | |
| 55 | \b To reload a saved session: single-click to select the session |
| 56 | name in the list box, and then press the \e{Load} button. Your saved |
| 57 | settings should all appear in the configuration panel. |
| 58 | |
| 59 | \b To modify a saved session: first load it as described above. Then |
| 60 | make the changes you want. Come back to the Session panel, |
| 61 | single-click to select the session name in the list box, and press |
| 62 | the \e{Save} button. The new settings will be saved over the top of |
| 63 | the old ones. |
| 64 | |
| 65 | \b To start a saved session immediately: double-click on the session |
| 66 | name in the list box. |
| 67 | |
| 68 | \b To delete a saved session: single-click to select the session |
| 69 | name in the list box, and then press the \e{Delete} button. |
| 70 | |
| 71 | Each saved session is independent of the Default Settings |
| 72 | configuration. If you change your preferences and update Default |
| 73 | Settings, you must also update every saved session separately. |
| 74 | |
| 75 | \S{config-closeonexit} \q{Close Window on Exit} |
| 76 | |
| 77 | Finally in the Session panel, there is a check box labelled \q{Close |
| 78 | Window on Exit}. If this is turned on, the PuTTY session window will |
| 79 | disappear as soon as the session inside it terminates. Otherwise, |
| 80 | the window will remain on the desktop until you close it yourself, |
| 81 | so you can still read and copy text out of it. |
| 82 | |
| 83 | \H{config-terminal} The Terminal panel |
| 84 | |
| 85 | The Terminal configuration panel allows you to control the behaviour |
| 86 | of PuTTY's terminal emulation. |
| 87 | |
| 88 | \S{config-autowrap} \q{Auto wrap mode initially on} |
| 89 | |
| 90 | Auto wrap mode controls what happens when text printed in a PuTTY |
| 91 | window reaches the right-hand edge of the window. |
| 92 | |
| 93 | With auto wrap mode on, if a long line of text reaches the |
| 94 | right-hand edge, it will wrap over on to the next line so you can |
| 95 | still see all the text. With auto wrap mode off, the cursor will |
| 96 | stay at the right-hand edge of the screen, and all the characters in |
| 97 | the line will be printed on top of each other. |
| 98 | |
| 99 | If you are running a full-screen application and you occasionally |
| 100 | find the screen scrolling up when it looks as if it shouldn't, you |
| 101 | could try turning this option off. |
| 102 | |
| 103 | Auto wrap mode can be turned on and off by control sequences sent by |
| 104 | the server. This configuration option only controls the \e{default} |
| 105 | state. If you modify this option in mid-session using \e{Change |
| 106 | Settings}, you will need to reset the terminal \#{ FIXME } before |
| 107 | the change takes effect. |
| 108 | |
| 109 | \S{config-decom} \q{DEC Origin Mode initially on} |
| 110 | |
| 111 | DEC Origin Mode is a minor option which controls how PuTTY |
| 112 | interprets cursor-position control sequences sent by the server. |
| 113 | |
| 114 | The server can send a control sequence that restricts the scrolling |
| 115 | region of the display. For example, in an editor, the server might |
| 116 | reserve a line at the top of the screen and a line at the bottom, |
| 117 | and might send a control sequence that causes scrolling operations |
| 118 | to affect only the remaining lines. |
| 119 | |
| 120 | With DEC Origin Mode on, cursor coordinates are counted from the top |
| 121 | of the scrolling region. With it turned off, cursor coordinates are |
| 122 | counted from the top of the whole screen regardless of the scrolling |
| 123 | region. |
| 124 | |
| 125 | It is unlikely you would need to change this option, but if you find |
| 126 | a full-screen application is displaying pieces of text in what looks |
| 127 | like the wrong part of the screen, you could try turning DEC Origin |
| 128 | Mode on to see whether that helps. |
| 129 | |
| 130 | DEC Origin Mode can be turned on and off by control sequences sent by |
| 131 | the server. This configuration option only controls the \e{default} |
| 132 | state. If you modify this option in mid-session using \e{Change |
| 133 | Settings}, you will need to reset the terminal \#{ FIXME } before |
| 134 | the change takes effect. |
| 135 | |
| 136 | \S{config-crlf} \q{Implicit CR in every LF} |
| 137 | |
| 138 | Most servers send two control characters, CR and LF, to start a new |
| 139 | line of the screen. The CR character makes the cursor return to the |
| 140 | left-hand side of the screen. The LF character makes the cursor move |
| 141 | one line down (and might make the screen scroll). |
| 142 | |
| 143 | Some servers only send LF, and expect the terminal to move the |
| 144 | cursor over to the left automatically. If you come across a server |
| 145 | that does this, you will see a stepped effect on the screen, like |
| 146 | this: |
| 147 | |
| 148 | \c First line of text |
| 149 | \c Second line |
| 150 | \c Third line |
| 151 | |
| 152 | If this happens to you, try enabling the \q{Implicit CR in every LF} |
| 153 | option, and things might go back to normal: |
| 154 | |
| 155 | \c First line of text |
| 156 | \c Second line |
| 157 | \c Third line |
| 158 | |
| 159 | \S{config-beep} \q{Beep enabled} |
| 160 | |
| 161 | This option lets you turn off beeps in PuTTY. If your server is |
| 162 | beeping too much or attracting unwelcome attention, you can turn the |
| 163 | beeps off. |
| 164 | |
| 165 | \S{config-erase} \q{Use background colour to erase screen} |
| 166 | |
| 167 | Not all terminals agree on what colour to turn the screen when the |
| 168 | server sends a \q{clear screen} sequence. Some terminals believe the |
| 169 | screen should always be cleared to the \e{default} background |
| 170 | colour. Others believe the screen should be cleared to whatever the |
| 171 | server has selected as a background colour. |
| 172 | |
| 173 | There exist applications that expect both kinds of behaviour. |
| 174 | Therefore, PuTTY can be configured to do either. |
| 175 | |
| 176 | With this option disabled, screen clearing is always done in the |
| 177 | default background colour. With this option enabled, it is done in |
| 178 | the \e{current} background colour. |
| 179 | |
| 180 | \S{config-blink} \q{Enable blinking text} |
| 181 | |
| 182 | The server can ask PuTTY to display text that blinks on and off. |
| 183 | This is very distracting, so PuTTY allows you to turn blinking text |
| 184 | off completely. |
| 185 | |
| 186 | \S{config-localterm} \q{Use local terminal line discipline} |
| 187 | |
| 188 | Normally, every character you type into the PuTTY window is sent |
| 189 | straight to the server. |
| 190 | |
| 191 | If you enable local terminal line discipline, this changes. PuTTY |
| 192 | will let you edit a whole line at a time locally, and the line will |
| 193 | only be sent to the server when you press Return. If you make a |
| 194 | mistake, you can use the Backspace key to correct it before you |
| 195 | press Return, and the server will never see the mistake. |
| 196 | |
| 197 | Since it would be hard to edit a line locally without being able to |
| 198 | see it, local terminal line discipline also makes PuTTY echo what |
| 199 | you type. This makes it ideal for use in raw mode \#{ FIXME } or |
| 200 | when connecting to MUDs or talkers. |
| 201 | |
| 202 | \S{config-logging} Controlling session logging |
| 203 | |
| 204 | PuTTY has the ability to log the output from your session into a |
| 205 | file. You might want this if you were saving a particular piece of |
| 206 | output to mail to somebody, for example in a bug report. |
| 207 | |
| 208 | You can choose between: |
| 209 | |
| 210 | \b not logging anything (the default) |
| 211 | |
| 212 | \b logging only the printable characters in a session (ignoring |
| 213 | control sequences to change colours or clear the screen) |
| 214 | |
| 215 | \b logging everything sent to the terminal by the server. |
| 216 | |
| 217 | You can turn logging on and off in mid-session using \e{Change |
| 218 | Settings}. |
| 219 | |
| 220 | \H{config-keyboard} The Keyboard panel |
| 221 | |
| 222 | \S{config-backspace} Changing the action of the Backspace key |
| 223 | |
| 224 | \S{config-homeend} Changing the action of the Home and End keys |
| 225 | |
| 226 | \S{config-funkeys} Changing the action of the function keys and keypad |
| 227 | |
| 228 | \S{config-appcursor} Controlling Application Cursor Keys mode |
| 229 | |
| 230 | \S{config-appkeypad} Controlling Application Keypad mode |
| 231 | |
| 232 | \S{config-nethack} Using NetHack keypad mode |
| 233 | |
| 234 | \S{config-compose} Enabling a DEC-like Compose key |
| 235 | |
| 236 | \H{config-window} The Window panel |
| 237 | |
| 238 | \S{config-winsize} Setting the size of the PuTTY window |
| 239 | |
| 240 | \S{config-scrollback} Controlling scrollback |
| 241 | |
| 242 | \S{config-warnonclose} \q{Warn before closing window} |
| 243 | |
| 244 | \S{config-altf4} \q{Window closes on ALT-F4} |
| 245 | |
| 246 | \S{config-altspace} \q{System menu appears on ALT-Space} |
| 247 | |
| 248 | \S{config-altonly} \q{System menu appears on Alt alone} |
| 249 | |
| 250 | \S{config-alwaysontop} \q{Ensure window is always on top} |
| 251 | |
| 252 | \H{config-appearance} The Appearance panel |
| 253 | |
| 254 | \S{config-cursor} Controlling the appearance of the cursor |
| 255 | |
| 256 | \# this will look considerably less silly when we bring in |
| 257 | \# underline-versus-block-versus-vertical-line cursor configuration |
| 258 | \# and also allow the cursor to vanish on keypress a la Word. Until |
| 259 | \# then, this box does look silly with only one thing in it. Deal. |
| 260 | |
| 261 | \S{config-font} Controlling the font used in the terminal window |
| 262 | |
| 263 | \S{config-title} Controlling the window title |
| 264 | |
| 265 | \H{config-translation} The Translation panel |
| 266 | |
| 267 | \S{config-linedraw} Line drawing characters |
| 268 | |
| 269 | \S{config-outputtrans} Character set translation of output data |
| 270 | |
| 271 | \S{config-inputtrans} Character set translation of input data |
| 272 | |
| 273 | \H{config-selection} The Selection panel |
| 274 | |
| 275 | \S{config-mouse} Changing the actions of the mouse buttons |
| 276 | |
| 277 | \S{config-charclasses} Configuring word-by-word selection |
| 278 | |
| 279 | \H{config-colours} The Colours panel |
| 280 | |
| 281 | \S{config-boldcolour} \q{Bolded text is a different colour} |
| 282 | |
| 283 | \S{config-logpalette} \q{Attempt to use logical palettes} |
| 284 | |
| 285 | \S{config-colourcfg} Adjusting the colours in the terminal window |
| 286 | |
| 287 | \H{config-connection} The Connection panel |
| 288 | |
| 289 | \S{config-termtype} \q{Terminal-type string} |
| 290 | |
| 291 | \S{config-username} \q{Auto-login username} |
| 292 | |
| 293 | \S{config-keepalive} Using keepalives to prevent disconnection |
| 294 | |
| 295 | \H{config-telnet} The Telnet panel |
| 296 | |
| 297 | \S{config-termspeed} \q{Terminal-speed string} |
| 298 | |
| 299 | \S{config-environ} Setting environment variables on the server |
| 300 | |
| 301 | \S{config-oldenviron} \q{Handling of OLD_ENVIRON ambiguity} |
| 302 | |
| 303 | \H{config-ssh} The SSH panel |
| 304 | |
| 305 | \S{config-command} Executing a specific command on the server |
| 306 | |
| 307 | \S{config-auth} SSH authentication options |
| 308 | |
| 309 | \S{config-protocol} SSH protocol options |