1 \define{versionidusing} \versionid $Id$
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.
9 \H{using-session} During your session
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.
16 \S{using-selection} Copying and pasting text
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.
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.
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.)
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.
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.)
63 If you have a \i{middle mouse button}, then you can use it to
64 \I{adjusting a selection}adjust an existing selection if you
65 selected something slightly wrong. (If you have configured the
66 middle mouse button to paste, then the right mouse button does this
67 instead.) Click the button on the screen, and you can pick up the
68 nearest end of the selection and drag it to somewhere else.
70 It's possible for the server to ask to \I{mouse reporting}handle mouse
71 clicks in the PuTTY window itself. If this happens, the \i{mouse pointer}
72 will turn into an arrow, and using the mouse to copy and paste will only
73 work if you hold down Shift. See \k{config-features-mouse} and
74 \k{config-mouseshift} for details of this feature and how to configure
77 \S{using-scrollback} \I{scrollback}Scrolling the screen back
79 PuTTY keeps track of text that has scrolled up off the top of the
80 terminal. So if something appears on the screen that you want to
81 read, but it scrolls too fast and it's gone by the time you try to
82 look for it, you can use the \i{scrollbar} on the right side of the
83 window to look back up the session \i{history} and find it again.
85 As well as using the scrollbar, you can also page the scrollback up
86 and down by pressing \i{Shift-PgUp} and \i{Shift-PgDn}. You can
87 scroll a line at a time using \i{Ctrl-PgUp} and \i{Ctrl-PgDn}. These
88 are still available if you configure the scrollbar to be invisible.
90 By default the last 200 lines scrolled off the top are
91 preserved for you to look at. You can increase (or decrease) this
92 value using the configuration box; see \k{config-scrollback}.
94 \S{using-sysmenu} The \ii{System menu}
96 If you click the left mouse button on the icon in the top left
97 corner of PuTTY's terminal window, or click the right mouse button
98 on the title bar, you will see the standard Windows system menu
99 containing items like Minimise, Move, Size and Close.
101 PuTTY's system menu contains extra program features in addition to
102 the Windows standard options. These extra menu commands are
105 (These options are also available in a \i{context menu} brought up
106 by holding Ctrl and clicking with the right mouse button anywhere
107 in the \i{PuTTY window}.)
109 \S2{using-eventlog} The PuTTY \i{Event Log}
111 If you choose \q{Event Log} from the system menu, a small window
112 will pop up in which PuTTY logs significant events during the
113 connection. Most of the events in the log will probably take place
114 during session startup, but a few can occur at any point in the
115 session, and one or two occur right at the end.
117 You can use the mouse to select one or more lines of the Event Log,
118 and hit the Copy button to copy them to the \i{clipboard}. If you
119 are reporting a bug, it's often useful to paste the contents of the
120 Event Log into your bug report.
122 \S2{using-specials} \ii{Special commands}
124 Depending on the protocol used for the current session, there may be
125 a submenu of \q{special commands}. These are protocol-specific
126 tokens, such as a \i{\q{break} signal}, that can be sent down a
127 connection in addition to normal data. Their precise effect is usually
128 up to the server. Currently only Telnet and SSH have special commands.
130 The following \I{Telnet special commands}special commands are
133 \b \I{Are You There, Telnet special command}Are You There
135 \b \I{Break, Telnet special command}Break
137 \b \I{Synch, Telnet special command}Synch
139 \b \I{Erase Character, Telnet special command}Erase Character
142 PuTTY can also be configured to send this when the Backspace key is
143 pressed; see \k{config-telnetkey}.
146 \b \I{Erase Line, Telnet special command}Erase Line
148 \b \I{Go Ahead, Telnet special command}Go Ahead
150 \b \I{No Operation, Telnet special command}No Operation
153 Should have no effect.
156 \b \I{Abort Process, Telnet special command}Abort Process
158 \b \I{Abort Output, Telnet special command}Abort Output
160 \b \I{Interrupt Process, Telnet special command}Interrupt Process
163 PuTTY can also be configured to send this when Ctrl-C is typed; see
164 \k{config-telnetkey}.
167 \b \I{Suspend Process, Telnet special command}Suspend Process
170 PuTTY can also be configured to send this when Ctrl-Z is typed; see
171 \k{config-telnetkey}.
174 \b \I{End Of Record, Telnet special command}End Of Record
176 \b \I{End Of File, Telnet special command}End Of File
178 In an SSH connection, the following \I{SSH special commands}special
179 commands are available:
181 \b \I{IGNORE message, SSH special command}\I{No-op, in SSH}\ii{IGNORE message}
184 Should have no effect.
187 \b \I{Repeat key exchange, SSH special command}Repeat key exchange
190 Only available in SSH-2. Forces a \i{repeat key exchange} immediately (and
191 resets associated timers and counters). For more information about
192 repeat key exchanges, see \k{config-ssh-kex-rekey}.
195 \b \I{Break, SSH special command}Break
198 Only available in SSH-2, and only during a session. Optional
199 extension; may not be supported by server. PuTTY requests the server's
200 default break length.
203 \b \I{Signal, SSH special command}Signals (SIGINT, SIGTERM etc)
206 Only available in SSH-2, and only during a session. Sends various
207 POSIX signals. Not honoured by all servers.
210 \S2{using-newsession} Starting new sessions
212 PuTTY's system menu provides some shortcut ways to start new
215 \b Selecting \i{\q{New Session}} will start a completely new
216 instance of PuTTY, and bring up the configuration box as normal.
218 \b Selecting \i{\q{Duplicate Session}} will start a session in a
219 new window with precisely the same options as your current one -
220 connecting to the same host using the same protocol, with all the
221 same terminal settings and everything.
223 \b In an inactive window, selecting \i{\q{Restart Session}} will
224 do the same as \q{Duplicate Session}, but in the current window.
226 \b The \i{\q{Saved Sessions} submenu} gives you quick access to any
227 sets of stored session details you have previously saved. See
228 \k{config-saving} for details of how to create saved sessions.
230 \S2{using-changesettings} \I{settings, changing}Changing your
233 If you select \i{\q{Change Settings}} from the system menu, PuTTY will
234 display a cut-down version of its initial configuration box. This
235 allows you to adjust most properties of your current session. You
236 can change the terminal size, the font, the actions of various
237 keypresses, the colours, and so on.
239 Some of the options that are available in the main configuration box
240 are not shown in the cut-down Change Settings box. These are usually
241 options which don't make sense to change in the middle of a session
242 (for example, you can't switch from SSH to Telnet in mid-session).
244 \S2{using-copyall} \i{Copy All to Clipboard}
246 This system menu option provides a convenient way to copy the whole
247 contents of the terminal screen (up to the last nonempty line) and
248 scrollback to the \i{clipboard} in one go.
250 \S2{reset-terminal} \I{scrollback, clearing}Clearing and
251 \I{terminal, resetting}resetting the terminal
253 The \i{\q{Clear Scrollback}} option on the system menu tells PuTTY
254 to discard all the lines of text that have been kept after they
255 scrolled off the top of the screen. This might be useful, for
256 example, if you displayed sensitive information and wanted to make
257 sure nobody could look over your shoulder and see it. (Note that
258 this only prevents a casual user from using the scrollbar to view
259 the information; the text is not guaranteed not to still be in
262 The \i{\q{Reset Terminal}} option causes a full reset of the
263 \i{terminal emulation}. A VT-series terminal is a complex piece of
264 software and can easily get into a state where all the text printed
265 becomes unreadable. (This can happen, for example, if you
266 accidentally output a binary file to your terminal.) If this
267 happens, selecting Reset Terminal should sort it out.
269 \S2{using-fullscreen} \ii{Full screen} mode
271 If you find the title bar on a maximised window to be ugly or
272 distracting, you can select Full Screen mode to maximise PuTTY
273 \q{even more}. When you select this, PuTTY will expand to fill the
274 whole screen and its borders, title bar and scrollbar will
275 disappear. (You can configure the scrollbar not to disappear in
276 full-screen mode if you want to keep it; see \k{config-scrollback}.)
278 When you are in full-screen mode, you can still access the \i{system
279 menu} if you click the left mouse button in the \e{extreme} top left
280 corner of the screen.
282 \H{using-logging} Creating a \i{log file} of your \I{session
285 For some purposes you may find you want to log everything that
286 appears on your screen. You can do this using the \q{Logging}
287 panel in the configuration box.
289 To begin a session log, select \q{Change Settings} from the system
290 menu and go to the Logging panel. Enter a log file name, and select
291 a logging mode. (You can log all session output including the
292 terminal \i{control sequence}s, or you can just log the printable text.
293 It depends what you want the log for.) Click \q{Apply} and your log
294 will be started. Later on, you can go back to the Logging panel and
295 select \q{Logging turned off completely} to stop logging; then PuTTY
296 will close the log file and you can safely read it.
298 See \k{config-logging} for more details and options.
300 \H{using-translation} Altering your \i{character set} configuration
302 If you find that special characters (\i{accented characters}, for
303 example, or \i{line-drawing characters}) are not being displayed
304 correctly in your PuTTY session, it may be that PuTTY is interpreting
305 the characters sent by the server according to the wrong \e{character
306 set}. There are a lot of different character sets available, so it's
307 entirely possible for this to happen.
309 If you click \q{Change Settings} and look at the \q{Translation}
310 panel, you should see a large number of character sets which you can
311 select, and other related options. Now all you need is to find out
312 which of them you want! (See \k{config-translation} for more
315 \H{using-x-forwarding} Using \i{X11 forwarding} in SSH
317 The SSH protocol has the ability to securely forward X Window System
318 applications over your encrypted SSH connection, so that you can run
319 an application on the SSH server machine and have it put its windows
320 up on your local machine without sending any X network traffic in
323 In order to use this feature, you will need an X display server for
324 your Windows machine, such as Cygwin/X, X-Win32, or Exceed. This will probably
325 install itself as display number 0 on your local machine; if it
326 doesn't, the manual for the \i{X server} should tell you what it
329 You should then tick the \q{Enable X11 forwarding} box in the
330 Tunnels panel (see \k{config-ssh-x11}) before starting your SSH
331 session. The \i{\q{X display location}} box is blank by default, which
332 means that PuTTY will try to use a sensible default such as \c{:0},
333 which is the usual display location where your X server will be
334 installed. If that needs changing, then change it.
336 Now you should be able to log in to the SSH server as normal. To
337 check that X forwarding has been successfully negotiated during
338 connection startup, you can check the PuTTY Event Log (see
339 \k{using-eventlog}). It should say something like this:
341 \c 2001-12-05 17:22:01 Requesting X11 forwarding
342 \c 2001-12-05 17:22:02 X11 forwarding enabled
344 If the remote system is Unix or Unix-like, you should also be able
345 to see that the \i{\c{DISPLAY} environment variable} has been set to
346 point at display 10 or above on the SSH server machine itself:
348 \c fred@unixbox:~$ echo $DISPLAY
351 If this works, you should then be able to run X applications in the
352 remote session and have them display their windows on your PC.
354 Note that if your PC X server requires \I{X11 authentication}authentication
355 to connect, then PuTTY cannot currently support it. If this is a problem for
356 you, you should mail the PuTTY authors \#{FIXME} and give details
359 For more options relating to X11 forwarding, see \k{config-ssh-x11}.
361 \H{using-port-forwarding} Using \i{port forwarding} in SSH
363 The SSH protocol has the ability to forward arbitrary \i{network
364 connection}s over your encrypted SSH connection, to avoid the network
365 traffic being sent in clear. For example, you could use this to
366 connect from your home computer to a \i{POP-3} server on a remote
367 machine without your POP-3 password being visible to network
370 In order to use port forwarding to \I{local port forwarding}connect
371 from your local machine to a port on a remote server, you need to:
373 \b Choose a \i{port number} on your local machine where PuTTY should
374 listen for incoming connections. There are likely to be plenty of
375 unused port numbers above 3000. (You can also use a local loopback
376 address here; see below for more details.)
378 \b Now, before you start your SSH connection, go to the Tunnels
379 panel (see \k{config-ssh-portfwd}). Make sure the \q{Local} radio
380 button is set. Enter the local port number into the \q{Source port}
381 box. Enter the destination host name and port number into the
382 \q{Destination} box, separated by a colon (for example,
383 \c{popserver.example.com:110} to connect to a POP-3 server).
385 \b Now click the \q{Add} button. The details of your port forwarding
386 should appear in the list box.
388 Now start your session and log in. (Port forwarding will not be
389 enabled until after you have logged in; otherwise it would be easy
390 to perform completely anonymous network attacks, and gain access to
391 anyone's virtual private network.) To check that PuTTY has set up
392 the port forwarding correctly, you can look at the PuTTY Event Log
393 (see \k{using-eventlog}). It should say something like this:
395 \c 2001-12-05 17:22:10 Local port 3110 forwarding to
396 \c popserver.example.com:110
398 Now if you connect to the source port number on your local PC, you
399 should find that it answers you exactly as if it were the service
400 running on the destination machine. So in this example, you could
401 then configure an e-mail client to use \c{localhost:3110} as a POP-3
402 server instead of \c{popserver.example.com:110}. (Of course, the
403 forwarding will stop happening when your PuTTY session closes down.)
405 You can also forward ports in the other direction: arrange for a
406 particular port number on the \e{server} machine to be \I{remote
407 port forwarding}forwarded back to your PC as a connection to a
408 service on your PC or near it.
409 To do this, just select the \q{Remote} radio button instead of the
410 \q{Local} one. The \q{Source port} box will now specify a port
411 number on the \e{server} (note that most servers will not allow you
412 to use \I{privileged port}port numbers under 1024 for this purpose).
414 An alternative way to forward local connections to remote hosts is
415 to use \I{dynamic port forwarding}dynamic SOCKS proxying. For
416 this, you will need to select the \q{Dynamic} radio button instead
417 of \q{Local}, and then you should not enter anything into the
418 \q{Destination} box (it will be ignored). This will cause PuTTY to
419 listen on the port you have specified, and provide a SOCKS proxy
420 service to any programs which connect to that port. So, in
421 particular, you can forward other PuTTY connections through it by
422 setting up the Proxy control panel (see \k{config-proxy} for
425 The source port for a forwarded connection usually does not accept
426 connections from any machine except the \I{localhost}SSH client or
427 server machine itself (for local and remote forwardings respectively).
428 There are controls in the Tunnels panel to change this:
430 \b The \q{Local ports accept connections from other hosts} option
431 allows you to set up local-to-remote port forwardings (including
432 dynamic port forwardings) in such a way that machines other than
433 your client PC can connect to the forwarded port.
435 \b The \q{Remote ports do the same} option does the same thing for
436 remote-to-local port forwardings (so that machines other than the
437 SSH server machine can connect to the forwarded port.) Note that
438 this feature is only available in the SSH-2 protocol, and not all
439 SSH-2 servers honour it (in \i{OpenSSH}, for example, it's usually
440 disabled by default).
442 You can also specify an \i{IP address} to \I{listen address}listen
443 on. Typically a Windows machine can be asked to listen on any single
444 IP address in the \cw{127.*.*.*} range, and all of these are
445 \i{loopback address}es available only to the local machine. So if
446 you forward (for example) \c{127.0.0.5:79} to a remote machine's
447 \i\cw{finger} port, then you should be able to run commands such as
448 \c{finger fred@127.0.0.5}.
449 This can be useful if the program connecting to the forwarded port
450 doesn't allow you to change the port number it uses. This feature is
451 available for local-to-remote forwarded ports; SSH-1 is unable to
452 support it for remote-to-local ports, while SSH-2 can support it in
453 theory but servers will not necessarily cooperate.
455 (Note that if you're using Windows XP Service Pack 2, you may need
456 to obtain a fix from Microsoft in order to use addresses like
457 \cw{127.0.0.5} - see \k{faq-alternate-localhost}.)
459 \H{using-rawprot} Making \i{raw TCP connections}
461 A lot of \I{debugging Internet protocols}Internet protocols are
462 composed of commands and responses in plain text. For example,
463 \i{SMTP} (the protocol used to transfer e-mail), \i{NNTP} (the
464 protocol used to transfer Usenet news), and \i{HTTP} (the protocol
465 used to serve Web pages) all consist of commands in readable plain
468 Sometimes it can be useful to connect directly to one of these
469 services and speak the protocol \q{by hand}, by typing protocol
470 commands and watching the responses. On Unix machines, you can do
471 this using the system's \c{telnet} command to connect to the right
472 port number. For example, \c{telnet mailserver.example.com 25} might
473 enable you to talk directly to the SMTP service running on a mail
476 Although the Unix \c{telnet} program provides this functionality,
477 the protocol being used is not really Telnet. Really there is no
478 actual protocol at all; the bytes sent down the connection are
479 exactly the ones you type, and the bytes shown on the screen are
480 exactly the ones sent by the server. Unix \c{telnet} will attempt to
481 detect or guess whether the service it is talking to is a real
482 Telnet service or not; PuTTY prefers to be told for certain.
484 In order to make a debugging connection to a service of this type,
485 you simply select the fourth protocol name, \I{\q{Raw}
486 protocol}\q{Raw}, from the \q{Protocol} buttons in the \q{Session}
487 configuration panel. (See \k{config-hostname}.) You can then enter a
488 host name and a port number, and make the connection.
490 \H{using-cmdline} The PuTTY command line
492 PuTTY can be made to do various things without user intervention by
493 supplying \i{command-line arguments} (e.g., from a \i{command prompt
494 window}, or a \i{Windows shortcut}).
496 \S{using-cmdline-session} Starting a session from the command line
498 \I\c{-ssh}\I\c{-telnet}\I\c{-rlogin}\I\c{-raw}These options allow
499 you to bypass the configuration window and launch straight into a
502 To start a connection to a server called \c{host}:
504 \c putty.exe [-ssh | -telnet | -rlogin | -raw] [user@]host
506 If this syntax is used, settings are taken from the \i{Default Settings}
507 (see \k{config-saving}); \c{user} overrides these settings if
508 supplied. Also, you can specify a protocol, which will override the
509 default protocol (see \k{using-cmdline-protocol}).
511 For telnet sessions, the following alternative syntax is supported
512 (this makes PuTTY suitable for use as a URL handler for \i{telnet
513 URLs} in web browsers):
515 \c putty.exe telnet://host[:port]/
517 In order to start an existing saved session called \c{sessionname},
518 use the \c{-load} option (described in \k{using-cmdline-load}).
520 \c putty.exe -load "session name"
522 \S{using-cleanup} \i\c{-cleanup}
524 \cfg{winhelp-topic}{options.cleanup}
526 If invoked with the \c{-cleanup} option, rather than running as
527 normal, PuTTY will remove its \I{removing registry entries}registry
528 entries and \i{random seed file} from the local machine (after
529 confirming with the user).
531 Note that on \i{multi-user systems}, \c{-cleanup} only removes
532 registry entries and files associated with the currently logged-in
535 \S{using-general-opts} Standard command-line options
537 PuTTY and its associated tools support a range of command-line
538 options, most of which are consistent across all the tools. This
539 section lists the available options in all tools. Options which are
540 specific to a particular tool are covered in the chapter about that
543 \S2{using-cmdline-load} \i\c{-load}: load a saved session
545 \I{saved sessions, loading from command line}The \c{-load} option
546 causes PuTTY to load configuration details out of a saved session.
547 If these details include a host name, then this option is all you
548 need to make PuTTY start a session.
550 You need double quotes around the session name if it contains spaces.
552 If you want to create a \i{Windows shortcut} to start a PuTTY saved
553 session, this is the option you should use: your shortcut should
556 \c d:\path\to\putty.exe -load "my session"
558 (Note that PuTTY itself supports an alternative form of this option,
559 for backwards compatibility. If you execute \i\c{putty @sessionname}
560 it will have the same effect as \c{putty -load "sessionname"}. With
561 the \c{@} form, no double quotes are required, and the \c{@} sign
562 must be the very first thing on the command line. This form of the
563 option is deprecated.)
565 \S2{using-cmdline-protocol} Selecting a protocol: \c{-ssh},
566 \c{-telnet}, \c{-rlogin}, \c{-raw}
568 To choose which protocol you want to connect with, you can use one
571 \b \i\c{-ssh} selects the SSH protocol.
573 \b \i\c{-telnet} selects the Telnet protocol.
575 \b \i\c{-rlogin} selects the Rlogin protocol.
577 \b \i\c{-raw} selects the raw protocol.
579 These options are not available in the file transfer tools PSCP and
580 PSFTP (which only work with the SSH protocol).
582 These options are equivalent to the \i{protocol selection} buttons
583 in the Session panel of the PuTTY configuration box (see
584 \k{config-hostname}).
586 \S2{using-cmdline-v} \i\c{-v}: increase verbosity
588 \I{verbose mode}Most of the PuTTY tools can be made to tell you more
589 about what they are doing by supplying the \c{-v} option. If you are
590 having trouble when making a connection, or you're simply curious,
591 you can turn this switch on and hope to find out more about what is
594 \S2{using-cmdline-l} \i\c{-l}: specify a \i{login name}
596 You can specify the user name to log in as on the remote server
597 using the \c{-l} option. For example, \c{plink login.example.com -l
600 These options are equivalent to the username selection box in the
601 Connection panel of the PuTTY configuration box (see
602 \k{config-username}).
604 \S2{using-cmdline-portfwd} \I{-L-upper}\c{-L}, \I{-R-upper}\c{-R}
605 and \I{-D-upper}\c{-D}: set up \i{port forwardings}
607 As well as setting up port forwardings in the PuTTY configuration
608 (see \k{config-ssh-portfwd}), you can also set up forwardings on the
609 command line. The command-line options work just like the ones in
610 Unix \c{ssh} programs.
612 To \I{local port forwarding}forward a local port (say 5110) to a
613 remote destination (say \cw{popserver.example.com} port 110), you
614 can write something like one of these:
616 \c putty -L 5110:popserver.example.com:110 -load mysession
617 \c plink mysession -L 5110:popserver.example.com:110
619 To forward a \I{remote port forwarding}remote port to a local
620 destination, just use the \c{-R} option instead of \c{-L}:
622 \c putty -R 5023:mytelnetserver.myhouse.org:23 -load mysession
623 \c plink mysession -R 5023:mytelnetserver.myhouse.org:23
625 To \I{listen address}specify an IP address for the listening end of the
626 tunnel, prepend it to the argument:
628 \c plink -L 127.0.0.5:23:localhost:23 myhost
630 To set up \I{dynamic port forwarding}SOCKS-based dynamic port
631 forwarding on a local port, use the \c{-D} option. For this one you
632 only have to pass the port number:
634 \c putty -D 4096 -load mysession
636 For general information on port forwarding, see
637 \k{using-port-forwarding}.
639 These options are not available in the file transfer tools PSCP and
642 \S2{using-cmdline-m} \i\c{-m}: \I{reading commands from a file}read
643 a remote command or script from a file
645 The \i\c{-m} option performs a similar function to the \q{\ii{Remote
646 command}} box in the SSH panel of the PuTTY configuration box (see
647 \k{config-command}). However, the \c{-m} option expects to be given
648 a local file name, and it will read a command from that file. On
649 most Unix systems, you can even put multiple lines in this file and
650 execute more than one command in sequence, or a whole shell script;
651 but this will not work on all servers (and is known not to work
652 with certain \q{embedded} servers such as routers).
654 This option is not available in the file transfer tools PSCP and
657 \S2{using-cmdline-p} \I{-P-upper}\c{-P}: specify a \i{port number}
659 The \c{-P} option is used to specify the port number to connect to. If
660 you have a Telnet server running on port 9696 of a machine instead of
661 port 23, for example:
663 \c putty -telnet -P 9696 host.name
664 \c plink -telnet -P 9696 host.name
666 (Note that this option is more useful in Plink than in PuTTY,
667 because in PuTTY you can write \c{putty -telnet host.name 9696} in
670 This option is equivalent to the port number control in the Session
671 panel of the PuTTY configuration box (see \k{config-hostname}).
673 \S2{using-cmdline-pw} \i\c{-pw}: specify a \i{password}
675 A simple way to automate a remote login is to supply your password
676 on the command line. This is \e{not recommended} for reasons of
677 security. If you possibly can, we recommend you set up public-key
678 authentication instead. See \k{pubkey} for details.
680 Note that the \c{-pw} option only works when you are using the SSH
681 protocol. Due to fundamental limitations of Telnet and Rlogin, these
682 protocols do not support automated password authentication.
684 \S2{using-cmdline-agent} \I{-A-upper}\c{-A} and \i\c{-a}: control \i{agent
687 The \c{-A} option turns on SSH agent forwarding, and \c{-a} turns it
688 off. These options are only meaningful if you are using SSH.
690 See \k{pageant} for general information on \i{Pageant}, and
691 \k{pageant-forward} for information on agent forwarding. Note that
692 there is a security risk involved with enabling this option; see
693 \k{pageant-security} for details.
695 These options are equivalent to the agent forwarding checkbox in the
696 Auth panel of the PuTTY configuration box (see \k{config-ssh-agentfwd}).
698 These options are not available in the file transfer tools PSCP and
701 \S2{using-cmdline-x11} \I{-X-upper}\c{-X} and \i\c{-x}: control \i{X11
704 The \c{-X} option turns on X11 forwarding in SSH, and \c{-x} turns
705 it off. These options are only meaningful if you are using SSH.
707 For information on X11 forwarding, see \k{using-x-forwarding}.
709 These options are equivalent to the X11 forwarding checkbox in the
710 Tunnels panel of the PuTTY configuration box (see
713 These options are not available in the file transfer tools PSCP and
716 \S2{using-cmdline-pty} \i\c{-t} and \I{-T-upper}\c{-T}: control
717 \i{pseudo-terminal allocation}
719 The \c{-t} option ensures PuTTY attempts to allocate a
720 pseudo-terminal at the server, and \c{-T} stops it from allocating
721 one. These options are only meaningful if you are using SSH.
723 These options are equivalent to the \q{Don't allocate a
724 pseudo-terminal} checkbox in the SSH panel of the PuTTY
725 configuration box (see \k{config-ssh-pty}).
727 These options are not available in the file transfer tools PSCP and
730 \S2{using-cmdline-noshell} \I{-N-upper}\c{-N}: suppress starting a
731 \I{suppressing remote shell}shell or command
733 The \c{-N} option prevents PuTTY from attempting to start a shell or
734 command on the remote server. You might want to use this option if
735 you are only using the SSH connection for port forwarding, and your
736 user account on the server does not have the ability to run a shell.
738 This feature is only available in SSH protocol version 2 (since the
739 version 1 protocol assumes you will always want to run a shell).
741 This option is equivalent to the \q{Don't start a shell or command
742 at all} checkbox in the SSH panel of the PuTTY configuration box
743 (see \k{config-ssh-noshell}).
745 This option is not available in the file transfer tools PSCP and
748 \S2{using-cmdline-compress} \I{-C-upper}\c{-C}: enable \i{compression}
750 The \c{-C} option enables compression of the data sent across the
751 network. This option is only meaningful if you are using SSH.
753 This option is equivalent to the \q{Enable compression} checkbox in
754 the SSH panel of the PuTTY configuration box (see
755 \k{config-ssh-comp}).
757 \S2{using-cmdline-sshprot} \i\c{-1} and \i\c{-2}: specify an \i{SSH
760 The \c{-1} and \c{-2} options force PuTTY to use version \I{SSH-1}1
761 or version \I{SSH-2}2 of the SSH protocol. These options are only
762 meaningful if you are using SSH.
764 These options are equivalent to selecting your preferred SSH
765 protocol version as \q{1 only} or \q{2 only} in the SSH panel of the
766 PuTTY configuration box (see \k{config-ssh-prot}).
768 \S2{using-cmdline-ipversion} \i\c{-4} and \i\c{-6}: specify an
769 \i{Internet protocol version}
771 The \c{-4} and \c{-6} options force PuTTY to use the older Internet
772 protocol \i{IPv4} or the newer \i{IPv6}.
774 These options are equivalent to selecting your preferred Internet
775 protocol version as \q{IPv4} or \q{IPv6} in the Connection panel of
776 the PuTTY configuration box (see \k{config-address-family}).
778 \S2{using-cmdline-identity} \i\c{-i}: specify an SSH \i{private key}
780 The \c{-i} option allows you to specify the name of a private key
781 file in \c{*.\i{PPK}} format which PuTTY will use to authenticate with the
782 server. This option is only meaningful if you are using SSH.
784 For general information on \i{public-key authentication}, see
787 This option is equivalent to the \q{Private key file for
788 authentication} box in the Auth panel of the PuTTY configuration box
789 (see \k{config-ssh-privkey}).
791 \S2{using-cmdline-pgpfp} \i\c{-pgpfp}: display \i{PGP key fingerprint}s
793 This option causes the PuTTY tools not to run as normal, but instead
794 to display the fingerprints of the PuTTY PGP Master Keys, in order to
795 aid with \i{verifying new versions}. See \k{pgpkeys} for more information.