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.
7 \H{using-session} During your session
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.
14 \S{using-selection} Copying and pasting text
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.
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.
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.)
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.
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.
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.)
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.
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
79 \S{using-scrollback} \I{scrollback}Scrolling the screen back
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.
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.
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}.
96 \S{using-sysmenu} The \ii{System menu}
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.
103 PuTTY's system menu contains extra program features in addition to
104 the Windows standard options. These extra menu commands are
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}.)
111 \S2{using-eventlog} The PuTTY \i{Event Log}
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.
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.
124 \S2{using-specials} \ii{Special commands}
126 Depending on the protocol used for the current session, there may be
127 a submenu of \q{special commands}. These are protocol-specific
128 tokens, such as a \q{break} signal, that can be sent down a
129 connection in addition to normal data. Their precise effect is usually
130 up to the server. Currently only Telnet, SSH, and serial connections
131 have special commands.
133 The \q{break} signal can also be invoked from the keyboard with
136 The following \I{Telnet special commands}special commands are
139 \b \I{Are You There, Telnet special command}Are You There
141 \b \I{Break, Telnet special command}Break
143 \b \I{Synch, Telnet special command}Synch
145 \b \I{Erase Character, Telnet special command}Erase Character
148 PuTTY can also be configured to send this when the Backspace key is
149 pressed; see \k{config-telnetkey}.
152 \b \I{Erase Line, Telnet special command}Erase Line
154 \b \I{Go Ahead, Telnet special command}Go Ahead
156 \b \I{No Operation, Telnet special command}No Operation
159 Should have no effect.
162 \b \I{Abort Process, Telnet special command}Abort Process
164 \b \I{Abort Output, Telnet special command}Abort Output
166 \b \I{Interrupt Process, Telnet special command}Interrupt Process
169 PuTTY can also be configured to send this when Ctrl-C is typed; see
170 \k{config-telnetkey}.
173 \b \I{Suspend Process, Telnet special command}Suspend Process
176 PuTTY can also be configured to send this when Ctrl-Z is typed; see
177 \k{config-telnetkey}.
180 \b \I{End Of Record, Telnet special command}End Of Record
182 \b \I{End Of File, Telnet special command}End Of File
184 In an SSH connection, the following \I{SSH special commands}special
185 commands are available:
187 \b \I{IGNORE message, SSH special command}\I{No-op, in SSH}\ii{IGNORE message}
190 Should have no effect.
193 \b \I{Repeat key exchange, SSH special command}Repeat key exchange
196 Only available in SSH-2. Forces a \i{repeat key exchange} immediately (and
197 resets associated timers and counters). For more information about
198 repeat key exchanges, see \k{config-ssh-kex-rekey}.
201 \b \I{Break, SSH special command}Break
204 Only available in SSH-2, and only during a session. Optional
205 extension; may not be supported by server. PuTTY requests the server's
206 default break length.
209 \b \I{Signal, SSH special command}Signals (SIGINT, SIGTERM etc)
212 Only available in SSH-2, and only during a session. Sends various
213 POSIX signals. Not honoured by all servers.
216 With a serial connection, the only available special command is
217 \I{Break, serial special command}\q{Break}.
219 \S2{using-newsession} Starting new sessions
221 PuTTY's system menu provides some shortcut ways to start new
224 \b Selecting \i{\q{New Session}} will start a completely new
225 instance of PuTTY, and bring up the configuration box as normal.
227 \b Selecting \i{\q{Duplicate Session}} will start a session in a
228 new window with precisely the same options as your current one -
229 connecting to the same host using the same protocol, with all the
230 same terminal settings and everything.
232 \b In an inactive window, selecting \i{\q{Restart Session}} will
233 do the same as \q{Duplicate Session}, but in the current window.
235 \b The \i{\q{Saved Sessions} submenu} gives you quick access to any
236 sets of stored session details you have previously saved. See
237 \k{config-saving} for details of how to create saved sessions.
239 \S2{using-changesettings} \I{settings, changing}Changing your
242 If you select \i{\q{Change Settings}} from the system menu, PuTTY will
243 display a cut-down version of its initial configuration box. This
244 allows you to adjust most properties of your current session. You
245 can change the terminal size, the font, the actions of various
246 keypresses, the colours, and so on.
248 Some of the options that are available in the main configuration box
249 are not shown in the cut-down Change Settings box. These are usually
250 options which don't make sense to change in the middle of a session
251 (for example, you can't switch from SSH to Telnet in mid-session).
253 You can save the current settings to a saved session for future use
254 from this dialog box. See \k{config-saving} for more on saved
257 \S2{using-copyall} \i{Copy All to Clipboard}
259 This system menu option provides a convenient way to copy the whole
260 contents of the terminal screen (up to the last nonempty line) and
261 scrollback to the \i{clipboard} in one go.
263 \S2{reset-terminal} \I{scrollback, clearing}Clearing and
264 \I{terminal, resetting}resetting the terminal
266 The \i{\q{Clear Scrollback}} option on the system menu tells PuTTY
267 to discard all the lines of text that have been kept after they
268 scrolled off the top of the screen. This might be useful, for
269 example, if you displayed sensitive information and wanted to make
270 sure nobody could look over your shoulder and see it. (Note that
271 this only prevents a casual user from using the scrollbar to view
272 the information; the text is not guaranteed not to still be in
275 The \i{\q{Reset Terminal}} option causes a full reset of the
276 \i{terminal emulation}. A VT-series terminal is a complex piece of
277 software and can easily get into a state where all the text printed
278 becomes unreadable. (This can happen, for example, if you
279 accidentally output a binary file to your terminal.) If this
280 happens, selecting Reset Terminal should sort it out.
282 \S2{using-fullscreen} \ii{Full screen} mode
284 If you find the title bar on a maximised window to be ugly or
285 distracting, you can select Full Screen mode to maximise PuTTY
286 \q{even more}. When you select this, PuTTY will expand to fill the
287 whole screen and its borders, title bar and scrollbar will
288 disappear. (You can configure the scrollbar not to disappear in
289 full-screen mode if you want to keep it; see \k{config-scrollback}.)
291 When you are in full-screen mode, you can still access the \i{system
292 menu} if you click the left mouse button in the \e{extreme} top left
293 corner of the screen.
295 \H{using-logging} Creating a \i{log file} of your \I{session
298 For some purposes you may find you want to log everything that
299 appears on your screen. You can do this using the \q{Logging}
300 panel in the configuration box.
302 To begin a session log, select \q{Change Settings} from the system
303 menu and go to the Logging panel. Enter a log file name, and select
304 a logging mode. (You can log all session output including the
305 terminal \i{control sequence}s, or you can just log the printable text.
306 It depends what you want the log for.) Click \q{Apply} and your log
307 will be started. Later on, you can go back to the Logging panel and
308 select \q{Logging turned off completely} to stop logging; then PuTTY
309 will close the log file and you can safely read it.
311 See \k{config-logging} for more details and options.
313 \H{using-translation} Altering your \i{character set} configuration
315 If you find that special characters (\i{accented characters}, for
316 example, or \i{line-drawing characters}) are not being displayed
317 correctly in your PuTTY session, it may be that PuTTY is interpreting
318 the characters sent by the server according to the wrong \e{character
319 set}. There are a lot of different character sets available, so it's
320 entirely possible for this to happen.
322 If you click \q{Change Settings} and look at the \q{Translation}
323 panel, you should see a large number of character sets which you can
324 select, and other related options. Now all you need is to find out
325 which of them you want! (See \k{config-translation} for more
328 \H{using-x-forwarding} Using \i{X11 forwarding} in SSH
330 The SSH protocol has the ability to securely forward X Window System
331 \i{graphical applications} over your encrypted SSH connection, so that
332 you can run an application on the SSH server machine and have it put
333 its windows up on your local machine without sending any X network
334 traffic in the clear.
336 In order to use this feature, you will need an X display server for
337 your Windows machine, such as Cygwin/X, X-Win32, or Exceed. This will probably
338 install itself as display number 0 on your local machine; if it
339 doesn't, the manual for the \i{X server} should tell you what it
342 You should then tick the \q{Enable X11 forwarding} box in the
343 X11 panel (see \k{config-ssh-x11}) before starting your SSH
344 session. The \i{\q{X display location}} box is blank by default, which
345 means that PuTTY will try to use a sensible default such as \c{:0},
346 which is the usual display location where your X server will be
347 installed. If that needs changing, then change it.
349 Now you should be able to log in to the SSH server as normal. To
350 check that X forwarding has been successfully negotiated during
351 connection startup, you can check the PuTTY Event Log (see
352 \k{using-eventlog}). It should say something like this:
354 \c 2001-12-05 17:22:01 Requesting X11 forwarding
355 \c 2001-12-05 17:22:02 X11 forwarding enabled
357 If the remote system is Unix or Unix-like, you should also be able
358 to see that the \i{\c{DISPLAY} environment variable} has been set to
359 point at display 10 or above on the SSH server machine itself:
361 \c fred@unixbox:~$ echo $DISPLAY
364 If this works, you should then be able to run X applications in the
365 remote session and have them display their windows on your PC.
367 For more options relating to X11 forwarding, see \k{config-ssh-x11}.
369 \H{using-port-forwarding} Using \i{port forwarding} in SSH
371 The SSH protocol has the ability to forward arbitrary \I{network
372 connection}network (TCP) connections over your encrypted SSH
373 connection, to avoid the network traffic being sent in clear. For
374 example, you could use this to connect from your home computer to a
375 \i{POP-3} server on a remote machine without your POP-3 password being
376 visible to network sniffers.
378 In order to use port forwarding to \I{local port forwarding}connect
379 from your local machine to a port on a remote server, you need to:
381 \b Choose a \i{port number} on your local machine where PuTTY should
382 listen for incoming connections. There are likely to be plenty of
383 unused port numbers above 3000. (You can also use a local loopback
384 address here; see below for more details.)
386 \b Now, before you start your SSH connection, go to the Tunnels
387 panel (see \k{config-ssh-portfwd}). Make sure the \q{Local} radio
388 button is set. Enter the local port number into the \q{Source port}
389 box. Enter the destination host name and port number into the
390 \q{Destination} box, separated by a colon (for example,
391 \c{popserver.example.com:110} to connect to a POP-3 server).
393 \b Now click the \q{Add} button. The details of your port forwarding
394 should appear in the list box.
396 Now start your session and log in. (Port forwarding will not be
397 enabled until after you have logged in; otherwise it would be easy
398 to perform completely anonymous network attacks, and gain access to
399 anyone's virtual private network.) To check that PuTTY has set up
400 the port forwarding correctly, you can look at the PuTTY Event Log
401 (see \k{using-eventlog}). It should say something like this:
403 \c 2001-12-05 17:22:10 Local port 3110 forwarding to
404 \c popserver.example.com:110
406 Now if you connect to the source port number on your local PC, you
407 should find that it answers you exactly as if it were the service
408 running on the destination machine. So in this example, you could
409 then configure an e-mail client to use \c{localhost:3110} as a POP-3
410 server instead of \c{popserver.example.com:110}. (Of course, the
411 forwarding will stop happening when your PuTTY session closes down.)
413 You can also forward ports in the other direction: arrange for a
414 particular port number on the \e{server} machine to be \I{remote
415 port forwarding}forwarded back to your PC as a connection to a
416 service on your PC or near it.
417 To do this, just select the \q{Remote} radio button instead of the
418 \q{Local} one. The \q{Source port} box will now specify a port
419 number on the \e{server} (note that most servers will not allow you
420 to use \I{privileged port}port numbers under 1024 for this purpose).
422 An alternative way to forward local connections to remote hosts is
423 to use \I{dynamic port forwarding}dynamic SOCKS proxying. In this
424 mode, PuTTY acts as a SOCKS server, which SOCKS-aware programs can
425 connect to and open forwarded connections to the destination of their
426 choice, so this can be an alternative to long lists of static
427 forwardings. To use this mode, you will need to select the \q{Dynamic}
428 radio button instead of \q{Local}, and then you should not enter
429 anything into the \q{Destination} box (it will be ignored). PuTTY will
430 then listen for SOCKS connections on the port you have specified.
431 Most \i{web browsers} can be configured to connect to this SOCKS proxy
432 service; also, you can forward other PuTTY connections through it by
433 setting up the Proxy control panel (see \k{config-proxy} for details).
435 The source port for a forwarded connection usually does not accept
436 connections from any machine except the \I{localhost}SSH client or
437 server machine itself (for local and remote forwardings respectively).
438 There are controls in the Tunnels panel to change this:
440 \b The \q{Local ports accept connections from other hosts} option
441 allows you to set up local-to-remote port forwardings (including
442 dynamic port forwardings) in such a way that machines other than
443 your client PC can connect to the forwarded port.
445 \b The \q{Remote ports do the same} option does the same thing for
446 remote-to-local port forwardings (so that machines other than the
447 SSH server machine can connect to the forwarded port.) Note that
448 this feature is only available in the SSH-2 protocol, and not all
449 SSH-2 servers honour it (in \i{OpenSSH}, for example, it's usually
450 disabled by default).
452 You can also specify an \i{IP address} to \I{listen address}listen
453 on. Typically a Windows machine can be asked to listen on any single
454 IP address in the \cw{127.*.*.*} range, and all of these are
455 \i{loopback address}es available only to the local machine. So if
456 you forward (for example) \c{127.0.0.5:79} to a remote machine's
457 \i\cw{finger} port, then you should be able to run commands such as
458 \c{finger fred@127.0.0.5}.
459 This can be useful if the program connecting to the forwarded port
460 doesn't allow you to change the port number it uses. This feature is
461 available for local-to-remote forwarded ports; SSH-1 is unable to
462 support it for remote-to-local ports, while SSH-2 can support it in
463 theory but servers will not necessarily cooperate.
465 (Note that if you're using Windows XP Service Pack 2, you may need
466 to obtain a fix from Microsoft in order to use addresses like
467 \cw{127.0.0.5} - see \k{faq-alternate-localhost}.)
469 For more options relating to port forwarding, see
470 \k{config-ssh-portfwd}.
472 If the connection you are forwarding over SSH is itself a second SSH
473 connection made by another copy of PuTTY, you might find the
474 \q{logical host name} configuration option useful to warn PuTTY of
475 which host key it should be expecting. See \k{config-loghost} for
478 \H{using-rawprot} Making \i{raw TCP connections}
480 A lot of \I{debugging Internet protocols}Internet protocols are
481 composed of commands and responses in plain text. For example,
482 \i{SMTP} (the protocol used to transfer e-mail), \i{NNTP} (the
483 protocol used to transfer Usenet news), and \i{HTTP} (the protocol
484 used to serve Web pages) all consist of commands in readable plain
487 Sometimes it can be useful to connect directly to one of these
488 services and speak the protocol \q{by hand}, by typing protocol
489 commands and watching the responses. On Unix machines, you can do
490 this using the system's \c{telnet} command to connect to the right
491 port number. For example, \c{telnet mailserver.example.com 25} might
492 enable you to talk directly to the SMTP service running on a mail
495 Although the Unix \c{telnet} program provides this functionality,
496 the protocol being used is not really Telnet. Really there is no
497 actual protocol at all; the bytes sent down the connection are
498 exactly the ones you type, and the bytes shown on the screen are
499 exactly the ones sent by the server. Unix \c{telnet} will attempt to
500 detect or guess whether the service it is talking to is a real
501 Telnet service or not; PuTTY prefers to be told for certain.
503 In order to make a debugging connection to a service of this type,
504 you simply select the fourth protocol name, \I{\q{Raw}
505 protocol}\q{Raw}, from the \q{Protocol} buttons in the \q{Session}
506 configuration panel. (See \k{config-hostname}.) You can then enter a
507 host name and a port number, and make the connection.
509 \H{using-serial} Connecting to a local serial line
511 PuTTY can connect directly to a local serial line as an alternative
512 to making a network connection. In this mode, text typed into the
513 PuTTY window will be sent straight out of your computer's serial
514 port, and data received through that port will be displayed in the
515 PuTTY window. You might use this mode, for example, if your serial
516 port is connected to another computer which has a serial connection.
518 To make a connection of this type, simply select \q{Serial} from the
519 \q{Connection type} radio buttons on the \q{Session} configuration
520 panel (see \k{config-hostname}). The \q{Host Name} and \q{Port}
521 boxes will transform into \q{Serial line} and \q{Speed}, allowing
522 you to specify which serial line to use (if your computer has more
523 than one) and what speed (baud rate) to use when transferring data.
524 For further configuration options (data bits, stop bits, parity,
525 flow control), you can use the \q{Serial} configuration panel (see
528 After you start up PuTTY in serial mode, you might find that you
529 have to make the first move, by sending some data out of the serial
530 line in order to notify the device at the other end that someone is
531 there for it to talk to. This probably depends on the device. If you
532 start up a PuTTY serial session and nothing appears in the window,
533 try pressing Return a few times and see if that helps.
535 A serial line provides no well defined means for one end of the
536 connection to notify the other that the connection is finished.
537 Therefore, PuTTY in serial mode will remain connected until you
538 close the window using the close button.
540 \H{using-cmdline} The PuTTY command line
542 PuTTY can be made to do various things without user intervention by
543 supplying \i{command-line arguments} (e.g., from a \i{command prompt
544 window}, or a \i{Windows shortcut}).
546 \S{using-cmdline-session} Starting a session from the command line
548 \I\c{-ssh}\I\c{-telnet}\I\c{-rlogin}\I\c{-raw}\I\c{-serial}These
549 options allow you to bypass the configuration window and launch
550 straight into a session.
552 To start a connection to a server called \c{host}:
554 \c putty.exe [-ssh | -telnet | -rlogin | -raw] [user@]host
556 If this syntax is used, settings are taken from the \i{Default Settings}
557 (see \k{config-saving}); \c{user} overrides these settings if
558 supplied. Also, you can specify a protocol, which will override the
559 default protocol (see \k{using-cmdline-protocol}).
561 For telnet sessions, the following alternative syntax is supported
562 (this makes PuTTY suitable for use as a URL handler for \i{telnet
563 URLs} in \i{web browsers}):
565 \c putty.exe telnet://host[:port]/
567 To start a connection to a serial port, e.g. COM1:
569 \c putty.exe -serial com1
571 In order to start an existing saved session called \c{sessionname},
572 use the \c{-load} option (described in \k{using-cmdline-load}).
574 \c putty.exe -load "session name"
576 \S{using-cleanup} \i\c{-cleanup}
578 \cfg{winhelp-topic}{options.cleanup}
580 If invoked with the \c{-cleanup} option, rather than running as
581 normal, PuTTY will remove its \I{removing registry entries}registry
582 entries and \i{random seed file} from the local machine (after
583 confirming with the user).
585 Note that on \i{multi-user systems}, \c{-cleanup} only removes
586 registry entries and files associated with the currently logged-in
589 \S{using-general-opts} Standard command-line options
591 PuTTY and its associated tools support a range of command-line
592 options, most of which are consistent across all the tools. This
593 section lists the available options in all tools. Options which are
594 specific to a particular tool are covered in the chapter about that
597 \S2{using-cmdline-load} \i\c{-load}: load a saved session
599 \I{saved sessions, loading from command line}The \c{-load} option
600 causes PuTTY to load configuration details out of a saved session.
601 If these details include a host name, then this option is all you
602 need to make PuTTY start a session.
604 You need double quotes around the session name if it contains spaces.
606 If you want to create a \i{Windows shortcut} to start a PuTTY saved
607 session, this is the option you should use: your shortcut should
610 \c d:\path\to\putty.exe -load "my session"
612 (Note that PuTTY itself supports an alternative form of this option,
613 for backwards compatibility. If you execute \i\c{putty @sessionname}
614 it will have the same effect as \c{putty -load "sessionname"}. With
615 the \c{@} form, no double quotes are required, and the \c{@} sign
616 must be the very first thing on the command line. This form of the
617 option is deprecated.)
619 \S2{using-cmdline-protocol} Selecting a protocol: \c{-ssh},
620 \c{-telnet}, \c{-rlogin}, \c{-raw} \c{-serial}
622 To choose which protocol you want to connect with, you can use one
625 \b \i\c{-ssh} selects the SSH protocol.
627 \b \i\c{-telnet} selects the Telnet protocol.
629 \b \i\c{-rlogin} selects the Rlogin protocol.
631 \b \i\c{-raw} selects the raw protocol.
633 \b \i\c{-serial} selects a serial connection.
635 These options are not available in the file transfer tools PSCP and
636 PSFTP (which only work with the SSH protocol).
638 These options are equivalent to the \i{protocol selection} buttons
639 in the Session panel of the PuTTY configuration box (see
640 \k{config-hostname}).
642 \S2{using-cmdline-v} \i\c{-v}: increase verbosity
644 \I{verbose mode}Most of the PuTTY tools can be made to tell you more
645 about what they are doing by supplying the \c{-v} option. If you are
646 having trouble when making a connection, or you're simply curious,
647 you can turn this switch on and hope to find out more about what is
650 \S2{using-cmdline-l} \i\c{-l}: specify a \i{login name}
652 You can specify the user name to log in as on the remote server
653 using the \c{-l} option. For example, \c{plink login.example.com -l
656 These options are equivalent to the username selection box in the
657 Connection panel of the PuTTY configuration box (see
658 \k{config-username}).
660 \S2{using-cmdline-portfwd} \I{-L-upper}\c{-L}, \I{-R-upper}\c{-R}
661 and \I{-D-upper}\c{-D}: set up \i{port forwardings}
663 As well as setting up port forwardings in the PuTTY configuration
664 (see \k{config-ssh-portfwd}), you can also set up forwardings on the
665 command line. The command-line options work just like the ones in
666 Unix \c{ssh} programs.
668 To \I{local port forwarding}forward a local port (say 5110) to a
669 remote destination (say \cw{popserver.example.com} port 110), you
670 can write something like one of these:
672 \c putty -L 5110:popserver.example.com:110 -load mysession
673 \c plink mysession -L 5110:popserver.example.com:110
675 To forward a \I{remote port forwarding}remote port to a local
676 destination, just use the \c{-R} option instead of \c{-L}:
678 \c putty -R 5023:mytelnetserver.myhouse.org:23 -load mysession
679 \c plink mysession -R 5023:mytelnetserver.myhouse.org:23
681 To \I{listen address}specify an IP address for the listening end of the
682 tunnel, prepend it to the argument:
684 \c plink -L 127.0.0.5:23:localhost:23 myhost
686 To set up \I{dynamic port forwarding}SOCKS-based dynamic port
687 forwarding on a local port, use the \c{-D} option. For this one you
688 only have to pass the port number:
690 \c putty -D 4096 -load mysession
692 For general information on port forwarding, see
693 \k{using-port-forwarding}.
695 These options are not available in the file transfer tools PSCP and
698 \S2{using-cmdline-m} \i\c{-m}: \I{reading commands from a file}read
699 a remote command or script from a file
701 The \i\c{-m} option performs a similar function to the \q{\ii{Remote
702 command}} box in the SSH panel of the PuTTY configuration box (see
703 \k{config-command}). However, the \c{-m} option expects to be given
704 a local file name, and it will read a command from that file.
706 With some servers (particularly Unix systems), you can even put
707 multiple lines in this file and execute more than one command in
708 sequence, or a whole shell script; but this is arguably an abuse, and
709 cannot be expected to work on all servers. In particular, it is known
710 \e{not} to work with certain \q{embedded} servers, such as \i{Cisco}
713 This option is not available in the file transfer tools PSCP and
716 \S2{using-cmdline-p} \I{-P-upper}\c{-P}: specify a \i{port number}
718 The \c{-P} option is used to specify the port number to connect to. If
719 you have a Telnet server running on port 9696 of a machine instead of
720 port 23, for example:
722 \c putty -telnet -P 9696 host.name
723 \c plink -telnet -P 9696 host.name
725 (Note that this option is more useful in Plink than in PuTTY,
726 because in PuTTY you can write \c{putty -telnet host.name 9696} in
729 This option is equivalent to the port number control in the Session
730 panel of the PuTTY configuration box (see \k{config-hostname}).
732 \S2{using-cmdline-pw} \i\c{-pw}: specify a \i{password}
734 A simple way to automate a remote login is to supply your password
735 on the command line. This is \e{not recommended} for reasons of
736 security. If you possibly can, we recommend you set up public-key
737 authentication instead. See \k{pubkey} for details.
739 Note that the \c{-pw} option only works when you are using the SSH
740 protocol. Due to fundamental limitations of Telnet and Rlogin, these
741 protocols do not support automated password authentication.
743 \S2{using-cmdline-agentauth} \i\c{-agent} and \i\c{-noagent}:
744 control use of Pageant for authentication
746 The \c{-agent} option turns on SSH authentication using Pageant, and
747 \c{-noagent} turns it off. These options are only meaningful if you
750 See \k{pageant} for general information on \i{Pageant}.
752 These options are equivalent to the agent authentication checkbox in
753 the Auth panel of the PuTTY configuration box (see
754 \k{config-ssh-tryagent}).
756 \S2{using-cmdline-agent} \I{-A-upper}\c{-A} and \i\c{-a}: control \i{agent
759 The \c{-A} option turns on SSH agent forwarding, and \c{-a} turns it
760 off. These options are only meaningful if you are using SSH.
762 See \k{pageant} for general information on \i{Pageant}, and
763 \k{pageant-forward} for information on agent forwarding. Note that
764 there is a security risk involved with enabling this option; see
765 \k{pageant-security} for details.
767 These options are equivalent to the agent forwarding checkbox in the
768 Auth panel of the PuTTY configuration box (see \k{config-ssh-agentfwd}).
770 These options are not available in the file transfer tools PSCP and
773 \S2{using-cmdline-x11} \I{-X-upper}\c{-X} and \i\c{-x}: control \i{X11
776 The \c{-X} option turns on X11 forwarding in SSH, and \c{-x} turns
777 it off. These options are only meaningful if you are using SSH.
779 For information on X11 forwarding, see \k{using-x-forwarding}.
781 These options are equivalent to the X11 forwarding checkbox in the
782 X11 panel of the PuTTY configuration box (see \k{config-ssh-x11}).
784 These options are not available in the file transfer tools PSCP and
787 \S2{using-cmdline-pty} \i\c{-t} and \I{-T-upper}\c{-T}: control
788 \i{pseudo-terminal allocation}
790 The \c{-t} option ensures PuTTY attempts to allocate a
791 pseudo-terminal at the server, and \c{-T} stops it from allocating
792 one. These options are only meaningful if you are using SSH.
794 These options are equivalent to the \q{Don't allocate a
795 pseudo-terminal} checkbox in the SSH panel of the PuTTY
796 configuration box (see \k{config-ssh-pty}).
798 These options are not available in the file transfer tools PSCP and
801 \S2{using-cmdline-noshell} \I{-N-upper}\c{-N}: suppress starting a
802 \I{suppressing remote shell}shell or command
804 The \c{-N} option prevents PuTTY from attempting to start a shell or
805 command on the remote server. You might want to use this option if
806 you are only using the SSH connection for port forwarding, and your
807 user account on the server does not have the ability to run a shell.
809 This feature is only available in SSH protocol version 2 (since the
810 version 1 protocol assumes you will always want to run a shell).
812 This option is equivalent to the \q{Don't start a shell or command
813 at all} checkbox in the SSH panel of the PuTTY configuration box
814 (see \k{config-ssh-noshell}).
816 This option is not available in the file transfer tools PSCP and
819 \S2{using-cmdline-ncmode} \I{-nc}\c{-nc}: make a \i{remote network
820 connection} in place of a remote shell or command
822 The \c{-nc} option prevents Plink (or PuTTY) from attempting to
823 start a shell or command on the remote server. Instead, it will
824 instruct the remote server to open a network connection to a host
825 name and port number specified by you, and treat that network
826 connection as if it were the main session.
828 You specify a host and port as an argument to the \c{-nc} option,
829 with a colon separating the host name from the port number, like
832 \c plink host1.example.com -nc host2.example.com:1234
834 You might want to use this feature if you needed to make an SSH
835 connection to a target host which you can only reach by going
836 through a proxy host, and rather than using port forwarding you
837 prefer to use the local proxy feature (see \k{config-proxy-type} for
838 more about local proxies). In this situation you might select
839 \q{Local} proxy type, set your local proxy command to be \cq{plink
840 %proxyhost -nc %host:%port}, enter the target host name on the
841 Session panel, and enter the directly reachable proxy host name on
844 This feature is only available in SSH protocol version 2 (since the
845 version 1 protocol assumes you will always want to run a shell). It
846 is not available in the file transfer tools PSCP and PSFTP. It is
847 available in PuTTY itself, although it is unlikely to be very useful
848 in any tool other than Plink. Also, \c{-nc} uses the same server
849 functionality as port forwarding, so it will not work if your server
850 administrator has disabled port forwarding.
852 (The option is named \c{-nc} after the Unix program
853 \W{http://www.vulnwatch.org/netcat/}\c{nc}, short for \q{netcat}.
854 The command \cq{plink host1 -nc host2:port} is very similar in
855 functionality to \cq{plink host1 nc host2 port}, which invokes
856 \c{nc} on the server and tells it to connect to the specified
857 destination. However, Plink's built-in \c{-nc} option does not
858 depend on the \c{nc} program being installed on the server.)
860 \S2{using-cmdline-compress} \I{-C-upper}\c{-C}: enable \i{compression}
862 The \c{-C} option enables compression of the data sent across the
863 network. This option is only meaningful if you are using SSH.
865 This option is equivalent to the \q{Enable compression} checkbox in
866 the SSH panel of the PuTTY configuration box (see
867 \k{config-ssh-comp}).
869 \S2{using-cmdline-sshprot} \i\c{-1} and \i\c{-2}: specify an \i{SSH
872 The \c{-1} and \c{-2} options force PuTTY to use version \I{SSH-1}1
873 or version \I{SSH-2}2 of the SSH protocol. These options are only
874 meaningful if you are using SSH.
876 These options are equivalent to selecting your preferred SSH
877 protocol version as \q{1 only} or \q{2 only} in the SSH panel of the
878 PuTTY configuration box (see \k{config-ssh-prot}).
880 \S2{using-cmdline-ipversion} \i\c{-4} and \i\c{-6}: specify an
881 \i{Internet protocol version}
883 The \c{-4} and \c{-6} options force PuTTY to use the older Internet
884 protocol \i{IPv4} or the newer \i{IPv6} for most outgoing
887 These options are equivalent to selecting your preferred Internet
888 protocol version as \q{IPv4} or \q{IPv6} in the Connection panel of
889 the PuTTY configuration box (see \k{config-address-family}).
891 \S2{using-cmdline-identity} \i\c{-i}: specify an SSH \i{private key}
893 The \c{-i} option allows you to specify the name of a private key
894 file in \c{*.\i{PPK}} format which PuTTY will use to authenticate with the
895 server. This option is only meaningful if you are using SSH.
897 For general information on \i{public-key authentication}, see
900 This option is equivalent to the \q{Private key file for
901 authentication} box in the Auth panel of the PuTTY configuration box
902 (see \k{config-ssh-privkey}).
904 \S2{using-cmdline-loghost} \i\c{-loghost}: specify a \i{logical host
907 This option overrides PuTTY's normal SSH host key caching policy by
908 telling it the name of the host you expect your connection to end up
909 at (in cases where this differs from the location PuTTY thinks it's
910 connecting to). It can be a plain host name, or a host name followed
911 by a colon and a port number. See \k{config-loghost} for more detail
914 \S2{using-cmdline-hostkey} \i\c{-hostkey}: \I{manually configuring
915 host keys}manually specify an expected host key
917 This option overrides PuTTY's normal SSH host key caching policy by
918 telling it exactly what host key to expect, which can be useful if the
919 normal automatic host key store in the Registry is unavailable. The
920 argument to this option should be either a host key fingerprint, or an
921 SSH-2 public key blob. See \k{config-ssh-kex-manual-hostkeys} for more
924 You can specify this option more than once if you want to configure
925 more than one key to be accepted.
927 \S2{using-cmdline-pgpfp} \i\c{-pgpfp}: display \i{PGP key fingerprint}s
929 This option causes the PuTTY tools not to run as normal, but instead
930 to display the fingerprints of the PuTTY PGP Master Keys, in order to
931 aid with \i{verifying new versions}. See \k{pgpkeys} for more information.
933 \S2{using-cmdline-sercfg} \i\c{-sercfg}: specify serial port
936 This option specifies the configuration parameters for the serial
937 port (baud rate, stop bits etc). Its argument is interpreted as a
938 comma-separated list of configuration options, which can be as
941 \b Any single digit from 5 to 9 sets the number of data bits.
943 \b \cq{1}, \cq{1.5} or \cq{2} sets the number of stop bits.
945 \b Any other numeric string is interpreted as a baud rate.
947 \b A single lower-case letter specifies the parity: \cq{n} for none,
948 \cq{o} for odd, \cq{e} for even, \cq{m} for mark and \cq{s} for space.
950 \b A single upper-case letter specifies the flow control: \cq{N} for
951 none, \cq{X} for XON/XOFF, \cq{R} for RTS/CTS and \cq{D} for
954 For example, \cq{-sercfg 19200,8,n,1,N} denotes a baud rate of
955 19200, 8 data bits, no parity, 1 stop bit and no flow control.