| 1 | \versionid $Id: using.but,v 1.6 2002/04/18 20:45:01 jacob Exp $ |
| 2 | |
| 3 | \C{using} Using PuTTY |
| 4 | |
| 5 | This chapter provides a general introduction to some more advanced |
| 6 | features of PuTTY. For extreme detail and reference purposes, |
| 7 | \k{config} is likely to contain more information. |
| 8 | |
| 9 | \H{using-session} During your session |
| 10 | |
| 11 | A lot of PuTTY's complexity and features are in the configuration |
| 12 | panel. Once you have worked your way through that and started |
| 13 | a session, things should be reasonably simple after that. |
| 14 | Nevertheless, there are a few more useful features available. |
| 15 | |
| 16 | \S{using-selection} Copying and pasting text |
| 17 | |
| 18 | Often in a PuTTY session you will find text on your terminal screen |
| 19 | which you want to type in again. Like most other terminal emulators, |
| 20 | PuTTY allows you to copy and paste the text rather than having to |
| 21 | type it again. Also, copy and paste uses the Windows clipboard, so |
| 22 | that you can paste (for example) URLs into a web browser, or paste |
| 23 | from a word processor or spreadsheet into your terminal session. |
| 24 | |
| 25 | PuTTY's copy and paste works entirely with the mouse. In order to |
| 26 | copy text to the clipboard, you just click the left mouse button in |
| 27 | the terminal window, and drag to select text. When you let go of the |
| 28 | button, the text is \e{automatically} copied to the clipboard. You |
| 29 | do not need to press Ctrl-C or Ctrl-Ins; in fact, if you do press |
| 30 | Ctrl-C, PuTTY will send a Ctrl-C character down your session to the |
| 31 | server where it will probably cause a process to be interrupted. |
| 32 | |
| 33 | Pasting is done using the right button (or the middle mouse button, |
| 34 | if you have a three-button mouse and have set it up; see |
| 35 | \k{config-mouse}). When you click the right mouse button, PuTTY will |
| 36 | read whatever is in the Windows Clipboard and paste it into your |
| 37 | session, \e{exactly} as if it had been typed at the keyboard. |
| 38 | (Therefore, be careful of pasting formatted text into an editor that |
| 39 | does automatic indenting; you may find that the spaces pasted from |
| 40 | the clipboard plus the spaces added by the editor add up to too many |
| 41 | spaces and ruin the formatting. There is nothing PuTTY can do about |
| 42 | this.) |
| 43 | |
| 44 | If you double-click the left mouse button, PuTTY will select a whole |
| 45 | word. If you double-click, hold down the second click, and drag the |
| 46 | mouse, PuTTY will select a sequence of whole words. (You can adjust |
| 47 | precisely what PuTTY considers to be part of a word; see |
| 48 | \k{config-charclasses}.) If you \e{triple}-click, or triple-click |
| 49 | and drag, then PuTTY will select a whole line or sequence of lines. |
| 50 | |
| 51 | If you want to select a rectangular region instead of selecting to |
| 52 | the end of each line, you can do this by holding down Alt when you |
| 53 | make your selection. (You can also configure rectangular selection |
| 54 | to be the default, and then holding down Alt gives the normal |
| 55 | behaviour instead. See \k{config-rectselect} for details.) |
| 56 | |
| 57 | If you have a middle mouse button, then you can use it to adjust an |
| 58 | existing selection if you selected something slightly wrong. (If you |
| 59 | have configured the middle mouse button to paste, then the right |
| 60 | mouse button does this instead.) Click the button on the screen, and |
| 61 | you can pick up the nearest end of the selection and drag it to |
| 62 | somewhere else. |
| 63 | |
| 64 | \S{using-scrollback} Scrolling the screen back |
| 65 | |
| 66 | PuTTY keeps track of text that has scrolled up off the top of the |
| 67 | terminal. So if something appears on the screen that you want to |
| 68 | read, but it scrolls too fast and it's gone by the time you try to |
| 69 | look for it, you can use the scrollbar on the right side of the |
| 70 | window to look back up the session history and find it again. |
| 71 | |
| 72 | As well as using the scrollbar, you can also page the scrollback up |
| 73 | and down by pressing Shift-PgUp and Shift-PgDn. These are still |
| 74 | available if you configure the scrollbar to be invisible. |
| 75 | |
| 76 | By default the last 200 lines scrolled off the top are |
| 77 | preserved for you to look at. You can increase (or decrease) this |
| 78 | value using the configuration box; see \k{config-scrollback}. |
| 79 | |
| 80 | \S{using-sysmenu} The System menu |
| 81 | |
| 82 | If you click the left mouse button on the icon in the top left |
| 83 | corner of PuTTY's window, or click the right mouse button on the |
| 84 | title bar, you will see the standard Windows system menu containing |
| 85 | items like Minimise, Move, Size and Close. |
| 86 | |
| 87 | PuTTY's system menu contains extra program features in addition to |
| 88 | the Windows standard options. These extra menu commands are |
| 89 | described below. |
| 90 | |
| 91 | \S2{using-eventlog} The PuTTY Event Log |
| 92 | |
| 93 | If you choose \q{Event Log} from the system menu, a small window |
| 94 | will pop up in which PuTTY logs significant events during the |
| 95 | connection. Most of the events in the log will probably take place |
| 96 | during session startup, but a few can occur at any point in the |
| 97 | session, and one or two occur right at the end. |
| 98 | |
| 99 | You can use the mouse to select one or more lines of the Event Log, |
| 100 | and hit the Copy button to copy them to the clipboard. If you are |
| 101 | reporting a bug, it's often useful to paste the contents of the |
| 102 | Event Log into your bug report. |
| 103 | |
| 104 | \S2{using-newsession} Starting new sessions |
| 105 | |
| 106 | PuTTY's system menu provides some shortcut ways to start new |
| 107 | sessions: |
| 108 | |
| 109 | \b Selecting \q{New Session} will start a completely new instance of |
| 110 | PuTTY, and bring up the configuration box as normal. |
| 111 | |
| 112 | \b Selecting \q{Duplicate Session} will start a session with |
| 113 | precisely the same options as your current one - connecting to the |
| 114 | same host using the same protocol, with all the same terminal |
| 115 | settings and everything. |
| 116 | |
| 117 | \b The \q{Saved Sessions} submenu gives you quick access to any |
| 118 | sets of stored session details you have previously saved. See |
| 119 | \k{config-saving} for details of how to create saved sessions. |
| 120 | |
| 121 | \S2{using-changesettings} Changing your session settings |
| 122 | |
| 123 | If you select \q{Change Settings} from the system menu, PuTTY will |
| 124 | display a cut-down version of its initial configuration box. This |
| 125 | allows you to adjust most properties of your current session. You |
| 126 | can change the terminal size, the font, the actions of various |
| 127 | keypresses, the colours, and so on. |
| 128 | |
| 129 | Some of the options that are available in the main configuration box |
| 130 | are not shown in the cut-down Change Settings box. These are usually |
| 131 | options which don't make sense to change in the middle of a session |
| 132 | (for example, you can't switch from SSH to Telnet in mid-session). |
| 133 | |
| 134 | \S2{using-copyall} Copy All to Clipboard |
| 135 | |
| 136 | This system menu option provides a convenient way to copy the whole |
| 137 | contents of the terminal screen and scrollback to the clipboard in |
| 138 | one go. |
| 139 | |
| 140 | \S2{reset-terminal} Clearing and resetting the terminal |
| 141 | |
| 142 | The \q{Clear Scrollback} option on the system menu tells PuTTY to |
| 143 | discard all the lines of text that have been kept after they |
| 144 | scrolled off the top of the screen. This might be useful, for |
| 145 | example, if you displayed sensitive information and wanted to make |
| 146 | sure nobody could look over your shoulder and see it. (Note that |
| 147 | this only prevents a casual user from using the scrollbar to view |
| 148 | the information; the text is not guaranteed not to still be in |
| 149 | PuTTY's memory.) |
| 150 | |
| 151 | The \q{Reset Terminal} option causes a full reset of the terminal |
| 152 | emulation. A VT-series terminal is a complex piece of software and |
| 153 | can easily get into a state where all the text printed becomes |
| 154 | unreadable. (This can happen, for example, if you accidentally |
| 155 | output a binary file to your terminal.) If this happens, selecting |
| 156 | Reset Terminal should sort it out. |
| 157 | |
| 158 | \S2{using-fullscreen} Full screen mode |
| 159 | |
| 160 | If you find the title bar on a maximised window to be ugly or |
| 161 | distracting, you can select Full Screen mode to maximise PuTTY |
| 162 | \q{even more}. When you select this, PuTTY will expand to fill the |
| 163 | whole screen and its borders, title bar and scrollbar will |
| 164 | disappear. (You can configure the scrollbar not to disappear in |
| 165 | full-screen mode if you want to keep it; see \k{config-scrollback}.) |
| 166 | |
| 167 | When you are in full-screen mode, you can still access the system |
| 168 | menu if you click the left mouse button in the \e{extreme} top left |
| 169 | corner of the screen. |
| 170 | |
| 171 | \H{using-logging} Creating a log file of your session |
| 172 | |
| 173 | For some purposes you may find you want to log everything that |
| 174 | appears on your screen. You can do this using the \q{Logging} panel |
| 175 | in the configuration box. |
| 176 | |
| 177 | To begin a session log, select \q{Change Settings} from the system |
| 178 | menu and go to the Logging panel. Enter a log file name, and select |
| 179 | a logging mode. (You can log all session output including the |
| 180 | terminal control sequences, or you can just log the printable text. |
| 181 | It depends what you want the log for.) Click \q{Apply} and your log |
| 182 | will be started. Later on, you can go back to the Logging panel and |
| 183 | select \q{Logging turned off completely} to stop logging; then PuTTY |
| 184 | will close the log file and you can safely read it. |
| 185 | |
| 186 | See \k{config-logging} for more details and options. |
| 187 | |
| 188 | \H{using-translation} Altering your character set configuration |
| 189 | |
| 190 | If you find that special characters (accented characters, for |
| 191 | example) are not being displayed correctly in your PuTTY session, it |
| 192 | may be that PuTTY is interpreting the characters sent by the server |
| 193 | according to the wrong \e{character set}. There are a lot of |
| 194 | different character sets available, so it's entirely possible for |
| 195 | this to happen. |
| 196 | |
| 197 | If you click \q{Change Settings} and look at the \q{Translation} |
| 198 | panel, you should see a large number of character sets which you can |
| 199 | select. Now all you need is to find out which of them you want! |
| 200 | |
| 201 | \H{using-x-forwarding} Using X11 forwarding in SSH |
| 202 | |
| 203 | The SSH protocol has the ability to securely forward X Window System |
| 204 | applications over your encrypted SSH connection, so that you can run |
| 205 | an application on the SSH server machine and have it put its windows |
| 206 | up on your local machine without sending any X network traffic in |
| 207 | the clear. |
| 208 | |
| 209 | In order to use this feature, you will need an X display server for |
| 210 | your Windows machine, such as X-Win32 or Exceed. This will probably |
| 211 | install itself as display number 0 on your local machine; if it |
| 212 | doesn't, the manual for the X server should tell you what it does |
| 213 | do. |
| 214 | |
| 215 | You should then tick the \q{Enable X11 forwarding} box in the |
| 216 | Tunnels panel (see \k{config-ssh-x11}) before starting your SSH |
| 217 | session. The \q{X display location} box reads \c{localhost:0} by |
| 218 | default, which is the usual display location where your X server |
| 219 | will be installed. If that needs changing, then change it. |
| 220 | |
| 221 | Now you should be able to log in to the SSH server as normal. To |
| 222 | check that X forwarding has been successfully negotiated during |
| 223 | connection startup, you can check the PuTTY Event Log (see |
| 224 | \k{using-eventlog}). It should say something like this: |
| 225 | |
| 226 | \c 2001-12-05 17:22:01 Requesting X11 forwarding |
| 227 | \c 2001-12-05 17:22:02 X11 forwarding enabled |
| 228 | |
| 229 | If the remote system is Unix or Unix-like, you should also be able |
| 230 | to see that the \c{DISPLAY} environment variable has been set to |
| 231 | point at display 10 or above on the SSH server machine itself: |
| 232 | |
| 233 | \c fred@unixbox:~$ echo $DISPLAY |
| 234 | \c unixbox:10.0 |
| 235 | |
| 236 | If this works, you should then be able to run X applications in the |
| 237 | remote session and have them display their windows on your PC. |
| 238 | |
| 239 | Note that if your PC X server requires authentication to connect, |
| 240 | then PuTTY cannot currently support it. If this is a problem for |
| 241 | you, you should mail the authors \#{FIXME} and give details. |
| 242 | |
| 243 | \H{using-port-forwarding} Using port forwarding in SSH |
| 244 | |
| 245 | The SSH protocol has the ability to forward arbitrary network |
| 246 | connections over your encrypted SSH connection, to avoid the network |
| 247 | traffic being sent in clear. For example, you could use this to |
| 248 | connect from your home computer to a POP-3 server on a remote |
| 249 | machine without your POP-3 password being visible to network |
| 250 | sniffers. |
| 251 | |
| 252 | In order to use port forwarding to connect from your local machine |
| 253 | to a port on a remote server, you need to: |
| 254 | |
| 255 | \b Choose a port number on your local machine where PuTTY should |
| 256 | listen for incoming connections. There are likely to be plenty of |
| 257 | unused port numbers above 3000. |
| 258 | |
| 259 | \b Now, before you start your SSH connection, go to the Tunnels |
| 260 | panel (see \k{config-ssh-portfwd}). Make sure the \q{Local} radio |
| 261 | button is set. Enter the local port number into the \q{Source port} |
| 262 | box. Enter the destination host name and port number into the |
| 263 | \q{Destination} box, separated by a colon (for example, |
| 264 | \c{popserver.example.com:110} to connect to a POP-3 server). |
| 265 | |
| 266 | \b Now click the \q{Add} button. The details of your port forwarding |
| 267 | should appear in the list box. |
| 268 | |
| 269 | Now start your session and log in. (Port forwarding will not be |
| 270 | enabled until after you have logged in; otherwise it would be easy |
| 271 | to perform completely anonymous network attacks, and gain access to |
| 272 | anyone's virtual private network). To check that PuTTY has set up |
| 273 | the port forwarding correctly, you can look at the PuTTY Event Log |
| 274 | (see \k{using-eventlog}). It should say something like this: |
| 275 | |
| 276 | \c 2001-12-05 17:22:10 Local port 3110 forwarding to |
| 277 | \c popserver.example.com:110 |
| 278 | |
| 279 | Now if you connect to the source port number on your local PC, you |
| 280 | should find that it answers you exactly as if it were the service |
| 281 | running on the destination machine. So in this example, you could |
| 282 | then configure an e-mail client to use \c{localhost:3110} as a POP-3 |
| 283 | server instead of \c{popserver.example.com:110}. (Of course, the |
| 284 | forwarding will stop happening when your PuTTY session closes down.) |
| 285 | |
| 286 | You can also forward ports in the other direction: arrange for a |
| 287 | particular port number on the \e{server} machine to be forwarded |
| 288 | back to your PC as a connection to a service on your PC or near it. |
| 289 | To do this, just select the \q{Remote} radio button instead of the |
| 290 | \q{Local} one. The \q{Source port} box will now specify a port |
| 291 | number on the \e{server} (note that most servers will not allow you |
| 292 | to use port numbers under 1024 for this purpose). |
| 293 | |
| 294 | The source port for a forwarded connection usually does not accept |
| 295 | connections from any machine except the SSH client or server machine |
| 296 | itself (for local and remote forwardings respectively). There are |
| 297 | controls in the Tunnels panel to change this: |
| 298 | |
| 299 | \b The \q{Local ports accept connections from other hosts} option |
| 300 | allows you to set up local-to-remote port forwardings in such a way |
| 301 | that machines other than your client PC can connect to the forwarded |
| 302 | port. |
| 303 | |
| 304 | \b The \q{Remote ports do the same} option does the same thing for |
| 305 | remote-to-local port forwardings (so that machines other than the |
| 306 | SSH server machine can connect to the forwarded port.) Note that |
| 307 | this feature is only available in the SSH 2 protocol, and not all |
| 308 | SSH 2 servers support it (OpenSSH 3.0 does not, for example). |
| 309 | |
| 310 | \H{using-rawprot} Making raw TCP connections |
| 311 | |
| 312 | A lot of Internet protocols are composed of commands and responses |
| 313 | in plain text. For example, SMTP (the protocol used to transfer |
| 314 | e-mail), NNTP (the protocol used to transfer Usenet news), and HTTP |
| 315 | (the protocol used to serve Web pages) all consist of commands in |
| 316 | readable plain text. |
| 317 | |
| 318 | Sometimes it can be useful to connect directly to one of these |
| 319 | services and speak the protocol \q{by hand}, by typing protocol |
| 320 | commands and watching the responses. On Unix machines, you can do |
| 321 | this using the system's \c{telnet} command to connect to the right |
| 322 | port number. For example, \c{telnet mailserver.example.com 25} might |
| 323 | enable you to talk directly to the SMTP service running on a mail |
| 324 | server. |
| 325 | |
| 326 | Although the Unix \c{telnet} program provides this functionality, |
| 327 | the protocol being used is not really Telnet. Really there is no |
| 328 | actual protocol at all; the bytes sent down the connection are |
| 329 | exactly the ones you type, and the bytes shown on the screen are |
| 330 | exactly the ones sent by the server. Unix \c{telnet} will attempt to |
| 331 | detect or guess whether the service it is talking to is a real |
| 332 | Telnet service or not; PuTTY prefers to be told for certain. |
| 333 | |
| 334 | In order to make a debugging connection to a service of this type, |
| 335 | you simply select the fourth protocol name, \q{Raw}, from the |
| 336 | \q{Protocol} buttons in the \q{Session} configuration panel. (See |
| 337 | \k{config-hostname}.) You can then enter a host name and a port |
| 338 | number, and make the connection. |
| 339 | |
| 340 | \H{putty-cmdline} The PuTTY command line |
| 341 | |
| 342 | PuTTY can be made to do various things without user intervention by |
| 343 | supplying command-line arguments (e.g., from a command prompt window, |
| 344 | or a Windows shortcut). |
| 345 | |
| 346 | \S{putty-cmdline-session} Starting a session from the command line |
| 347 | |
| 348 | These options allow you to bypass the configuration window and launch |
| 349 | straight into a session. |
| 350 | |
| 351 | To start a connection to \c{host}: |
| 352 | |
| 353 | \c putty.exe [-ssh] [user@]host[:port] |
| 354 | |
| 355 | If this syntax is used, settings are taken from the Default Settings |
| 356 | (see \k{config-saving}); \c{user} and \c{port} override these settings |
| 357 | if supplied. Also, \c{-ssh} overrides the default protocol, if |
| 358 | specified. |
| 359 | |
| 360 | For telnet sessions, the following alternative syntax is supported |
| 361 | (this makes PuTTY suitable for use as a URL handler for telnet URLs in |
| 362 | web browsers): |
| 363 | |
| 364 | \c putty.exe telnet://host[:port]/ |
| 365 | |
| 366 | In order to start an existing saved session called \c{sessionname}, |
| 367 | use the following syntax: |
| 368 | |
| 369 | \c putty.exe @sessionname |
| 370 | |
| 371 | \S{putty-cleanup} \c{-cleanup} |
| 372 | |
| 373 | If invoked with the \c{-cleanup} option, rather than running as |
| 374 | normal, PuTTY will remove its registry entries and random seed file |
| 375 | from the local machine (after confirming with the user). |