| 1 | \define{versionidusing} \versionid $Id$ |
| 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 | \I{copy and paste}Often in a PuTTY session you will find text on |
| 19 | your terminal screen which you want to type in again. Like most |
| 20 | other terminal emulators, PuTTY allows you to copy and paste the |
| 21 | text rather than having to type it again. Also, copy and paste uses |
| 22 | the \I{Windows clipboard}Windows \i{clipboard}, so that you can |
| 23 | paste (for example) URLs into a web browser, or paste from a word |
| 24 | processor or spreadsheet into your terminal session. |
| 25 | |
| 26 | PuTTY's copy and paste works entirely with the \i{mouse}. In order |
| 27 | to copy text to the clipboard, you just click the \i{left mouse |
| 28 | button} in the \i{terminal window}, and drag to \I{selecting text}select |
| 29 | text. When you let go of the button, the text is \e{automatically} |
| 30 | copied to the clipboard. You do not need to press Ctrl-C or |
| 31 | Ctrl-Ins; in fact, if you do press Ctrl-C, PuTTY will send a Ctrl-C |
| 32 | character down your session to the server where it will probably |
| 33 | cause a process to be interrupted. |
| 34 | |
| 35 | Pasting is done using the right button (or the middle mouse button, |
| 36 | if you have a \i{three-button mouse} and have set it up; see |
| 37 | \k{config-mouse}). (Pressing \i{Shift-Ins}, or selecting \q{Paste} |
| 38 | from the \I{right mouse button, with Ctrl}Ctrl+right-click |
| 39 | \i{context menu}, have the same effect.) When |
| 40 | you click the \i{right mouse button}, PuTTY will read whatever is in |
| 41 | the Windows clipboard and paste it into your session, \e{exactly} as |
| 42 | if it had been typed at the keyboard. (Therefore, be careful of |
| 43 | pasting formatted text into an editor that does automatic indenting; |
| 44 | you may find that the spaces pasted from the clipboard plus the |
| 45 | spaces added by the editor add up to too many spaces and ruin the |
| 46 | formatting. There is nothing PuTTY can do about this.) |
| 47 | |
| 48 | If you \i{double-click} the left mouse button, PuTTY will |
| 49 | \I{selecting words}select a whole word. If you double-click, hold |
| 50 | down the second click, and drag the mouse, PuTTY will select a |
| 51 | sequence of whole words. (You can adjust precisely what PuTTY |
| 52 | considers to be part of a word; see \k{config-charclasses}.) |
| 53 | If you \e{triple}-click, or \i{triple-click} and drag, then |
| 54 | PuTTY will \I{selecting lines}select a whole line or sequence of lines. |
| 55 | |
| 56 | If you want to select a \I{rectangular selection}rectangular region |
| 57 | instead of selecting to the end of each line, you can do this by |
| 58 | holding down Alt when you make your selection. You can also |
| 59 | configure rectangular selection to be the default, and then holding |
| 60 | down Alt gives the normal behaviour instead: see |
| 61 | \k{config-rectselect} for details. |
| 62 | |
| 63 | (In some Unix environments, Alt+drag is intercepted by the window |
| 64 | manager. Shift+Alt+drag should work for rectangular selection as |
| 65 | well, so you could try that instead.) |
| 66 | |
| 67 | If you have a \i{middle mouse button}, then you can use it to |
| 68 | \I{adjusting a selection}adjust an existing selection if you |
| 69 | selected something slightly wrong. (If you have configured the |
| 70 | middle mouse button to paste, then the right mouse button does this |
| 71 | instead.) Click the button on the screen, and you can pick up the |
| 72 | nearest end of the selection and drag it to somewhere else. |
| 73 | |
| 74 | It's possible for the server to ask to \I{mouse reporting}handle mouse |
| 75 | clicks in the PuTTY window itself. If this happens, the \i{mouse pointer} |
| 76 | will turn into an arrow, and using the mouse to copy and paste will only |
| 77 | work if you hold down Shift. See \k{config-features-mouse} and |
| 78 | \k{config-mouseshift} for details of this feature and how to configure |
| 79 | it. |
| 80 | |
| 81 | \S{using-scrollback} \I{scrollback}Scrolling the screen back |
| 82 | |
| 83 | PuTTY keeps track of text that has scrolled up off the top of the |
| 84 | terminal. So if something appears on the screen that you want to |
| 85 | read, but it scrolls too fast and it's gone by the time you try to |
| 86 | look for it, you can use the \i{scrollbar} on the right side of the |
| 87 | window to look back up the session \i{history} and find it again. |
| 88 | |
| 89 | As well as using the scrollbar, you can also page the scrollback up |
| 90 | and down by pressing \i{Shift-PgUp} and \i{Shift-PgDn}. You can |
| 91 | scroll a line at a time using \i{Ctrl-PgUp} and \i{Ctrl-PgDn}. These |
| 92 | are still available if you configure the scrollbar to be invisible. |
| 93 | |
| 94 | By default the last 200 lines scrolled off the top are |
| 95 | preserved for you to look at. You can increase (or decrease) this |
| 96 | value using the configuration box; see \k{config-scrollback}. |
| 97 | |
| 98 | \S{using-sysmenu} The \ii{System menu} |
| 99 | |
| 100 | If you click the left mouse button on the icon in the top left |
| 101 | corner of PuTTY's terminal window, or click the right mouse button |
| 102 | on the title bar, you will see the standard Windows system menu |
| 103 | containing items like Minimise, Move, Size and Close. |
| 104 | |
| 105 | PuTTY's system menu contains extra program features in addition to |
| 106 | the Windows standard options. These extra menu commands are |
| 107 | described below. |
| 108 | |
| 109 | (These options are also available in a \i{context menu} brought up |
| 110 | by holding Ctrl and clicking with the right mouse button anywhere |
| 111 | in the \i{PuTTY window}.) |
| 112 | |
| 113 | \S2{using-eventlog} The PuTTY \i{Event Log} |
| 114 | |
| 115 | If you choose \q{Event Log} from the system menu, a small window |
| 116 | will pop up in which PuTTY logs significant events during the |
| 117 | connection. Most of the events in the log will probably take place |
| 118 | during session startup, but a few can occur at any point in the |
| 119 | session, and one or two occur right at the end. |
| 120 | |
| 121 | You can use the mouse to select one or more lines of the Event Log, |
| 122 | and hit the Copy button to copy them to the \i{clipboard}. If you |
| 123 | are reporting a bug, it's often useful to paste the contents of the |
| 124 | Event Log into your bug report. |
| 125 | |
| 126 | \S2{using-specials} \ii{Special commands} |
| 127 | |
| 128 | Depending on the protocol used for the current session, there may be |
| 129 | a submenu of \q{special commands}. These are protocol-specific |
| 130 | tokens, such as a \q{break} signal, that can be sent down a |
| 131 | connection in addition to normal data. Their precise effect is usually |
| 132 | up to the server. Currently only Telnet, SSH, and serial connections |
| 133 | have special commands. |
| 134 | |
| 135 | The \q{break} signal can also be invoked from the keyboard with |
| 136 | \i{Ctrl-Break}. |
| 137 | |
| 138 | The following \I{Telnet special commands}special commands are |
| 139 | available in Telnet: |
| 140 | |
| 141 | \b \I{Are You There, Telnet special command}Are You There |
| 142 | |
| 143 | \b \I{Break, Telnet special command}Break |
| 144 | |
| 145 | \b \I{Synch, Telnet special command}Synch |
| 146 | |
| 147 | \b \I{Erase Character, Telnet special command}Erase Character |
| 148 | |
| 149 | \lcont{ |
| 150 | PuTTY can also be configured to send this when the Backspace key is |
| 151 | pressed; see \k{config-telnetkey}. |
| 152 | } |
| 153 | |
| 154 | \b \I{Erase Line, Telnet special command}Erase Line |
| 155 | |
| 156 | \b \I{Go Ahead, Telnet special command}Go Ahead |
| 157 | |
| 158 | \b \I{No Operation, Telnet special command}No Operation |
| 159 | |
| 160 | \lcont{ |
| 161 | Should have no effect. |
| 162 | } |
| 163 | |
| 164 | \b \I{Abort Process, Telnet special command}Abort Process |
| 165 | |
| 166 | \b \I{Abort Output, Telnet special command}Abort Output |
| 167 | |
| 168 | \b \I{Interrupt Process, Telnet special command}Interrupt Process |
| 169 | |
| 170 | \lcont{ |
| 171 | PuTTY can also be configured to send this when Ctrl-C is typed; see |
| 172 | \k{config-telnetkey}. |
| 173 | } |
| 174 | |
| 175 | \b \I{Suspend Process, Telnet special command}Suspend Process |
| 176 | |
| 177 | \lcont{ |
| 178 | PuTTY can also be configured to send this when Ctrl-Z is typed; see |
| 179 | \k{config-telnetkey}. |
| 180 | } |
| 181 | |
| 182 | \b \I{End Of Record, Telnet special command}End Of Record |
| 183 | |
| 184 | \b \I{End Of File, Telnet special command}End Of File |
| 185 | |
| 186 | In an SSH connection, the following \I{SSH special commands}special |
| 187 | commands are available: |
| 188 | |
| 189 | \b \I{IGNORE message, SSH special command}\I{No-op, in SSH}\ii{IGNORE message} |
| 190 | |
| 191 | \lcont{ |
| 192 | Should have no effect. |
| 193 | } |
| 194 | |
| 195 | \b \I{Repeat key exchange, SSH special command}Repeat key exchange |
| 196 | |
| 197 | \lcont{ |
| 198 | Only available in SSH-2. Forces a \i{repeat key exchange} immediately (and |
| 199 | resets associated timers and counters). For more information about |
| 200 | repeat key exchanges, see \k{config-ssh-kex-rekey}. |
| 201 | } |
| 202 | |
| 203 | \b \I{Break, SSH special command}Break |
| 204 | |
| 205 | \lcont{ |
| 206 | Only available in SSH-2, and only during a session. Optional |
| 207 | extension; may not be supported by server. PuTTY requests the server's |
| 208 | default break length. |
| 209 | } |
| 210 | |
| 211 | \b \I{Signal, SSH special command}Signals (SIGINT, SIGTERM etc) |
| 212 | |
| 213 | \lcont{ |
| 214 | Only available in SSH-2, and only during a session. Sends various |
| 215 | POSIX signals. Not honoured by all servers. |
| 216 | } |
| 217 | |
| 218 | With a serial connection, the only available special command is |
| 219 | \I{Break, serial special command}\q{Break}. |
| 220 | |
| 221 | \S2{using-newsession} Starting new sessions |
| 222 | |
| 223 | PuTTY's system menu provides some shortcut ways to start new |
| 224 | sessions: |
| 225 | |
| 226 | \b Selecting \i{\q{New Session}} will start a completely new |
| 227 | instance of PuTTY, and bring up the configuration box as normal. |
| 228 | |
| 229 | \b Selecting \i{\q{Duplicate Session}} will start a session in a |
| 230 | new window with precisely the same options as your current one - |
| 231 | connecting to the same host using the same protocol, with all the |
| 232 | same terminal settings and everything. |
| 233 | |
| 234 | \b In an inactive window, selecting \i{\q{Restart Session}} will |
| 235 | do the same as \q{Duplicate Session}, but in the current window. |
| 236 | |
| 237 | \b The \i{\q{Saved Sessions} submenu} gives you quick access to any |
| 238 | sets of stored session details you have previously saved. See |
| 239 | \k{config-saving} for details of how to create saved sessions. |
| 240 | |
| 241 | \S2{using-changesettings} \I{settings, changing}Changing your |
| 242 | session settings |
| 243 | |
| 244 | If you select \i{\q{Change Settings}} from the system menu, PuTTY will |
| 245 | display a cut-down version of its initial configuration box. This |
| 246 | allows you to adjust most properties of your current session. You |
| 247 | can change the terminal size, the font, the actions of various |
| 248 | keypresses, the colours, and so on. |
| 249 | |
| 250 | Some of the options that are available in the main configuration box |
| 251 | are not shown in the cut-down Change Settings box. These are usually |
| 252 | options which don't make sense to change in the middle of a session |
| 253 | (for example, you can't switch from SSH to Telnet in mid-session). |
| 254 | |
| 255 | You can save the current settings to a saved session for future use |
| 256 | from this dialog box. See \k{config-saving} for more on saved |
| 257 | sessions. |
| 258 | |
| 259 | \S2{using-copyall} \i{Copy All to Clipboard} |
| 260 | |
| 261 | This system menu option provides a convenient way to copy the whole |
| 262 | contents of the terminal screen (up to the last nonempty line) and |
| 263 | scrollback to the \i{clipboard} in one go. |
| 264 | |
| 265 | \S2{reset-terminal} \I{scrollback, clearing}Clearing and |
| 266 | \I{terminal, resetting}resetting the terminal |
| 267 | |
| 268 | The \i{\q{Clear Scrollback}} option on the system menu tells PuTTY |
| 269 | to discard all the lines of text that have been kept after they |
| 270 | scrolled off the top of the screen. This might be useful, for |
| 271 | example, if you displayed sensitive information and wanted to make |
| 272 | sure nobody could look over your shoulder and see it. (Note that |
| 273 | this only prevents a casual user from using the scrollbar to view |
| 274 | the information; the text is not guaranteed not to still be in |
| 275 | PuTTY's memory.) |
| 276 | |
| 277 | The \i{\q{Reset Terminal}} option causes a full reset of the |
| 278 | \i{terminal emulation}. A VT-series terminal is a complex piece of |
| 279 | software and can easily get into a state where all the text printed |
| 280 | becomes unreadable. (This can happen, for example, if you |
| 281 | accidentally output a binary file to your terminal.) If this |
| 282 | happens, selecting Reset Terminal should sort it out. |
| 283 | |
| 284 | \S2{using-fullscreen} \ii{Full screen} mode |
| 285 | |
| 286 | If you find the title bar on a maximised window to be ugly or |
| 287 | distracting, you can select Full Screen mode to maximise PuTTY |
| 288 | \q{even more}. When you select this, PuTTY will expand to fill the |
| 289 | whole screen and its borders, title bar and scrollbar will |
| 290 | disappear. (You can configure the scrollbar not to disappear in |
| 291 | full-screen mode if you want to keep it; see \k{config-scrollback}.) |
| 292 | |
| 293 | When you are in full-screen mode, you can still access the \i{system |
| 294 | menu} if you click the left mouse button in the \e{extreme} top left |
| 295 | corner of the screen. |
| 296 | |
| 297 | \H{using-logging} Creating a \i{log file} of your \I{session |
| 298 | log}session |
| 299 | |
| 300 | For some purposes you may find you want to log everything that |
| 301 | appears on your screen. You can do this using the \q{Logging} |
| 302 | panel in the configuration box. |
| 303 | |
| 304 | To begin a session log, select \q{Change Settings} from the system |
| 305 | menu and go to the Logging panel. Enter a log file name, and select |
| 306 | a logging mode. (You can log all session output including the |
| 307 | terminal \i{control sequence}s, or you can just log the printable text. |
| 308 | It depends what you want the log for.) Click \q{Apply} and your log |
| 309 | will be started. Later on, you can go back to the Logging panel and |
| 310 | select \q{Logging turned off completely} to stop logging; then PuTTY |
| 311 | will close the log file and you can safely read it. |
| 312 | |
| 313 | See \k{config-logging} for more details and options. |
| 314 | |
| 315 | \H{using-translation} Altering your \i{character set} configuration |
| 316 | |
| 317 | If you find that special characters (\i{accented characters}, for |
| 318 | example, or \i{line-drawing characters}) are not being displayed |
| 319 | correctly in your PuTTY session, it may be that PuTTY is interpreting |
| 320 | the characters sent by the server according to the wrong \e{character |
| 321 | set}. There are a lot of different character sets available, so it's |
| 322 | entirely possible for this to happen. |
| 323 | |
| 324 | If you click \q{Change Settings} and look at the \q{Translation} |
| 325 | panel, you should see a large number of character sets which you can |
| 326 | select, and other related options. Now all you need is to find out |
| 327 | which of them you want! (See \k{config-translation} for more |
| 328 | information.) |
| 329 | |
| 330 | \H{using-x-forwarding} Using \i{X11 forwarding} in SSH |
| 331 | |
| 332 | The SSH protocol has the ability to securely forward X Window System |
| 333 | applications over your encrypted SSH connection, so that you can run |
| 334 | an application on the SSH server machine and have it put its windows |
| 335 | up on your local machine without sending any X network traffic in |
| 336 | the clear. |
| 337 | |
| 338 | In order to use this feature, you will need an X display server for |
| 339 | your Windows machine, such as Cygwin/X, X-Win32, or Exceed. This will probably |
| 340 | install itself as display number 0 on your local machine; if it |
| 341 | doesn't, the manual for the \i{X server} should tell you what it |
| 342 | does do. |
| 343 | |
| 344 | You should then tick the \q{Enable X11 forwarding} box in the |
| 345 | X11 panel (see \k{config-ssh-x11}) before starting your SSH |
| 346 | session. The \i{\q{X display location}} box is blank by default, which |
| 347 | means that PuTTY will try to use a sensible default such as \c{:0}, |
| 348 | which is the usual display location where your X server will be |
| 349 | installed. If that needs changing, then change it. |
| 350 | |
| 351 | Now you should be able to log in to the SSH server as normal. To |
| 352 | check that X forwarding has been successfully negotiated during |
| 353 | connection startup, you can check the PuTTY Event Log (see |
| 354 | \k{using-eventlog}). It should say something like this: |
| 355 | |
| 356 | \c 2001-12-05 17:22:01 Requesting X11 forwarding |
| 357 | \c 2001-12-05 17:22:02 X11 forwarding enabled |
| 358 | |
| 359 | If the remote system is Unix or Unix-like, you should also be able |
| 360 | to see that the \i{\c{DISPLAY} environment variable} has been set to |
| 361 | point at display 10 or above on the SSH server machine itself: |
| 362 | |
| 363 | \c fred@unixbox:~$ echo $DISPLAY |
| 364 | \c unixbox:10.0 |
| 365 | |
| 366 | If this works, you should then be able to run X applications in the |
| 367 | remote session and have them display their windows on your PC. |
| 368 | |
| 369 | Note that if your PC X server requires \I{X11 authentication}authentication |
| 370 | to connect, then PuTTY cannot currently support it. If this is a problem for |
| 371 | you, you should mail the PuTTY authors \#{FIXME} and give details |
| 372 | (see \k{feedback}). |
| 373 | |
| 374 | For more options relating to X11 forwarding, see \k{config-ssh-x11}. |
| 375 | |
| 376 | \H{using-port-forwarding} Using \i{port forwarding} in SSH |
| 377 | |
| 378 | The SSH protocol has the ability to forward arbitrary \i{network |
| 379 | connection}s over your encrypted SSH connection, to avoid the network |
| 380 | traffic being sent in clear. For example, you could use this to |
| 381 | connect from your home computer to a \i{POP-3} server on a remote |
| 382 | machine without your POP-3 password being visible to network |
| 383 | sniffers. |
| 384 | |
| 385 | In order to use port forwarding to \I{local port forwarding}connect |
| 386 | from your local machine to a port on a remote server, you need to: |
| 387 | |
| 388 | \b Choose a \i{port number} on your local machine where PuTTY should |
| 389 | listen for incoming connections. There are likely to be plenty of |
| 390 | unused port numbers above 3000. (You can also use a local loopback |
| 391 | address here; see below for more details.) |
| 392 | |
| 393 | \b Now, before you start your SSH connection, go to the Tunnels |
| 394 | panel (see \k{config-ssh-portfwd}). Make sure the \q{Local} radio |
| 395 | button is set. Enter the local port number into the \q{Source port} |
| 396 | box. Enter the destination host name and port number into the |
| 397 | \q{Destination} box, separated by a colon (for example, |
| 398 | \c{popserver.example.com:110} to connect to a POP-3 server). |
| 399 | |
| 400 | \b Now click the \q{Add} button. The details of your port forwarding |
| 401 | should appear in the list box. |
| 402 | |
| 403 | Now start your session and log in. (Port forwarding will not be |
| 404 | enabled until after you have logged in; otherwise it would be easy |
| 405 | to perform completely anonymous network attacks, and gain access to |
| 406 | anyone's virtual private network.) To check that PuTTY has set up |
| 407 | the port forwarding correctly, you can look at the PuTTY Event Log |
| 408 | (see \k{using-eventlog}). It should say something like this: |
| 409 | |
| 410 | \c 2001-12-05 17:22:10 Local port 3110 forwarding to |
| 411 | \c popserver.example.com:110 |
| 412 | |
| 413 | Now if you connect to the source port number on your local PC, you |
| 414 | should find that it answers you exactly as if it were the service |
| 415 | running on the destination machine. So in this example, you could |
| 416 | then configure an e-mail client to use \c{localhost:3110} as a POP-3 |
| 417 | server instead of \c{popserver.example.com:110}. (Of course, the |
| 418 | forwarding will stop happening when your PuTTY session closes down.) |
| 419 | |
| 420 | You can also forward ports in the other direction: arrange for a |
| 421 | particular port number on the \e{server} machine to be \I{remote |
| 422 | port forwarding}forwarded back to your PC as a connection to a |
| 423 | service on your PC or near it. |
| 424 | To do this, just select the \q{Remote} radio button instead of the |
| 425 | \q{Local} one. The \q{Source port} box will now specify a port |
| 426 | number on the \e{server} (note that most servers will not allow you |
| 427 | to use \I{privileged port}port numbers under 1024 for this purpose). |
| 428 | |
| 429 | An alternative way to forward local connections to remote hosts is |
| 430 | to use \I{dynamic port forwarding}dynamic SOCKS proxying. For |
| 431 | this, you will need to select the \q{Dynamic} radio button instead |
| 432 | of \q{Local}, and then you should not enter anything into the |
| 433 | \q{Destination} box (it will be ignored). This will cause PuTTY to |
| 434 | listen on the port you have specified, and provide a SOCKS proxy |
| 435 | service to any programs which connect to that port. So, in |
| 436 | particular, you can forward other PuTTY connections through it by |
| 437 | setting up the Proxy control panel (see \k{config-proxy} for |
| 438 | details). |
| 439 | |
| 440 | The source port for a forwarded connection usually does not accept |
| 441 | connections from any machine except the \I{localhost}SSH client or |
| 442 | server machine itself (for local and remote forwardings respectively). |
| 443 | There are controls in the Tunnels panel to change this: |
| 444 | |
| 445 | \b The \q{Local ports accept connections from other hosts} option |
| 446 | allows you to set up local-to-remote port forwardings (including |
| 447 | dynamic port forwardings) in such a way that machines other than |
| 448 | your client PC can connect to the forwarded port. |
| 449 | |
| 450 | \b The \q{Remote ports do the same} option does the same thing for |
| 451 | remote-to-local port forwardings (so that machines other than the |
| 452 | SSH server machine can connect to the forwarded port.) Note that |
| 453 | this feature is only available in the SSH-2 protocol, and not all |
| 454 | SSH-2 servers honour it (in \i{OpenSSH}, for example, it's usually |
| 455 | disabled by default). |
| 456 | |
| 457 | You can also specify an \i{IP address} to \I{listen address}listen |
| 458 | on. Typically a Windows machine can be asked to listen on any single |
| 459 | IP address in the \cw{127.*.*.*} range, and all of these are |
| 460 | \i{loopback address}es available only to the local machine. So if |
| 461 | you forward (for example) \c{127.0.0.5:79} to a remote machine's |
| 462 | \i\cw{finger} port, then you should be able to run commands such as |
| 463 | \c{finger fred@127.0.0.5}. |
| 464 | This can be useful if the program connecting to the forwarded port |
| 465 | doesn't allow you to change the port number it uses. This feature is |
| 466 | available for local-to-remote forwarded ports; SSH-1 is unable to |
| 467 | support it for remote-to-local ports, while SSH-2 can support it in |
| 468 | theory but servers will not necessarily cooperate. |
| 469 | |
| 470 | (Note that if you're using Windows XP Service Pack 2, you may need |
| 471 | to obtain a fix from Microsoft in order to use addresses like |
| 472 | \cw{127.0.0.5} - see \k{faq-alternate-localhost}.) |
| 473 | |
| 474 | For more options relating to port forwarding, see |
| 475 | \k{config-ssh-portfwd}. |
| 476 | |
| 477 | If the connection you are forwarding over SSH is itself a second SSH |
| 478 | connection made by another copy of PuTTY, you might find the |
| 479 | \q{logical host name} configuration option useful to warn PuTTY of |
| 480 | which host key it should be expecting. See \k{config-loghost} for |
| 481 | details of this. |
| 482 | |
| 483 | \H{using-rawprot} Making \i{raw TCP connections} |
| 484 | |
| 485 | A lot of \I{debugging Internet protocols}Internet protocols are |
| 486 | composed of commands and responses in plain text. For example, |
| 487 | \i{SMTP} (the protocol used to transfer e-mail), \i{NNTP} (the |
| 488 | protocol used to transfer Usenet news), and \i{HTTP} (the protocol |
| 489 | used to serve Web pages) all consist of commands in readable plain |
| 490 | text. |
| 491 | |
| 492 | Sometimes it can be useful to connect directly to one of these |
| 493 | services and speak the protocol \q{by hand}, by typing protocol |
| 494 | commands and watching the responses. On Unix machines, you can do |
| 495 | this using the system's \c{telnet} command to connect to the right |
| 496 | port number. For example, \c{telnet mailserver.example.com 25} might |
| 497 | enable you to talk directly to the SMTP service running on a mail |
| 498 | server. |
| 499 | |
| 500 | Although the Unix \c{telnet} program provides this functionality, |
| 501 | the protocol being used is not really Telnet. Really there is no |
| 502 | actual protocol at all; the bytes sent down the connection are |
| 503 | exactly the ones you type, and the bytes shown on the screen are |
| 504 | exactly the ones sent by the server. Unix \c{telnet} will attempt to |
| 505 | detect or guess whether the service it is talking to is a real |
| 506 | Telnet service or not; PuTTY prefers to be told for certain. |
| 507 | |
| 508 | In order to make a debugging connection to a service of this type, |
| 509 | you simply select the fourth protocol name, \I{\q{Raw} |
| 510 | protocol}\q{Raw}, from the \q{Protocol} buttons in the \q{Session} |
| 511 | configuration panel. (See \k{config-hostname}.) You can then enter a |
| 512 | host name and a port number, and make the connection. |
| 513 | |
| 514 | \H{using-serial} Connecting to a local serial line |
| 515 | |
| 516 | PuTTY can connect directly to a local serial line as an alternative |
| 517 | to making a network connection. In this mode, text typed into the |
| 518 | PuTTY window will be sent straight out of your computer's serial |
| 519 | port, and data received through that port will be displayed in the |
| 520 | PuTTY window. You might use this mode, for example, if your serial |
| 521 | port is connected to another computer which has a serial connection. |
| 522 | |
| 523 | To make a connection of this type, simply select \q{Serial} from the |
| 524 | \q{Connection type} radio buttons on the \q{Session} configuration |
| 525 | panel (see \k{config-hostname}). The \q{Host Name} and \q{Port} |
| 526 | boxes will transform into \q{Serial line} and \q{Speed}, allowing |
| 527 | you to specify which serial line to use (if your computer has more |
| 528 | than one) and what speed (baud rate) to use when transferring data. |
| 529 | For further configuration options (data bits, stop bits, parity, |
| 530 | flow control), you can use the \q{Serial} configuration panel (see |
| 531 | \k{config-serial}). |
| 532 | |
| 533 | After you start up PuTTY in serial mode, you might find that you |
| 534 | have to make the first move, by sending some data out of the serial |
| 535 | line in order to notify the device at the other end that someone is |
| 536 | there for it to talk to. This probably depends on the device. If you |
| 537 | start up a PuTTY serial session and nothing appears in the window, |
| 538 | try pressing Return a few times and see if that helps. |
| 539 | |
| 540 | A serial line provides no well defined means for one end of the |
| 541 | connection to notify the other that the connection is finished. |
| 542 | Therefore, PuTTY in serial mode will remain connected until you |
| 543 | close the window using the close button. |
| 544 | |
| 545 | \H{using-cmdline} The PuTTY command line |
| 546 | |
| 547 | PuTTY can be made to do various things without user intervention by |
| 548 | supplying \i{command-line arguments} (e.g., from a \i{command prompt |
| 549 | window}, or a \i{Windows shortcut}). |
| 550 | |
| 551 | \S{using-cmdline-session} Starting a session from the command line |
| 552 | |
| 553 | \I\c{-ssh}\I\c{-telnet}\I\c{-rlogin}\I\c{-raw}These options allow |
| 554 | you to bypass the configuration window and launch straight into a |
| 555 | session. |
| 556 | |
| 557 | To start a connection to a server called \c{host}: |
| 558 | |
| 559 | \c putty.exe [-ssh | -telnet | -rlogin | -raw] [user@]host |
| 560 | |
| 561 | If this syntax is used, settings are taken from the \i{Default Settings} |
| 562 | (see \k{config-saving}); \c{user} overrides these settings if |
| 563 | supplied. Also, you can specify a protocol, which will override the |
| 564 | default protocol (see \k{using-cmdline-protocol}). |
| 565 | |
| 566 | For telnet sessions, the following alternative syntax is supported |
| 567 | (this makes PuTTY suitable for use as a URL handler for \i{telnet |
| 568 | URLs} in web browsers): |
| 569 | |
| 570 | \c putty.exe telnet://host[:port]/ |
| 571 | |
| 572 | In order to start an existing saved session called \c{sessionname}, |
| 573 | use the \c{-load} option (described in \k{using-cmdline-load}). |
| 574 | |
| 575 | \c putty.exe -load "session name" |
| 576 | |
| 577 | \S{using-cleanup} \i\c{-cleanup} |
| 578 | |
| 579 | \cfg{winhelp-topic}{options.cleanup} |
| 580 | |
| 581 | If invoked with the \c{-cleanup} option, rather than running as |
| 582 | normal, PuTTY will remove its \I{removing registry entries}registry |
| 583 | entries and \i{random seed file} from the local machine (after |
| 584 | confirming with the user). |
| 585 | |
| 586 | Note that on \i{multi-user systems}, \c{-cleanup} only removes |
| 587 | registry entries and files associated with the currently logged-in |
| 588 | user. |
| 589 | |
| 590 | \S{using-general-opts} Standard command-line options |
| 591 | |
| 592 | PuTTY and its associated tools support a range of command-line |
| 593 | options, most of which are consistent across all the tools. This |
| 594 | section lists the available options in all tools. Options which are |
| 595 | specific to a particular tool are covered in the chapter about that |
| 596 | tool. |
| 597 | |
| 598 | \S2{using-cmdline-load} \i\c{-load}: load a saved session |
| 599 | |
| 600 | \I{saved sessions, loading from command line}The \c{-load} option |
| 601 | causes PuTTY to load configuration details out of a saved session. |
| 602 | If these details include a host name, then this option is all you |
| 603 | need to make PuTTY start a session. |
| 604 | |
| 605 | You need double quotes around the session name if it contains spaces. |
| 606 | |
| 607 | If you want to create a \i{Windows shortcut} to start a PuTTY saved |
| 608 | session, this is the option you should use: your shortcut should |
| 609 | call something like |
| 610 | |
| 611 | \c d:\path\to\putty.exe -load "my session" |
| 612 | |
| 613 | (Note that PuTTY itself supports an alternative form of this option, |
| 614 | for backwards compatibility. If you execute \i\c{putty @sessionname} |
| 615 | it will have the same effect as \c{putty -load "sessionname"}. With |
| 616 | the \c{@} form, no double quotes are required, and the \c{@} sign |
| 617 | must be the very first thing on the command line. This form of the |
| 618 | option is deprecated.) |
| 619 | |
| 620 | \S2{using-cmdline-protocol} Selecting a protocol: \c{-ssh}, |
| 621 | \c{-telnet}, \c{-rlogin}, \c{-raw} |
| 622 | |
| 623 | To choose which protocol you want to connect with, you can use one |
| 624 | of these options: |
| 625 | |
| 626 | \b \i\c{-ssh} selects the SSH protocol. |
| 627 | |
| 628 | \b \i\c{-telnet} selects the Telnet protocol. |
| 629 | |
| 630 | \b \i\c{-rlogin} selects the Rlogin protocol. |
| 631 | |
| 632 | \b \i\c{-raw} selects the raw protocol. |
| 633 | |
| 634 | These options are not available in the file transfer tools PSCP and |
| 635 | PSFTP (which only work with the SSH protocol). |
| 636 | |
| 637 | These options are equivalent to the \i{protocol selection} buttons |
| 638 | in the Session panel of the PuTTY configuration box (see |
| 639 | \k{config-hostname}). |
| 640 | |
| 641 | \S2{using-cmdline-v} \i\c{-v}: increase verbosity |
| 642 | |
| 643 | \I{verbose mode}Most of the PuTTY tools can be made to tell you more |
| 644 | about what they are doing by supplying the \c{-v} option. If you are |
| 645 | having trouble when making a connection, or you're simply curious, |
| 646 | you can turn this switch on and hope to find out more about what is |
| 647 | happening. |
| 648 | |
| 649 | \S2{using-cmdline-l} \i\c{-l}: specify a \i{login name} |
| 650 | |
| 651 | You can specify the user name to log in as on the remote server |
| 652 | using the \c{-l} option. For example, \c{plink login.example.com -l |
| 653 | fred}. |
| 654 | |
| 655 | These options are equivalent to the username selection box in the |
| 656 | Connection panel of the PuTTY configuration box (see |
| 657 | \k{config-username}). |
| 658 | |
| 659 | \S2{using-cmdline-portfwd} \I{-L-upper}\c{-L}, \I{-R-upper}\c{-R} |
| 660 | and \I{-D-upper}\c{-D}: set up \i{port forwardings} |
| 661 | |
| 662 | As well as setting up port forwardings in the PuTTY configuration |
| 663 | (see \k{config-ssh-portfwd}), you can also set up forwardings on the |
| 664 | command line. The command-line options work just like the ones in |
| 665 | Unix \c{ssh} programs. |
| 666 | |
| 667 | To \I{local port forwarding}forward a local port (say 5110) to a |
| 668 | remote destination (say \cw{popserver.example.com} port 110), you |
| 669 | can write something like one of these: |
| 670 | |
| 671 | \c putty -L 5110:popserver.example.com:110 -load mysession |
| 672 | \c plink mysession -L 5110:popserver.example.com:110 |
| 673 | |
| 674 | To forward a \I{remote port forwarding}remote port to a local |
| 675 | destination, just use the \c{-R} option instead of \c{-L}: |
| 676 | |
| 677 | \c putty -R 5023:mytelnetserver.myhouse.org:23 -load mysession |
| 678 | \c plink mysession -R 5023:mytelnetserver.myhouse.org:23 |
| 679 | |
| 680 | To \I{listen address}specify an IP address for the listening end of the |
| 681 | tunnel, prepend it to the argument: |
| 682 | |
| 683 | \c plink -L 127.0.0.5:23:localhost:23 myhost |
| 684 | |
| 685 | To set up \I{dynamic port forwarding}SOCKS-based dynamic port |
| 686 | forwarding on a local port, use the \c{-D} option. For this one you |
| 687 | only have to pass the port number: |
| 688 | |
| 689 | \c putty -D 4096 -load mysession |
| 690 | |
| 691 | For general information on port forwarding, see |
| 692 | \k{using-port-forwarding}. |
| 693 | |
| 694 | These options are not available in the file transfer tools PSCP and |
| 695 | PSFTP. |
| 696 | |
| 697 | \S2{using-cmdline-m} \i\c{-m}: \I{reading commands from a file}read |
| 698 | a remote command or script from a file |
| 699 | |
| 700 | The \i\c{-m} option performs a similar function to the \q{\ii{Remote |
| 701 | command}} box in the SSH panel of the PuTTY configuration box (see |
| 702 | \k{config-command}). However, the \c{-m} option expects to be given |
| 703 | a local file name, and it will read a command from that file. |
| 704 | |
| 705 | With some servers (particularly Unix systems), you can even put |
| 706 | multiple lines in this file and execute more than one command in |
| 707 | sequence, or a whole shell script; but this is arguably an abuse, and |
| 708 | cannot be expected to work on all servers. In particular, it is known |
| 709 | \e{not} to work with certain \q{embedded} servers, such as \i{Cisco} |
| 710 | routers. |
| 711 | |
| 712 | This option is not available in the file transfer tools PSCP and |
| 713 | PSFTP. |
| 714 | |
| 715 | \S2{using-cmdline-p} \I{-P-upper}\c{-P}: specify a \i{port number} |
| 716 | |
| 717 | The \c{-P} option is used to specify the port number to connect to. If |
| 718 | you have a Telnet server running on port 9696 of a machine instead of |
| 719 | port 23, for example: |
| 720 | |
| 721 | \c putty -telnet -P 9696 host.name |
| 722 | \c plink -telnet -P 9696 host.name |
| 723 | |
| 724 | (Note that this option is more useful in Plink than in PuTTY, |
| 725 | because in PuTTY you can write \c{putty -telnet host.name 9696} in |
| 726 | any case.) |
| 727 | |
| 728 | This option is equivalent to the port number control in the Session |
| 729 | panel of the PuTTY configuration box (see \k{config-hostname}). |
| 730 | |
| 731 | \S2{using-cmdline-pw} \i\c{-pw}: specify a \i{password} |
| 732 | |
| 733 | A simple way to automate a remote login is to supply your password |
| 734 | on the command line. This is \e{not recommended} for reasons of |
| 735 | security. If you possibly can, we recommend you set up public-key |
| 736 | authentication instead. See \k{pubkey} for details. |
| 737 | |
| 738 | Note that the \c{-pw} option only works when you are using the SSH |
| 739 | protocol. Due to fundamental limitations of Telnet and Rlogin, these |
| 740 | protocols do not support automated password authentication. |
| 741 | |
| 742 | \S2{using-cmdline-agentauth} \i\c{-agent} and \i\c{-noagent}: |
| 743 | control use of Pageant for authentication |
| 744 | |
| 745 | The \c{-agent} option turns on SSH authentication using Pageant, and |
| 746 | \c{-noagent} turns it off. These options are only meaningful if you |
| 747 | are using SSH. |
| 748 | |
| 749 | See \k{pageant} for general information on \i{Pageant}. |
| 750 | |
| 751 | These options are equivalent to the agent authentication checkbox in |
| 752 | the Auth panel of the PuTTY configuration box (see |
| 753 | \k{config-ssh-tryagent}). |
| 754 | |
| 755 | \S2{using-cmdline-agent} \I{-A-upper}\c{-A} and \i\c{-a}: control \i{agent |
| 756 | forwarding} |
| 757 | |
| 758 | The \c{-A} option turns on SSH agent forwarding, and \c{-a} turns it |
| 759 | off. These options are only meaningful if you are using SSH. |
| 760 | |
| 761 | See \k{pageant} for general information on \i{Pageant}, and |
| 762 | \k{pageant-forward} for information on agent forwarding. Note that |
| 763 | there is a security risk involved with enabling this option; see |
| 764 | \k{pageant-security} for details. |
| 765 | |
| 766 | These options are equivalent to the agent forwarding checkbox in the |
| 767 | Auth panel of the PuTTY configuration box (see \k{config-ssh-agentfwd}). |
| 768 | |
| 769 | These options are not available in the file transfer tools PSCP and |
| 770 | PSFTP. |
| 771 | |
| 772 | \S2{using-cmdline-x11} \I{-X-upper}\c{-X} and \i\c{-x}: control \i{X11 |
| 773 | forwarding} |
| 774 | |
| 775 | The \c{-X} option turns on X11 forwarding in SSH, and \c{-x} turns |
| 776 | it off. These options are only meaningful if you are using SSH. |
| 777 | |
| 778 | For information on X11 forwarding, see \k{using-x-forwarding}. |
| 779 | |
| 780 | These options are equivalent to the X11 forwarding checkbox in the |
| 781 | X11 panel of the PuTTY configuration box (see \k{config-ssh-x11}). |
| 782 | |
| 783 | These options are not available in the file transfer tools PSCP and |
| 784 | PSFTP. |
| 785 | |
| 786 | \S2{using-cmdline-pty} \i\c{-t} and \I{-T-upper}\c{-T}: control |
| 787 | \i{pseudo-terminal allocation} |
| 788 | |
| 789 | The \c{-t} option ensures PuTTY attempts to allocate a |
| 790 | pseudo-terminal at the server, and \c{-T} stops it from allocating |
| 791 | one. These options are only meaningful if you are using SSH. |
| 792 | |
| 793 | These options are equivalent to the \q{Don't allocate a |
| 794 | pseudo-terminal} checkbox in the SSH panel of the PuTTY |
| 795 | configuration box (see \k{config-ssh-pty}). |
| 796 | |
| 797 | These options are not available in the file transfer tools PSCP and |
| 798 | PSFTP. |
| 799 | |
| 800 | \S2{using-cmdline-noshell} \I{-N-upper}\c{-N}: suppress starting a |
| 801 | \I{suppressing remote shell}shell or command |
| 802 | |
| 803 | The \c{-N} option prevents PuTTY from attempting to start a shell or |
| 804 | command on the remote server. You might want to use this option if |
| 805 | you are only using the SSH connection for port forwarding, and your |
| 806 | user account on the server does not have the ability to run a shell. |
| 807 | |
| 808 | This feature is only available in SSH protocol version 2 (since the |
| 809 | version 1 protocol assumes you will always want to run a shell). |
| 810 | |
| 811 | This option is equivalent to the \q{Don't start a shell or command |
| 812 | at all} checkbox in the SSH panel of the PuTTY configuration box |
| 813 | (see \k{config-ssh-noshell}). |
| 814 | |
| 815 | This option is not available in the file transfer tools PSCP and |
| 816 | PSFTP. |
| 817 | |
| 818 | \S2{using-cmdline-ncmode} \I{-nc}\c{-nc}: make a \i{remote network |
| 819 | connection} in place of a remote shell or command |
| 820 | |
| 821 | The \c{-nc} option prevents Plink (or PuTTY) from attempting to |
| 822 | start a shell or command on the remote server. Instead, it will |
| 823 | instruct the remote server to open a network connection to a host |
| 824 | name and port number specified by you, and treat that network |
| 825 | connection as if it were the main session. |
| 826 | |
| 827 | You specify a host and port as an argument to the \c{-nc} option, |
| 828 | with a colon separating the host name from the port number, like |
| 829 | this: |
| 830 | |
| 831 | \c plink host1.example.com -nc host2.example.com:1234 |
| 832 | |
| 833 | You might want to use this feature if you needed to make an SSH |
| 834 | connection to a target host which you can only reach by going |
| 835 | through a proxy host, and rather than using port forwarding you |
| 836 | prefer to use the local proxy feature (see \k{config-proxy-type} for |
| 837 | more about local proxies). In this situation you might select |
| 838 | \q{Local} proxy type, set your local proxy command to be \cq{plink |
| 839 | %proxyhost -nc %host:%port}, enter the target host name on the |
| 840 | Session panel, and enter the directly reachable proxy host name on |
| 841 | the Proxy panel. |
| 842 | |
| 843 | This feature is only available in SSH protocol version 2 (since the |
| 844 | version 1 protocol assumes you will always want to run a shell). It |
| 845 | is not available in the file transfer tools PSCP and PSFTP. It is |
| 846 | available in PuTTY itself, although it is unlikely to be very useful |
| 847 | in any tool other than Plink. Also, \c{-nc} uses the same server |
| 848 | functionality as port forwarding, so it will not work if your server |
| 849 | administrator has disabled port forwarding. |
| 850 | |
| 851 | (The option is named \c{-nc} after the Unix program |
| 852 | \W{http://www.vulnwatch.org/netcat/}\c{nc}, short for \q{netcat}. |
| 853 | The command \cq{plink host1 -nc host2:port} is very similar in |
| 854 | functionality to \cq{plink host1 nc host2 port}, which invokes |
| 855 | \c{nc} on the server and tells it to connect to the specified |
| 856 | destination. However, Plink's built-in \c{-nc} option does not |
| 857 | depend on the \c{nc} program being installed on the server.) |
| 858 | |
| 859 | \S2{using-cmdline-compress} \I{-C-upper}\c{-C}: enable \i{compression} |
| 860 | |
| 861 | The \c{-C} option enables compression of the data sent across the |
| 862 | network. This option is only meaningful if you are using SSH. |
| 863 | |
| 864 | This option is equivalent to the \q{Enable compression} checkbox in |
| 865 | the SSH panel of the PuTTY configuration box (see |
| 866 | \k{config-ssh-comp}). |
| 867 | |
| 868 | \S2{using-cmdline-sshprot} \i\c{-1} and \i\c{-2}: specify an \i{SSH |
| 869 | protocol version} |
| 870 | |
| 871 | The \c{-1} and \c{-2} options force PuTTY to use version \I{SSH-1}1 |
| 872 | or version \I{SSH-2}2 of the SSH protocol. These options are only |
| 873 | meaningful if you are using SSH. |
| 874 | |
| 875 | These options are equivalent to selecting your preferred SSH |
| 876 | protocol version as \q{1 only} or \q{2 only} in the SSH panel of the |
| 877 | PuTTY configuration box (see \k{config-ssh-prot}). |
| 878 | |
| 879 | \S2{using-cmdline-ipversion} \i\c{-4} and \i\c{-6}: specify an |
| 880 | \i{Internet protocol version} |
| 881 | |
| 882 | The \c{-4} and \c{-6} options force PuTTY to use the older Internet |
| 883 | protocol \i{IPv4} or the newer \i{IPv6} for most outgoing |
| 884 | connections. |
| 885 | |
| 886 | These options are equivalent to selecting your preferred Internet |
| 887 | protocol version as \q{IPv4} or \q{IPv6} in the Connection panel of |
| 888 | the PuTTY configuration box (see \k{config-address-family}). |
| 889 | |
| 890 | \S2{using-cmdline-identity} \i\c{-i}: specify an SSH \i{private key} |
| 891 | |
| 892 | The \c{-i} option allows you to specify the name of a private key |
| 893 | file in \c{*.\i{PPK}} format which PuTTY will use to authenticate with the |
| 894 | server. This option is only meaningful if you are using SSH. |
| 895 | |
| 896 | For general information on \i{public-key authentication}, see |
| 897 | \k{pubkey}. |
| 898 | |
| 899 | This option is equivalent to the \q{Private key file for |
| 900 | authentication} box in the Auth panel of the PuTTY configuration box |
| 901 | (see \k{config-ssh-privkey}). |
| 902 | |
| 903 | \S2{using-cmdline-loghost} \i\c{-loghost}: specify a \i{logical host |
| 904 | name} |
| 905 | |
| 906 | This option overrides PuTTY's normal SSH host key caching policy by |
| 907 | telling it the name of the host you expect your connection to end up |
| 908 | at (in cases where this differs from the location PuTTY thinks it's |
| 909 | connecting to). It can be a plain host name, or a host name followed |
| 910 | by a colon and a port number. See \k{config-loghost} for more detail |
| 911 | on this. |
| 912 | |
| 913 | \S2{using-cmdline-pgpfp} \i\c{-pgpfp}: display \i{PGP key fingerprint}s |
| 914 | |
| 915 | This option causes the PuTTY tools not to run as normal, but instead |
| 916 | to display the fingerprints of the PuTTY PGP Master Keys, in order to |
| 917 | aid with \i{verifying new versions}. See \k{pgpkeys} for more information. |