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