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