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