30sk2EEL

1                             PuTTY User Manual
2                             =================
3
4PuTTY is a free (MIT-licensed) Windows Telnet and SSH client. This manual
5documents PuTTY, and its companion utilities PSCP, PSFTP, Plink, Pageant
6and PuTTYgen.
7
8_Note to Unix users:_ this manual currently primarily documents the Windows
9versions of the PuTTY utilities. Some options are therefore mentioned
10that are absent from the Unix version; the Unix version has features not
11described here; and the pterm and command-line puttygen utilities are not
12described at all. The only Unix-specific documentation that currently
13exists is the man pages.
14
15This manual is copyright 1997-2017 Simon Tatham. All rights reserved. You
16may distribute this documentation under the MIT licence. See appendix C for
17the licence text in full.
18
19Chapter 1: Introduction to PuTTY
20--------------------------------
21
22       PuTTY is a free SSH, Telnet and Rlogin client for Windows systems.
23
24   1.1 What are SSH, Telnet and Rlogin?
25
26       If you already know what SSH, Telnet and Rlogin are, you can safely
27       skip on to the next section.
28
29       SSH, Telnet and Rlogin are three ways of doing the same thing:
30       logging in to a multi-user computer from another computer, over a
31       network.
32
33       Multi-user operating systems, such as Unix and VMS, usually present
34       a command-line interface to the user, much like the `Command Prompt'
35       or `MS-DOS Prompt' in Windows. The system prints a prompt, and you
36       type commands which the system will obey.
37
38       Using this type of interface, there is no need for you to be sitting
39       at the same machine you are typing commands to. The commands,
40       and responses, can be sent over a network, so you can sit at one
41       computer and give commands to another one, or even to more than one.
42
43       SSH, Telnet and Rlogin are _network protocols_ that allow you to do
44       this. On the computer you sit at, you run a _client_, which makes a
45       network connection to the other computer (the _server_). The network
46       connection carries your keystrokes and commands from the client to
47       the server, and carries the server's responses back to you.
48
49       These protocols can also be used for other types of keyboard-based
50       interactive session. In particular, there are a lot of bulletin
51       boards, talker systems and MUDs (Multi-User Dungeons) which support
52       access using Telnet. There are even a few that support SSH.
53
54       You might want to use SSH, Telnet or Rlogin if:
55
56        -  you have an account on a Unix or VMS system which you want to be
57           able to access from somewhere else
58
59        -  your Internet Service Provider provides you with a login account
60           on a web server. (This might also be known as a _shell account_.
61           A _shell_ is the program that runs on the server and interprets
62           your commands for you.)
63
64        -  you want to use a bulletin board system, talker or MUD which can
65           be accessed using Telnet.
66
67       You probably do _not_ want to use SSH, Telnet or Rlogin if:
68
69        -  you only use Windows. Windows computers have their own ways
70           of networking between themselves, and unless you are doing
71           something fairly unusual, you will not need to use any of these
72           remote login protocols.
73
74   1.2 How do SSH, Telnet and Rlogin differ?
75
76       This list summarises some of the differences between SSH, Telnet and
77       Rlogin.
78
79        -  SSH (which stands for `secure shell') is a recently designed,
80           high-security protocol. It uses strong cryptography to protect
81           your connection against eavesdropping, hijacking and other
82           attacks. Telnet and Rlogin are both older protocols offering
83           minimal security.
84
85        -  SSH and Rlogin both allow you to log in to the server without
86           having to type a password. (Rlogin's method of doing this is
87           insecure, and can allow an attacker to access your account on
88           the server. SSH's method is much more secure, and typically
89           breaking the security requires the attacker to have gained
90           access to your actual client machine.)
91
92        -  SSH allows you to connect to the server and automatically send
93           a command, so that the server will run that command and then
94           disconnect. So you can use it in automated processing.
95
96       The Internet is a hostile environment and security is everybody's
97       responsibility. If you are connecting across the open Internet,
98       then we recommend you use SSH. If the server you want to connect
99       to doesn't support SSH, it might be worth trying to persuade the
100       administrator to install it.
101
102       If your client and server are both behind the same (good) firewall,
103       it is more likely to be safe to use Telnet or Rlogin, but we still
104       recommend you use SSH.
105
106Chapter 2: Getting started with PuTTY
107-------------------------------------
108
109       This chapter gives a quick guide to the simplest types of
110       interactive login session using PuTTY.
111
112   2.1 Starting a session
113
114       When you start PuTTY, you will see a dialog box. This dialog box
115       allows you to control everything PuTTY can do. See chapter 4 for
116       details of all the things you can control.
117
118       You don't usually need to change most of the configuration options.
119       To start the simplest kind of session, all you need to do is to
120       enter a few basic parameters.
121
122       In the `Host Name' box, enter the Internet host name of the server
123       you want to connect to. You should have been told this by the
124       provider of your login account.
125
126       Now select a login protocol to use, from the `Connection type'
127       buttons. For a login session, you should select Telnet, Rlogin or
128       SSH. See section 1.2 for a description of the differences between
129       the three protocols, and advice on which one to use. The fourth
130       protocol, _Raw_, is not used for interactive login sessions; you
131       would usually use this for debugging other Internet services (see
132       section 3.6). The fifth option, _Serial_, is used for connecting to
133       a local serial line, and works somewhat differently: see section 3.7
134       for more information on this.
135
136       When you change the selected protocol, the number in the `Port'
137       box will change. This is normal: it happens because the various
138       login services are usually provided on different network ports
139       by the server machine. Most servers will use the standard port
140       numbers, so you will not need to change the port setting. If your
141       server provides login services on a non-standard port, your system
142       administrator should have told you which one. (For example, many
143       MUDs run Telnet service on a port other than 23.)
144
145       Once you have filled in the `Host Name', `Protocol', and possibly
146       `Port' settings, you are ready to connect. Press the `Open' button
147       at the bottom of the dialog box, and PuTTY will begin trying to
148       connect you to the server.
149
150   2.2 Verifying the host key (SSH only)
151
152       If you are not using the SSH protocol, you can skip this section.
153
154       If you are using SSH to connect to a server for the first time, you
155       will probably see a message looking something like this:
156
157         The server's host key is not cached in the registry. You
158         have no guarantee that the server is the computer you
159         think it is.
160         The server's rsa2 key fingerprint is:
161         ssh-rsa 1024 7b:e5:6f:a7:f4:f9:81:62:5c:e3:1f:bf:8b:57:6c:5a
162         If you trust this host, hit Yes to add the key to
163         PuTTY's cache and carry on connecting.
164         If you want to carry on connecting just once, without
165         adding the key to the cache, hit No.
166         If you do not trust this host, hit Cancel to abandon the
167         connection.
168
169       This is a feature of the SSH protocol. It is designed to protect you
170       against a network attack known as _spoofing_: secretly redirecting
171       your connection to a different computer, so that you send your
172       password to the wrong machine. Using this technique, an attacker
173       would be able to learn the password that guards your login account,
174       and could then log in as if they were you and use the account for
175       their own purposes.
176
177       To prevent this attack, each server has a unique identifying code,
178       called a _host key_. These keys are created in a way that prevents
179       one server from forging another server's key. So if you connect to a
180       server and it sends you a different host key from the one you were
181       expecting, PuTTY can warn you that the server may have been switched
182       and that a spoofing attack might be in progress.
183
184       PuTTY records the host key for each server you connect to, in the
185       Windows Registry. Every time you connect to a server, it checks that
186       the host key presented by the server is the same host key as it was
187       the last time you connected. If it is not, you will see a warning,
188       and you will have the chance to abandon your connection before you
189       type any private information (such as a password) into it.
190
191       However, when you connect to a server you have not connected to
192       before, PuTTY has no way of telling whether the host key is the
193       right one or not. So it gives the warning shown above, and asks you
194       whether you want to trust this host key or not.
195
196       Whether or not to trust the host key is your choice. If you are
197       connecting within a company network, you might feel that all
198       the network users are on the same side and spoofing attacks are
199       unlikely, so you might choose to trust the key without checking
200       it. If you are connecting across a hostile network (such as the
201       Internet), you should check with your system administrator,
202       perhaps by telephone or in person. (Many servers have more than
203       one host key. If the system administrator sends you more than one
204       fingerprint, you should make sure the one PuTTY shows you is on the
205       list, but it doesn't matter which one it is.)
206
207       See section 4.20 for advanced options for managing host keys.
208
209   2.3 Logging in
210
211       After you have connected, and perhaps verified the server's host
212       key, you will be asked to log in, probably using a username and a
213       password. Your system administrator should have provided you with
214       these. Enter the username and the password, and the server should
215       grant you access and begin your session. If you have mistyped your
216       password, most servers will give you several chances to get it
217       right.
218
219       If you are using SSH, be careful not to type your username wrongly,
220       because you will not have a chance to correct it after you press
221       Return; many SSH servers do not permit you to make two login
222       attempts using different usernames. If you type your username
223       wrongly, you must close PuTTY and start again.
224
225       If your password is refused but you are sure you have typed it
226       correctly, check that Caps Lock is not enabled. Many login servers,
227       particularly Unix computers, treat upper case and lower case as
228       different when checking your password; so if Caps Lock is on, your
229       password will probably be refused.
230
231   2.4 After logging in
232
233       After you log in to the server, what happens next is up to the
234       server! Most servers will print some sort of login message and then
235       present a prompt, at which you can type commands which the server
236       will carry out. Some servers will offer you on-line help; others
237       might not. If you are in doubt about what to do next, consult your
238       system administrator.
239
240   2.5 Logging out
241
242       When you have finished your session, you should log out by typing
243       the server's own logout command. This might vary between servers; if
244       in doubt, try `logout' or `exit', or consult a manual or your system
245       administrator. When the server processes your logout command, the
246       PuTTY window should close itself automatically.
247
248       You _can_ close a PuTTY session using the Close button in the window
249       border, but this might confuse the server - a bit like hanging up a
250       telephone unexpectedly in the middle of a conversation. We recommend
251       you do not do this unless the server has stopped responding to you
252       and you cannot close the window any other way.
253
254Chapter 3: Using PuTTY
255----------------------
256
257       This chapter provides a general introduction to some more advanced
258       features of PuTTY. For extreme detail and reference purposes,
259       chapter 4 is likely to contain more information.
260
261   3.1 During your session
262
263       A lot of PuTTY's complexity and features are in the configuration
264       panel. Once you have worked your way through that and started
265       a session, things should be reasonably simple after that.
266       Nevertheless, there are a few more useful features available.
267
268 3.1.1 Copying and pasting text
269
270       Often in a PuTTY session you will find text on your terminal screen
271       which you want to type in again. Like most other terminal emulators,
272       PuTTY allows you to copy and paste the text rather than having to
273       type it again. Also, copy and paste uses the Windows clipboard, so
274       that you can paste (for example) URLs into a web browser, or paste
275       from a word processor or spreadsheet into your terminal session.
276
277       PuTTY's copy and paste works entirely with the mouse. In order to
278       copy text to the clipboard, you just click the left mouse button in
279       the terminal window, and drag to select text. When you let go of the
280       button, the text is _automatically_ copied to the clipboard. You
281       do not need to press Ctrl-C or Ctrl-Ins; in fact, if you do press
282       Ctrl-C, PuTTY will send a Ctrl-C character down your session to the
283       server where it will probably cause a process to be interrupted.
284
285       Pasting is done using the right button (or the middle mouse
286       button, if you have a three-button mouse and have set it up; see
287       section 4.11.2). (Pressing Shift-Ins, or selecting `Paste' from
288       the Ctrl+right-click context menu, have the same effect.) When you
289       click the right mouse button, PuTTY will read whatever is in the
290       Windows clipboard and paste it into your session, _exactly_ as if it
291       had been typed at the keyboard. (Therefore, be careful of pasting
292       formatted text into an editor that does automatic indenting; you may
293       find that the spaces pasted from the clipboard plus the spaces added
294       by the editor add up to too many spaces and ruin the formatting.
295       There is nothing PuTTY can do about this.)
296
297       If you double-click the left mouse button, PuTTY will select a whole
298       word. If you double-click, hold down the second click, and drag the
299       mouse, PuTTY will select a sequence of whole words. (You can adjust
300       precisely what PuTTY considers to be part of a word; see section
301       4.11.5.) If you _triple_-click, or triple-click and drag, then PuTTY
302       will select a whole line or sequence of lines.
303
304       If you want to select a rectangular region instead of selecting to
305       the end of each line, you can do this by holding down Alt when you
306       make your selection. You can also configure rectangular selection to
307       be the default, and then holding down Alt gives the normal behaviour
308       instead: see section 4.11.4 for details.
309
310       (In some Unix environments, Alt+drag is intercepted by the window
311       manager. Shift+Alt+drag should work for rectangular selection as
312       well, so you could try that instead.)
313
314       If you have a middle mouse button, then you can use it to adjust an
315       existing selection if you selected something slightly wrong. (If you
316       have configured the middle mouse button to paste, then the right
317       mouse button does this instead.) Click the button on the screen,
318       and you can pick up the nearest end of the selection and drag it to
319       somewhere else.
320
321       It's possible for the server to ask to handle mouse clicks in the
322       PuTTY window itself. If this happens, the mouse pointer will turn
323       into an arrow, and using the mouse to copy and paste will only work
324       if you hold down Shift. See section 4.6.2 and section 4.11.3 for
325       details of this feature and how to configure it.
326
327 3.1.2 Scrolling the screen back
328
329       PuTTY keeps track of text that has scrolled up off the top of the
330       terminal. So if something appears on the screen that you want to
331       read, but it scrolls too fast and it's gone by the time you try to
332       look for it, you can use the scrollbar on the right side of the
333       window to look back up the session history and find it again.
334
335       As well as using the scrollbar, you can also page the scrollback
336       up and down by pressing Shift-PgUp and Shift-PgDn. You can scroll
337       a line at a time using Ctrl-PgUp and Ctrl-PgDn. These are still
338       available if you configure the scrollbar to be invisible.
339
340       By default the last 2000 lines scrolled off the top are preserved
341       for you to look at. You can increase (or decrease) this value using
342       the configuration box; see section 4.7.3.
343
344 3.1.3 The System menu
345
346       If you click the left mouse button on the icon in the top left
347       corner of PuTTY's terminal window, or click the right mouse button
348       on the title bar, you will see the standard Windows system menu
349       containing items like Minimise, Move, Size and Close.
350
351       PuTTY's system menu contains extra program features in addition
352       to the Windows standard options. These extra menu commands are
353       described below.
354
355       (These options are also available in a context menu brought up by
356       holding Ctrl and clicking with the right mouse button anywhere in
357       the PuTTY window.)
358
3593.1.3.1 The PuTTY Event Log
360
361       If you choose `Event Log' from the system menu, a small window will
362       pop up in which PuTTY logs significant events during the connection.
363       Most of the events in the log will probably take place during
364       session startup, but a few can occur at any point in the session,
365       and one or two occur right at the end.
366
367       You can use the mouse to select one or more lines of the Event Log,
368       and hit the Copy button to copy them to the clipboard. If you are
369       reporting a bug, it's often useful to paste the contents of the
370       Event Log into your bug report.
371
372       (The Event Log is not the same as the facility to create a log file
373       of your session; that's described in section 3.2.)
374
3753.1.3.2 Special commands
376
377       Depending on the protocol used for the current session, there may
378       be a submenu of `special commands'. These are protocol-specific
379       tokens, such as a `break' signal, that can be sent down a connection
380       in addition to normal data. Their precise effect is usually up to
381       the server. Currently only Telnet, SSH, and serial connections have
382       special commands.
383
384       The `break' signal can also be invoked from the keyboard with Ctrl-
385       Break.
386
387       The following special commands are available in Telnet:
388
389        -  Are You There
390
391        -  Break
392
393        -  Synch
394
395        -  Erase Character
396
397           PuTTY can also be configured to send this when the Backspace key
398           is pressed; see section 4.16.3.
399
400        -  Erase Line
401
402        -  Go Ahead
403
404        -  No Operation
405
406           Should have no effect.
407
408        -  Abort Process
409
410        -  Abort Output
411
412        -  Interrupt Process
413
414           PuTTY can also be configured to send this when Ctrl-C is typed;
415           see section 4.16.3.
416
417        -  Suspend Process
418
419           PuTTY can also be configured to send this when Ctrl-Z is typed;
420           see section 4.16.3.
421
422        -  End Of Record
423
424        -  End Of File
425
426       In an SSH connection, the following special commands are available:
427
428        -  IGNORE message
429
430           Should have no effect.
431
432        -  Repeat key exchange
433
434           Only available in SSH-2. Forces a repeat key exchange
435           immediately (and resets associated timers and counters). For
436           more information about repeat key exchanges, see section 4.19.2.
437
438        -  Cache new host key type
439
440           Only available in SSH-2. This submenu appears only if the server
441           has host keys of a type that PuTTY doesn't already have cached,
442           and so won't consider. Selecting a key here will allow PuTTY
443           to use that key now and in future: PuTTY will do a fresh key-
444           exchange with the selected key, and immediately add that key to
445           its permanent cache (relying on the host key used at the start
446           of the connection to cross-certify the new key). That key will
447           be used for the rest of the current session; it may not actually
448           be used for future sessions, depending on your preferences (see
449           section 4.20.1).
450
451           Normally, PuTTY will carry on using a host key it already knows,
452           even if the server offers key formats that PuTTY would otherwise
453           prefer, to avoid host key prompts. As a result, if you've been
454           using a server for some years, you may still be using an older
455           key than a new user would use, due to server upgrades in the
456           meantime. The SSH protocol unfortunately does not have organised
457           facilities for host key migration and rollover, but this allows
458           you to manually upgrade.
459
460        -  Break
461
462           Only available in SSH-2, and only during a session. Optional
463           extension; may not be supported by server. PuTTY requests the
464           server's default break length.
465
466        -  Signals (SIGINT, SIGTERM etc)
467
468           Only available in SSH-2, and only during a session. Sends
469           various POSIX signals. Not honoured by all servers.
470
471       With a serial connection, the only available special command is
472       `Break'.
473
4743.1.3.3 Starting new sessions
475
476       PuTTY's system menu provides some shortcut ways to start new
477       sessions:
478
479        -  Selecting `New Session' will start a completely new instance of
480           PuTTY, and bring up the configuration box as normal.
481
482        -  Selecting `Duplicate Session' will start a session in a new
483           window with precisely the same options as your current one -
484           connecting to the same host using the same protocol, with all
485           the same terminal settings and everything.
486
487        -  In an inactive window, selecting `Restart Session' will do the
488           same as `Duplicate Session', but in the current window.
489
490        -  The `Saved Sessions' submenu gives you quick access to any sets
491           of stored session details you have previously saved. See section
492           4.1.2 for details of how to create saved sessions.
493
4943.1.3.4 Changing your session settings
495
496       If you select `Change Settings' from the system menu, PuTTY will
497       display a cut-down version of its initial configuration box. This
498       allows you to adjust most properties of your current session. You
499       can change the terminal size, the font, the actions of various
500       keypresses, the colours, and so on.
501
502       Some of the options that are available in the main configuration box
503       are not shown in the cut-down Change Settings box. These are usually
504       options which don't make sense to change in the middle of a session
505       (for example, you can't switch from SSH to Telnet in mid-session).
506
507       You can save the current settings to a saved session for future use
508       from this dialog box. See section 4.1.2 for more on saved sessions.
509
5103.1.3.5 Copy All to Clipboard
511
512       This system menu option provides a convenient way to copy the whole
513       contents of the terminal screen (up to the last nonempty line) and
514       scrollback to the clipboard in one go.
515
5163.1.3.6 Clearing and resetting the terminal
517
518       The `Clear Scrollback' option on the system menu tells PuTTY to
519       discard all the lines of text that have been kept after they
520       scrolled off the top of the screen. This might be useful, for
521       example, if you displayed sensitive information and wanted to make
522       sure nobody could look over your shoulder and see it. (Note that
523       this only prevents a casual user from using the scrollbar to view
524       the information; the text is not guaranteed not to still be in
525       PuTTY's memory.)
526
527       The `Reset Terminal' option causes a full reset of the terminal
528       emulation. A VT-series terminal is a complex piece of software and
529       can easily get into a state where all the text printed becomes
530       unreadable. (This can happen, for example, if you accidentally
531       output a binary file to your terminal.) If this happens, selecting
532       Reset Terminal should sort it out.
533
5343.1.3.7 Full screen mode
535
536       If you find the title bar on a maximised window to be ugly or
537       distracting, you can select Full Screen mode to maximise PuTTY `even
538       more'. When you select this, PuTTY will expand to fill the whole
539       screen and its borders, title bar and scrollbar will disappear. (You
540       can configure the scrollbar not to disappear in full-screen mode if
541       you want to keep it; see section 4.7.3.)
542
543       When you are in full-screen mode, you can still access the system
544       menu if you click the left mouse button in the _extreme_ top left
545       corner of the screen.
546
547   3.2 Creating a log file of your session
548
549       For some purposes you may find you want to log everything that
550       appears on your screen. You can do this using the `Logging' panel in
551       the configuration box.
552
553       To begin a session log, select `Change Settings' from the system
554       menu and go to the Logging panel. Enter a log file name, and select
555       a logging mode. (You can log all session output including the
556       terminal control sequences, or you can just log the printable text.
557       It depends what you want the log for.) Click `Apply' and your log
558       will be started. Later on, you can go back to the Logging panel and
559       select `Logging turned off completely' to stop logging; then PuTTY
560       will close the log file and you can safely read it.
561
562       See section 4.2 for more details and options.
563
564   3.3 Altering your character set configuration
565
566       If you find that special characters (accented characters, for
567       example, or line-drawing characters) are not being displayed
568       correctly in your PuTTY session, it may be that PuTTY is
569       interpreting the characters sent by the server according to the
570       wrong _character set_. There are a lot of different character sets
571       available, and no good way for PuTTY to know which to use, so it's
572       entirely possible for this to happen.
573
574       If you click `Change Settings' and look at the `Translation' panel,
575       you should see a large number of character sets which you can
576       select, and other related options. Now all you need is to find out
577       which of them you want! (See section 4.10 for more information.)
578
579   3.4 Using X11 forwarding in SSH
580
581       The SSH protocol has the ability to securely forward X Window System
582       graphical applications over your encrypted SSH connection, so that
583       you can run an application on the SSH server machine and have it put
584       its windows up on your local machine without sending any X network
585       traffic in the clear.
586
587       In order to use this feature, you will need an X display server
588       for your Windows machine, such as Cygwin/X, X-Win32, or Exceed.
589       This will probably install itself as display number 0 on your local
590       machine; if it doesn't, the manual for the X server should tell you
591       what it does do.
592
593       You should then tick the `Enable X11 forwarding' box in the X11
594       panel (see section 4.25) before starting your SSH session. The `X
595       display location' box is blank by default, which means that PuTTY
596       will try to use a sensible default such as `:0', which is the usual
597       display location where your X server will be installed. If that
598       needs changing, then change it.
599
600       Now you should be able to log in to the SSH server as normal. To
601       check that X forwarding has been successfully negotiated during
602       connection startup, you can check the PuTTY Event Log (see section
603       3.1.3.1). It should say something like this:
604
605         2001-12-05 17:22:01 Requesting X11 forwarding
606         2001-12-05 17:22:02 X11 forwarding enabled
607
608       If the remote system is Unix or Unix-like, you should also be able
609       to see that the `DISPLAY' environment variable has been set to point
610       at display 10 or above on the SSH server machine itself:
611
612         fred@unixbox:~$ echo $DISPLAY
613         unixbox:10.0
614
615       If this works, you should then be able to run X applications in the
616       remote session and have them display their windows on your PC.
617
618       For more options relating to X11 forwarding, see section 4.25.
619
620   3.5 Using port forwarding in SSH
621
622       The SSH protocol has the ability to forward arbitrary network
623       (TCP) connections over your encrypted SSH connection, to avoid the
624       network traffic being sent in clear. For example, you could use
625       this to connect from your home computer to a POP-3 server on a
626       remote machine without your POP-3 password being visible to network
627       sniffers.
628
629       In order to use port forwarding to connect from your local machine
630       to a port on a remote server, you need to:
631
632        -  Choose a port number on your local machine where PuTTY should
633           listen for incoming connections. There are likely to be plenty
634           of unused port numbers above 3000. (You can also use a local
635           loopback address here; see below for more details.)
636
637        -  Now, before you start your SSH connection, go to the Tunnels
638           panel (see section 4.26). Make sure the `Local' radio button
639           is set. Enter the local port number into the `Source port'
640           box. Enter the destination host name and port number into
641           the `Destination' box, separated by a colon (for example,
642           `popserver.example.com:110' to connect to a POP-3 server).
643
644        -  Now click the `Add' button. The details of your port forwarding
645           should appear in the list box.
646
647       Now start your session and log in. (Port forwarding will not be
648       enabled until after you have logged in; otherwise it would be easy
649       to perform completely anonymous network attacks, and gain access to
650       anyone's virtual private network.) To check that PuTTY has set up
651       the port forwarding correctly, you can look at the PuTTY Event Log
652       (see section 3.1.3.1). It should say something like this:
653
654         2001-12-05 17:22:10 Local port 3110 forwarding to
655                  popserver.example.com:110
656
657       Now if you connect to the source port number on your local PC, you
658       should find that it answers you exactly as if it were the service
659       running on the destination machine. So in this example, you could
660       then configure an e-mail client to use `localhost:3110' as a POP-
661       3 server instead of `popserver.example.com:110'. (Of course, the
662       forwarding will stop happening when your PuTTY session closes down.)
663
664       You can also forward ports in the other direction: arrange for a
665       particular port number on the _server_ machine to be forwarded back
666       to your PC as a connection to a service on your PC or near it. To do
667       this, just select the `Remote' radio button instead of the `Local'
668       one. The `Source port' box will now specify a port number on the
669       _server_ (note that most servers will not allow you to use port
670       numbers under 1024 for this purpose).
671
672       An alternative way to forward local connections to remote hosts
673       is to use dynamic SOCKS proxying. In this mode, PuTTY acts as a
674       SOCKS server, which SOCKS-aware programs can connect to and open
675       forwarded connections to the destination of their choice, so this
676       can be an alternative to long lists of static forwardings. To use
677       this mode, you will need to select the `Dynamic' radio button
678       instead of `Local', and then you should not enter anything into the
679       `Destination' box (it will be ignored). PuTTY will then listen for
680       SOCKS connections on the port you have specified. Most web browsers
681       can be configured to connect to this SOCKS proxy service; also, you
682       can forward other PuTTY connections through it by setting up the
683       Proxy control panel (see section 4.15 for details).
684
685       The source port for a forwarded connection usually does not accept
686       connections from any machine except the SSH client or server machine
687       itself (for local and remote forwardings respectively). There are
688       controls in the Tunnels panel to change this:
689
690        -  The `Local ports accept connections from other hosts' option
691           allows you to set up local-to-remote port forwardings (including
692           dynamic port forwardings) in such a way that machines other than
693           your client PC can connect to the forwarded port.
694
695        -  The `Remote ports do the same' option does the same thing for
696           remote-to-local port forwardings (so that machines other than
697           the SSH server machine can connect to the forwarded port.) Note
698           that this feature is only available in the SSH-2 protocol, and
699           not all SSH-2 servers honour it (in OpenSSH, for example, it's
700           usually disabled by default).
701
702       You can also specify an IP address to listen on. Typically a
703       Windows machine can be asked to listen on any single IP address
704       in the 127.*.*.* range, and all of these are loopback addresses
705       available only to the local machine. So if you forward (for example)
706       `127.0.0.5:79' to a remote machine's finger port, then you should be
707       able to run commands such as `finger fred@127.0.0.5'. This can be
708       useful if the program connecting to the forwarded port doesn't allow
709       you to change the port number it uses. This feature is available
710       for local-to-remote forwarded ports; SSH-1 is unable to support it
711       for remote-to-local ports, while SSH-2 can support it in theory but
712       servers will not necessarily cooperate.
713
714       (Note that if you're using Windows XP Service Pack 2, you may need
715       to obtain a fix from Microsoft in order to use addresses like
716       127.0.0.5 - see question A.7.17.)
717
718       For more options relating to port forwarding, see section 4.26.
719
720       If the connection you are forwarding over SSH is itself a second
721       SSH connection made by another copy of PuTTY, you might find the
722       `logical host name' configuration option useful to warn PuTTY of
723       which host key it should be expecting. See section 4.13.5 for
724       details of this.
725
726   3.6 Making raw TCP connections
727
728       A lot of Internet protocols are composed of commands and responses
729       in plain text. For example, SMTP (the protocol used to transfer e-
730       mail), NNTP (the protocol used to transfer Usenet news), and HTTP
731       (the protocol used to serve Web pages) all consist of commands in
732       readable plain text.
733
734       Sometimes it can be useful to connect directly to one of these
735       services and speak the protocol `by hand', by typing protocol
736       commands and watching the responses. On Unix machines, you can do
737       this using the system's `telnet' command to connect to the right
738       port number. For example, `telnet mailserver.example.com 25' might
739       enable you to talk directly to the SMTP service running on a mail
740       server.
741
742       Although the Unix `telnet' program provides this functionality, the
743       protocol being used is not really Telnet. Really there is no actual
744       protocol at all; the bytes sent down the connection are exactly the
745       ones you type, and the bytes shown on the screen are exactly the
746       ones sent by the server. Unix `telnet' will attempt to detect or
747       guess whether the service it is talking to is a real Telnet service
748       or not; PuTTY prefers to be told for certain.
749
750       In order to make a debugging connection to a service of this
751       type, you simply select the fourth protocol name, `Raw', from the
752       `Protocol' buttons in the `Session' configuration panel. (See
753       section 4.1.1.) You can then enter a host name and a port number,
754       and make the connection.
755
756   3.7 Connecting to a local serial line
757
758       PuTTY can connect directly to a local serial line as an alternative
759       to making a network connection. In this mode, text typed into the
760       PuTTY window will be sent straight out of your computer's serial
761       port, and data received through that port will be displayed in the
762       PuTTY window. You might use this mode, for example, if your serial
763       port is connected to another computer which has a serial connection.
764
765       To make a connection of this type, simply select `Serial' from the
766       `Connection type' radio buttons on the `Session' configuration panel
767       (see section 4.1.1). The `Host Name' and `Port' boxes will transform
768       into `Serial line' and `Speed', allowing you to specify which serial
769       line to use (if your computer has more than one) and what speed
770       (baud rate) to use when transferring data. For further configuration
771       options (data bits, stop bits, parity, flow control), you can use
772       the `Serial' configuration panel (see section 4.28).
773
774       After you start up PuTTY in serial mode, you might find that you
775       have to make the first move, by sending some data out of the serial
776       line in order to notify the device at the other end that someone is
777       there for it to talk to. This probably depends on the device. If you
778       start up a PuTTY serial session and nothing appears in the window,
779       try pressing Return a few times and see if that helps.
780
781       A serial line provides no well defined means for one end of the
782       connection to notify the other that the connection is finished.
783       Therefore, PuTTY in serial mode will remain connected until you
784       close the window using the close button.
785
786   3.8 The PuTTY command line
787
788       PuTTY can be made to do various things without user intervention
789       by supplying command-line arguments (e.g., from a command prompt
790       window, or a Windows shortcut).
791
792 3.8.1 Starting a session from the command line
793
794       These options allow you to bypass the configuration window and
795       launch straight into a session.
796
797       To start a connection to a server called `host':
798
799         putty.exe [-ssh | -telnet | -rlogin | -raw] [user@]host
800
801       If this syntax is used, settings are taken from the Default Settings
802       (see section 4.1.2); `user' overrides these settings if supplied.
803       Also, you can specify a protocol, which will override the default
804       protocol (see section 3.8.3.2).
805
806       For telnet sessions, the following alternative syntax is supported
807       (this makes PuTTY suitable for use as a URL handler for telnet URLs
808       in web browsers):
809
810         putty.exe telnet://host[:port]/
811
812       To start a connection to a serial port, e.g. COM1:
813
814         putty.exe -serial com1
815
816       In order to start an existing saved session called `sessionname',
817       use the `-load' option (described in section 3.8.3.1).
818
819         putty.exe -load "session name"
820
821 3.8.2 `-cleanup'
822
823       If invoked with the `-cleanup' option, rather than running as
824       normal, PuTTY will remove its registry entries and random seed file
825       from the local machine (after confirming with the user). It will
826       also attempt to remove information about recently launched sessions
827       stored in the `jump list' on Windows 7 and up.
828
829       Note that on multi-user systems, `-cleanup' only removes registry
830       entries and files associated with the currently logged-in user.
831
832 3.8.3 Standard command-line options
833
834       PuTTY and its associated tools support a range of command-line
835       options, most of which are consistent across all the tools. This
836       section lists the available options in all tools. Options which are
837       specific to a particular tool are covered in the chapter about that
838       tool.
839
8403.8.3.1 `-load': load a saved session
841
842       The `-load' option causes PuTTY to load configuration details out
843       of a saved session. If these details include a host name, then this
844       option is all you need to make PuTTY start a session.
845
846       You need double quotes around the session name if it contains
847       spaces.
848
849       If you want to create a Windows shortcut to start a PuTTY saved
850       session, this is the option you should use: your shortcut should
851       call something like
852
853         d:\path\to\putty.exe -load "my session"
854
855       (Note that PuTTY itself supports an alternative form of this option,
856       for backwards compatibility. If you execute `putty @sessionname' it
857       will have the same effect as `putty -load "sessionname"'. With the
858       `@' form, no double quotes are required, and the `@' sign must be
859       the very first thing on the command line. This form of the option is
860       deprecated.)
861
8623.8.3.2 Selecting a protocol: `-ssh', `-telnet', `-rlogin', `-raw' `-
863       serial'
864
865       To choose which protocol you want to connect with, you can use one
866       of these options:
867
868        -  `-ssh' selects the SSH protocol.
869
870        -  `-telnet' selects the Telnet protocol.
871
872        -  `-rlogin' selects the Rlogin protocol.
873
874        -  `-raw' selects the raw protocol.
875
876        -  `-serial' selects a serial connection.
877
878       These options are not available in the file transfer tools PSCP and
879       PSFTP (which only work with the SSH protocol).
880
881       These options are equivalent to the protocol selection buttons
882       in the Session panel of the PuTTY configuration box (see section
883       4.1.1).
884
8853.8.3.3 `-v': increase verbosity
886
887       Most of the PuTTY tools can be made to tell you more about what they
888       are doing by supplying the `-v' option. If you are having trouble
889       when making a connection, or you're simply curious, you can turn
890       this switch on and hope to find out more about what is happening.
891
8923.8.3.4 `-l': specify a login name
893
894       You can specify the user name to log in as on the remote server
895       using the `-l' option. For example, `plink login.example.com -
896       l fred'.
897
898       These options are equivalent to the username selection box in
899       the Connection panel of the PuTTY configuration box (see section
900       4.14.1).
901
9023.8.3.5 `-L', `-R' and `-D': set up port forwardings
903
904       As well as setting up port forwardings in the PuTTY configuration
905       (see section 4.26), you can also set up forwardings on the command
906       line. The command-line options work just like the ones in Unix `ssh'
907       programs.
908
909       To forward a local port (say 5110) to a remote destination (say
910       popserver.example.com port 110), you can write something like one of
911       these:
912
913         putty -L 5110:popserver.example.com:110 -load mysession
914         plink mysession -L 5110:popserver.example.com:110
915
916       To forward a remote port to a local destination, just use the `-R'
917       option instead of `-L':
918
919         putty -R 5023:mytelnetserver.myhouse.org:23 -load mysession
920         plink mysession -R 5023:mytelnetserver.myhouse.org:23
921
922       To specify an IP address for the listening end of the tunnel,
923       prepend it to the argument:
924
925         plink -L 127.0.0.5:23:localhost:23 myhost
926
927       To set up SOCKS-based dynamic port forwarding on a local port, use
928       the `-D' option. For this one you only have to pass the port number:
929
930         putty -D 4096 -load mysession
931
932       For general information on port forwarding, see section 3.5.
933
934       These options are not available in the file transfer tools PSCP and
935       PSFTP.
936
9373.8.3.6 `-m': read a remote command or script from a file
938
939       The `-m' option performs a similar function to the `Remote command'
940       box in the SSH panel of the PuTTY configuration box (see section
941       4.18.1). However, the `-m' option expects to be given a local file
942       name, and it will read a command from that file.
943
944       With some servers (particularly Unix systems), you can even put
945       multiple lines in this file and execute more than one command in
946       sequence, or a whole shell script; but this is arguably an abuse,
947       and cannot be expected to work on all servers. In particular, it is
948       known _not_ to work with certain `embedded' servers, such as Cisco
949       routers.
950
951       This option is not available in the file transfer tools PSCP and
952       PSFTP.
953
9543.8.3.7 `-P': specify a port number
955
956       The `-P' option is used to specify the port number to connect to. If
957       you have a Telnet server running on port 9696 of a machine instead
958       of port 23, for example:
959
960         putty -telnet -P 9696 host.name
961         plink -telnet -P 9696 host.name
962
963       (Note that this option is more useful in Plink than in PuTTY,
964       because in PuTTY you can write `putty -telnet host.name 9696' in any
965       case.)
966
967       This option is equivalent to the port number control in the Session
968       panel of the PuTTY configuration box (see section 4.1.1).
969
9703.8.3.8 `-pw': specify a password
971
972       A simple way to automate a remote login is to supply your password
973       on the command line. This is _not recommended_ for reasons of
974       security. If you possibly can, we recommend you set up public-key
975       authentication instead. See chapter 8 for details.
976
977       Note that the `-pw' option only works when you are using the SSH
978       protocol. Due to fundamental limitations of Telnet and Rlogin, these
979       protocols do not support automated password authentication.
980
9813.8.3.9 `-agent' and `-noagent': control use of Pageant for authentication
982
983       The `-agent' option turns on SSH authentication using Pageant, and
984       `-noagent' turns it off. These options are only meaningful if you
985       are using SSH.
986
987       See chapter 9 for general information on Pageant.
988
989       These options are equivalent to the agent authentication checkbox in
990       the Auth panel of the PuTTY configuration box (see section 4.22.3).
991
9923.8.3.10 `-A' and `-a': control agent forwarding
993
994       The `-A' option turns on SSH agent forwarding, and `-a' turns it
995       off. These options are only meaningful if you are using SSH.
996
997       See chapter 9 for general information on Pageant, and section 9.4
998       for information on agent forwarding. Note that there is a security
999       risk involved with enabling this option; see section 9.5 for
1000       details.
1001
1002       These options are equivalent to the agent forwarding checkbox in the
1003       Auth panel of the PuTTY configuration box (see section 4.22.6).
1004
1005       These options are not available in the file transfer tools PSCP and
1006       PSFTP.
1007
10083.8.3.11 `-X' and `-x': control X11 forwarding
1009
1010       The `-X' option turns on X11 forwarding in SSH, and `-x' turns it
1011       off. These options are only meaningful if you are using SSH.
1012
1013       For information on X11 forwarding, see section 3.4.
1014
1015       These options are equivalent to the X11 forwarding checkbox in the
1016       X11 panel of the PuTTY configuration box (see section 4.25).
1017
1018       These options are not available in the file transfer tools PSCP and
1019       PSFTP.
1020
10213.8.3.12 `-t' and `-T': control pseudo-terminal allocation
1022
1023       The `-t' option ensures PuTTY attempts to allocate a pseudo-terminal
1024       at the server, and `-T' stops it from allocating one. These options
1025       are only meaningful if you are using SSH.
1026
1027       These options are equivalent to the `Don't allocate a pseudo-
1028       terminal' checkbox in the SSH panel of the PuTTY configuration box
1029       (see section 4.24.1).
1030
1031       These options are not available in the file transfer tools PSCP and
1032       PSFTP.
1033
10343.8.3.13 `-N': suppress starting a shell or command
1035
1036       The `-N' option prevents PuTTY from attempting to start a shell or
1037       command on the remote server. You might want to use this option if
1038       you are only using the SSH connection for port forwarding, and your
1039       user account on the server does not have the ability to run a shell.
1040
1041       This feature is only available in SSH protocol version 2 (since the
1042       version 1 protocol assumes you will always want to run a shell).
1043
1044       This option is equivalent to the `Don't start a shell or command at
1045       all' checkbox in the SSH panel of the PuTTY configuration box (see
1046       section 4.18.2).
1047
1048       This option is not available in the file transfer tools PSCP and
1049       PSFTP.
1050
10513.8.3.14 `-nc': make a remote network connection in place of a remote shell
1052       or command
1053
1054       The `-nc' option prevents Plink (or PuTTY) from attempting to start
1055       a shell or command on the remote server. Instead, it will instruct
1056       the remote server to open a network connection to a host name and
1057       port number specified by you, and treat that network connection as
1058       if it were the main session.
1059
1060       You specify a host and port as an argument to the `-nc' option, with
1061       a colon separating the host name from the port number, like this:
1062
1063         plink host1.example.com -nc host2.example.com:1234
1064
1065       You might want to use this feature if you needed to make an SSH
1066       connection to a target host which you can only reach by going
1067       through a proxy host, and rather than using port forwarding you
1068       prefer to use the local proxy feature (see section 4.15.1 for more
1069       about local proxies). In this situation you might select `Local'
1070       proxy type, set your local proxy command to be `plink %proxyhost -
1071       nc %host:%port', enter the target host name on the Session panel,
1072       and enter the directly reachable proxy host name on the Proxy panel.
1073
1074       This feature is only available in SSH protocol version 2 (since the
1075       version 1 protocol assumes you will always want to run a shell). It
1076       is not available in the file transfer tools PSCP and PSFTP. It is
1077       available in PuTTY itself, although it is unlikely to be very useful
1078       in any tool other than Plink. Also, `-nc' uses the same server
1079       functionality as port forwarding, so it will not work if your server
1080       administrator has disabled port forwarding.
1081
1082       (The option is named `-nc' after the Unix program `nc', short for
1083       `netcat'. The command `plink host1 -nc host2:port' is very similar
1084       in functionality to `plink host1 nc host2 port', which invokes `nc'
1085       on the server and tells it to connect to the specified destination.
1086       However, Plink's built-in `-nc' option does not depend on the `nc'
1087       program being installed on the server.)
1088
10893.8.3.15 `-C': enable compression
1090
1091       The `-C' option enables compression of the data sent across the
1092       network. This option is only meaningful if you are using SSH.
1093
1094       This option is equivalent to the `Enable compression' checkbox in
1095       the SSH panel of the PuTTY configuration box (see section 4.18.3).
1096
10973.8.3.16 `-1' and `-2': specify an SSH protocol version
1098
1099       The `-1' and `-2' options force PuTTY to use version 1 or version 2
1100       of the SSH protocol. These options are only meaningful if you are
1101       using SSH.
1102
1103       These options are equivalent to selecting the SSH protocol version
1104       in the SSH panel of the PuTTY configuration box (see section
1105       4.18.4).
1106
11073.8.3.17 `-4' and `-6': specify an Internet protocol version
1108
1109       The `-4' and `-6' options force PuTTY to use the older Internet
1110       protocol IPv4 or the newer IPv6 for most outgoing connections.
1111
1112       These options are equivalent to selecting your preferred Internet
1113       protocol version as `IPv4' or `IPv6' in the Connection panel of the
1114       PuTTY configuration box (see section 4.13.4).
1115
11163.8.3.18 `-i': specify an SSH private key
1117
1118       The `-i' option allows you to specify the name of a private key file
1119       in `*.PPK' format which PuTTY will use to authenticate with the
1120       server. This option is only meaningful if you are using SSH.
1121
1122       If you are using Pageant, you can also specify a _public_ key file
1123       (in RFC 4716 or OpenSSH format) to identify a specific key file to
1124       use. (This won't work if you're not running Pageant, of course.)
1125
1126       For general information on public-key authentication, see chapter 8.
1127
1128       This option is equivalent to the `Private key file for
1129       authentication' box in the Auth panel of the PuTTY configuration box
1130       (see section 4.22.8).
1131
11323.8.3.19 `-loghost': specify a logical host name
1133
1134       This option overrides PuTTY's normal SSH host key caching policy by
1135       telling it the name of the host you expect your connection to end up
1136       at (in cases where this differs from the location PuTTY thinks it's
1137       connecting to). It can be a plain host name, or a host name followed
1138       by a colon and a port number. See section 4.13.5 for more detail on
1139       this.
1140
11413.8.3.20 `-hostkey': manually specify an expected host key
1142
1143       This option overrides PuTTY's normal SSH host key caching policy
1144       by telling it exactly what host key to expect, which can be
1145       useful if the normal automatic host key store in the Registry is
1146       unavailable. The argument to this option should be either a host key
1147       fingerprint, or an SSH-2 public key blob. See section 4.20.2 for
1148       more information.
1149
1150       You can specify this option more than once if you want to configure
1151       more than one key to be accepted.
1152
11533.8.3.21 `-pgpfp': display PGP key fingerprints
1154
1155       This option causes the PuTTY tools not to run as normal, but instead
1156       to display the fingerprints of the PuTTY PGP Master Keys, in
1157       order to aid with verifying new versions. See appendix E for more
1158       information.
1159
11603.8.3.22 `-sercfg': specify serial port configuration
1161
1162       This option specifies the configuration parameters for the serial
1163       port (baud rate, stop bits etc). Its argument is interpreted as
1164       a comma-separated list of configuration options, which can be as
1165       follows:
1166
1167        -  Any single digit from 5 to 9 sets the number of data bits.
1168
1169        -  `1', `1.5' or `2' sets the number of stop bits.
1170
1171        -  Any other numeric string is interpreted as a baud rate.
1172
1173        -  A single lower-case letter specifies the parity: `n' for none,
1174           `o' for odd, `e' for even, `m' for mark and `s' for space.
1175
1176        -  A single upper-case letter specifies the flow control: `N' for
1177           none, `X' for XON/XOFF, `R' for RTS/CTS and `D' for DSR/DTR.
1178
1179       For example, `-sercfg 19200,8,n,1,N' denotes a baud rate of 19200, 8
1180       data bits, no parity, 1 stop bit and no flow control.
1181
11823.8.3.23 `-sessionlog', `-sshlog', `-sshrawlog': specify session logging
1183
1184       These options cause the PuTTY network tools to write out a log
1185       file. Each of them expects a file name as an argument, e.g. `-
1186       sshlog putty.log' causes an SSH packet log to be written to a file
1187       called `putty.log'. The three different options select different
1188       logging modes, all available from the GUI too:
1189
1190        -  `-sessionlog' selects `All session output' logging mode.
1191
1192        -  `-sshlog' selects `SSH packets' logging mode.
1193
1194        -  `-sshrawlog' selects `SSH packets and raw data' logging mode.
1195
1196       For more information on logging configuration, see section 4.2.
1197
11983.8.3.24 `-proxycmd': specify a local proxy command
1199
1200       This option enables PuTTY's mode for running a command on the local
1201       machine and using it as a proxy for the network connection. It
1202       expects a shell command string as an argument.
1203
1204       See section 4.15.1 for more information on this, and on other proxy
1205       settings. In particular, note that since the special sequences
1206       described there are understood in the argument string, literal
1207       backslashes must be doubled (if you want `\' in your command, you
1208       must put `\\' on the command line).
1209
12103.8.3.25 `-restrict-acl': restrict the Windows process ACL
1211
1212       This option (on Windows only) causes PuTTY (or another PuTTY tool)
1213       to try to lock down the operating system's access control on its own
1214       process. If this succeeds, it should present an extra obstacle to
1215       malware that has managed to run under the same user id as the PuTTY
1216       process, by preventing it from attaching to PuTTY using the same
1217       interfaces debuggers use and either reading sensitive information
1218       out of its memory or hijacking its network session.
1219
1220       This option is not enabled by default, because this form of
1221       interaction between Windows programs has many legitimate uses,
1222       including accessibility software such as screen readers. Also,
1223       it cannot provide full security against this class of attack in
1224       any case, because PuTTY can only lock down its own ACL _after_ it
1225       has started up, and malware could still get in if it attacks the
1226       process between startup and lockdown. So it trades away noticeable
1227       convenience, and delivers less real security than you might want.
1228       However, if you do want to make that tradeoff anyway, the option is
1229       available.
1230
1231       A PuTTY process started with `-restrict-acl' will pass that on to
1232       any processes started with Duplicate Session, New Session etc.
1233       (However, if you're invoking PuTTY tools explicitly, for instance as
1234       a proxy command, you'll need to arrange to pass them the `-restrict-
1235       acl' option yourself, if that's what you want.)
1236
1237Chapter 4: Configuring PuTTY
1238----------------------------
1239
1240       This chapter describes all the configuration options in PuTTY.
1241
1242       PuTTY is configured using the control panel that comes up before you
1243       start a session. Some options can also be changed in the middle of a
1244       session, by selecting `Change Settings' from the window menu.
1245
1246   4.1 The Session panel
1247
1248       The Session configuration panel contains the basic options you need
1249       to specify in order to open a session at all, and also allows you to
1250       save your settings to be reloaded later.
1251
1252 4.1.1 The host name section
1253
1254       The top box on the Session panel, labelled `Specify your connection
1255       by host name', contains the details that need to be filled in before
1256       PuTTY can open a session at all.
1257
1258        -  The `Host Name' box is where you type the name, or the IP
1259           address, of the server you want to connect to.
1260
1261        -  The `Connection type' radio buttons let you choose what type
1262           of connection you want to make: a raw connection, a Telnet
1263           connection, an Rlogin connection, an SSH connection, or a
1264           connection to a local serial line. (See section 1.2 for a
1265           summary of the differences between SSH, Telnet and rlogin; see
1266           section 3.6 for an explanation of `raw' connections; see section
1267           3.7 for information about using a serial line.)
1268
1269        -  The `Port' box lets you specify which port number on the server
1270           to connect to. If you select Telnet, Rlogin, or SSH, this box
1271           will be filled in automatically to the usual value, and you will
1272           only need to change it if you have an unusual server. If you
1273           select Raw mode, you will almost certainly need to fill in the
1274           `Port' box yourself.
1275
1276       If you select `Serial' from the `Connection type' radio buttons,
1277       the `Host Name' and `Port' boxes are replaced by `Serial line' and
1278       `Speed'; see section 4.28 for more details of these.
1279
1280 4.1.2 Loading and storing saved sessions
1281
1282       The next part of the Session configuration panel allows you to save
1283       your preferred PuTTY options so they will appear automatically the
1284       next time you start PuTTY. It also allows you to create _saved
1285       sessions_, which contain a full set of configuration options plus a
1286       host name and protocol. A saved session contains all the information
1287       PuTTY needs to start exactly the session you want.
1288
1289        -  To save your default settings: first set up the settings the way
1290           you want them saved. Then come back to the Session panel. Select
1291           the `Default Settings' entry in the saved sessions list, with a
1292           single click. Then press the `Save' button.
1293
1294       If there is a specific host you want to store the details of how
1295       to connect to, you should create a saved session, which will be
1296       separate from the Default Settings.
1297
1298        -  To save a session: first go through the rest of the
1299           configuration box setting up all the options you want. Then come
1300           back to the Session panel. Enter a name for the saved session in
1301           the `Saved Sessions' input box. (The server name is often a good
1302           choice for a saved session name.) Then press the `Save' button.
1303           Your saved session name should now appear in the list box.
1304
1305           You can also save settings in mid-session, from the `Change
1306           Settings' dialog. Settings changed since the start of the
1307           session will be saved with their current values; as well as
1308           settings changed through the dialog, this includes changes in
1309           window size, window title changes sent by the server, and so on.
1310
1311        -  To reload a saved session: single-click to select the session
1312           name in the list box, and then press the `Load' button. Your
1313           saved settings should all appear in the configuration panel.
1314
1315        -  To modify a saved session: first load it as described above.
1316           Then make the changes you want. Come back to the Session panel,
1317           and press the `Save' button. The new settings will be saved over
1318           the top of the old ones.
1319
1320           To save the new settings under a different name, you can enter
1321           the new name in the `Saved Sessions' box, or single-click to
1322           select a session name in the list box to overwrite that session.
1323           To save `Default Settings', you must single-click the name
1324           before saving.
1325
1326        -  To start a saved session immediately: double-click on the
1327           session name in the list box.
1328
1329        -  To delete a saved session: single-click to select the session
1330           name in the list box, and then press the `Delete' button.
1331
1332       Each saved session is independent of the Default Settings
1333       configuration. If you change your preferences and update Default
1334       Settings, you must also update every saved session separately.
1335
1336       Saved sessions are stored in the Registry, at the location
1337
1338         HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\Sessions
1339
1340       If you need to store them in a file, you could try the method
1341       described in section 4.29.
1342
1343 4.1.3 `Close Window on Exit'
1344
1345       Finally in the Session panel, there is an option labelled `Close
1346       Window on Exit'. This controls whether the PuTTY terminal window
1347       disappears as soon as the session inside it terminates. If you are
1348       likely to want to copy and paste text out of the session after it
1349       has terminated, or restart the session, you should arrange for this
1350       option to be off.
1351
1352       `Close Window On Exit' has three settings. `Always' means always
1353       close the window on exit; `Never' means never close on exit (always
1354       leave the window open, but inactive). The third setting, and the
1355       default one, is `Only on clean exit'. In this mode, a session which
1356       terminates normally will cause its window to close, but one which is
1357       aborted unexpectedly by network trouble or a confusing message from
1358       the server will leave the window up.
1359
1360   4.2 The Logging panel
1361
1362       The Logging configuration panel allows you to save log files of your
1363       PuTTY sessions, for debugging, analysis or future reference.
1364
1365       The main option is a radio-button set that specifies whether PuTTY
1366       will log anything at all. The options are:
1367
1368        -  `None'. This is the default option; in this mode PuTTY will not
1369           create a log file at all.
1370
1371        -  `Printable output'. In this mode, a log file will be created
1372           and written to, but only printable text will be saved into it.
1373           The various terminal control codes that are typically sent down
1374           an interactive session alongside the printable text will be
1375           omitted. This might be a useful mode if you want to read a log
1376           file in a text editor and hope to be able to make sense of it.
1377
1378        -  `All session output'. In this mode, _everything_ sent by the
1379           server into your terminal session is logged. If you view the log
1380           file in a text editor, therefore, you may well find it full of
1381           strange control characters. This is a particularly useful mode
1382           if you are experiencing problems with PuTTY's terminal handling:
1383           you can record everything that went to the terminal, so that
1384           someone else can replay the session later in slow motion and
1385           watch to see what went wrong.
1386
1387        -  `SSH packets'. In this mode (which is only used by SSH
1388           connections), the SSH message packets sent over the encrypted
1389           connection are written to the log file (as well as Event Log
1390           entries). You might need this to debug a network-level problem,
1391           or more likely to send to the PuTTY authors as part of a bug
1392           report. _BE WARNED_ that if you log in using a password, the
1393           password can appear in the log file; see section 4.2.4 for
1394           options that may help to remove sensitive material from the log
1395           file before you send it to anyone else.
1396
1397        -  `SSH packets and raw data'. In this mode, as well as the
1398           decrypted packets (as in the previous mode), the _raw_
1399           (encrypted, compressed, etc) packets are _also_ logged. This
1400           could be useful to diagnose corruption in transit. (The same
1401           caveats as the previous mode apply, of course.)
1402
1403       Note that the non-SSH logging options (`Printable output' and `All
1404       session output') only work with PuTTY proper; in programs without
1405       terminal emulation (such as Plink), they will have no effect, even
1406       if enabled via saved settings.
1407
1408 4.2.1 `Log file name'
1409
1410       In this edit box you enter the name of the file you want to log the
1411       session to. The `Browse' button will let you look around your file
1412       system to find the right place to put the file; or if you already
1413       know exactly where you want it to go, you can just type a pathname
1414       into the edit box.
1415
1416       There are a few special features in this box. If you use the `&'
1417       character in the file name box, PuTTY will insert details of the
1418       current session in the name of the file it actually opens. The
1419       precise replacements it will do are:
1420
1421        -  `&Y' will be replaced by the current year, as four digits.
1422
1423        -  `&M' will be replaced by the current month, as two digits.
1424
1425        -  `&D' will be replaced by the current day of the month, as two
1426           digits.
1427
1428        -  `&T' will be replaced by the current time, as six digits
1429           (HHMMSS) with no punctuation.
1430
1431        -  `&H' will be replaced by the host name you are connecting to.
1432
1433        -  `&P' will be replaced by the port number you are connecting to
1434           on the target host.
1435
1436       For example, if you enter the host name `c:\puttylogs\log-&h-&y&m&d-
1437       &t.dat', you will end up with files looking like
1438
1439         log-server1.example.com-20010528-110859.dat
1440         log-unixbox.somewhere.org-20010611-221001.dat
1441
1442 4.2.2 `What to do if the log file already exists'
1443
1444       This control allows you to specify what PuTTY should do if it tries
1445       to start writing to a log file and it finds the file already exists.
1446       You might want to automatically destroy the existing log file and
1447       start a new one with the same name. Alternatively, you might want to
1448       open the existing log file and add data to the _end_ of it. Finally
1449       (the default option), you might not want to have any automatic
1450       behaviour, but to ask the user every time the problem comes up.
1451
1452 4.2.3 `Flush log file frequently'
1453
1454       This option allows you to control how frequently logged data is
1455       flushed to disc. By default, PuTTY will flush data as soon as it
1456       is displayed, so that if you view the log file while a session is
1457       still open, it will be up to date; and if the client system crashes,
1458       there's a greater chance that the data will be preserved.
1459
1460       However, this can incur a performance penalty. If PuTTY is running
1461       slowly with logging enabled, you could try unchecking this option.
1462       Be warned that the log file may not always be up to date as a result
1463       (although it will of course be flushed when it is closed, for
1464       instance at the end of a session).
1465
1466 4.2.4 Options specific to SSH packet logging
1467
1468       These options only apply if SSH packet data is being logged.
1469
1470       The following options allow particularly sensitive portions of
1471       unencrypted packets to be automatically left out of the log file.
1472       They are only intended to deter casual nosiness; an attacker could
1473       glean a lot of useful information from even these obfuscated logs
1474       (e.g., length of password).
1475
14764.2.4.1 `Omit known password fields'
1477
1478       When checked, decrypted password fields are removed from the log of
1479       transmitted packets. (This includes any user responses to challenge-
1480       response authentication methods such as `keyboard-interactive'.)
1481       This does not include X11 authentication data if using X11
1482       forwarding.
1483
1484       Note that this will only omit data that PuTTY _knows_ to be a
1485       password. However, if you start another login session within your
1486       PuTTY session, for instance, any password used will appear in the
1487       clear in the packet log. The next option may be of use to protect
1488       against this.
1489
1490       This option is enabled by default.
1491
14924.2.4.2 `Omit session data'
1493
1494       When checked, all decrypted `session data' is omitted; this is
1495       defined as data in terminal sessions and in forwarded channels (TCP,
1496       X11, and authentication agent). This will usually substantially
1497       reduce the size of the resulting log file.
1498
1499       This option is disabled by default.
1500
1501   4.3 The Terminal panel
1502
1503       The Terminal configuration panel allows you to control the behaviour
1504       of PuTTY's terminal emulation.
1505
1506 4.3.1 `Auto wrap mode initially on'
1507
1508       Auto wrap mode controls what happens when text printed in a PuTTY
1509       window reaches the right-hand edge of the window.
1510
1511       With auto wrap mode on, if a long line of text reaches the right-
1512       hand edge, it will wrap over on to the next line so you can still
1513       see all the text. With auto wrap mode off, the cursor will stay at
1514       the right-hand edge of the screen, and all the characters in the
1515       line will be printed on top of each other.
1516
1517       If you are running a full-screen application and you occasionally
1518       find the screen scrolling up when it looks as if it shouldn't, you
1519       could try turning this option off.
1520
1521       Auto wrap mode can be turned on and off by control sequences sent by
1522       the server. This configuration option controls the _default_ state,
1523       which will be restored when you reset the terminal (see section
1524       3.1.3.6). However, if you modify this option in mid-session using
1525       `Change Settings', it will take effect immediately.
1526
1527 4.3.2 `DEC Origin Mode initially on'
1528
1529       DEC Origin Mode is a minor option which controls how PuTTY
1530       interprets cursor-position control sequences sent by the server.
1531
1532       The server can send a control sequence that restricts the scrolling
1533       region of the display. For example, in an editor, the server might
1534       reserve a line at the top of the screen and a line at the bottom,
1535       and might send a control sequence that causes scrolling operations
1536       to affect only the remaining lines.
1537
1538       With DEC Origin Mode on, cursor coordinates are counted from the top
1539       of the scrolling region. With it turned off, cursor coordinates are
1540       counted from the top of the whole screen regardless of the scrolling
1541       region.
1542
1543       It is unlikely you would need to change this option, but if you find
1544       a full-screen application is displaying pieces of text in what looks
1545       like the wrong part of the screen, you could try turning DEC Origin
1546       Mode on to see whether that helps.
1547
1548       DEC Origin Mode can be turned on and off by control sequences sent
1549       by the server. This configuration option controls the _default_
1550       state, which will be restored when you reset the terminal (see
1551       section 3.1.3.6). However, if you modify this option in mid-session
1552       using `Change Settings', it will take effect immediately.
1553
1554 4.3.3 `Implicit CR in every LF'
1555
1556       Most servers send two control characters, CR and LF, to start a new
1557       line of the screen. The CR character makes the cursor return to the
1558       left-hand side of the screen. The LF character makes the cursor move
1559       one line down (and might make the screen scroll).
1560
1561       Some servers only send LF, and expect the terminal to move the
1562       cursor over to the left automatically. If you come across a server
1563       that does this, you will see a stepped effect on the screen, like
1564       this:
1565
1566         First line of text
1567                           Second line
1568                                      Third line
1569
1570       If this happens to you, try enabling the `Implicit CR in every LF'
1571       option, and things might go back to normal:
1572
1573         First line of text
1574         Second line
1575         Third line
1576
1577 4.3.4 `Implicit LF in every CR'
1578
1579       Most servers send two control characters, CR and LF, to start a new
1580       line of the screen. The CR character makes the cursor return to the
1581       left-hand side of the screen. The LF character makes the cursor move
1582       one line down (and might make the screen scroll).
1583
1584       Some servers only send CR, and so the newly written line is
1585       overwritten by the following line. This option causes a line feed so
1586       that all lines are displayed.
1587
1588 4.3.5 `Use background colour to erase screen'
1589
1590       Not all terminals agree on what colour to turn the screen when the
1591       server sends a `clear screen' sequence. Some terminals believe the
1592       screen should always be cleared to the _default_ background colour.
1593       Others believe the screen should be cleared to whatever the server
1594       has selected as a background colour.
1595
1596       There exist applications that expect both kinds of behaviour.
1597       Therefore, PuTTY can be configured to do either.
1598
1599       With this option disabled, screen clearing is always done in the
1600       default background colour. With this option enabled, it is done in
1601       the _current_ background colour.
1602
1603       Background-colour erase can be turned on and off by control
1604       sequences sent by the server. This configuration option controls the
1605       _default_ state, which will be restored when you reset the terminal
1606       (see section 3.1.3.6). However, if you modify this option in mid-
1607       session using `Change Settings', it will take effect immediately.
1608
1609 4.3.6 `Enable blinking text'
1610
1611       The server can ask PuTTY to display text that blinks on and off.
1612       This is very distracting, so PuTTY allows you to turn blinking text
1613       off completely.
1614
1615       When blinking text is disabled and the server attempts to make
1616       some text blink, PuTTY will instead display the text with a bolded
1617       background colour.
1618
1619       Blinking text can be turned on and off by control sequences sent by
1620       the server. This configuration option controls the _default_ state,
1621       which will be restored when you reset the terminal (see section
1622       3.1.3.6). However, if you modify this option in mid-session using
1623       `Change Settings', it will take effect immediately.
1624
1625 4.3.7 `Answerback to ^E'
1626
1627       This option controls what PuTTY will send back to the server if the
1628       server sends it the ^E enquiry character. Normally it just sends the
1629       string `PuTTY'.
1630
1631       If you accidentally write the contents of a binary file to your
1632       terminal, you will probably find that it contains more than one ^E
1633       character, and as a result your next command line will probably
1634       read `PuTTYPuTTYPuTTY...' as if you had typed the answerback string
1635       multiple times at the keyboard. If you set the answerback string
1636       to be empty, this problem should go away, but doing so might cause
1637       other problems.
1638
1639       Note that this is _not_ the feature of PuTTY which the server will
1640       typically use to determine your terminal type. That feature is the
1641       `Terminal-type string' in the Connection panel; see section 4.14.3
1642       for details.
1643
1644       You can include control characters in the answerback string using
1645       `^C' notation. (Use `^~' to get a literal `^'.)
1646
1647 4.3.8 `Local echo'
1648
1649       With local echo disabled, characters you type into the PuTTY window
1650       are not echoed in the window _by PuTTY_. They are simply sent to the
1651       server. (The _server_ might choose to echo them back to you; this
1652       can't be controlled from the PuTTY control panel.)
1653
1654       Some types of session need local echo, and many do not. In its
1655       default mode, PuTTY will automatically attempt to deduce whether
1656       or not local echo is appropriate for the session you are working
1657       in. If you find it has made the wrong decision, you can use this
1658       configuration option to override its choice: you can force local
1659       echo to be turned on, or force it to be turned off, instead of
1660       relying on the automatic detection.
1661
1662 4.3.9 `Local line editing'
1663
1664       Normally, every character you type into the PuTTY window is sent
1665       immediately to the server the moment you type it.
1666
1667       If you enable local line editing, this changes. PuTTY will let you
1668       edit a whole line at a time locally, and the line will only be sent
1669       to the server when you press Return. If you make a mistake, you can
1670       use the Backspace key to correct it before you press Return, and the
1671       server will never see the mistake.
1672
1673       Since it is hard to edit a line locally without being able to see
1674       it, local line editing is mostly used in conjunction with local echo
1675       (section 4.3.8). This makes it ideal for use in raw mode or when
1676       connecting to MUDs or talkers. (Although some more advanced MUDs do
1677       occasionally turn local line editing on and turn local echo off, in
1678       order to accept a password from the user.)
1679
1680       Some types of session need local line editing, and many do not. In
1681       its default mode, PuTTY will automatically attempt to deduce whether
1682       or not local line editing is appropriate for the session you are
1683       working in. If you find it has made the wrong decision, you can use
1684       this configuration option to override its choice: you can force
1685       local line editing to be turned on, or force it to be turned off,
1686       instead of relying on the automatic detection.
1687
16884.3.10 Remote-controlled printing
1689
1690       A lot of VT100-compatible terminals support printing under control
1691       of the remote server (sometimes called `passthrough printing').
1692       PuTTY supports this feature as well, but it is turned off by
1693       default.
1694
1695       To enable remote-controlled printing, choose a printer from
1696       the `Printer to send ANSI printer output to' drop-down list
1697       box. This should allow you to select from all the printers you
1698       have installed drivers for on your computer. Alternatively, you
1699       can type the network name of a networked printer (for example,
1700       `\\printserver\printer1') even if you haven't already installed a
1701       driver for it on your own machine.
1702
1703       When the remote server attempts to print some data, PuTTY will send
1704       that data to the printer _raw_ - without translating it, attempting
1705       to format it, or doing anything else to it. It is up to you to
1706       ensure your remote server knows what type of printer it is talking
1707       to.
1708
1709       Since PuTTY sends data to the printer raw, it cannot offer options
1710       such as portrait versus landscape, print quality, or paper tray
1711       selection. All these things would be done by your PC printer driver
1712       (which PuTTY bypasses); if you need them done, you will have to find
1713       a way to configure your remote server to do them.
1714
1715       To disable remote printing again, choose `None (printing disabled)'
1716       from the printer selection list. This is the default state.
1717
1718   4.4 The Keyboard panel
1719
1720       The Keyboard configuration panel allows you to control the behaviour
1721       of the keyboard in PuTTY. The correct state for many of these
1722       settings depends on what the server to which PuTTY is connecting
1723       expects. With a Unix server, this is likely to depend on the
1724       `termcap' or `terminfo' entry it uses, which in turn is likely to be
1725       controlled by the `Terminal-type string' setting in the Connection
1726       panel; see section 4.14.3 for details. If none of the settings here
1727       seems to help, you may find question A.7.13 to be useful.
1728
1729 4.4.1 Changing the action of the Backspace key
1730
1731       Some terminals believe that the Backspace key should send the same
1732       thing to the server as Control-H (ASCII code 8). Other terminals
1733       believe that the Backspace key should send ASCII code 127 (usually
1734       known as Control-?) so that it can be distinguished from Control-H.
1735       This option allows you to choose which code PuTTY generates when you
1736       press Backspace.
1737
1738       If you are connecting over SSH, PuTTY by default tells the server
1739       the value of this option (see section 4.24.2), so you may find that
1740       the Backspace key does the right thing either way. Similarly, if
1741       you are connecting to a Unix system, you will probably find that
1742       the Unix `stty' command lets you configure which the server expects
1743       to see, so again you might not need to change which one PuTTY
1744       generates. On other systems, the server's expectation might be fixed
1745       and you might have no choice but to configure PuTTY.
1746
1747       If you do have the choice, we recommend configuring PuTTY to
1748       generate Control-? and configuring the server to expect it, because
1749       that allows applications such as `emacs' to use Control-H for help.
1750
1751       (Typing Shift-Backspace will cause PuTTY to send whichever code
1752       isn't configured here as the default.)
1753
1754 4.4.2 Changing the action of the Home and End keys
1755
1756       The Unix terminal emulator `rxvt' disagrees with the rest of the
1757       world about what character sequences should be sent to the server by
1758       the Home and End keys.
1759
1760       `xterm', and other terminals, send `ESC [1~' for the Home key, and
1761       `ESC [4~' for the End key. `rxvt' sends `ESC [H' for the Home key
1762       and `ESC [Ow' for the End key.
1763
1764       If you find an application on which the Home and End keys aren't
1765       working, you could try switching this option to see if it helps.
1766
1767 4.4.3 Changing the action of the function keys and keypad
1768
1769       This option affects the function keys (F1 to F12) and the top row of
1770       the numeric keypad.
1771
1772        -  In the default mode, labelled `ESC [n~', the function keys
1773           generate sequences like `ESC [11~', `ESC [12~' and so on. This
1774           matches the general behaviour of Digital's terminals.
1775
1776        -  In Linux mode, F6 to F12 behave just like the default mode, but
1777           F1 to F5 generate `ESC [[A' through to `ESC [[E'. This mimics
1778           the Linux virtual console.
1779
1780        -  In Xterm R6 mode, F5 to F12 behave like the default mode, but
1781           F1 to F4 generate `ESC OP' through to `ESC OS', which are the
1782           sequences produced by the top row of the _keypad_ on Digital's
1783           terminals.
1784
1785        -  In VT400 mode, all the function keys behave like the default
1786           mode, but the actual top row of the numeric keypad generates
1787           `ESC OP' through to `ESC OS'.
1788
1789        -  In VT100+ mode, the function keys generate `ESC OP' through to
1790           `ESC O['
1791
1792        -  In SCO mode, the function keys F1 to F12 generate `ESC [M'
1793           through to `ESC [X'. Together with shift, they generate `ESC [Y'
1794           through to `ESC [j'. With control they generate `ESC [k' through
1795           to `ESC [v', and with shift and control together they generate
1796           `ESC [w' through to `ESC [{'.
1797
1798       If you don't know what any of this means, you probably don't need to
1799       fiddle with it.
1800
1801 4.4.4 Controlling Application Cursor Keys mode
1802
1803       Application Cursor Keys mode is a way for the server to change the
1804       control sequences sent by the arrow keys. In normal mode, the arrow
1805       keys send `ESC [A' through to `ESC [D'. In application mode, they
1806       send `ESC OA' through to `ESC OD'.
1807
1808       Application Cursor Keys mode can be turned on and off by the server,
1809       depending on the application. PuTTY allows you to configure the
1810       initial state.
1811
1812       You can also disable application cursor keys mode completely, using
1813       the `Features' configuration panel; see section 4.6.1.
1814
1815 4.4.5 Controlling Application Keypad mode
1816
1817       Application Keypad mode is a way for the server to change the
1818       behaviour of the numeric keypad.
1819
1820       In normal mode, the keypad behaves like a normal Windows keypad:
1821       with NumLock on, the number keys generate numbers, and with NumLock
1822       off they act like the arrow keys and Home, End etc.
1823
1824       In application mode, all the keypad keys send special control
1825       sequences, _including_ Num Lock. Num Lock stops behaving like Num
1826       Lock and becomes another function key.
1827
1828       Depending on which version of Windows you run, you may find the Num
1829       Lock light still flashes on and off every time you press Num Lock,
1830       even when application mode is active and Num Lock is acting like a
1831       function key. This is unavoidable.
1832
1833       Application keypad mode can be turned on and off by the server,
1834       depending on the application. PuTTY allows you to configure the
1835       initial state.
1836
1837       You can also disable application keypad mode completely, using the
1838       `Features' configuration panel; see section 4.6.1.
1839
1840 4.4.6 Using NetHack keypad mode
1841
1842       PuTTY has a special mode for playing NetHack. You can enable it
1843       by selecting `NetHack' in the `Initial state of numeric keypad'
1844       control.
1845
1846       In this mode, the numeric keypad keys 1-9 generate the NetHack
1847       movement commands (hjklyubn). The 5 key generates the `.' command
1848       (do nothing).
1849
1850       In addition, pressing Shift or Ctrl with the keypad keys generate
1851       the Shift- or Ctrl-keys you would expect (e.g. keypad-7 generates
1852       `y', so Shift-keypad-7 generates `Y' and Ctrl-keypad-7 generates
1853       Ctrl-Y); these commands tell NetHack to keep moving you in the same
1854       direction until you encounter something interesting.
1855
1856       For some reason, this feature only works properly when Num Lock is
1857       on. We don't know why.
1858
1859 4.4.7 Enabling a DEC-like Compose key
1860
1861       DEC terminals have a Compose key, which provides an easy-to-remember
1862       way of typing accented characters. You press Compose and then type
1863       two more characters. The two characters are `combined' to produce
1864       an accented character. The choices of character are designed to be
1865       easy to remember; for example, composing `e' and ``' produces the
1866       `e-grave' character.
1867
1868       If your keyboard has a Windows Application key, it acts as a Compose
1869       key in PuTTY. Alternatively, if you enable the `AltGr acts as
1870       Compose key' option, the AltGr key will become a Compose key.
1871
1872 4.4.8 `Control-Alt is different from AltGr'
1873
1874       Some old keyboards do not have an AltGr key, which can make it
1875       difficult to type some characters. PuTTY can be configured to treat
1876       the key combination Ctrl + Left Alt the same way as the AltGr key.
1877
1878       By default, this checkbox is checked, and the key combination Ctrl +
1879       Left Alt does something completely different. PuTTY's usual handling
1880       of the left Alt key is to prefix the Escape (Control-[) character to
1881       whatever character sequence the rest of the keypress would generate.
1882       For example, Alt-A generates Escape followed by `a'. So Alt-Ctrl-A
1883       would generate Escape, followed by Control-A.
1884
1885       If you uncheck this box, Ctrl-Alt will become a synonym for AltGr,
1886       so you can use it to type extra graphic characters if your keyboard
1887       has any.
1888
1889       (However, Ctrl-Alt will never act as a Compose key, regardless of
1890       the setting of `AltGr acts as Compose key' described in section
1891       4.4.7.)
1892
1893   4.5 The Bell panel
1894
1895       The Bell panel controls the terminal bell feature: the server's
1896       ability to cause PuTTY to beep at you.
1897
1898       In the default configuration, when the server sends the character
1899       with ASCII code 7 (Control-G), PuTTY will play the Windows Default
1900       Beep sound. This is not always what you want the terminal bell
1901       feature to do; the Bell panel allows you to configure alternative
1902       actions.
1903
1904 4.5.1 `Set the style of bell'
1905
1906       This control allows you to select various different actions to occur
1907       on a terminal bell:
1908
1909        -  Selecting `None' disables the bell completely. In this mode, the
1910           server can send as many Control-G characters as it likes and
1911           nothing at all will happen.
1912
1913        -  `Make default system alert sound' is the default setting.
1914           It causes the Windows `Default Beep' sound to be played. To
1915           change what this sound is, or to test it if nothing seems to
1916           be happening, use the Sound configurer in the Windows Control
1917           Panel.
1918
1919        -  `Visual bell' is a silent alternative to a beeping computer. In
1920           this mode, when the server sends a Control-G, the whole PuTTY
1921           window will flash white for a fraction of a second.
1922
1923        -  `Beep using the PC speaker' is self-explanatory.
1924
1925        -  `Play a custom sound file' allows you to specify a particular
1926           sound file to be used by PuTTY alone, or even by a particular
1927           individual PuTTY session. This allows you to distinguish your
1928           PuTTY beeps from any other beeps on the system. If you select
1929           this option, you will also need to enter the name of your sound
1930           file in the edit control `Custom sound file to play as a bell'.
1931
1932 4.5.2 `Taskbar/caption indication on bell'
1933
1934       This feature controls what happens to the PuTTY window's entry in
1935       the Windows Taskbar if a bell occurs while the window does not have
1936       the input focus.
1937
1938       In the default state (`Disabled') nothing unusual happens.
1939
1940       If you select `Steady', then when a bell occurs and the window is
1941       not in focus, the window's Taskbar entry and its title bar will
1942       change colour to let you know that PuTTY session is asking for your
1943       attention. The change of colour will persist until you select the
1944       window, so you can leave several PuTTY windows minimised in your
1945       terminal, go away from your keyboard, and be sure not to have missed
1946       any important beeps when you get back.
1947
1948       `Flashing' is even more eye-catching: the Taskbar entry will
1949       continuously flash on and off until you select the window.
1950
1951 4.5.3 `Control the bell overload behaviour'
1952
1953       A common user error in a terminal session is to accidentally run the
1954       Unix command `cat' (or equivalent) on an inappropriate file type,
1955       such as an executable, image file, or ZIP file. This produces a huge
1956       stream of non-text characters sent to the terminal, which typically
1957       includes a lot of bell characters. As a result of this the terminal
1958       often doesn't stop beeping for ten minutes, and everybody else in
1959       the office gets annoyed.
1960
1961       To try to avoid this behaviour, or any other cause of excessive
1962       beeping, PuTTY includes a bell overload management feature. In the
1963       default configuration, receiving more than five bell characters in a
1964       two-second period will cause the overload feature to activate. Once
1965       the overload feature is active, further bells will  have no effect
1966       at all, so the rest of your binary file will be sent to the screen
1967       in silence. After a period of five seconds during which no further
1968       bells are received, the overload feature will turn itself off again
1969       and bells will be re-enabled.
1970
1971       If you want this feature completely disabled, you can turn it off
1972       using the checkbox `Bell is temporarily disabled when over-used'.
1973
1974       Alternatively, if you like the bell overload feature but don't
1975       agree with the settings, you can configure the details: how many
1976       bells constitute an overload, how short a time period they have to
1977       arrive in to do so, and how much silent time is required before the
1978       overload feature will deactivate itself.
1979
1980       Bell overload mode is always deactivated by any keypress in the
1981       terminal. This means it can respond to large unexpected streams of
1982       data, but does not interfere with ordinary command-line activities
1983       that generate beeps (such as filename completion).
1984
1985   4.6 The Features panel
1986
1987       PuTTY's terminal emulation is very highly featured, and can do a
1988       lot of things under remote server control. Some of these features
1989       can cause problems due to buggy or strangely configured server
1990       applications.
1991
1992       The Features configuration panel allows you to disable some of
1993       PuTTY's more advanced terminal features, in case they cause trouble.
1994
1995 4.6.1 Disabling application keypad and cursor keys
1996
1997       Application keypad mode (see section 4.4.5) and application cursor
1998       keys mode (see section 4.4.4) alter the behaviour of the keypad and
1999       cursor keys. Some applications enable these modes but then do not
2000       deal correctly with the modified keys. You can force these modes to
2001       be permanently disabled no matter what the server tries to do.
2002
2003 4.6.2 Disabling xterm-style mouse reporting
2004
2005       PuTTY allows the server to send control codes that let it take
2006       over the mouse and use it for purposes other than copy and paste.
2007       Applications which use this feature include the text-mode web
2008       browser `links', the Usenet newsreader `trn' version 4, and the file
2009       manager `mc' (Midnight Commander).
2010
2011       If you find this feature inconvenient, you can disable it using the
2012       `Disable xterm-style mouse reporting' control. With this box ticked,
2013       the mouse will _always_ do copy and paste in the normal way.
2014
2015       Note that even if the application takes over the mouse, you can
2016       still manage PuTTY's copy and paste by holding down the Shift key
2017       while you select and paste, unless you have deliberately turned this
2018       feature off (see section 4.11.3).
2019
2020 4.6.3 Disabling remote terminal resizing
2021
2022       PuTTY has the ability to change the terminal's size and position in
2023       response to commands from the server. If you find PuTTY is doing
2024       this unexpectedly or inconveniently, you can tell PuTTY not to
2025       respond to those server commands.
2026
2027 4.6.4 Disabling switching to the alternate screen
2028
2029       Many terminals, including PuTTY, support an `alternate screen'. This
2030       is the same size as the ordinary terminal screen, but separate.
2031       Typically a screen-based program such as a text editor might switch
2032       the terminal to the alternate screen before starting up. Then at the
2033       end of the run, it switches back to the primary screen, and you see
2034       the screen contents just as they were before starting the editor.
2035
2036       Some people prefer this not to happen. If you want your editor to
2037       run in the same screen as the rest of your terminal activity, you
2038       can disable the alternate screen feature completely.
2039
2040 4.6.5 Disabling remote window title changing
2041
2042       PuTTY has the ability to change the window title in response
2043       to commands from the server. If you find PuTTY is doing this
2044       unexpectedly or inconveniently, you can tell PuTTY not to respond to
2045       those server commands.
2046
2047 4.6.6 Response to remote window title querying
2048
2049       PuTTY can optionally provide the xterm service of allowing server
2050       applications to find out the local window title. This feature is
2051       disabled by default, but you can turn it on if you really want it.
2052
2053       NOTE that this feature is a _potential security hazard_. If a
2054       malicious application can write data to your terminal (for example,
2055       if you merely `cat' a file owned by someone else on the server
2056       machine), it can change your window title (unless you have disabled
2057       this as mentioned in section 4.6.5) and then use this service to
2058       have the new window title sent back to the server as if typed at the
2059       keyboard. This allows an attacker to fake keypresses and potentially
2060       cause your server-side applications to do things you didn't want.
2061       Therefore this feature is disabled by default, and we recommend you
2062       do not set it to `Window title' unless you _really_ know what you
2063       are doing.
2064
2065       There are three settings for this option:
2066
2067       `None'
2068
2069           PuTTY makes no response whatsoever to the relevant escape
2070           sequence. This may upset server-side software that is expecting
2071           some sort of response.
2072
2073       `Empty string'
2074
2075           PuTTY makes a well-formed response, but leaves it blank. Thus,
2076           server-side software that expects a response is kept happy,
2077           but an attacker cannot influence the response string. This is
2078           probably the setting you want if you have no better ideas.
2079
2080       `Window title'
2081
2082           PuTTY responds with the actual window title. This is dangerous
2083           for the reasons described above.
2084
2085 4.6.7 Disabling remote scrollback clearing
2086
2087       PuTTY has the ability to clear the terminal's scrollback buffer in
2088       response to a command from the server. If you find PuTTY is doing
2089       this unexpectedly or inconveniently, you can tell PuTTY not to
2090       respond to that server command.
2091
2092 4.6.8 Disabling destructive backspace
2093
2094       Normally, when PuTTY receives character 127 (^?) from the server,
2095       it will perform a `destructive backspace': move the cursor one
2096       space left and delete the character under it. This can apparently
2097       cause problems in some applications, so PuTTY provides the ability
2098       to configure character 127 to perform a normal backspace (without
2099       deleting a character) instead.
2100
2101 4.6.9 Disabling remote character set configuration
2102
2103       PuTTY has the ability to change its character set configuration
2104       in response to commands from the server. Some programs send these
2105       commands unexpectedly or inconveniently. In particular, BitchX (an
2106       IRC client) seems to have a habit of reconfiguring the character set
2107       to something other than the user intended.
2108
2109       If you find that accented characters are not showing up the way you
2110       expect them to, particularly if you're running BitchX, you could try
2111       disabling the remote character set configuration commands.
2112
21134.6.10 Disabling Arabic text shaping
2114
2115       PuTTY supports shaping of Arabic text, which means that if your
2116       server sends text written in the basic Unicode Arabic alphabet then
2117       it will convert it to the correct display forms before printing it
2118       on the screen.
2119
2120       If you are using full-screen software which was not expecting
2121       this to happen (especially if you are not an Arabic speaker and
2122       you unexpectedly find yourself dealing with Arabic text files in
2123       applications which are not Arabic-aware), you might find that the
2124       display becomes corrupted. By ticking this box, you can disable
2125       Arabic text shaping so that PuTTY displays precisely the characters
2126       it is told to display.
2127
2128       You may also find you need to disable bidirectional text display;
2129       see section 4.6.11.
2130
21314.6.11 Disabling bidirectional text display
2132
2133       PuTTY supports bidirectional text display, which means that if your
2134       server sends text written in a language which is usually displayed
2135       from right to left (such as Arabic or Hebrew) then PuTTY will
2136       automatically flip it round so that it is displayed in the right
2137       direction on the screen.
2138
2139       If you are using full-screen software which was not expecting
2140       this to happen (especially if you are not an Arabic speaker and
2141       you unexpectedly find yourself dealing with Arabic text files in
2142       applications which are not Arabic-aware), you might find that the
2143       display becomes corrupted. By ticking this box, you can disable
2144       bidirectional text display, so that PuTTY displays text from left to
2145       right in all situations.
2146
2147       You may also find you need to disable Arabic text shaping; see
2148       section 4.6.10.
2149
2150   4.7 The Window panel
2151
2152       The Window configuration panel allows you to control aspects of the
2153       PuTTY window.
2154
2155 4.7.1 Setting the size of the PuTTY window
2156
2157       The `Columns' and `Rows' boxes let you set the PuTTY window to a
2158       precise size. Of course you can also drag the window to a new size
2159       while a session is running.
2160
2161 4.7.2 What to do when the window is resized
2162
2163       These options allow you to control what happens when the user tries
2164       to resize the PuTTY window using its window furniture.
2165
2166       There are four options here:
2167
2168        -  `Change the number of rows and columns': the font size will not
2169           change. (This is the default.)
2170
2171        -  `Change the size of the font': the number of rows and columns in
2172           the terminal will stay the same, and the font size will change.
2173
2174        -  `Change font size when maximised': when the window is resized,
2175           the number of rows and columns will change, _except_ when the
2176           window is maximised (or restored), when the font size will
2177           change. (In this mode, holding down the Alt key while resizing
2178           will also cause the font size to change.)
2179
2180        -  `Forbid resizing completely': the terminal will refuse to be
2181           resized at all.
2182
2183 4.7.3 Controlling scrollback
2184
2185       These options let you configure the way PuTTY keeps text after it
2186       scrolls off the top of the screen (see section 3.1.2).
2187
2188       The `Lines of scrollback' box lets you configure how many lines of
2189       text PuTTY keeps. The `Display scrollbar' options allow you to hide
2190       the scrollbar (although you can still view the scrollback using
2191       the keyboard as described in section 3.1.2). You can separately
2192       configure whether the scrollbar is shown in full-screen mode and in
2193       normal modes.
2194
2195       If you are viewing part of the scrollback when the server sends
2196       more text to PuTTY, the screen will revert to showing the current
2197       terminal contents. You can disable this behaviour by turning off
2198       `Reset scrollback on display activity'. You can also make the screen
2199       revert when you press a key, by turning on `Reset scrollback on
2200       keypress'.
2201
2202 4.7.4 `Push erased text into scrollback'
2203
2204       When this option is enabled, the contents of the terminal screen
2205       will be pushed into the scrollback when a server-side application
2206       clears the screen, so that your scrollback will contain a better
2207       record of what was on your screen in the past.
2208
2209       If the application switches to the alternate screen (see section
2210       4.6.4 for more about this), then the contents of the primary screen
2211       will be visible in the scrollback until the application switches
2212       back again.
2213
2214       This option is enabled by default.
2215
2216   4.8 The Appearance panel
2217
2218       The Appearance configuration panel allows you to control aspects of
2219       the appearance of PuTTY's window.
2220
2221 4.8.1 Controlling the appearance of the cursor
2222
2223       The `Cursor appearance' option lets you configure the cursor to be a
2224       block, an underline, or a vertical line. A block cursor becomes an
2225       empty box when the window loses focus; an underline or a vertical
2226       line becomes dotted.
2227
2228       The `Cursor blinks' option makes the cursor blink on and off. This
2229       works in any of the cursor modes.
2230
2231 4.8.2 Controlling the font used in the terminal window
2232
2233       This option allows you to choose what font, in what size, the PuTTY
2234       terminal window uses to display the text in the session.
2235
2236       By default, you will be offered a choice from all the fixed-width
2237       fonts installed on the system, since VT100-style terminal handling
2238       expects a fixed-width font. If you tick the box marked `Allow
2239       selection of variable-pitch fonts', however, PuTTY will offer
2240       variable-width fonts as well: if you select one of these, the font
2241       will be coerced into fixed-size character cells, which will probably
2242       not look very good (but can work OK with some fonts).
2243
2244 4.8.3 `Hide mouse pointer when typing in window'
2245
2246       If you enable this option, the mouse pointer will disappear if the
2247       PuTTY window is selected and you press a key. This way, it will
2248       not obscure any of the text in the window while you work in your
2249       session. As soon as you move the mouse, the pointer will reappear.
2250
2251       This option is disabled by default, so the mouse pointer remains
2252       visible at all times.
2253
2254 4.8.4 Controlling the window border
2255
2256       PuTTY allows you to configure the appearance of the window border to
2257       some extent.
2258
2259       The checkbox marked `Sunken-edge border' changes the appearance of
2260       the window border to something more like a DOS box: the inside edge
2261       of the border is highlighted as if it sank down to meet the surface
2262       inside the window. This makes the border a little bit thicker as
2263       well. It's hard to describe well. Try it and see if you like it.
2264
2265       You can also configure a completely blank gap between the text in
2266       the window and the border, using the `Gap between text and window
2267       edge' control. By default this is set at one pixel. You can reduce
2268       it to zero, or increase it further.
2269
2270   4.9 The Behaviour panel
2271
2272       The Behaviour configuration panel allows you to control aspects of
2273       the behaviour of PuTTY's window.
2274
2275 4.9.1 Controlling the window title
2276
2277       The `Window title' edit box allows you to set the title of the PuTTY
2278       window. By default the window title will contain the host name
2279       followed by `PuTTY', for example `server1.example.com - PuTTY'. If
2280       you want a different window title, this is where to set it.
2281
2282       PuTTY allows the server to send `xterm' control sequences which
2283       modify the title of the window in mid-session (unless this is
2284       disabled - see section 4.6.5); the title string set here is
2285       therefore only the _initial_ window title.
2286
2287       As well as the _window_ title, there is also an `xterm' sequence
2288       to modify the title of the window's _icon_. This makes sense in a
2289       windowing system where the window becomes an icon when minimised,
2290       such as Windows 3.1 or most X Window System setups; but in the
2291       Windows 95-like user interface it isn't as applicable.
2292
2293       By default, PuTTY only uses the server-supplied _window_ title,
2294       and ignores the icon title entirely. If for some reason you want
2295       to see both titles, check the box marked `Separate window and icon
2296       titles'. If you do this, PuTTY's window title and Taskbar caption
2297       will change into the server-supplied icon title if you minimise the
2298       PuTTY window, and change back to the server-supplied window title if
2299       you restore it. (If the server has not bothered to supply a window
2300       or icon title, none of this will happen.)
2301
2302 4.9.2 `Warn before closing window'
2303
2304       If you press the Close button in a PuTTY window that contains a
2305       running session, PuTTY will put up a warning window asking if you
2306       really meant to close the window. A window whose session has already
2307       terminated can always be closed without a warning.
2308
2309       If you want to be able to close a window quickly, you can disable
2310       the `Warn before closing window' option.
2311
2312 4.9.3 `Window closes on ALT-F4'
2313
2314       By default, pressing ALT-F4 causes the window to close (or a warning
2315       box to appear; see section 4.9.2). If you disable the `Window closes
2316       on ALT-F4' option, then pressing ALT-F4 will simply send a key
2317       sequence to the server.
2318
2319 4.9.4 `System menu appears on ALT-Space'
2320
2321       If this option is enabled, then pressing ALT-Space will bring up the
2322       PuTTY window's menu, like clicking on the top left corner. If it is
2323       disabled, then pressing ALT-Space will just send `ESC SPACE' to the
2324       server.
2325
2326       Some accessibility programs for Windows may need this option
2327       enabling to be able to control PuTTY's window successfully. For
2328       instance, Dragon NaturallySpeaking requires it both to open the
2329       system menu via voice, and to close, minimise, maximise and restore
2330       the window.
2331
2332 4.9.5 `System menu appears on Alt alone'
2333
2334       If this option is enabled, then pressing and releasing ALT will
2335       bring up the PuTTY window's menu, like clicking on the top left
2336       corner. If it is disabled, then pressing and releasing ALT will have
2337       no effect.
2338
2339 4.9.6 `Ensure window is always on top'
2340
2341       If this option is enabled, the PuTTY window will stay on top of all
2342       other windows.
2343
2344 4.9.7 `Full screen on Alt-Enter'
2345
2346       If this option is enabled, then pressing Alt-Enter will cause the
2347       PuTTY window to become full-screen. Pressing Alt-Enter again will
2348       restore the previous window size.
2349
2350       The full-screen feature is also available from the System menu, even
2351       when it is configured not to be available on the Alt-Enter key. See
2352       section 3.1.3.7.
2353
2354  4.10 The Translation panel
2355
2356       The Translation configuration panel allows you to control the
2357       translation between the character set understood by the server and
2358       the character set understood by PuTTY.
2359
23604.10.1 Controlling character set translation
2361
2362       During an interactive session, PuTTY receives a stream of 8-bit
2363       bytes from the server, and in order to display them on the screen it
2364       needs to know what character set to interpret them in. Similarly,
2365       PuTTY needs to know how to translate your keystrokes into the
2366       encoding the server expects. Unfortunately, there is no satisfactory
2367       mechanism for PuTTY and the server to communicate this information,
2368       so it must usually be manually configured.
2369
2370       There are a lot of character sets to choose from. The `Remote
2371       character set' option lets you select one.
2372
2373       By default PuTTY will use the UTF-8 encoding of Unicode, which can
2374       represent pretty much any character; data coming from the server
2375       is interpreted as UTF-8, and keystrokes are sent UTF-8 encoded.
2376       This is what most modern distributions of Linux will expect by
2377       default. However, if this is wrong for your server, you can select a
2378       different character set using this control.
2379
2380       A few other notable character sets are:
2381
2382        -  The ISO-8859 series are all standard character sets that include
2383           various accented characters appropriate for different sets of
2384           languages.
2385
2386        -  The Win125x series are defined by Microsoft, for similar
2387           purposes. In particular Win1252 is almost equivalent to ISO-
2388           8859-1, but contains a few extra characters such as matched
2389           quotes and the Euro symbol.
2390
2391        -  If you want the old IBM PC character set with block graphics and
2392           line-drawing characters, you can select `CP437'.
2393
2394       If you need support for a numeric code page which is not listed in
2395       the drop-down list, such as code page 866, then you can try entering
2396       its name manually (`CP866' for example) in the list box. If the
2397       underlying version of Windows has the appropriate translation table
2398       installed, PuTTY will use it.
2399
24004.10.2 `Treat CJK ambiguous characters as wide'
2401
2402       There are some Unicode characters whose width is not well-defined.
2403       In most contexts, such characters should be treated as single-
2404       width for the purposes of wrapping and so on; however, in some CJK
2405       contexts, they are better treated as double-width for historical
2406       reasons, and some server-side applications may expect them to be
2407       displayed as such. Setting this option will cause PuTTY to take the
2408       double-width interpretation.
2409
2410       If you use legacy CJK applications, and you find your lines are
2411       wrapping in the wrong places, or you are having other display
2412       problems, you might want to play with this setting.
2413
2414       This option only has any effect in UTF-8 mode (see section 4.10.1).
2415
24164.10.3 `Caps Lock acts as Cyrillic switch'
2417
2418       This feature allows you to switch between a US/UK keyboard layout
2419       and a Cyrillic keyboard layout by using the Caps Lock key, if you
2420       need to type (for example) Russian and English side by side in the
2421       same document.
2422
2423       Currently this feature is not expected to work properly if your
2424       native keyboard layout is not US or UK.
2425
24264.10.4 Controlling display of line-drawing characters
2427
2428       VT100-series terminals allow the server to send control sequences
2429       that shift temporarily into a separate character set for drawing
2430       simple lines and boxes. However, there are a variety of ways in
2431       which PuTTY can attempt to find appropriate characters, and the
2432       right one to use depends on the locally configured font. In general
2433       you should probably try lots of options until you find one that your
2434       particular font supports.
2435
2436        -  `Use Unicode line drawing code points' tries to use the box
2437           characters that are present in Unicode. For good Unicode-
2438           supporting fonts this is probably the most reliable and
2439           functional option.
2440
2441        -  `Poor man's line drawing' assumes that the font _cannot_
2442           generate the line and box characters at all, so it will use the
2443           `+', `-' and `|' characters to draw approximations to boxes. You
2444           should use this option if none of the other options works.
2445
2446        -  `Font has XWindows encoding' is for use with fonts that have a
2447           special encoding, where the lowest 32 character positions (below
2448           the ASCII printable range) contain the line-drawing characters.
2449           This is unlikely to be the case with any standard Windows font;
2450           it will probably only apply to custom-built fonts or fonts that
2451           have been automatically converted from the X Window System.
2452
2453        -  `Use font in both ANSI and OEM modes' tries to use the same font
2454           in two different character sets, to obtain a wider range of
2455           characters. This doesn't always work; some fonts claim to be a
2456           different size depending on which character set you try to use.
2457
2458        -  `Use font in OEM mode only' is more reliable than that, but can
2459           miss out other characters from the main character set.
2460
24614.10.5 Controlling copy and paste of line drawing characters
2462
2463       By default, when you copy and paste a piece of the PuTTY screen that
2464       contains VT100 line and box drawing characters, PuTTY will paste
2465       them in the form they appear on the screen: either Unicode line
2466       drawing code points, or the `poor man's' line-drawing characters
2467       `+', `-' and `|'. The checkbox `Copy and paste VT100 line drawing
2468       chars as lqqqk' disables this feature, so line-drawing characters
2469       will be pasted as the ASCII characters that were printed to produce
2470       them. This will typically mean they come out mostly as `q' and `x',
2471       with a scattering of `jklmntuvw' at the corners. This might be
2472       useful if you were trying to recreate the same box layout in another
2473       program, for example.
2474
2475       Note that this option only applies to line-drawing characters which
2476       _were_ printed by using the VT100 mechanism. Line-drawing characters
2477       that were received as Unicode code points will paste as Unicode
2478       always.
2479
2480  4.11 The Selection panel
2481
2482       The Selection panel allows you to control the way copy and paste
2483       work in the PuTTY window.
2484
24854.11.1 Pasting in Rich Text Format
2486
2487       If you enable `Paste to clipboard in RTF as well as plain text',
2488       PuTTY will write formatting information to the clipboard as well
2489       as the actual text you copy. The effect of this is that if you
2490       paste into (say) a word processor, the text will appear in the word
2491       processor in the same font, colour, and style (e.g. bold, underline)
2492       PuTTY was using to display it.
2493
2494       This option can easily be inconvenient, so by default it is
2495       disabled.
2496
24974.11.2 Changing the actions of the mouse buttons
2498
2499       PuTTY's copy and paste mechanism is by default modelled on the Unix
2500       `xterm' application. The X Window System uses a three-button mouse,
2501       and the convention is that the left button selects, the right button
2502       extends an existing selection, and the middle button pastes.
2503
2504       Windows often only has two mouse buttons, so in PuTTY's default
2505       configuration (`Compromise'), the _right_ button pastes, and the
2506       _middle_ button (if you have one) extends a selection.
2507
2508       If you have a three-button mouse and you are already used to the
2509       `xterm' arrangement, you can select it using the `Action of mouse
2510       buttons' control.
2511
2512       Alternatively, with the `Windows' option selected, the middle button
2513       extends, and the right button brings up a context menu (on which one
2514       of the options is `Paste'). (This context menu is always available
2515       by holding down Ctrl and right-clicking, regardless of the setting
2516       of this option.)
2517
25184.11.3 `Shift overrides application's use of mouse'
2519
2520       PuTTY allows the server to send control codes that let it take
2521       over the mouse and use it for purposes other than copy and paste.
2522       Applications which use this feature include the text-mode web
2523       browser `links', the Usenet newsreader `trn' version 4, and the file
2524       manager `mc' (Midnight Commander).
2525
2526       When running one of these applications, pressing the mouse buttons
2527       no longer performs copy and paste. If you do need to copy and paste,
2528       you can still do so if you hold down Shift while you do your mouse
2529       clicks.
2530
2531       However, it is possible in theory for applications to even detect
2532       and make use of Shift + mouse clicks. We don't know of any
2533       applications that do this, but in case someone ever writes one,
2534       unchecking the `Shift overrides application's use of mouse' checkbox
2535       will cause Shift + mouse clicks to go to the server as well (so that
2536       mouse-driven copy and paste will be completely disabled).
2537
2538       If you want to prevent the application from taking over the mouse at
2539       all, you can do this using the Features control panel; see section
2540       4.6.2.
2541
25424.11.4 Default selection mode
2543
2544       As described in section 3.1.1, PuTTY has two modes of selecting
2545       text to be copied to the clipboard. In the default mode (`Normal'),
2546       dragging the mouse from point A to point B selects to the end of
2547       the line containing A, all the lines in between, and from the very
2548       beginning of the line containing B. In the other mode (`Rectangular
2549       block'), dragging the mouse between two points defines a rectangle,
2550       and everything within that rectangle is copied.
2551
2552       Normally, you have to hold down Alt while dragging the mouse to
2553       select a rectangular block. Using the `Default selection mode'
2554       control, you can set rectangular selection as the default, and then
2555       you have to hold down Alt to get the _normal_ behaviour.
2556
25574.11.5 Configuring word-by-word selection
2558
2559       PuTTY will select a word at a time in the terminal window if you
2560       double-click to begin the drag. This panel allows you to control
2561       precisely what is considered to be a word.
2562
2563       Each character is given a _class_, which is a small number
2564       (typically 0, 1 or 2). PuTTY considers a single word to be any
2565       number of adjacent characters in the same class. So by modifying the
2566       assignment of characters to classes, you can modify the word-by-word
2567       selection behaviour.
2568
2569       In the default configuration, the character classes are:
2570
2571        -  Class 0 contains white space and control characters.
2572
2573        -  Class 1 contains most punctuation.
2574
2575        -  Class 2 contains letters, numbers and a few pieces of
2576           punctuation (the double quote, minus sign, period, forward slash
2577           and underscore).
2578
2579       So, for example, if you assign the `@' symbol into character class
2580       2, you will be able to select an e-mail address with just a double
2581       click.
2582
2583       In order to adjust these assignments, you start by selecting a group
2584       of characters in the list box. Then enter a class number in the edit
2585       box below, and press the `Set' button.
2586
2587       This mechanism currently only covers ASCII characters, because it
2588       isn't feasible to expand the list to cover the whole of Unicode.
2589
2590       Character class definitions can be modified by control sequences
2591       sent by the server. This configuration option controls the _default_
2592       state, which will be restored when you reset the terminal (see
2593       section 3.1.3.6). However, if you modify this option in mid-session
2594       using `Change Settings', it will take effect immediately.
2595
2596  4.12 The Colours panel
2597
2598       The Colours panel allows you to control PuTTY's use of colour.
2599
26004.12.1 `Allow terminal to specify ANSI colours'
2601
2602       This option is enabled by default. If it is disabled, PuTTY will
2603       ignore any control sequences sent by the server to request coloured
2604       text.
2605
2606       If you have a particularly garish application, you might want to
2607       turn this option off and make PuTTY only use the default foreground
2608       and background colours.
2609
26104.12.2 `Allow terminal to use xterm 256-colour mode'
2611
2612       This option is enabled by default. If it is disabled, PuTTY will
2613       ignore any control sequences sent by the server which use the
2614       extended 256-colour mode supported by recent versions of xterm.
2615
2616       If you have an application which is supposed to use 256-colour mode
2617       and it isn't working, you may find you need to tell your server that
2618       your terminal supports 256 colours. On Unix, you do this by ensuring
2619       that the setting of TERM describes a 256-colour-capable terminal.
2620       You can check this using a command such as `infocmp':
2621
2622         $ infocmp | grep colors
2623                 colors#256, cols#80, it#8, lines#24, pairs#256,
2624
2625       If you do not see `colors#256' in the output, you may need to change
2626       your terminal setting. On modern Linux machines, you could try
2627       `xterm-256color'.
2628
26294.12.3 `Indicate bolded text by changing...'
2630
2631       When the server sends a control sequence indicating that some text
2632       should be displayed in bold, PuTTY can handle this in several ways.
2633       It can either change the font for a bold version, or use the same
2634       font in a brighter colour, or it can do both (brighten the colour
2635       _and_ embolden the font). This control lets you choose which.
2636
2637       By default bold is indicated by colour, so non-bold text is
2638       displayed in light grey and bold text is displayed in bright white
2639       (and similarly in other colours). If you change the setting to `The
2640       font' box, bold and non-bold text will be displayed in the same
2641       colour, and instead the font will change to indicate the difference.
2642       If you select `Both', the font and the colour will both change.
2643
2644       Some applications rely on `bold black' being distinguishable from a
2645       black background; if you choose `The font', their text may become
2646       invisible.
2647
26484.12.4 `Attempt to use logical palettes'
2649
2650       Logical palettes are a mechanism by which a Windows application
2651       running on an 8-bit colour display can select precisely the colours
2652       it wants instead of going with the Windows standard defaults.
2653
2654       If you are not getting the colours you ask for on an 8-bit display,
2655       you can try enabling this option. However, be warned that it's never
2656       worked very well.
2657
26584.12.5 `Use system colours'
2659
2660       Enabling this option will cause PuTTY to ignore the configured
2661       colours for `Default Background/Foreground' and `Cursor Colour/Text'
2662       (see section 4.12.6), instead going with the system-wide defaults.
2663
2664       Note that non-bold and bold text will be the same colour if this
2665       option is enabled. You might want to change to indicating bold text
2666       by font changes (see section 4.12.3).
2667
26684.12.6 Adjusting the colours in the terminal window
2669
2670       The main colour control allows you to specify exactly what colours
2671       things should be displayed in. To modify one of the PuTTY colours,
2672       use the list box to select which colour you want to modify. The
2673       RGB values for that colour will appear on the right-hand side of
2674       the list box. Now, if you press the `Modify' button, you will be
2675       presented with a colour selector, in which you can choose a new
2676       colour to go in place of the old one. (You may also edit the RGB
2677       values directly in the edit boxes, if you wish; each value is an
2678       integer from 0 to 255.)
2679
2680       PuTTY allows you to set the cursor colour, the default foreground
2681       and background, and the precise shades of all the ANSI configurable
2682       colours (black, red, green, yellow, blue, magenta, cyan, and white).
2683       You can also modify the precise shades used for the bold versions
2684       of these colours; these are used to display bold text if you have
2685       chosen to indicate that by colour (see section 4.12.3), and can also
2686       be used if the server asks specifically to use them. (Note that
2687       `Default Bold Background' is _not_ the background colour used for
2688       bold text; it is only used if the server specifically asks for a
2689       bold background.)
2690
2691  4.13 The Connection panel
2692
2693       The Connection panel allows you to configure options that apply to
2694       more than one type of connection.
2695
26964.13.1 Using keepalives to prevent disconnection
2697
2698       If you find your sessions are closing unexpectedly (most often with
2699       `Connection reset by peer') after they have been idle for a while,
2700       you might want to try using this option.
2701
2702       Some network routers and firewalls need to keep track of all
2703       connections through them. Usually, these firewalls will assume a
2704       connection is dead if no data is transferred in either direction
2705       after a certain time interval. This can cause PuTTY sessions to be
2706       unexpectedly closed by the firewall if no traffic is seen in the
2707       session for some time.
2708
2709       The keepalive option (`Seconds between keepalives') allows you
2710       to configure PuTTY to send data through the session at regular
2711       intervals, in a way that does not disrupt the actual terminal
2712       session. If you find your firewall is cutting idle connections off,
2713       you can try entering a non-zero value in this field. The value
2714       is measured in seconds; so, for example, if your firewall cuts
2715       connections off after ten minutes then you might want to enter 300
2716       seconds (5 minutes) in the box.
2717
2718       Note that keepalives are not always helpful. They help if you have
2719       a firewall which drops your connection after an idle period; but
2720       if the network between you and the server suffers from breaks in
2721       connectivity then keepalives can actually make things worse. If a
2722       session is idle, and connectivity is temporarily lost between the
2723       endpoints, but the connectivity is restored before either side
2724       tries to send anything, then there will be no problem - neither
2725       endpoint will notice that anything was wrong. However, if one side
2726       does send something during the break, it will repeatedly try to
2727       re-send, and eventually give up and abandon the connection. Then
2728       when connectivity is restored, the other side will find that the
2729       first side doesn't believe there is an open connection any more.
2730       Keepalives can make this sort of problem worse, because they
2731       increase the probability that PuTTY will attempt to send data during
2732       a break in connectivity. (Other types of periodic network activity
2733       can cause this behaviour; in particular, SSH-2 re-keys can have this
2734       effect. See section 4.19.2.)
2735
2736       Therefore, you might find that keepalives help connection loss,
2737       or you might find they make it worse, depending on what _kind_ of
2738       network problems you have between you and the server.
2739
2740       Keepalives are only supported in Telnet and SSH; the Rlogin and Raw
2741       protocols offer no way of implementing them. (For an alternative,
2742       see section 4.13.3.)
2743
2744       Note that if you are using SSH-1 and the server has a bug that makes
2745       it unable to deal with SSH-1 ignore messages (see section 4.27.1),
2746       enabling keepalives will have no effect.
2747
27484.13.2 `Disable Nagle's algorithm'
2749
2750       Nagle's algorithm is a detail of TCP/IP implementations that tries
2751       to minimise the number of small data packets sent down a network
2752       connection. With Nagle's algorithm enabled, PuTTY's bandwidth usage
2753       will be slightly more efficient; with it disabled, you may find you
2754       get a faster response to your keystrokes when connecting to some
2755       types of server.
2756
2757       The Nagle algorithm is disabled by default for interactive
2758       connections.
2759
27604.13.3 `Enable TCP keepalives'
2761
2762       _NOTE:_ TCP keepalives should not be confused with the application-
2763       level keepalives described in section 4.13.1. If in doubt, you
2764       probably want application-level keepalives; TCP keepalives are
2765       provided for completeness.
2766
2767       The idea of TCP keepalives is similar to application-level
2768       keepalives, and the same caveats apply. The main differences are:
2769
2770        -  TCP keepalives are available on _all_ connection types,
2771           including Raw and Rlogin.
2772
2773        -  The interval between TCP keepalives is usually much longer,
2774           typically two hours; this is set by the operating system, and
2775           cannot be configured within PuTTY.
2776
2777        -  If the operating system does not receive a response to a
2778           keepalive, it may send out more in quick succession and
2779           terminate the connection if no response is received.
2780
2781       TCP keepalives may be more useful for ensuring that half-open
2782       connections are terminated than for keeping a connection alive.
2783
2784       TCP keepalives are disabled by default.
2785
27864.13.4 `Internet protocol'
2787
2788       This option allows the user to select between the old and new
2789       Internet protocols and addressing schemes (IPv4 and IPv6). The
2790       selected protocol will be used for most outgoing network connections
2791       (including connections to proxies); however, tunnels have their own
2792       configuration, for which see section 4.26.2.
2793
2794       The default setting is `Auto', which means PuTTY will do something
2795       sensible and try to guess which protocol you wanted. (If you specify
2796       a literal Internet address, it will use whichever protocol that
2797       address implies. If you provide a hostname, it will see what kinds
2798       of address exist for that hostname; it will use IPv6 if there is an
2799       IPv6 address available, and fall back to IPv4 if not.)
2800
2801       If you need to force PuTTY to use a particular protocol, you can
2802       explicitly set this to `IPv4' or `IPv6'.
2803
28044.13.5 `Logical name of remote host'
2805
2806       This allows you to tell PuTTY that the host it will really end up
2807       connecting to is different from where it thinks it is making a
2808       network connection.
2809
2810       You might use this, for instance, if you had set up an SSH port
2811       forwarding in one PuTTY session so that connections to some
2812       arbitrary port (say, localhost port 10022) were forwarded to a
2813       second machine's SSH port (say, foovax port 22), and then started a
2814       second PuTTY connecting to the forwarded port.
2815
2816       In normal usage, the second PuTTY will access the host key cache
2817       under the host name and port it actually connected to (i.e.
2818       localhost port 10022 in this example). Using the logical host name
2819       option, however, you can configure the second PuTTY to cache the
2820       host key under the name of the host _you_ know that it's _really_
2821       going to end up talking to (here `foovax').
2822
2823       This can be useful if you expect to connect to the same actual
2824       server through many different channels (perhaps because your port
2825       forwarding arrangements keep changing): by consistently setting the
2826       logical host name, you can arrange that PuTTY will not keep asking
2827       you to reconfirm its host key. Conversely, if you expect to use the
2828       same local port number for port forwardings to lots of different
2829       servers, you probably didn't want any particular server's host
2830       key cached under that local port number. (For this latter case,
2831       you could instead explicitly configure host keys in the relevant
2832       sessions; see section 4.20.2.)
2833
2834       If you just enter a host name for this option, PuTTY will cache the
2835       SSH host key under the default SSH port for that host, irrespective
2836       of the port you really connected to (since the typical scenario is
2837       like the above example: you connect to a silly real port number and
2838       your connection ends up forwarded to the normal port-22 SSH server
2839       of some other machine). To override this, you can append a port
2840       number to the logical host name, separated by a colon. E.g. entering
2841       `foovax:2200' as the logical host name will cause the host key to be
2842       cached as if you had connected to port 2200 of `foovax'.
2843
2844       If you provide a host name using this option, it is also displayed
2845       in other locations which contain the remote host name, such as the
2846       default window title and the default SSH password prompt. This
2847       reflects the fact that this is the host you're _really_ connecting
2848       to, which is more important than the mere means you happen to be
2849       using to contact that host. (This applies even if you're using a
2850       protocol other than SSH.)
2851
2852  4.14 The Data panel
2853
2854       The Data panel allows you to configure various pieces of data which
2855       can be sent to the server to affect your connection at the far end.
2856
2857       Each option on this panel applies to more than one protocol.
2858       Options which apply to only one protocol appear on that protocol's
2859       configuration panels.
2860
28614.14.1 `Auto-login username'
2862
2863       All three of the SSH, Telnet and Rlogin protocols allow you to
2864       specify what user name you want to log in as, without having to type
2865       it explicitly every time. (Some Telnet servers don't support this.)
2866
2867       In this box you can type that user name.
2868
28694.14.2 Use of system username
2870
2871       When the previous box (section 4.14.1) is left blank, by default,
2872       PuTTY will prompt for a username at the time you make a connection.
2873
2874       In some environments, such as the networks of large organisations
2875       implementing single sign-on, a more sensible default may be to
2876       use the name of the user logged in to the local operating system
2877       (if any); this is particularly likely to be useful with GSSAPI
2878       authentication (see section 4.23). This control allows you to change
2879       the default behaviour.
2880
2881       The current system username is displayed in the dialog as a
2882       convenience. It is not saved in the configuration; if a saved
2883       session is later used by a different user, that user's name will be
2884       used.
2885
28864.14.3 `Terminal-type string'
2887
2888       Most servers you might connect to with PuTTY are designed to be
2889       connected to from lots of different types of terminal. In order to
2890       send the right control sequences to each one, the server will need
2891       to know what type of terminal it is dealing with. Therefore, each
2892       of the SSH, Telnet and Rlogin protocols allow a text string to be
2893       sent down the connection describing the terminal. On a Unix server,
2894       this selects an entry from the `termcap' or `terminfo' database that
2895       tells applications what control sequences to send to the terminal,
2896       and what character sequences to expect the keyboard to generate.
2897
2898       PuTTY attempts to emulate the Unix `xterm' program, and by default
2899       it reflects this by sending `xterm' as a terminal-type string. If
2900       you find this is not doing what you want - perhaps the remote system
2901       reports `Unknown terminal type' - you could try setting this to
2902       something different, such as `vt220'.
2903
2904       If you're not sure whether a problem is due to the terminal type
2905       setting or not, you probably need to consult the manual for your
2906       application or your server.
2907
29084.14.4 `Terminal speeds'
2909
2910       The Telnet, Rlogin, and SSH protocols allow the client to specify
2911       terminal speeds to the server.
2912
2913       This parameter does _not_ affect the actual speed of the connection,
2914       which is always `as fast as possible'; it is just a hint that is
2915       sometimes used by server software to modify its behaviour. For
2916       instance, if a slow speed is indicated, the server may switch to a
2917       less bandwidth-hungry display mode.
2918
2919       The value is usually meaningless in a network environment, but PuTTY
2920       lets you configure it, in case you find the server is reacting badly
2921       to the default value.
2922
2923       The format is a pair of numbers separated by a comma, for instance,
2924       `38400,38400'. The first number represents the output speed (_from_
2925       the server) in bits per second, and the second is the input speed
2926       (_to_ the server). (Only the first is used in the Rlogin protocol.)
2927
2928       This option has no effect on Raw connections.
2929
29304.14.5 Setting environment variables on the server
2931
2932       The Telnet protocol provides a means for the client to pass
2933       environment variables to the server. Many Telnet servers have
2934       stopped supporting this feature due to security flaws, but PuTTY
2935       still supports it for the benefit of any servers which have found
2936       other ways around the security problems than just disabling the
2937       whole mechanism.
2938
2939       Version 2 of the SSH protocol also provides a similar mechanism,
2940       which is easier to implement without security flaws. Newer SSH-2
2941       servers are more likely to support it than older ones.
2942
2943       This configuration data is not used in the SSH-1, rlogin or raw
2944       protocols.
2945
2946       To add an environment variable to the list transmitted down the
2947       connection, you enter the variable name in the `Variable' box, enter
2948       its value in the `Value' box, and press the `Add' button. To remove
2949       one from the list, select it in the list box and press `Remove'.
2950
2951  4.15 The Proxy panel
2952
2953       The Proxy panel allows you to configure PuTTY to use various types
2954       of proxy in order to make its network connections. The settings in
2955       this panel affect the primary network connection forming your PuTTY
2956       session, and also any extra connections made as a result of SSH port
2957       forwarding (see section 3.5).
2958
2959       Note that unlike some software (such as web browsers), PuTTY does
2960       not attempt to automatically determine whether to use a proxy and
2961       (if so) which one to use for a given destination. If you need to use
2962       a proxy, it must always be explicitly configured.
2963
29644.15.1 Setting the proxy type
2965
2966       The `Proxy type' radio buttons allow you to configure what type of
2967       proxy you want PuTTY to use for its network connections. The default
2968       setting is `None'; in this mode no proxy is used for any connection.
2969
2970        -  Selecting `HTTP' allows you to proxy your connections through a
2971           web server supporting the HTTP CONNECT command, as documented in
2972           RFC 2817.
2973
2974        -  Selecting `SOCKS 4' or `SOCKS 5' allows you to proxy your
2975           connections through a SOCKS server.
2976
2977        -  Many firewalls implement a less formal type of proxy in which
2978           a user can make a Telnet connection directly to the firewall
2979           machine and enter a command such as `connect myhost.com 22' to
2980           connect through to an external host. Selecting `Telnet' allows
2981           you to tell PuTTY to use this type of proxy.
2982
2983        -  Selecting `Local' allows you to specify an arbitrary command
2984           on the local machine to act as a proxy. When the session is
2985           started, instead of creating a TCP connection, PuTTY runs the
2986           command (specified in section 4.15.5), and uses its standard
2987           input and output streams.
2988
2989           This could be used, for instance, to talk to some kind of
2990           network proxy that PuTTY does not natively support; or you could
2991           tunnel a connection over something other than TCP/IP entirely.
2992
2993           If you want your local proxy command to make a secondary
2994           SSH connection to a proxy host and then tunnel the primary
2995           connection over that, you might well want the `-nc' command-line
2996           option in Plink. See section 3.8.3.14 for more information.
2997
2998           You can also enable this mode on the command line; see section
2999           3.8.3.24.
3000
30014.15.2 Excluding parts of the network from proxying
3002
3003       Typically you will only need to use a proxy to connect to non-local
3004       parts of your network; for example, your proxy might be required for
3005       connections outside your company's internal network. In the `Exclude
3006       Hosts/IPs' box you can enter ranges of IP addresses, or ranges of
3007       DNS names, for which PuTTY will avoid using the proxy and make a
3008       direct connection instead.
3009
3010       The `Exclude Hosts/IPs' box may contain more than one exclusion
3011       range, separated by commas. Each range can be an IP address or a DNS
3012       name, with a `*' character allowing wildcards. For example:
3013
3014         *.example.com
3015
3016       This excludes any host with a name ending in `.example.com' from
3017       proxying.
3018
3019         192.168.88.*
3020
3021       This excludes any host with an IP address starting with 192.168.88
3022       from proxying.
3023
3024         192.168.88.*,*.example.com
3025
3026       This excludes both of the above ranges at once.
3027
3028       Connections to the local host (the host name `localhost', and any
3029       loopback IP address) are never proxied, even if the proxy exclude
3030       list does not explicitly contain them. It is very unlikely that this
3031       behaviour would ever cause problems, but if it does you can change
3032       it by enabling `Consider proxying local host connections'.
3033
3034       Note that if you are doing DNS at the proxy (see section 4.15.3),
3035       you should make sure that your proxy exclusion settings do not
3036       depend on knowing the IP address of a host. If the name is passed on
3037       to the proxy without PuTTY looking it up, it will never know the IP
3038       address and cannot check it against your list.
3039
30404.15.3 Name resolution when using a proxy
3041
3042       If you are using a proxy to access a private network, it can make a
3043       difference whether DNS name resolution is performed by PuTTY itself
3044       (on the client machine) or performed by the proxy.
3045
3046       The `Do DNS name lookup at proxy end' configuration option allows
3047       you to control this. If you set it to `No', PuTTY will always do its
3048       own DNS, and will always pass an IP address to the proxy. If you set
3049       it to `Yes', PuTTY will always pass host names straight to the proxy
3050       without trying to look them up first.
3051
3052       If you set this option to `Auto' (the default), PuTTY will do
3053       something it considers appropriate for each type of proxy. Telnet,
3054       HTTP, and SOCKS5 proxies will have host names passed straight to
3055       them; SOCKS4 proxies will not.
3056
3057       Note that if you are doing DNS at the proxy, you should make sure
3058       that your proxy exclusion settings (see section 4.15.2) do not
3059       depend on knowing the IP address of a host. If the name is passed on
3060       to the proxy without PuTTY looking it up, it will never know the IP
3061       address and cannot check it against your list.
3062
3063       The original SOCKS 4 protocol does not support proxy-side DNS. There
3064       is a protocol extension (SOCKS 4A) which does support it, but not
3065       all SOCKS 4 servers provide this extension. If you enable proxy DNS
3066       and your SOCKS 4 server cannot deal with it, this might be why.
3067
30684.15.4 Username and password
3069
3070       If your proxy requires authentication, you can enter a username and
3071       a password in the `Username' and `Password' boxes.
3072
3073       Note that if you save your session, the proxy password will be saved
3074       in plain text, so anyone who can access your PuTTY configuration
3075       data will be able to discover it.
3076
3077       Authentication is not fully supported for all forms of proxy:
3078
3079        -  Username and password authentication is supported for HTTP
3080           proxies and SOCKS 5 proxies.
3081
3082            -  With SOCKS 5, authentication is via CHAP if the proxy
3083               supports it (this is not supported in PuTTYtel); otherwise
3084               the password is sent to the proxy in plain text.
3085
3086            -  With HTTP proxying, the only currently supported
3087               authentication method is `basic', where the password is sent
3088               to the proxy in plain text.
3089
3090        -  SOCKS 4 can use the `Username' field, but does not support
3091           passwords.
3092
3093        -  You can specify a way to include a username and password in the
3094           Telnet/Local proxy command (see section 4.15.5).
3095
30964.15.5 Specifying the Telnet or Local proxy command
3097
3098       If you are using the Telnet proxy type, the usual command required
3099       by the firewall's Telnet server is `connect', followed by a host
3100       name and a port number. If your proxy needs a different command, you
3101       can enter an alternative here.
3102
3103       If you are using the Local proxy type, the local command to run is
3104       specified here.
3105
3106       In this string, you can use `\n' to represent a new-line, `\r' to
3107       represent a carriage return, `\t' to represent a tab character, and
3108       `\x' followed by two hex digits to represent any other character.
3109       `\\' is used to encode the `\' character itself.
3110
3111       Also, the special strings `%host' and `%port' will be replaced by
3112       the host name and port number you want to connect to. The strings
3113       `%user' and `%pass' will be replaced by the proxy username and
3114       password you specify. The strings `%proxyhost' and `%proxyport' will
3115       be replaced by the host details specified on the _Proxy_ panel, if
3116       any (this is most likely to be useful for the Local proxy type). To
3117       get a literal `%' sign, enter `%%'.
3118
3119       If a Telnet proxy server prompts for a username and password before
3120       commands can be sent, you can use a command such as:
3121
3122         %user\n%pass\nconnect %host %port\n
3123
3124       This will send your username and password as the first two lines
3125       to the proxy, followed by a command to connect to the desired host
3126       and port. Note that if you do not include the `%user' or `%pass'
3127       tokens in the Telnet command, then the `Username' and `Password'
3128       configuration fields will be ignored.
3129
31304.15.6 Controlling proxy logging
3131
3132       Often the proxy interaction has its own diagnostic output; this is
3133       particularly the case for local proxy commands.
3134
3135       The setting `Print proxy diagnostics in the terminal window' lets
3136       you control how much of the proxy's diagnostics are printed to the
3137       main terminal window, along with output from your main session.
3138
3139       By default (`No'), proxy diagnostics are only sent to the Event Log;
3140       with `Yes' they are also printed to the terminal, where they may
3141       get mixed up with your main session. `Only until session starts' is
3142       a compromise; proxy messages will go to the terminal window until
3143       the main session is deemed to have started (in a protocol-dependent
3144       way), which is when they're most likely to be interesting; any
3145       further proxy-related messages during the session will only go to
3146       the Event Log.
3147
3148  4.16 The Telnet panel
3149
3150       The Telnet panel allows you to configure options that only apply to
3151       Telnet sessions.
3152
31534.16.1 `Handling of OLD_ENVIRON ambiguity'
3154
3155       The original Telnet mechanism for passing environment variables was
3156       badly specified. At the time the standard (RFC 1408) was written,
3157       BSD telnet implementations were already supporting the feature, and
3158       the intention of the standard was to describe the behaviour the BSD
3159       implementations were already using.
3160
3161       Sadly there was a typing error in the standard when it was issued,
3162       and two vital function codes were specified the wrong way round. BSD
3163       implementations did not change, and the standard was not corrected.
3164       Therefore, it's possible you might find either BSD or RFC-compliant
3165       implementations out there. This switch allows you to choose which
3166       one PuTTY claims to be.
3167
3168       The problem was solved by issuing a second standard, defining a
3169       new Telnet mechanism called NEW_ENVIRON, which behaved exactly
3170       like the original OLD_ENVIRON but was not encumbered by existing
3171       implementations. Most Telnet servers now support this, and it's
3172       unambiguous. This feature should only be needed if you have trouble
3173       passing environment variables to quite an old server.
3174
31754.16.2 Passive and active Telnet negotiation modes
3176
3177       In a Telnet connection, there are two types of data passed between
3178       the client and the server: actual text, and _negotiations_ about
3179       which Telnet extra features to use.
3180
3181       PuTTY can use two different strategies for negotiation:
3182
3183        -  In _active_ mode, PuTTY starts to send negotiations as soon as
3184           the connection is opened.
3185
3186        -  In _passive_ mode, PuTTY will wait to negotiate until it sees a
3187           negotiation from the server.
3188
3189       The obvious disadvantage of passive mode is that if the server is
3190       also operating in a passive mode, then negotiation will never begin
3191       at all. For this reason PuTTY defaults to active mode.
3192
3193       However, sometimes passive mode is required in order to successfully
3194       get through certain types of firewall and Telnet proxy server. If
3195       you have confusing trouble with a firewall, you could try enabling
3196       passive mode to see if it helps.
3197
31984.16.3 `Keyboard sends Telnet special commands'
3199
3200       If this box is checked, several key sequences will have their normal
3201       actions modified:
3202
3203        -  the Backspace key on the keyboard will send the Telnet special
3204           backspace code;
3205
3206        -  Control-C will send the Telnet special Interrupt Process code;
3207
3208        -  Control-Z will send the Telnet special Suspend Process code.
3209
3210       You probably shouldn't enable this unless you know what you're
3211       doing.
3212
32134.16.4 `Return key sends Telnet New Line instead of ^M'
3214
3215       Unlike most other remote login protocols, the Telnet protocol has
3216       a special `new line' code that is not the same as the usual line
3217       endings of Control-M or Control-J. By default, PuTTY sends the
3218       Telnet New Line code when you press Return, instead of sending
3219       Control-M as it does in most other protocols.
3220
3221       Most Unix-style Telnet servers don't mind whether they receive
3222       Telnet New Line or Control-M; some servers do expect New Line,
3223       and some servers prefer to see ^M. If you are seeing surprising
3224       behaviour when you press Return in a Telnet session, you might try
3225       turning this option off to see if it helps.
3226
3227  4.17 The Rlogin panel
3228
3229       The Rlogin panel allows you to configure options that only apply to
3230       Rlogin sessions.
3231
32324.17.1 `Local username'
3233
3234       Rlogin allows an automated (password-free) form of login by means
3235       of a file called `.rhosts' on the server. You put a line in your
3236       `.rhosts' file saying something like `jbloggs@pc1.example.com', and
3237       then when you make an Rlogin connection the client transmits the
3238       username of the user running the Rlogin client. The server checks
3239       the username and hostname against `.rhosts', and if they match it
3240       does not ask for a password.
3241
3242       This only works because Unix systems contain a safeguard to stop a
3243       user from pretending to be another user in an Rlogin connection.
3244       Rlogin connections have to come from port numbers below 1024, and
3245       Unix systems prohibit this to unprivileged processes; so when the
3246       server sees a connection from a low-numbered port, it assumes the
3247       client end of the connection is held by a privileged (and therefore
3248       trusted) process, so it believes the claim of who the user is.
3249
3250       Windows does not have this restriction: _any_ user can initiate
3251       an outgoing connection from a low-numbered port. Hence, the
3252       Rlogin `.rhosts' mechanism is completely useless for securely
3253       distinguishing several different users on a Windows machine. If you
3254       have a `.rhosts' entry pointing at a Windows PC, you should assume
3255       that _anyone_ using that PC can spoof your username in an Rlogin
3256       connection and access your account on the server.
3257
3258       The `Local username' control allows you to specify what user name
3259       PuTTY should claim you have, in case it doesn't match your Windows
3260       user name (or in case you didn't bother to set up a Windows user
3261       name).
3262
3263  4.18 The SSH panel
3264
3265       The SSH panel allows you to configure options that only apply to SSH
3266       sessions.
3267
32684.18.1 Executing a specific command on the server
3269
3270       In SSH, you don't have to run a general shell session on the server.
3271       Instead, you can choose to run a single specific command (such as
3272       a mail user agent, for example). If you want to do this, enter the
3273       command in the `Remote command' box.
3274
3275       Note that most servers will close the session after executing the
3276       command.
3277
32784.18.2 `Don't start a shell or command at all'
3279
3280       If you tick this box, PuTTY will not attempt to run a shell or
3281       command after connecting to the remote server. You might want to
3282       use this option if you are only using the SSH connection for port
3283       forwarding, and your user account on the server does not have the
3284       ability to run a shell.
3285
3286       This feature is only available in SSH protocol version 2 (since the
3287       version 1 protocol assumes you will always want to run a shell).
3288
3289       This feature can also be enabled using the `-N' command-line option;
3290       see section 3.8.3.13.
3291
3292       If you use this feature in Plink, you will not be able to terminate
3293       the Plink process by any graceful means; the only way to kill it
3294       will be by pressing Control-C or sending a kill signal from another
3295       program.
3296
32974.18.3 `Enable compression'
3298
3299       This enables data compression in the SSH connection: data sent by
3300       the server is compressed before sending, and decompressed at the
3301       client end. Likewise, data sent by PuTTY to the server is compressed
3302       first and the server decompresses it at the other end. This can help
3303       make the most of a low-bandwidth connection.
3304
33054.18.4 `SSH protocol version'
3306
3307       This allows you to select whether to use SSH protocol version 2 or
3308       the older version 1.
3309
3310       You should normally leave this at the default of `2'. As well
3311       as having fewer features, the older SSH-1 protocol is no longer
3312       developed, has many known cryptographic weaknesses, and is generally
3313       not considered to be secure. PuTTY's protocol 1 implementation is
3314       provided mainly for compatibility, and is no longer being enhanced.
3315
3316       If a server offers both versions, prefer `2'. If you have some
3317       server or piece of equipment that only talks SSH-1, select `1' here,
3318       and do not treat the resulting connection as secure.
3319
3320       PuTTY will not automatically fall back to the other version of the
3321       protocol if the server turns out not to match your selection here;
3322       instead, it will put up an error message and abort the connection.
3323       This prevents an active attacker downgrading an intended SSH-2
3324       connection to SSH-1.
3325
33264.18.5 Sharing an SSH connection between PuTTY tools
3327
3328       The controls in this box allow you to configure PuTTY to reuse an
3329       existing SSH connection, where possible.
3330
3331       The SSH-2 protocol permits you to run multiple data channels over
3332       the same SSH connection, so that you can log in just once (and do
3333       the expensive encryption setup just once) and then have more than
3334       one terminal window open.
3335
3336       Each instance of PuTTY can still run at most one terminal session,
3337       but using the controls in this box, you can configure PuTTY to check
3338       if another instance of itself has already connected to the target
3339       host, and if so, share that instance's SSH connection instead of
3340       starting a separate new one.
3341
3342       To enable this feature, just tick the box `Share SSH connections if
3343       possible'. Then, whenever you start up a PuTTY session connecting to
3344       a particular host, it will try to reuse an existing SSH connection
3345       if one is available. For example, selecting `Duplicate Session' from
3346       the system menu will launch another session on the same host, and if
3347       sharing is enabled then it will reuse the existing SSH connection.
3348
3349       When this mode is in use, the first PuTTY that connected to a given
3350       server becomes the `upstream', which means that it is the one
3351       managing the real SSH connection. All subsequent PuTTYs which reuse
3352       the connection are referred to as `downstreams': they do not connect
3353       to the real server at all, but instead connect to the upstream PuTTY
3354       via local inter-process communication methods.
3355
3356       For this system to be activated, _both_ the upstream and downstream
3357       instances of PuTTY must have the sharing option enabled.
3358
3359       The upstream PuTTY can therefore not terminate until all its
3360       downstreams have closed. This is similar to the effect you get with
3361       port forwarding or X11 forwarding, in which a PuTTY whose terminal
3362       session has already finished will still remain open so as to keep
3363       serving forwarded connections.
3364
3365       In case you need to configure this system in more detail, there
3366       are two additional checkboxes which allow you to specify whether a
3367       particular PuTTY can act as an upstream or a downstream or both.
3368       (These boxes only take effect if the main `Share SSH connections if
3369       possible' box is also ticked.) By default both of these boxes are
3370       ticked, so that multiple PuTTYs started from the same configuration
3371       will designate one of themselves as the upstream and share a single
3372       connection; but if for some reason you need a particular PuTTY
3373       configuration _not_ to be an upstream (e.g. because you definitely
3374       need it to close promptly) or not to be a downstream (e.g. because
3375       it needs to do its own authentication using a special private key)
3376       then you can untick one or the other of these boxes.
3377
3378       I have referred to `PuTTY' throughout the above discussion, but
3379       all the other PuTTY tools which make SSH connections can use this
3380       mechanism too. For example, if PSCP or PSFTP loads a configuration
3381       with sharing enabled, then it can act as a downstream and use an
3382       existing SSH connection set up by an instance of GUI PuTTY. The one
3383       special case is that PSCP and PSFTP will _never_ act as upstreams.
3384
3385       It is possible to test programmatically for the existence of a live
3386       upstream using Plink. See section 7.2.3.3.
3387
3388  4.19 The Kex panel
3389
3390       The Kex panel (short for `key exchange') allows you to configure
3391       options related to SSH-2 key exchange.
3392
3393       Key exchange occurs at the start of an SSH connection (and
3394       occasionally thereafter); it establishes a shared secret that
3395       is used as the basis for all of SSH's security features. It is
3396       therefore very important for the security of the connection that the
3397       key exchange is secure.
3398
3399       Key exchange is a cryptographically intensive process; if either
3400       the client or the server is a relatively slow machine, the slower
3401       methods may take several tens of seconds to complete.
3402
3403       If connection startup is too slow, or the connection hangs
3404       periodically, you may want to try changing these settings.
3405
3406       If you don't understand what any of this means, it's safe to leave
3407       these settings alone.
3408
3409       This entire panel is only relevant to SSH protocol version 2; none
3410       of these settings affect SSH-1 at all.
3411
34124.19.1 Key exchange algorithm selection
3413
3414       PuTTY supports a variety of SSH-2 key exchange methods, and allows
3415       you to choose which one you prefer to use; configuration is similar
3416       to cipher selection (see section 4.21).
3417
3418       PuTTY currently supports the following key exchange methods:
3419
3420        -  `ECDH': elliptic curve Diffie-Hellman key exchange.
3421
3422        -  `Group 14': Diffie-Hellman key exchange with a well-known 2048-
3423           bit group.
3424
3425        -  `Group 1': Diffie-Hellman key exchange with a well-known 1024-
3426           bit group. We no longer recommend using this method, and it's
3427           not used by default in new installations; however, it may be the
3428           only method supported by very old server software.
3429
3430        -  `Group exchange': with this method, instead of using a fixed
3431           group, PuTTY requests that the server suggest a group to use for
3432           key exchange; the server can avoid groups known to be weak, and
3433           possibly invent new ones over time, without any changes required
3434           to PuTTY's configuration. We recommend use of this method
3435           instead of the well-known groups, if possible.
3436
3437        -  `RSA key exchange': this requires much less computational effort
3438           on the part of the client, and somewhat less on the part of the
3439           server, than Diffie-Hellman key exchange.
3440
3441       If the first algorithm PuTTY finds is below the `warn below here'
3442       line, you will see a warning box when you make the connection,
3443       similar to that for cipher selection (see section 4.21).
3444
34454.19.2 Repeat key exchange
3446
3447       If the session key negotiated at connection startup is used too much
3448       or for too long, it may become feasible to mount attacks against the
3449       SSH connection. Therefore, the SSH-2 protocol specifies that a new
3450       key exchange should take place every so often; this can be initiated
3451       by either the client or the server.
3452
3453       While this renegotiation is taking place, no data can pass through
3454       the SSH connection, so it may appear to `freeze'. (The occurrence
3455       of repeat key exchange is noted in the Event Log; see section
3456       3.1.3.1.) Usually the same algorithm is used as at the start of the
3457       connection, with a similar overhead.
3458
3459       These options control how often PuTTY will initiate a repeat key
3460       exchange (`rekey'). You can also force a key exchange at any time
3461       from the Special Commands menu (see section 3.1.3.2).
3462
3463        -  `Max minutes before rekey' specifies the amount of time that
3464           is allowed to elapse before a rekey is initiated. If this is
3465           set to zero, PuTTY will not rekey due to elapsed time. The SSH-
3466           2 protocol specification recommends a timeout of at most 60
3467           minutes.
3468
3469       You might have a need to disable time-based rekeys completely
3470       for the same reasons that keepalives aren't always helpful. If
3471       you anticipate suffering a network dropout of several hours in
3472       the middle of an SSH connection, but were not actually planning
3473       to send _data_ down that connection during those hours, then an
3474       attempted rekey in the middle of the dropout will probably cause
3475       the connection to be abandoned, whereas if rekeys are disabled
3476       then the connection should in principle survive (in the absence
3477       of interfering firewalls). See section 4.13.1 for more discussion
3478       of these issues; for these purposes, rekeys have much the same
3479       properties as keepalives. (Except that rekeys have cryptographic
3480       value in themselves, so you should bear that in mind when deciding
3481       whether to turn them off.) Note, however, the the SSH _server_ can
3482       still initiate rekeys.
3483
3484        -  `Max data before rekey' specifies the amount of data (in bytes)
3485           that is permitted to flow in either direction before a rekey is
3486           initiated. If this is set to zero, PuTTY will not rekey due to
3487           transferred data. The SSH-2 protocol specification recommends a
3488           limit of at most 1 gigabyte.
3489
3490           As well as specifying a value in bytes, the following shorthand
3491           can be used:
3492
3493            -  `1k' specifies 1 kilobyte (1024 bytes).
3494
3495            -  `1M' specifies 1 megabyte (1024 kilobytes).
3496
3497            -  `1G' specifies 1 gigabyte (1024 megabytes).
3498
3499       Disabling data-based rekeys entirely is a bad idea. The integrity,
3500       and to a lesser extent, confidentiality of the SSH-2 protocol depend
3501       in part on rekeys occurring before a 32-bit packet sequence number
3502       wraps around. Unlike time-based rekeys, data-based rekeys won't
3503       occur when the SSH connection is idle, so they shouldn't cause the
3504       same problems. The SSH-1 protocol, incidentally, has even weaker
3505       integrity protection than SSH-2 without rekeys.
3506
3507  4.20 The Host Keys panel
3508
3509       The Host Keys panel allows you to configure options related to SSH-2
3510       host key management.
3511
3512       Host keys are used to prove the server's identity, and assure you
3513       that the server is not being spoofed (either by a man-in-the-middle
3514       attack or by completely replacing it on the network). See section
3515       2.2 for a basic introduction to host keys.
3516
3517       This entire panel is only relevant to SSH protocol version 2; none
3518       of these settings affect SSH-1 at all.
3519
35204.20.1 Host key type selection
3521
3522       PuTTY supports a variety of SSH-2 host key types, and allows you
3523       to choose which one you prefer to use to identify the server.
3524       Configuration is similar to cipher selection (see section 4.21).
3525
3526       PuTTY currently supports the following host key types:
3527
3528        -  `Ed25519': Edwards-curve DSA using a twisted Edwards curve with
3529           modulus 2^255-19.
3530
3531        -  `ECDSA': elliptic curve DSA using one of the NIST-standardised
3532           elliptic curves.
3533
3534        -  `DSA': straightforward DSA using modular exponentiation.
3535
3536        -  `RSA': the ordinary RSA algorithm.
3537
3538       If PuTTY already has one or more host keys stored for the server,
3539       it will prefer to use one of those, even if the server has a key
3540       type that is higher in the preference order. You can add such a key
3541       to PuTTY's cache from within an existing session using the `Special
3542       Commands' menu; see section 3.1.3.2.
3543
3544       Otherwise, PuTTY will choose a key type based purely on the
3545       preference order you specify in the configuration.
3546
3547       If the first key type PuTTY finds is below the `warn below here'
3548       line, you will see a warning box when you make the connection,
3549       similar to that for cipher selection (see section 4.21).
3550
35514.20.2 Manually configuring host keys
3552
3553       In some situations, if PuTTY's automated host key management is not
3554       doing what you need, you might need to manually configure PuTTY to
3555       accept a specific host key, or one of a specific set of host keys.
3556
3557       One reason why you might want to do this is because the host name
3558       PuTTY is connecting to is using round-robin DNS to return one of
3559       multiple actual servers, and they all have different host keys. In
3560       that situation, you might need to configure PuTTY to accept any of
3561       a list of host keys for the possible servers, while still rejecting
3562       any key not in that list.
3563
3564       Another reason is if PuTTY's automated host key management is
3565       completely unavailable, e.g. because PuTTY (or Plink or PSFTP, etc)
3566       is running in a Windows environment without access to the Registry.
3567       In that situation, you will probably want to use the -hostkey
3568       command-line option to configure the expected host key(s); see
3569       section 3.8.3.20.
3570
3571       For situations where PuTTY's automated host key management simply
3572       picks the wrong host name to store a key under, you may want to
3573       consider setting a `logical host name' instead; see section 4.13.5.
3574
3575       To configure manual host keys via the GUI, enter some text
3576       describing the host key into the edit box in the `Manually configure
3577       host keys for this connection' container, and press the `Add'
3578       button. The text will appear in the `Host keys or fingerprints
3579       to accept' list box. You can remove keys again with the `Remove'
3580       button.
3581
3582       The text describing a host key can be in one of the following
3583       formats:
3584
3585        -  An MD5-based host key fingerprint of the form displayed in
3586           PuTTY's Event Log and host key dialog boxes, i.e. sixteen 2-
3587           digit hex numbers separated by colons.
3588
3589        -  A base64-encoded blob describing an SSH-2 public key in
3590           OpenSSH's one-line public key format. How you acquire
3591           a public key in this format is server-dependent; on an
3592           OpenSSH server it can typically be found in a location like
3593           `/etc/ssh/ssh_host_rsa_key.pub'.
3594
3595       If this box contains at least one host key or fingerprint when PuTTY
3596       makes an SSH connection, then PuTTY's automated host key management
3597       is completely bypassed: the connection will be permitted if and only
3598       if the host key presented by the server is one of the keys listed
3599       in this box, and the host key store in the Registry will be neither
3600       read _nor written_, unless you explicitly do so.
3601
3602       If the box is empty (as it usually is), then PuTTY's automated host
3603       key management will work as normal.
3604
3605  4.21 The Cipher panel
3606
3607       PuTTY supports a variety of different encryption algorithms, and
3608       allows you to choose which one you prefer to use. You can do this by
3609       dragging the algorithms up and down in the list box (or moving them
3610       using the Up and Down buttons) to specify a preference order. When
3611       you make an SSH connection, PuTTY will search down the list from the
3612       top until it finds an algorithm supported by the server, and then
3613       use that.
3614
3615       PuTTY currently supports the following algorithms:
3616
3617        -  ChaCha20-Poly1305, a combined cipher and MAC (SSH-2 only)
3618
3619        -  AES (Rijndael) - 256, 192, or 128-bit SDCTR or CBC (SSH-2 only)
3620
3621        -  Arcfour (RC4) - 256 or 128-bit stream cipher (SSH-2 only)
3622
3623        -  Blowfish - 256-bit SDCTR (SSH-2 only) or 128-bit CBC
3624
3625        -  Triple-DES - 168-bit SDCTR (SSH-2 only) or CBC
3626
3627        -  Single-DES - 56-bit CBC (see below for SSH-2)
3628
3629       If the algorithm PuTTY finds is below the `warn below here' line,
3630       you will see a warning box when you make the connection:
3631
3632         The first cipher supported by the server
3633         is single-DES, which is below the configured
3634         warning threshold.
3635         Do you want to continue with this connection?
3636
3637       This warns you that the first available encryption is not a very
3638       secure one. Typically you would put the `warn below here' line
3639       between the encryptions you consider secure and the ones you
3640       consider substandard. By default, PuTTY supplies a preference order
3641       intended to reflect a reasonable preference in terms of security and
3642       speed.
3643
3644       In SSH-2, the encryption algorithm is negotiated independently for
3645       each direction of the connection, although PuTTY does not support
3646       separate configuration of the preference orders. As a result you may
3647       get two warnings similar to the one above, possibly with different
3648       encryptions.
3649
3650       Single-DES is not recommended in the SSH-2 protocol standards, but
3651       one or two server implementations do support it. PuTTY can use
3652       single-DES to interoperate with these servers if you enable the
3653       `Enable legacy use of single-DES in SSH-2' option; by default this
3654       is disabled and PuTTY will stick to recommended ciphers.
3655
3656  4.22 The Auth panel
3657
3658       The Auth panel allows you to configure authentication options for
3659       SSH sessions.
3660
36614.22.1 `Display pre-authentication banner'
3662
3663       SSH-2 servers can provide a message for clients to display to the
3664       prospective user before the user logs in; this is sometimes known
3665       as a pre-authentication `banner'. Typically this is used to provide
3666       information about the server and legal notices.
3667
3668       By default, PuTTY displays this message before prompting for a
3669       password or similar credentials (although, unfortunately, not before
3670       prompting for a login name, due to the nature of the protocol
3671       design). By unchecking this option, display of the banner can be
3672       suppressed entirely.
3673
36744.22.2 `Bypass authentication entirely'
3675
3676       In SSH-2, it is in principle possible to establish a connection
3677       without using SSH's mechanisms to identify or prove who you are to
3678       the server. An SSH server could prefer to handle authentication
3679       in the data channel, for instance, or simply require no user
3680       authentication whatsoever.
3681
3682       By default, PuTTY assumes the server requires authentication (we've
3683       never heard of one that doesn't), and thus must start this process
3684       with a username. If you find you are getting username prompts that
3685       you cannot answer, you could try enabling this option. However, most
3686       SSH servers will reject this.
3687
3688       This is not the option you want if you have a username and just
3689       want PuTTY to remember it; for that see section 4.14.1. It's
3690       also probably not what if you're trying to set up passwordless
3691       login to a mainstream SSH server; depending on the server, you
3692       probably wanted public-key authentication (chapter 8) or perhaps
3693       GSSAPI authentication (section 4.23). (These are still forms of
3694       authentication, even if you don't have to interact with them.)
3695
3696       This option only affects SSH-2 connections. SSH-1 connections always
3697       require an authentication step.
3698
36994.22.3 `Attempt authentication using Pageant'
3700
3701       If this option is enabled, then PuTTY will look for Pageant (the
3702       SSH private-key storage agent) and attempt to authenticate with any
3703       suitable public keys Pageant currently holds.
3704
3705       This behaviour is almost always desirable, and is therefore enabled
3706       by default. In rare cases you might need to turn it off in order
3707       to force authentication by some non-public-key method such as
3708       passwords.
3709
3710       This option can also be controlled using the `-noagent' command-line
3711       option. See section 3.8.3.9.
3712
3713       See chapter 9 for more information about Pageant in general.
3714
37154.22.4 `Attempt TIS or CryptoCard authentication'
3716
3717       TIS and CryptoCard authentication are (despite their names) generic
3718       forms of simple challenge/response authentication available in SSH
3719       protocol version 1 only. You might use them if you were using S/Key
3720       one-time passwords, for example, or if you had a physical security
3721       token that generated responses to authentication challenges. They
3722       can even be used to prompt for simple passwords.
3723
3724       With this switch enabled, PuTTY will attempt these forms of
3725       authentication if the server is willing to try them. You will be
3726       presented with a challenge string (which may be different every
3727       time) and must supply the correct response in order to log in.
3728       If your server supports this, you should talk to your system
3729       administrator about precisely what form these challenges and
3730       responses take.
3731
37324.22.5 `Attempt keyboard-interactive authentication'
3733
3734       The SSH-2 equivalent of TIS authentication is called `keyboard-
3735       interactive'. It is a flexible authentication method using an
3736       arbitrary sequence of requests and responses; so it is not only
3737       useful for challenge/response mechanisms such as S/Key, but it can
3738       also be used for (for example) asking the user for a new password
3739       when the old one has expired.
3740
3741       PuTTY leaves this option enabled by default, but supplies a switch
3742       to turn it off in case you should have trouble with it.
3743
37444.22.6 `Allow agent forwarding'
3745
3746       This option allows the SSH server to open forwarded connections back
3747       to your local copy of Pageant. If you are not running Pageant, this
3748       option will do nothing.
3749
3750       See chapter 9 for general information on Pageant, and section 9.4
3751       for information on agent forwarding. Note that there is a security
3752       risk involved with enabling this option; see section 9.5 for
3753       details.
3754
37554.22.7 `Allow attempted changes of username in SSH-2'
3756
3757       In the SSH-1 protocol, it is impossible to change username after
3758       failing to authenticate. So if you mis-type your username at the
3759       PuTTY `login as:' prompt, you will not be able to change it except
3760       by restarting PuTTY.
3761
3762       The SSH-2 protocol _does_ allow changes of username, in principle,
3763       but does not make it mandatory for SSH-2 servers to accept them.
3764       In particular, OpenSSH does not accept a change of username; once
3765       you have sent one username, it will reject attempts to try to
3766       authenticate as another user. (Depending on the version of OpenSSH,
3767       it may quietly return failure for all login attempts, or it may send
3768       an error message.)
3769
3770       For this reason, PuTTY will by default not prompt you for your
3771       username more than once, in case the server complains. If you know
3772       your server can cope with it, you can enable the `Allow attempted
3773       changes of username' option to modify PuTTY's behaviour.
3774
37754.22.8 `Private key file for authentication'
3776
3777       This box is where you enter the name of your private key file if you
3778       are using public key authentication. See chapter 8 for information
3779       about public key authentication in SSH.
3780
3781       This key must be in PuTTY's native format (`*.PPK'). If you have a
3782       private key in another format that you want to use with PuTTY, see
3783       section 8.2.12.
3784
3785       You can use the authentication agent Pageant so that you do not need
3786       to explicitly configure a key here; see chapter 9.
3787
3788       If a private key file is specified here with Pageant running, PuTTY
3789       will first try asking Pageant to authenticate with that key, and
3790       ignore any other keys Pageant may have. If that fails, PuTTY will
3791       ask for a passphrase as normal. You can also specify a _public_
3792       key file in this case (in RFC 4716 or OpenSSH format), as that's
3793       sufficient to identify the key to Pageant, but of course if Pageant
3794       isn't present PuTTY can't fall back to using this file itself.
3795
3796  4.23 The GSSAPI panel
3797
3798       The `GSSAPI' subpanel of the `Auth' panel controls the use of
3799       GSSAPI authentication. This is a mechanism which delegates the
3800       authentication exchange to a library elsewhere on the client
3801       machine, which in principle can authenticate in many different ways
3802       but in practice is usually used with the Kerberos single sign-on
3803       protocol to implement passwordless login.
3804
3805       GSSAPI is only available in the SSH-2 protocol.
3806
3807       The topmost control on the GSSAPI subpanel is the checkbox labelled
3808       `Attempt GSSAPI authentication'. If this is disabled, GSSAPI will
3809       not be attempted at all and the rest of this panel is unused. If it
3810       is enabled, GSSAPI authentication will be attempted, and (typically)
3811       if your client machine has valid Kerberos credentials loaded, then
3812       PuTTY should be able to authenticate automatically to servers that
3813       support Kerberos logins.
3814
38154.23.1 `Allow GSSAPI credential delegation'
3816
3817       GSSAPI credential delegation is a mechanism for passing on your
3818       Kerberos (or other) identity to the session on the SSH server. If
3819       you enable this option, then not only will PuTTY be able to log in
3820       automatically to a server that accepts your Kerberos credentials,
3821       but also you will be able to connect out from that server to other
3822       Kerberos-supporting services and use the same credentials just as
3823       automatically.
3824
3825       (This option is the Kerberos analogue of SSH agent forwarding; see
3826       section 9.4 for some information on that.)
3827
3828       Note that, like SSH agent forwarding, there is a security
3829       implication in the use of this option: the administrator of
3830       the server you connect to, or anyone else who has cracked the
3831       administrator account on that server, could fake your identity
3832       when connecting to further Kerberos-supporting services. However,
3833       Kerberos sites are typically run by a central authority, so the
3834       administrator of one server is likely to already have access to the
3835       other services too; so this would typically be less of a risk than
3836       SSH agent forwarding.
3837
38384.23.2 Preference order for GSSAPI libraries
3839
3840       GSSAPI is a mechanism which allows more than one authentication
3841       method to be accessed through the same interface. Therefore, more
3842       than one authentication library may exist on your system which can
3843       be accessed using GSSAPI.
3844
3845       PuTTY contains native support for a few well-known such libraries,
3846       and will look for all of them on your system and use whichever it
3847       finds. If more than one exists on your system and you need to use a
3848       specific one, you can adjust the order in which it will search using
3849       this preference list control.
3850
3851       One of the options in the preference list is to use a user-specified
3852       GSSAPI library. If the library you want to use is not mentioned by
3853       name in PuTTY's list of options, you can enter its full pathname in
3854       the `User-supplied GSSAPI library path' field, and move the `User-
3855       supplied GSSAPI library' option in the preference list to make sure
3856       it is selected before anything else.
3857
3858       On Windows, such libraries are files with a .dll extension, and
3859       must have been built in the same way as the PuTTY executable you're
3860       running; if you have a 32-bit DLL, you must run a 32-bit version
3861       of PuTTY, and the same with 64-bit (see question A.6.10). On Unix,
3862       shared libraries generally have a .so extension.
3863
3864  4.24 The TTY panel
3865
3866       The TTY panel lets you configure the remote pseudo-terminal.
3867
38684.24.1 `Don't allocate a pseudo-terminal'
3869
3870       When connecting to a Unix system, most interactive shell sessions
3871       are run in a _pseudo-terminal_, which allows the Unix system to
3872       pretend it's talking to a real physical terminal device but allows
3873       the SSH server to catch all the data coming from that fake device
3874       and send it back to the client.
3875
3876       Occasionally you might find you have a need to run a session _not_
3877       in a pseudo-terminal. In PuTTY, this is generally only useful for
3878       very specialist purposes; although in Plink (see chapter 7) it is
3879       the usual way of working.
3880
38814.24.2 Sending terminal modes
3882
3883       The SSH protocol allows the client to send `terminal modes' for
3884       the remote pseudo-terminal. These usually control the server's
3885       expectation of the local terminal's behaviour.
3886
3887       If your server does not have sensible defaults for these modes, you
3888       may find that changing them here helps, although the server is at
3889       liberty to ignore your changes. If you don't understand any of this,
3890       it's safe to leave these settings alone.
3891
3892       (None of these settings will have any effect if no pseudo-terminal
3893       is requested or allocated.)
3894
3895       You can change what happens for a particular mode by selecting it in
3896       the list, choosing one of the options and specifying the exact value
3897       if necessary, and hitting `Set'. The effect of the options is as
3898       follows:
3899
3900        -  If the `Auto' option is selected, the PuTTY tools will decide
3901           whether to specify that mode to the server, and if so, will send
3902           a sensible value.
3903
3904           PuTTY proper will send modes that it has an opinion on
3905           (currently only the code for the Backspace key, ERASE, and
3906           whether the character set is UTF-8, IUTF8). Plink on Unix will
3907           propagate appropriate modes from the local terminal, if any.
3908
3909        -  If `Nothing' is selected, no value for the mode will be
3910           specified to the server under any circumstances.
3911
3912        -  If a value is specified, it will be sent to the server under all
3913           circumstances. The precise syntax of the value box depends on
3914           the mode.
3915
3916       By default, all of the available modes are listed as `Auto', which
3917       should do the right thing in most circumstances.
3918
3919       The precise effect of each setting, if any, is up to the server.
3920       Their names come from POSIX and other Unix systems, and they are
3921       most likely to have a useful effect on such systems. (These are the
3922       same settings that can usually be changed using the `stty' command
3923       once logged in to such servers.)
3924
3925       Some notable modes are described below; for fuller explanations, see
3926       your server documentation.
3927
3928        -  ERASE is the character that when typed by the user will delete
3929           one space to the left. When set to `Auto' (the default setting),
3930           this follows the setting of the local Backspace key in PuTTY
3931           (see section 4.4.1).
3932
3933           This and other special characters are specified using `^C'
3934           notation for Ctrl-C, and so on. Use `^<27>' or `^<0x1B>' to
3935           specify a character numerically, and `^~' to get a literal `^'.
3936           Other non-control characters are denoted by themselves. Leaving
3937           the box entirely blank indicates that _no_ character should be
3938           assigned to the specified function, although this may not be
3939           supported by all servers.
3940
3941        -  QUIT is a special character that usually forcefully ends the
3942           current process on the server (SIGQUIT). On many servers its
3943           default setting is Ctrl-backslash (`^\'), which is easy to
3944           accidentally invoke on many keyboards. If this is getting in
3945           your way, you may want to change it to another character or turn
3946           it off entirely.
3947
3948        -  Boolean modes such as ECHO and ICANON can be specified in PuTTY
3949           in a variety of ways, such as true/false, yes/no, and 0/1.
3950           (Explicitly specifying a value of no is different from not
3951           sending the mode at all.)
3952
3953        -  The boolean mode IUTF8 signals to the server whether the
3954           terminal character set is UTF-8 or not, for purposes such as
3955           basic line editing; if this is set incorrectly, the backspace
3956           key may erase the wrong amount of text, for instance. However,
3957           simply setting this is not usually sufficient for the server to
3958           use UTF-8; POSIX servers will generally also require the locale
3959           to be set (by some server-dependent means), although many newer
3960           installations default to UTF-8. Also, since this mode was added
3961           to the SSH protocol much later than the others, many servers
3962           (particularly older servers) do not honour this mode sent over
3963           SSH; indeed, a few poorly-written servers object to its mere
3964           presence, so you may find you need to set it to not be sent
3965           at all. When set to `Auto', this follows the local configured
3966           character set (see section 4.10.1).
3967
3968        -  Terminal speeds are configured elsewhere; see section 4.14.4.
3969
3970  4.25 The X11 panel
3971
3972       The X11 panel allows you to configure forwarding of X11 over an SSH
3973       connection.
3974
3975       If your server lets you run X Window System graphical applications,
3976       X11 forwarding allows you to securely give those applications access
3977       to a local X display on your PC.
3978
3979       To enable X11 forwarding, check the `Enable X11 forwarding' box.
3980       If your X display is somewhere unusual, you will need to enter its
3981       location in the `X display location' box; if this is left blank,
3982       PuTTY will try to find a sensible default in the environment, or use
3983       the primary local display (`:0') if that fails.
3984
3985       See section 3.4 for more information about X11 forwarding.
3986
39874.25.1 Remote X11 authentication
3988
3989       If you are using X11 forwarding, the virtual X server created on the
3990       SSH server machine will be protected by authorisation data. This
3991       data is invented, and checked, by PuTTY.
3992
3993       The usual authorisation method used for this is called MIT-MAGIC-
3994       COOKIE-1. This is a simple password-style protocol: the X client
3995       sends some cookie data to the server, and the server checks that it
3996       matches the real cookie. The cookie data is sent over an unencrypted
3997       X11 connection; so if you allow a client on a third machine to
3998       access the virtual X server, then the cookie will be sent in the
3999       clear.
4000
4001       PuTTY offers the alternative protocol XDM-AUTHORIZATION-1. This is
4002       a cryptographically authenticated protocol: the data sent by the X
4003       client is different every time, and it depends on the IP address
4004       and port of the client's end of the connection and is also stamped
4005       with the current time. So an eavesdropper who captures an XDM-
4006       AUTHORIZATION-1 string cannot immediately re-use it for their own X
4007       connection.
4008
4009       PuTTY's support for XDM-AUTHORIZATION-1 is a somewhat experimental
4010       feature, and may encounter several problems:
4011
4012        -  Some X clients probably do not even support XDM-AUTHORIZATION-
4013           1, so they will not know what to do with the data PuTTY has
4014           provided.
4015
4016        -  This authentication mechanism will only work in SSH-2. In SSH-
4017           1, the SSH server does not tell the client the source address
4018           of a forwarded connection in a machine-readable format, so it's
4019           impossible to verify the XDM-AUTHORIZATION-1 data.
4020
4021        -  You may find this feature causes problems with some SSH servers,
4022           which will not clean up XDM-AUTHORIZATION-1 data after a
4023           session, so that if you then connect to the same server using
4024           a client which only does MIT-MAGIC-COOKIE-1 and are allocated
4025           the same remote display number, you might find that out-of-date
4026           authentication data is still present on your server and your X
4027           connections fail.
4028
4029       PuTTY's default is MIT-MAGIC-COOKIE-1. If you change it, you should
4030       be sure you know what you're doing.
4031
40324.25.2 X authority file for local display
4033
4034       If you are using X11 forwarding, the local X server to which your
4035       forwarded connections are eventually directed may itself require
4036       authorisation.
4037
4038       Some Windows X servers do not require this: they do authorisation
4039       by simpler means, such as accepting any connection from the local
4040       machine but not from anywhere else. However, if your X server does
4041       require authorisation, then PuTTY needs to know what authorisation
4042       is required.
4043
4044       One way in which this data might be made available is for the X
4045       server to store it somewhere in a file which has the same format
4046       as the Unix `.Xauthority' file. If this is how your Windows X
4047       server works, then you can tell PuTTY where to find this file by
4048       configuring this option. By default, PuTTY will not attempt to find
4049       any authorisation for your local display.
4050
4051  4.26 The Tunnels panel
4052
4053       The Tunnels panel allows you to configure tunnelling of arbitrary
4054       connection types through an SSH connection.
4055
4056       Port forwarding allows you to tunnel other types of network
4057       connection down an SSH session. See section 3.5 for a general
4058       discussion of port forwarding and how it works.
4059
4060       The port forwarding section in the Tunnels panel shows a list of all
4061       the port forwardings that PuTTY will try to set up when it connects
4062       to the server. By default no port forwardings are set up, so this
4063       list is empty.
4064
4065       To add a port forwarding:
4066
4067        -  Set one of the `Local' or `Remote' radio buttons, depending on
4068           whether you want to forward a local port to a remote destination
4069           (`Local') or forward a remote port to a local destination
4070           (`Remote'). Alternatively, select `Dynamic' if you want PuTTY to
4071           provide a local SOCKS 4/4A/5 proxy on a local port (note that
4072           this proxy only supports TCP connections; the SSH protocol does
4073           not support forwarding UDP).
4074
4075        -  Enter a source port number into the `Source port' box. For local
4076           forwardings, PuTTY will listen on this port of your PC. For
4077           remote forwardings, your SSH server will listen on this port of
4078           the remote machine. Note that most servers will not allow you to
4079           listen on port numbers less than 1024.
4080
4081        -  If you have selected `Local' or `Remote' (this step is not
4082           needed with `Dynamic'), enter a hostname and port number
4083           separated by a colon, in the `Destination' box. Connections
4084           received on the source port will be directed to this
4085           destination. For example, to connect to a POP-3 server, you
4086           might enter `popserver.example.com:110'. (If you need to enter
4087           a literal IPv6 address, enclose it in square brackets, for
4088           instance `[::1]:2200'.)
4089
4090        -  Click the `Add' button. Your forwarding details should appear in
4091           the list box.
4092
4093       To remove a port forwarding, simply select its details in the list
4094       box, and click the `Remove' button.
4095
4096       In the `Source port' box, you can also optionally enter an IP
4097       address to listen on, by specifying (for instance) `127.0.0.5:79'.
4098       See section 3.5 for more information on how this works and its
4099       restrictions.
4100
4101       In place of port numbers, you can enter service names, if they are
4102       known to the local system. For instance, in the `Destination' box,
4103       you could enter `popserver.example.com:pop3'.
4104
4105       You can modify the currently active set of port forwardings in mid-
4106       session using `Change Settings' (see section 3.1.3.4). If you delete
4107       a local or dynamic port forwarding in mid-session, PuTTY will stop
4108       listening for connections on that port, so it can be re-used by
4109       another program. If you delete a remote port forwarding, note that:
4110
4111        -  The SSH-1 protocol contains no mechanism for asking the server
4112           to stop listening on a remote port.
4113
4114        -  The SSH-2 protocol does contain such a mechanism, but not all
4115           SSH servers support it. (In particular, OpenSSH does not support
4116           it in any version earlier than 3.9.)
4117
4118       If you ask to delete a remote port forwarding and PuTTY cannot make
4119       the server actually stop listening on the port, it will instead
4120       just start refusing incoming connections on that port. Therefore,
4121       although the port cannot be reused by another program, you can at
4122       least be reasonably sure that server-side programs can no longer
4123       access the service at your end of the port forwarding.
4124
4125       If you delete a forwarding, any existing connections established
4126       using that forwarding remain open. Similarly, changes to global
4127       settings such as `Local ports accept connections from other hosts'
4128       only take effect on new forwardings.
4129
4130       If the connection you are forwarding over SSH is itself a second
4131       SSH connection made by another copy of PuTTY, you might find the
4132       `logical host name' configuration option useful to warn PuTTY of
4133       which host key it should be expecting. See section 4.13.5 for
4134       details of this.
4135
41364.26.1 Controlling the visibility of forwarded ports
4137
4138       The source port for a forwarded connection usually does not accept
4139       connections from any machine except the SSH client or server machine
4140       itself (for local and remote forwardings respectively). There are
4141       controls in the Tunnels panel to change this:
4142
4143        -  The `Local ports accept connections from other hosts' option
4144           allows you to set up local-to-remote port forwardings in such a
4145           way that machines other than your client PC can connect to the
4146           forwarded port. (This also applies to dynamic SOCKS forwarding.)
4147
4148        -  The `Remote ports do the same' option does the same thing for
4149           remote-to-local port forwardings (so that machines other than
4150           the SSH server machine can connect to the forwarded port.) Note
4151           that this feature is only available in the SSH-2 protocol, and
4152           not all SSH-2 servers support it (OpenSSH 3.0 does not, for
4153           example).
4154
41554.26.2 Selecting Internet protocol version for forwarded ports
4156
4157       This switch allows you to select a specific Internet protocol (IPv4
4158       or IPv6) for the local end of a forwarded port. By default, it is
4159       set on `Auto', which means that:
4160
4161        -  for a local-to-remote port forwarding, PuTTY will listen for
4162           incoming connections in both IPv4 and (if available) IPv6
4163
4164        -  for a remote-to-local port forwarding, PuTTY will choose a
4165           sensible protocol for the outgoing connection.
4166
4167       This overrides the general Internet protocol version preference on
4168       the Connection panel (see section 4.13.4).
4169
4170       Note that some operating systems may listen for incoming connections
4171       in IPv4 even if you specifically asked for IPv6, because their IPv4
4172       and IPv6 protocol stacks are linked together. Apparently Linux does
4173       this, and Windows does not. So if you're running PuTTY on Windows
4174       and you tick `IPv6' for a local or dynamic port forwarding, it will
4175       _only_ be usable by connecting to it using IPv6; whereas if you do
4176       the same on Linux, you can also use it with IPv4. However, ticking
4177       `Auto' should always give you a port which you can connect to using
4178       either protocol.
4179
4180  4.27 The Bugs and More Bugs panels
4181
4182       Not all SSH servers work properly. Various existing servers have
4183       bugs in them, which can make it impossible for a client to talk to
4184       them unless it knows about the bug and works around it.
4185
4186       Since most servers announce their software version number at the
4187       beginning of the SSH connection, PuTTY will attempt to detect which
4188       bugs it can expect to see in the server and automatically enable
4189       workarounds. However, sometimes it will make mistakes; if the server
4190       has been deliberately configured to conceal its version number, or
4191       if the server is a version which PuTTY's bug database does not know
4192       about, then PuTTY will not know what bugs to expect.
4193
4194       The Bugs and More Bugs panels (there are two because we have so many
4195       bug compatibility modes) allow you to manually configure the bugs
4196       PuTTY expects to see in the server. Each bug can be configured in
4197       three states:
4198
4199        -  `Off': PuTTY will assume the server does not have the bug.
4200
4201        -  `On': PuTTY will assume the server _does_ have the bug.
4202
4203        -  `Auto': PuTTY will use the server's version number announcement
4204           to try to guess whether or not the server has the bug.
4205
42064.27.1 `Chokes on SSH-1 ignore messages'
4207
4208       An ignore message (SSH_MSG_IGNORE) is a message in the SSH protocol
4209       which can be sent from the client to the server, or from the server
4210       to the client, at any time. Either side is required to ignore the
4211       message whenever it receives it. PuTTY uses ignore messages to hide
4212       the password packet in SSH-1, so that a listener cannot tell the
4213       length of the user's password; it also uses ignore messages for
4214       connection keepalives (see section 4.13.1).
4215
4216       If this bug is detected, PuTTY will stop using ignore messages.
4217       This means that keepalives will stop working, and PuTTY will
4218       have to fall back to a secondary defence against SSH-1 password-
4219       length eavesdropping. See section 4.27.2. If this bug is enabled
4220       when talking to a correct server, the session will succeed, but
4221       keepalives will not work and the session might be more vulnerable to
4222       eavesdroppers than it could be.
4223
42244.27.2 `Refuses all SSH-1 password camouflage'
4225
4226       When talking to an SSH-1 server which cannot deal with ignore
4227       messages (see section 4.27.1), PuTTY will attempt to disguise the
4228       length of the user's password by sending additional padding _within_
4229       the password packet. This is technically a violation of the SSH-
4230       1 specification, and so PuTTY will only do it when it cannot use
4231       standards-compliant ignore messages as camouflage. In this sense,
4232       for a server to refuse to accept a padded password packet is not
4233       really a bug, but it does make life inconvenient if the server can
4234       also not handle ignore messages.
4235
4236       If this `bug' is detected, PuTTY will assume that neither ignore
4237       messages nor padding are acceptable, and that it thus has no choice
4238       but to send the user's password with no form of camouflage, so
4239       that an eavesdropping user will be easily able to find out the
4240       exact length of the password. If this bug is enabled when talking
4241       to a correct server, the session will succeed, but will be more
4242       vulnerable to eavesdroppers than it could be.
4243
4244       This is an SSH-1-specific bug. SSH-2 is secure against this type of
4245       attack.
4246
42474.27.3 `Chokes on SSH-1 RSA authentication'
4248
4249       Some SSH-1 servers cannot deal with RSA authentication messages at
4250       all. If Pageant is running and contains any SSH-1 keys, PuTTY will
4251       normally automatically try RSA authentication before falling back
4252       to passwords, so these servers will crash when they see the RSA
4253       attempt.
4254
4255       If this bug is detected, PuTTY will go straight to password
4256       authentication. If this bug is enabled when talking to a correct
4257       server, the session will succeed, but of course RSA authentication
4258       will be impossible.
4259
4260       This is an SSH-1-specific bug.
4261
42624.27.4 `Chokes on SSH-2 ignore messages'
4263
4264       An ignore message (SSH_MSG_IGNORE) is a message in the SSH protocol
4265       which can be sent from the client to the server, or from the server
4266       to the client, at any time. Either side is required to ignore the
4267       message whenever it receives it. PuTTY uses ignore messages in
4268       SSH-2 to confuse the encrypted data stream and make it harder to
4269       cryptanalyse. It also uses ignore messages for connection keepalives
4270       (see section 4.13.1).
4271
4272       If it believes the server to have this bug, PuTTY will stop using
4273       ignore messages. If this bug is enabled when talking to a correct
4274       server, the session will succeed, but keepalives will not work and
4275       the session might be less cryptographically secure than it could be.
4276
42774.27.5 `Chokes on PuTTY's SSH-2 `winadj' requests'
4278
4279       PuTTY sometimes sends a special request to SSH servers in the middle
4280       of channel data, with the name winadj@putty.projects.tartarus.org
4281       (see section F.1). The purpose of this request is to measure the
4282       round-trip time to the server, which PuTTY uses to tune its flow
4283       control. The server does not actually have to _understand_ the
4284       message; it is expected to send back a SSH_MSG_CHANNEL_FAILURE
4285       message indicating that it didn't understand it. (All PuTTY needs
4286       for its timing calculations is _some_ kind of response.)
4287
4288       It has been known for some SSH servers to get confused by this
4289       message in one way or another - because it has a long name, or
4290       because they can't cope with unrecognised request names even to the
4291       extent of sending back the correct failure response, or because they
4292       handle it sensibly but fill up the server's log file with pointless
4293       spam, or whatever. PuTTY therefore supports this bug-compatibility
4294       flag: if it believes the server has this bug, it will never send
4295       its `winadj@putty.projects.tartarus.org' request, and will make do
4296       without its timing data.
4297
42984.27.6 `Miscomputes SSH-2 HMAC keys'
4299
4300       Versions 2.3.0 and below of the SSH server software from ssh.com
4301       compute the keys for their HMAC message authentication codes
4302       incorrectly. A typical symptom of this problem is that PuTTY dies
4303       unexpectedly at the beginning of the session, saying `Incorrect MAC
4304       received on packet'.
4305
4306       If this bug is detected, PuTTY will compute its HMAC keys in the
4307       same way as the buggy server, so that communication will still be
4308       possible. If this bug is enabled when talking to a correct server,
4309       communication will fail.
4310
4311       This is an SSH-2-specific bug.
4312
43134.27.7 `Miscomputes SSH-2 encryption keys'
4314
4315       Versions below 2.0.11 of the SSH server software from ssh.com
4316       compute the keys for the session encryption incorrectly. This
4317       problem can cause various error messages, such as `Incoming packet
4318       was garbled on decryption', or possibly even `Out of memory'.
4319
4320       If this bug is detected, PuTTY will compute its encryption keys
4321       in the same way as the buggy server, so that communication will
4322       still be possible. If this bug is enabled when talking to a correct
4323       server, communication will fail.
4324
4325       This is an SSH-2-specific bug.
4326
43274.27.8 `Requires padding on SSH-2 RSA signatures'
4328
4329       Versions below 3.3 of OpenSSH require SSH-2 RSA signatures to be
4330       padded with zero bytes to the same length as the RSA key modulus.
4331       The SSH-2 specification says that an unpadded signature MUST be
4332       accepted, so this is a bug. A typical symptom of this problem is
4333       that PuTTY mysteriously fails RSA authentication once in every few
4334       hundred attempts, and falls back to passwords.
4335
4336       If this bug is detected, PuTTY will pad its signatures in the way
4337       OpenSSH expects. If this bug is enabled when talking to a correct
4338       server, it is likely that no damage will be done, since correct
4339       servers usually still accept padded signatures because they're used
4340       to talking to OpenSSH.
4341
4342       This is an SSH-2-specific bug.
4343
43444.27.9 `Misuses the session ID in SSH-2 PK auth'
4345
4346       Versions below 2.3 of OpenSSH require SSH-2 public-key
4347       authentication to be done slightly differently: the data to be
4348       signed by the client contains the session ID formatted in a
4349       different way. If public-key authentication mysteriously does
4350       not work but the Event Log (see section 3.1.3.1) thinks it has
4351       successfully sent a signature, it might be worth enabling the
4352       workaround for this bug to see if it helps.
4353
4354       If this bug is detected, PuTTY will sign data in the way OpenSSH
4355       expects. If this bug is enabled when talking to a correct server,
4356       SSH-2 public-key authentication will fail.
4357
4358       This is an SSH-2-specific bug.
4359
43604.27.10 `Handles SSH-2 key re-exchange badly'
4361
4362       Some SSH servers cannot cope with repeat key exchange at all, and
4363       will ignore attempts by the client to start one. Since PuTTY pauses
4364       the session while performing a repeat key exchange, the effect of
4365       this would be to cause the session to hang after an hour (unless
4366       you have your rekey timeout set differently; see section 4.19.2 for
4367       more about rekeys). Other, very old, SSH servers handle repeat key
4368       exchange even more badly, and disconnect upon receiving a repeat key
4369       exchange request.
4370
4371       If this bug is detected, PuTTY will never initiate a repeat key
4372       exchange. If this bug is enabled when talking to a correct server,
4373       the session should still function, but may be less secure than you
4374       would expect.
4375
4376       This is an SSH-2-specific bug.
4377
43784.27.11 `Ignores SSH-2 maximum packet size'
4379
4380       When an SSH-2 channel is set up, each end announces the maximum size
4381       of data packet that it is willing to receive for that channel. Some
4382       servers ignore PuTTY's announcement and send packets larger than
4383       PuTTY is willing to accept, causing it to report `Incoming packet
4384       was garbled on decryption'.
4385
4386       If this bug is detected, PuTTY never allows the channel's flow-
4387       control window to grow large enough to allow the server to send an
4388       over-sized packet. If this bug is enabled when talking to a correct
4389       server, the session will work correctly, but download performance
4390       will be less than it could be.
4391
43924.27.12 `Replies to requests on closed channels'
4393
4394       The SSH protocol as published in RFC 4254 has an ambiguity which
4395       arises if one side of a connection tries to close a channel, while
4396       the other side simultaneously sends a request within the channel and
4397       asks for a reply. RFC 4254 leaves it unclear whether the closing
4398       side should reply to the channel request after having announced its
4399       intention to close the channel.
4400
4401       Discussion on the ietf-ssh mailing list in April 2014 formed a clear
4402       consensus that the right answer is no. However, because of the
4403       ambiguity in the specification, some SSH servers have implemented
4404       the other policy; for example, OpenSSH used to until it was fixed.
4405
4406       Because PuTTY sends channel requests with the `want reply'
4407       flag throughout channels' lifetime (see section 4.27.5), it's
4408       possible that when connecting to such a server it might receive
4409       a reply to a request after it thinks the channel has entirely
4410       closed, and terminate with an error along the lines of `Received
4411       SSH2_MSG_CHANNEL_FAILURE for nonexistent channel 256'.
4412
44134.27.13 `Only supports pre-RFC4419 SSH-2 DH GEX'
4414
4415       The SSH key exchange method that uses Diffie-Hellman group exchange
4416       was redesigned after its original release, to use a slightly more
4417       sophisticated setup message. Almost all SSH implementations switched
4418       over to the new version. (PuTTY was one of the last.) A few old
4419       servers still only support the old one.
4420
4421       If this bug is detected, and the client and server negotiate Diffie-
4422       Hellman group exchange, then PuTTY will send the old message now
4423       known as SSH2_MSG_KEX_DH_GEX_REQUEST_OLD in place of the new
4424       SSH2_MSG_KEX_DH_GEX_REQUEST.
4425
4426       This is an SSH-2-specific bug.
4427
4428  4.28 The Serial panel
4429
4430       The Serial panel allows you to configure options that only apply
4431       when PuTTY is connecting to a local serial line.
4432
44334.28.1 Selecting a serial line to connect to
4434
4435       The `Serial line to connect to' box allows you to choose which
4436       serial line you want PuTTY to talk to, if your computer has more
4437       than one serial port.
4438
4439       On Windows, the first serial line is called COM1, and if there is a
4440       second it is called COM2, and so on.
4441
4442       This configuration setting is also visible on the Session panel,
4443       where it replaces the `Host Name' box (see section 4.1.1) if the
4444       connection type is set to `Serial'.
4445
44464.28.2 Selecting the speed of your serial line
4447
4448       The `Speed' box allows you to choose the speed (or `baud rate') at
4449       which to talk to the serial line. Typical values might be 9600,
4450       19200, 38400 or 57600. Which one you need will depend on the device
4451       at the other end of the serial cable; consult the manual for that
4452       device if you are in doubt.
4453
4454       This configuration setting is also visible on the Session panel,
4455       where it replaces the `Port' box (see section 4.1.1) if the
4456       connection type is set to `Serial'.
4457
44584.28.3 Selecting the number of data bits
4459
4460       The `Data bits' box allows you to choose how many data bits are
4461       transmitted in each byte sent or received through the serial line.
4462       Typical values are 7 or 8.
4463
44644.28.4 Selecting the number of stop bits
4465
4466       The `Stop bits' box allows you to choose how many stop bits are used
4467       in the serial line protocol. Typical values are 1, 1.5 or 2.
4468
44694.28.5 Selecting the serial parity checking scheme
4470
4471       The `Parity' box allows you to choose what type of parity checking
4472       is used on the serial line. The settings are:
4473
4474        -  `None': no parity bit is sent at all.
4475
4476        -  `Odd': an extra parity bit is sent alongside each byte, and
4477           arranged so that the total number of 1 bits is odd.
4478
4479        -  `Even': an extra parity bit is sent alongside each byte, and
4480           arranged so that the total number of 1 bits is even.
4481
4482        -  `Mark': an extra parity bit is sent alongside each byte, and
4483           always set to 1.
4484
4485        -  `Space': an extra parity bit is sent alongside each byte, and
4486           always set to 0.
4487
44884.28.6 Selecting the serial flow control scheme
4489
4490       The `Flow control' box allows you to choose what type of flow
4491       control checking is used on the serial line. The settings are:
4492
4493        -  `None': no flow control is done. Data may be lost if either side
4494           attempts to send faster than the serial line permits.
4495
4496        -  `XON/XOFF': flow control is done by sending XON and XOFF
4497           characters within the data stream.
4498
4499        -  `RTS/CTS': flow control is done using the RTS and CTS wires on
4500           the serial line.
4501
4502        -  `DSR/DTR': flow control is done using the DSR and DTR wires on
4503           the serial line.
4504
4505  4.29 Storing configuration in a file
4506
4507       PuTTY does not currently support storing its configuration in a file
4508       instead of the Registry. However, you can work around this with a
4509       couple of batch files.
4510
4511       You will need a file called (say) `PUTTY.BAT' which imports the
4512       contents of a file into the Registry, then runs PuTTY, exports
4513       the contents of the Registry back into the file, and deletes the
4514       Registry entries. This can all be done using the Regedit command
4515       line options, so it's all automatic. Here is what you need in
4516       `PUTTY.BAT':
4517
4518         @ECHO OFF
4519         regedit /s putty.reg
4520         regedit /s puttyrnd.reg
4521         start /w putty.exe
4522         regedit /ea new.reg HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
4523         copy new.reg putty.reg
4524         del new.reg
4525         regedit /s puttydel.reg
4526
4527       This batch file needs two auxiliary files: `PUTTYRND.REG' which sets
4528       up an initial safe location for the `PUTTY.RND' random seed file,
4529       and `PUTTYDEL.REG' which destroys everything in the Registry once
4530       it's been successfully saved back to the file.
4531
4532       Here is `PUTTYDEL.REG':
4533
4534         REGEDIT4
4535          
4536         [-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
4537
4538       Here is an example `PUTTYRND.REG' file:
4539
4540         REGEDIT4
4541          
4542         [HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]
4543         "RandSeedFile"="a:\\putty.rnd"
4544
4545       You should replace `a:\putty.rnd' with the location where you want
4546       to store your random number data. If the aim is to carry around
4547       PuTTY and its settings on one USB stick, you probably want to store
4548       it on the USB stick.
4549
4550Chapter 5: Using PSCP to transfer files securely
4551------------------------------------------------
4552
4553       PSCP, the PuTTY Secure Copy client, is a tool for transferring files
4554       securely between computers using an SSH connection.
4555
4556       If you have an SSH-2 server, you might prefer PSFTP (see chapter
4557       6) for interactive use. PSFTP does not in general work with SSH-1
4558       servers, however.
4559
4560   5.1 Starting PSCP
4561
4562       PSCP is a command line application. This means that you cannot just
4563       double-click on its icon to run it and instead you have to bring up
4564       a console window. With Windows 95, 98, and ME, this is called an
4565       `MS-DOS Prompt' and with Windows NT, 2000, and XP, it is called a
4566       `Command Prompt'. It should be available from the Programs section
4567       of your Start Menu.
4568
4569       To start PSCP it will need either to be on your `PATH' or in your
4570       current directory. To add the directory containing PSCP to your
4571       `PATH' environment variable, type into the console window:
4572
4573         set PATH=C:\path\to\putty\directory;%PATH%
4574
4575       This will only work for the lifetime of that particular console
4576       window. To set your `PATH' more permanently on Windows NT, 2000, and
4577       XP, use the Environment tab of the System Control Panel. On Windows
4578       95, 98, and ME, you will need to edit your `AUTOEXEC.BAT' to include
4579       a `set' command like the one above.
4580
4581   5.2 PSCP Usage
4582
4583       Once you've got a console window to type into, you can just type
4584       `pscp' on its own to bring up a usage message. This tells you the
4585       version of PSCP you're using, and gives you a brief summary of how
4586       to use PSCP:
4587
4588         Z:\owendadmin>pscp
4589         PuTTY Secure Copy client
4590         Release 0.70
4591         Usage: pscp [options] [user@]host:source target
4592                pscp [options] source [source...] [user@]host:target
4593                pscp [options] -ls [user@]host:filespec
4594         Options:
4595           -V        print version information and exit
4596           -pgpfp    print PGP key fingerprints and exit
4597           -p        preserve file attributes
4598           -q        quiet, don't show statistics
4599           -r        copy directories recursively
4600           -v        show verbose messages
4601           -load sessname  Load settings from saved session
4602           -P port   connect to specified port
4603           -l user   connect with specified username
4604           -pw passw login with specified password
4605           -1 -2     force use of particular SSH protocol version
4606           -4 -6     force use of IPv4 or IPv6
4607           -C        enable compression
4608           -i key    private key file for user authentication
4609           -noagent  disable use of Pageant
4610           -agent    enable use of Pageant
4611           -hostkey aa:bb:cc:...
4612                     manually specify a host key (may be repeated)
4613           -batch    disable all interactive prompts
4614           -proxycmd command
4615                     use 'command' as local proxy
4616           -unsafe   allow server-side wildcards (DANGEROUS)
4617           -sftp     force use of SFTP protocol
4618           -scp      force use of SCP protocol
4619           -sshlog file
4620           -sshrawlog file
4621                     log protocol details to a file
4622
4623       (PSCP's interface is much like the Unix `scp' command, if you're
4624       familiar with that.)
4625
4626 5.2.1 The basics
4627
4628       To receive (a) file(s) from a remote server:
4629
4630         pscp [options] [user@]host:source target
4631
4632       So to copy the file `/etc/hosts' from the server `example.com' as
4633       user `fred' to the file `c:\temp\example-hosts.txt', you would type:
4634
4635         pscp fred@example.com:/etc/hosts c:\temp\example-hosts.txt
4636
4637       To send (a) file(s) to a remote server:
4638
4639         pscp [options] source [source...] [user@]host:target
4640
4641       So to copy the local file `c:\documents\foo.txt' to the server
4642       `example.com' as user `fred' to the file `/tmp/foo' you would type:
4643
4644         pscp c:\documents\foo.txt fred@example.com:/tmp/foo
4645
4646       You can use wildcards to transfer multiple files in either
4647       direction, like this:
4648
4649         pscp c:\documents\*.doc fred@example.com:docfiles
4650         pscp fred@example.com:source/*.c c:\source
4651
4652       However, in the second case (using a wildcard for multiple remote
4653       files) you may see a warning saying something like `warning: remote
4654       host tried to write to a file called `terminal.c' when we requested
4655       a file called `*.c'. If this is a wildcard, consider upgrading to
4656       SSH-2 or using the `-unsafe' option. Renaming of this file has been
4657       disallowed'.
4658
4659       This is due to a fundamental insecurity in the old-style SCP
4660       protocol: the client sends the wildcard string (`*.c') to the
4661       server, and the server sends back a sequence of file names that
4662       match the wildcard pattern. However, there is nothing to stop the
4663       server sending back a _different_ pattern and writing over one of
4664       your other files: if you request `*.c', the server might send back
4665       the file name `AUTOEXEC.BAT' and install a virus for you. Since the
4666       wildcard matching rules are decided by the server, the client cannot
4667       reliably verify that the filenames sent back match the pattern.
4668
4669       PSCP will attempt to use the newer SFTP protocol (part of SSH-2)
4670       where possible, which does not suffer from this security flaw. If
4671       you are talking to an SSH-2 server which supports SFTP, you will
4672       never see this warning. (You can force use of the SFTP protocol, if
4673       available, with `-sftp' - see section 5.2.2.6.)
4674
4675       If you really need to use a server-side wildcard with an SSH-1
4676       server, you can use the `-unsafe' command line option with PSCP:
4677
4678         pscp -unsafe fred@example.com:source/*.c c:\source
4679
4680       This will suppress the warning message and the file transfer will
4681       happen. However, you should be aware that by using this option you
4682       are giving the server the ability to write to _any_ file in the
4683       target directory, so you should only use this option if you trust
4684       the server administrator not to be malicious (and not to let the
4685       server machine be cracked by malicious people). Alternatively, do
4686       any such download in a newly created empty directory. (Even in
4687       `unsafe' mode, PSCP will still protect you against the server trying
4688       to get out of that directory using pathnames including `..'.)
4689
46905.2.1.1 `user'
4691
4692       The login name on the remote server. If this is omitted, and `host'
4693       is a PuTTY saved session, PSCP will use any username specified by
4694       that saved session. Otherwise, PSCP will attempt to use the local
4695       Windows username.
4696
46975.2.1.2 `host'
4698
4699       The name of the remote server, or the name of an existing PuTTY
4700       saved session. In the latter case, the session's settings for
4701       hostname, port number, cipher type and username will be used.
4702
47035.2.1.3 `source'
4704
4705       One or more source files. Wildcards are allowed. The syntax of
4706       wildcards depends on the system to which they apply, so if you are
4707       copying _from_ a Windows system _to_ a UNIX system, you should use
4708       Windows wildcard syntax (e.g. `*.*'), but if you are copying _from_
4709       a UNIX system _to_ a Windows system, you would use the wildcard
4710       syntax allowed by your UNIX shell (e.g. `*').
4711
4712       If the source is a remote server and you do not specify a full
4713       pathname (in UNIX, a pathname beginning with a `/' (slash)
4714       character), what you specify as a source will be interpreted
4715       relative to your home directory on the remote server.
4716
47175.2.1.4 `target'
4718
4719       The filename or directory to put the file(s). When copying from a
4720       remote server to a local host, you may wish simply to place the
4721       file(s) in the current directory. To do this, you should specify a
4722       target of `.'. For example:
4723
4724         pscp fred@example.com:/home/tom/.emacs .
4725
4726       ...would copy `/home/tom/.emacs' on the remote server to the current
4727       directory.
4728
4729       As with the `source' parameter, if the target is on a remote server
4730       and is not a full path name, it is interpreted relative to your home
4731       directory on the remote server.
4732
4733 5.2.2 Options
4734
4735       PSCP accepts all the general command line options supported by the
4736       PuTTY tools, except the ones which make no sense in a file transfer
4737       utility. See section 3.8.3 for a description of these options. (The
4738       ones not supported by PSCP are clearly marked.)
4739
4740       PSCP also supports some of its own options. The following sections
4741       describe PSCP's specific command-line options.
4742
47435.2.2.1 `-ls' list remote files
4744
4745       If the `-ls' option is given, no files are transferred; instead,
4746       remote files are listed. Only a hostname specification and optional
4747       remote file specification need be given. For example:
4748
4749         pscp -ls fred@example.com:dir1
4750
4751       The SCP protocol does not contain within itself a means of listing
4752       files. If SCP is in use, this option therefore assumes that the
4753       server responds appropriately to the command `ls -la'; this may not
4754       work with all servers.
4755
4756       If SFTP is in use, this option should work with all servers.
4757
47585.2.2.2 `-p' preserve file attributes
4759
4760       By default, files copied with PSCP are timestamped with the date
4761       and time they were copied. The `-p' option preserves the original
4762       timestamp on copied files.
4763
47645.2.2.3 `-q' quiet, don't show statistics
4765
4766       By default, PSCP displays a meter displaying the progress of the
4767       current transfer:
4768
4769         mibs.tar          |   168 kB |  84.0 kB/s | ETA: 00:00:13 |  13%
4770
4771       The fields in this display are (from left to right), filename, size
4772       (in kilobytes) of file transferred so far, estimate of how fast the
4773       file is being transferred (in kilobytes per second), estimated time
4774       that the transfer will be complete, and percentage of the file so
4775       far transferred. The `-q' option to PSCP suppresses the printing of
4776       these statistics.
4777
47785.2.2.4 `-r' copies directories recursively
4779
4780       By default, PSCP will only copy files. Any directories you specify
4781       to copy will be skipped, as will their contents. The `-r' option
4782       tells PSCP to descend into any directories you specify, and to copy
4783       them and their contents. This allows you to use PSCP to transfer
4784       whole directory structures between machines.
4785
47865.2.2.5 `-batch' avoid interactive prompts
4787
4788       If you use the `-batch' option, PSCP will never give an interactive
4789       prompt while establishing the connection. If the server's host key
4790       is invalid, for example (see section 2.2), then the connection will
4791       simply be abandoned instead of asking you what to do next.
4792
4793       This may help PSCP's behaviour when it is used in automated scripts:
4794       using `-batch', if something goes wrong at connection time, the
4795       batch job will fail rather than hang.
4796
47975.2.2.6 `-sftp', `-scp' force use of particular protocol
4798
4799       As mentioned in section 5.2.1, there are two different file transfer
4800       protocols in use with SSH. Despite its name, PSCP (like many other
4801       ostensible scp clients) can use either of these protocols.
4802
4803       The older SCP protocol does not have a written specification and
4804       leaves a lot of detail to the server platform. Wildcards are
4805       expanded on the server. The simple design means that any wildcard
4806       specification supported by the server platform (such as brace
4807       expansion) can be used, but also leads to interoperability issues
4808       such as with filename quoting (for instance, where filenames contain
4809       spaces), and also the security issue described in section 5.2.1.
4810
4811       The newer SFTP protocol, which is usually associated with SSH-
4812       2 servers, is specified in a more platform independent way, and
4813       leaves issues such as wildcard syntax up to the client. (PuTTY's
4814       SFTP wildcard syntax is described in section 6.2.2.) This makes it
4815       more consistent across platforms, more suitable for scripting and
4816       automation, and avoids security issues with wildcard matching.
4817
4818       Normally PSCP will attempt to use the SFTP protocol, and only fall
4819       back to the SCP protocol if SFTP is not available on the server.
4820
4821       The `-scp' option forces PSCP to use the SCP protocol or quit.
4822
4823       The `-sftp' option forces PSCP to use the SFTP protocol or quit.
4824       When this option is specified, PSCP looks harder for an SFTP server,
4825       which may allow use of SFTP with SSH-1 depending on server setup.
4826
4827 5.2.3 Return value
4828
4829       PSCP returns an ERRORLEVEL of zero (success) only if the files were
4830       correctly transferred. You can test for this in a batch file, using
4831       code such as this:
4832
4833         pscp file*.* user@hostname:
4834         if errorlevel 1 echo There was an error
4835
4836 5.2.4 Using public key authentication with PSCP
4837
4838       Like PuTTY, PSCP can authenticate using a public key instead of a
4839       password. There are three ways you can do this.
4840
4841       Firstly, PSCP can use PuTTY saved sessions in place of hostnames
4842       (see section 5.2.1.2). So you would do this:
4843
4844        -  Run PuTTY, and create a PuTTY saved session (see section 4.1.2)
4845           which specifies your private key file (see section 4.22.8). You
4846           will probably also want to specify a username to log in as (see
4847           section 4.14.1).
4848
4849        -  In PSCP, you can now use the name of the session instead of
4850           a hostname: type `pscp sessionname:file localfile', where
4851           `sessionname' is replaced by the name of your saved session.
4852
4853       Secondly, you can supply the name of a private key file on the
4854       command line, with the `-i' option. See section 3.8.3.18 for more
4855       information.
4856
4857       Thirdly, PSCP will attempt to authenticate using Pageant if Pageant
4858       is running (see chapter 9). So you would do this:
4859
4860        -  Ensure Pageant is running, and has your private key stored in
4861           it.
4862
4863        -  Specify a user and host name to PSCP as normal. PSCP will
4864           automatically detect Pageant and try to use the keys within it.
4865
4866       For more general information on public-key authentication, see
4867       chapter 8.
4868
4869Chapter 6: Using PSFTP to transfer files securely
4870-------------------------------------------------
4871
4872       PSFTP, the PuTTY SFTP client, is a tool for transferring files
4873       securely between computers using an SSH connection.
4874
4875       PSFTP differs from PSCP in the following ways:
4876
4877        -  PSCP should work on virtually every SSH server. PSFTP uses the
4878           new SFTP protocol, which is a feature of SSH-2 only. (PSCP
4879           will also use this protocol if it can, but there is an SSH-1
4880           equivalent it can fall back to if it cannot.)
4881
4882        -  PSFTP allows you to run an interactive file transfer session,
4883           much like the Windows `ftp' program. You can list the contents
4884           of directories, browse around the file system, issue multiple
4885           `get' and `put' commands, and eventually log out. By contrast,
4886           PSCP is designed to do a single file transfer operation and
4887           immediately terminate.
4888
4889   6.1 Starting PSFTP
4890
4891       The usual way to start PSFTP is from a command prompt, much like
4892       PSCP. To do this, it will need either to be on your `PATH' or in
4893       your current directory. To add the directory containing PSFTP to
4894       your `PATH' environment variable, type into the console window:
4895
4896         set PATH=C:\path\to\putty\directory;%PATH%
4897
4898       Unlike PSCP, however, PSFTP has no complex command-line syntax; you
4899       just specify a host name and perhaps a user name:
4900
4901         psftp server.example.com
4902
4903       or perhaps
4904
4905         psftp fred@server.example.com
4906
4907       Alternatively, if you just type `psftp' on its own (or double-click
4908       the PSFTP icon in the Windows GUI), you will see the PSFTP prompt,
4909       and a message telling you PSFTP has not connected to any server:
4910
4911         C:\>psftp
4912         psftp: no hostname specified; use "open host.name" to connect
4913         psftp>
4914
4915       At this point you can type `open server.example.com' or
4916       `open fred@server.example.com' to start a session.
4917
4918       PSFTP accepts all the general command line options supported by the
4919       PuTTY tools, except the ones which make no sense in a file transfer
4920       utility. See section 3.8.3 for a description of these options. (The
4921       ones not supported by PSFTP are clearly marked.)
4922
4923       PSFTP also supports some of its own options. The following sections
4924       describe PSFTP's specific command-line options.
4925
4926 6.1.1 `-b': specify a file containing batch commands
4927
4928       In normal operation, PSFTP is an interactive program which displays
4929       a command line and accepts commands from the keyboard.
4930
4931       If you need to do automated tasks with PSFTP, you would probably
4932       prefer to specify a set of commands in advance and have them
4933       executed automatically. The `-b' option allows you to do this. You
4934       use it with a file name containing batch commands. For example, you
4935       might create a file called `myscript.scr' containing lines like
4936       this:
4937
4938         cd /home/ftp/users/jeff
4939         del jam-old.tar.gz
4940         ren jam.tar.gz jam-old.tar.gz
4941         put jam.tar.gz
4942         chmod a+r jam.tar.gz
4943
4944       and then you could run the script by typing
4945
4946         psftp user@hostname -b myscript.scr
4947
4948       When you run a batch script in this way, PSFTP will abort the script
4949       if any command fails to complete successfully. To change this
4950       behaviour, you can add the `-be' option (section 6.1.3).
4951
4952       PSFTP will terminate after it finishes executing the batch script.
4953
4954 6.1.2 `-bc': display batch commands as they are run
4955
4956       The `-bc' option alters what PSFTP displays while processing a
4957       batch script specified with `-b'. With the `-bc' option, PSFTP will
4958       display prompts and commands just as if the commands had been typed
4959       at the keyboard. So instead of seeing this:
4960
4961         C:\>psftp fred@hostname -b batchfile
4962         Sent username "fred"
4963         Remote working directory is /home/fred
4964         Listing directory /home/fred/lib
4965         drwxrwsr-x    4 fred     fred         1024 Sep  6 10:42 .
4966         drwxr-sr-x   25 fred     fred         2048 Dec 14 09:36 ..
4967         drwxrwsr-x    3 fred     fred         1024 Apr 17  2000 jed
4968         lrwxrwxrwx    1 fred     fred           24 Apr 17  2000 timber
4969         drwxrwsr-x    2 fred     fred         1024 Mar 13  2000 trn
4970
4971       you might see this:
4972
4973         C:\>psftp fred@hostname -bc -b batchfile
4974         Sent username "fred"
4975         Remote working directory is /home/fred
4976         psftp> dir lib
4977         Listing directory /home/fred/lib
4978         drwxrwsr-x    4 fred     fred         1024 Sep  6 10:42 .
4979         drwxr-sr-x   25 fred     fred         2048 Dec 14 09:36 ..
4980         drwxrwsr-x    3 fred     fred         1024 Apr 17  2000 jed
4981         lrwxrwxrwx    1 fred     fred           24 Apr 17  2000 timber
4982         drwxrwsr-x    2 fred     fred         1024 Mar 13  2000 trn
4983         psftp> quit
4984
4985 6.1.3 `-be': continue batch processing on errors
4986
4987       When running a batch file, this additional option causes PSFTP
4988       to continue processing even if a command fails to complete
4989       successfully.
4990
4991       You might want this to happen if you wanted to delete a file and
4992       didn't care if it was already not present, for example.
4993
4994 6.1.4 `-batch': avoid interactive prompts
4995
4996       If you use the `-batch' option, PSFTP will never give an interactive
4997       prompt while establishing the connection. If the server's host key
4998       is invalid, for example (see section 2.2), then the connection will
4999       simply be abandoned instead of asking you what to do next.
5000
5001       This may help PSFTP's behaviour when it is used in automated
5002       scripts: using `-batch', if something goes wrong at connection time,
5003       the batch job will fail rather than hang.
5004
5005   6.2 Running PSFTP
5006
5007       Once you have started your PSFTP session, you will see a `psftp>'
5008       prompt. You can now type commands to perform file-transfer
5009       functions. This section lists all the available commands.
5010
5011       Any line starting with a # will be treated as a comment and ignored.
5012
5013 6.2.1 General quoting rules for PSFTP commands
5014
5015       Most PSFTP commands are considered by the PSFTP command interpreter
5016       as a sequence of words, separated by spaces. For example, the
5017       command `ren oldfilename newfilename' splits up into three words:
5018       `ren' (the command name), `oldfilename' (the name of the file to be
5019       renamed), and `newfilename' (the new name to give the file).
5020
5021       Sometimes you will need to specify file names that _contain_ spaces.
5022       In order to do this, you can surround the file name with double
5023       quotes. This works equally well for local file names and remote file
5024       names:
5025
5026         psftp> get "spacey file name.txt" "save it under this name.txt"
5027
5028       The double quotes themselves will not appear as part of the file
5029       names; they are removed by PSFTP and their only effect is to stop
5030       the spaces inside them from acting as word separators.
5031
5032       If you need to _use_ a double quote (on some types of remote system,
5033       such as Unix, you are allowed to use double quotes in file names),
5034       you can do this by doubling it. This works both inside and outside
5035       double quotes. For example, this command
5036
5037         psftp> ren ""this"" "a file with ""quotes"" in it"
5038
5039       will take a file whose current name is `"this"' (with a double quote
5040       character at the beginning and the end) and rename it to a file
5041       whose name is `a file with "quotes" in it'.
5042
5043       (The one exception to the PSFTP quoting rules is the `!' command,
5044       which passes its command line straight to Windows without splitting
5045       it up into words at all. See section 6.2.19.)
5046
5047 6.2.2 Wildcards in PSFTP
5048
5049       Several commands in PSFTP support `wildcards' to select multiple
5050       files.
5051
5052       For _local_ file specifications (such as the first argument to
5053       `put'), wildcard rules for the local operating system are used. For
5054       instance, PSFTP running on Windows might require the use of `*.*'
5055       where PSFTP on Unix would need `*'.
5056
5057       For _remote_ file specifications (such as the first argument to
5058       `get'), PSFTP uses a standard wildcard syntax (similar to POSIX
5059       wildcards):
5060
5061        -  `*' matches any sequence of characters (including a zero-length
5062           sequence).
5063
5064        -  `?' matches exactly one character.
5065
5066        -  `[abc]' matches exactly one character which can be a, b, or c.
5067
5068           `[a-z]' matches any character in the range a to z.
5069
5070           `[^abc]' matches a single character that is _not_ a, b, or c.
5071
5072           Special cases: `[-a]' matches a literal hyphen (-) or a; `[^-a]'
5073           matches all other characters. `[a^]' matches a literal caret (^)
5074           or a.
5075
5076        -  `\' (backslash) before any of the above characters (or itself)
5077           removes that character's special meaning.
5078
5079       A leading period (.) on a filename is not treated specially, unlike
5080       in some Unix contexts; `get *' will fetch all files, whether or not
5081       they start with a leading period.
5082
5083 6.2.3 The `open' command: start a session
5084
5085       If you started PSFTP by double-clicking in the GUI, or just by
5086       typing `psftp' at the command line, you will need to open a
5087       connection to an SFTP server before you can issue any other commands
5088       (except `help' and `quit').
5089
5090       To create a connection, type `open host.name', or if you need to
5091       specify a user name as well you can type `open user@host.name'. You
5092       can optionally specify a port as well: `open user@host.name 22'.
5093
5094       Once you have issued this command, you will not be able to issue it
5095       again, _even_ if the command fails (for example, if you mistype the
5096       host name or the connection times out). So if the connection is not
5097       opened successfully, PSFTP will terminate immediately.
5098
5099 6.2.4 The `quit' command: end your session
5100
5101       When you have finished your session, type the command `quit' to
5102       close the connection, terminate PSFTP and return to the command line
5103       (or just close the PSFTP console window if you started it from the
5104       GUI).
5105
5106       You can also use the `bye' and `exit' commands, which have exactly
5107       the same effect.
5108
5109 6.2.5 The `close' command: close your connection
5110
5111       If you just want to close the network connection but keep PSFTP
5112       running, you can use the `close' command. You can then use the
5113       `open' command to open a new connection.
5114
5115 6.2.6 The `help' command: get quick online help
5116
5117       If you type `help', PSFTP will give a short list of the available
5118       commands.
5119
5120       If you type `help' with a command name - for example, `help get'
5121       - then PSFTP will give a short piece of help on that particular
5122       command.
5123
5124 6.2.7 The `cd' and `pwd' commands: changing the remote working directory
5125
5126       PSFTP maintains a notion of your `working directory' on the server.
5127       This is the default directory that other commands will operate on.
5128       For example, if you type `get filename.dat' then PSFTP will look for
5129       `filename.dat' in your remote working directory on the server.
5130
5131       To change your remote working directory, use the `cd' command. If
5132       you don't provide an argument, `cd' will return you to your home
5133       directory on the server (more precisely, the remote directory you
5134       were in at the start of the connection).
5135
5136       To display your current remote working directory, type `pwd'.
5137
5138 6.2.8 The `lcd' and `lpwd' commands: changing the local working directory
5139
5140       As well as having a working directory on the remote server, PSFTP
5141       also has a working directory on your local machine (just like
5142       any other Windows process). This is the default local directory
5143       that other commands will operate on. For example, if you type
5144       `get filename.dat' then PSFTP will save the resulting file as
5145       `filename.dat' in your local working directory.
5146
5147       To change your local working directory, use the `lcd' command. To
5148       display your current local working directory, type `lpwd'.
5149
5150 6.2.9 The `get' command: fetch a file from the server
5151
5152       To download a file from the server and store it on your local PC,
5153       you use the `get' command.
5154
5155       In its simplest form, you just use this with a file name:
5156
5157         get myfile.dat
5158
5159       If you want to store the file locally under a different name,
5160       specify the local file name after the remote one:
5161
5162         get myfile.dat newname.dat
5163
5164       This will fetch the file on the server called `myfile.dat', but will
5165       save it to your local machine under the name `newname.dat'.
5166
5167       To fetch an entire directory recursively, you can use the `-r'
5168       option:
5169
5170         get -r mydir
5171         get -r mydir newname
5172
5173       (If you want to fetch a file whose name starts with a hyphen, you
5174       may have to use the `--' special argument, which stops `get' from
5175       interpreting anything as a switch after it. For example, `get -- -
5176       silly-name-'.)
5177
51786.2.10 The `put' command: send a file to the server
5179
5180       To upload a file to the server from your local PC, you use the `put'
5181       command.
5182
5183       In its simplest form, you just use this with a file name:
5184
5185         put myfile.dat
5186
5187       If you want to store the file remotely under a different name,
5188       specify the remote file name after the local one:
5189
5190         put myfile.dat newname.dat
5191
5192       This will send the local file called `myfile.dat', but will store it
5193       on the server under the name `newname.dat'.
5194
5195       To send an entire directory recursively, you can use the `-r'
5196       option:
5197
5198         put -r mydir
5199         put -r mydir newname
5200
5201       (If you want to send a file whose name starts with a hyphen, you
5202       may have to use the `--' special argument, which stops `put' from
5203       interpreting anything as a switch after it. For example, `put -- -
5204       silly-name-'.)
5205
52066.2.11 The `mget' and `mput' commands: fetch or send multiple files
5207
5208       `mget' works almost exactly like `get', except that it allows you to
5209       specify more than one file to fetch at once. You can do this in two
5210       ways:
5211
5212        -  by giving two or more explicit file names
5213           (`mget file1.txt file2.txt')
5214
5215        -  by using a wildcard (`mget *.txt').
5216
5217       Every argument to `mget' is treated as the name of a file to fetch
5218       (unlike `get', which will interpret at most one argument like
5219       that, and a second argument will be treated as an alternative name
5220       under which to store the retrieved file), or a wildcard expression
5221       matching more than one file.
5222
5223       The `-r' and `--' options from `get' are also available with `mget'.
5224
5225       `mput' is similar to `put', with the same differences.
5226
52276.2.12 The `reget' and `reput' commands: resuming file transfers
5228
5229       If a file transfer fails half way through, and you end up with half
5230       the file stored on your disk, you can resume the file transfer using
5231       the `reget' and `reput' commands. These work exactly like the `get'
5232       and `put' commands, but they check for the presence of the half-
5233       written destination file and start transferring from where the last
5234       attempt left off.
5235
5236       The syntax of `reget' and `reput' is exactly the same as the syntax
5237       of `get' and `put':
5238
5239         reget myfile.dat
5240         reget myfile.dat newname.dat
5241         reget -r mydir
5242
5243       These commands are intended mainly for resuming interrupted
5244       transfers. They assume that the remote file or directory structure
5245       has not changed in any way; if there have been changes, you may end
5246       up with corrupted files. In particular, the `-r' option will not
5247       pick up changes to files or directories already transferred in full.
5248
52496.2.13 The `dir' command: list remote files
5250
5251       To list the files in your remote working directory, just type `dir'.
5252
5253       You can also list the contents of a different directory by typing
5254       `dir' followed by the directory name:
5255
5256         dir /home/fred
5257         dir sources
5258
5259       And you can list a subset of the contents of a directory by
5260       providing a wildcard:
5261
5262         dir /home/fred/*.txt
5263         dir sources/*.c
5264
5265       The `ls' command works exactly the same way as `dir'.
5266
52676.2.14 The `chmod' command: change permissions on remote files
5268
5269       PSFTP allows you to modify the file permissions on files and
5270       directories on the server. You do this using the `chmod' command,
5271       which works very much like the Unix `chmod' command.
5272
5273       The basic syntax is `chmod modes file', where `modes' represents a
5274       modification to the file permissions, and `file' is the filename to
5275       modify. You can specify multiple files or wildcards. For example:
5276
5277         chmod go-rwx,u+w privatefile
5278         chmod a+r public*
5279         chmod 640 groupfile1 groupfile2
5280
5281       The `modes' parameter can be a set of octal digits in the Unix
5282       style. (If you don't know what this means, you probably don't want
5283       to be using it!) Alternatively, it can be a list of permission
5284       modifications, separated by commas. Each modification consists of:
5285
5286        -  The people affected by the modification. This can be `u'
5287           (the owning user), `g' (members of the owning group), or `o'
5288           (everybody else - `others'), or some combination of those. It
5289           can also be `a' (`all') to affect everybody at once.
5290
5291        -  A `+' or `-' sign, indicating whether permissions are to be
5292           added or removed.
5293
5294        -  The actual permissions being added or removed. These can be
5295           `r' (permission to read the file), `w' (permission to write
5296           to the file), and `x' (permission to execute the file, or in
5297           the case of a directory, permission to access files within the
5298           directory).
5299
5300       So the above examples would do:
5301
5302        -  The first example: `go-rwx' removes read, write and execute
5303           permissions for members of the owning group and everybody else
5304           (so the only permissions left are the ones for the file owner).
5305           `u+w' adds write permission for the file owner.
5306
5307        -  The second example: `a+r' adds read permission for everybody to
5308           all files and directories starting with `public'.
5309
5310       In addition to all this, there are a few extra special cases for
5311       Unix systems. On non-Unix systems these are unlikely to be useful:
5312
5313        -  You can specify `u+s' and `u-s' to add or remove the Unix set-
5314           user-ID bit. This is typically only useful for special purposes;
5315           refer to your Unix documentation if you're not sure about it.
5316
5317        -  You can specify `g+s' and `g-s' to add or remove the Unix set-
5318           group-ID bit. On a file, this works similarly to the set-user-
5319           ID bit (see your Unix documentation again); on a directory it
5320           ensures that files created in the directory are accessible by
5321           members of the group that owns the directory.
5322
5323        -  You can specify `+t' and `-t' to add or remove the Unix `sticky
5324           bit'. When applied to a directory, this means that the owner of
5325           a file in that directory can delete the file (whereas normally
5326           only the owner of the _directory_ would be allowed to).
5327
53286.2.15 The `del' command: delete remote files
5329
5330       To delete a file on the server, type `del' and then the filename or
5331       filenames:
5332
5333         del oldfile.dat
5334         del file1.txt file2.txt
5335         del *.o
5336
5337       Files will be deleted without further prompting, even if multiple
5338       files are specified.
5339
5340       `del' will only delete files. You cannot use it to delete
5341       directories; use `rmdir' for that.
5342
5343       The `rm' command works exactly the same way as `del'.
5344
53456.2.16 The `mkdir' command: create remote directories
5346
5347       To create a directory on the server, type `mkdir' and then the
5348       directory name:
5349
5350         mkdir newstuff
5351
5352       You can specify multiple directories to create at once:
5353
5354         mkdir dir1 dir2 dir3
5355
53566.2.17 The `rmdir' command: remove remote directories
5357
5358       To remove a directory on the server, type `rmdir' and then the
5359       directory name or names:
5360
5361         rmdir oldstuff
5362         rmdir *.old ancient
5363
5364       Directories will be deleted without further prompting, even if
5365       multiple directories are specified.
5366
5367       Most SFTP servers will probably refuse to remove a directory if
5368       the directory has anything in it, so you will need to delete the
5369       contents first.
5370
53716.2.18 The `mv' command: move and rename remote files
5372
5373       To rename a single file on the server, type `mv', then the current
5374       file name, and then the new file name:
5375
5376         mv oldfile newname
5377
5378       You can also move the file into a different directory and change the
5379       name:
5380
5381         mv oldfile dir/newname
5382
5383       To move one or more files into an existing subdirectory, specify
5384       the files (using wildcards if desired), and then the destination
5385       directory:
5386
5387         mv file dir
5388         mv file1 dir1/file2 dir2
5389         mv *.c *.h ..
5390
5391       The `rename' and `ren' commands work exactly the same way as `mv'.
5392
53936.2.19 The `!' command: run a local Windows command
5394
5395       You can run local Windows commands using the `!' command. This is
5396       the only PSFTP command that is not subject to the command quoting
5397       rules given in section 6.2.1. If any command line begins with the
5398       `!' character, then the rest of the line will be passed straight to
5399       Windows without further translation.
5400
5401       For example, if you want to move an existing copy of a file out of
5402       the way before downloading an updated version, you might type:
5403
5404         psftp> !ren myfile.dat myfile.bak
5405         psftp> get myfile.dat
5406
5407       using the Windows `ren' command to rename files on your local PC.
5408
5409   6.3 Using public key authentication with PSFTP
5410
5411       Like PuTTY, PSFTP can authenticate using a public key instead of a
5412       password. There are three ways you can do this.
5413
5414       Firstly, PSFTP can use PuTTY saved sessions in place of hostnames.
5415       So you might do this:
5416
5417        -  Run PuTTY, and create a PuTTY saved session (see section 4.1.2)
5418           which specifies your private key file (see section 4.22.8). You
5419           will probably also want to specify a username to log in as (see
5420           section 4.14.1).
5421
5422        -  In PSFTP, you can now use the name of the session instead of
5423           a hostname: type `psftp sessionname', where `sessionname' is
5424           replaced by the name of your saved session.
5425
5426       Secondly, you can supply the name of a private key file on the
5427       command line, with the `-i' option. See section 3.8.3.18 for more
5428       information.
5429
5430       Thirdly, PSFTP will attempt to authenticate using Pageant if Pageant
5431       is running (see chapter 9). So you would do this:
5432
5433        -  Ensure Pageant is running, and has your private key stored in
5434           it.
5435
5436        -  Specify a user and host name to PSFTP as normal. PSFTP will
5437           automatically detect Pageant and try to use the keys within it.
5438
5439       For more general information on public-key authentication, see
5440       chapter 8.
5441
5442Chapter 7: Using the command-line connection tool Plink
5443-------------------------------------------------------
5444
5445       Plink is a command-line connection tool similar to UNIX `ssh'. It is
5446       mostly used for automated operations, such as making CVS access a
5447       repository on a remote server.
5448
5449       Plink is probably not what you want if you want to run an
5450       interactive session in a console window.
5451
5452   7.1 Starting Plink
5453
5454       Plink is a command line application. This means that you cannot just
5455       double-click on its icon to run it and instead you have to bring
5456       up a console window. In Windows 95, 98, and ME, this is called an
5457       `MS-DOS Prompt', and in Windows NT, 2000, and XP, it is called a
5458       `Command Prompt'. It should be available from the Programs section
5459       of your Start Menu.
5460
5461       In order to use Plink, the file `plink.exe' will need either to be
5462       on your `PATH' or in your current directory. To add the directory
5463       containing Plink to your `PATH' environment variable, type into the
5464       console window:
5465
5466         set PATH=C:\path\to\putty\directory;%PATH%
5467
5468       This will only work for the lifetime of that particular console
5469       window. To set your `PATH' more permanently on Windows NT, 2000, and
5470       XP, use the Environment tab of the System Control Panel. On Windows
5471       95, 98, and ME, you will need to edit your `AUTOEXEC.BAT' to include
5472       a `set' command like the one above.
5473
5474   7.2 Using Plink
5475
5476       This section describes the basics of how to use Plink for
5477       interactive logins and for automated processes.
5478
5479       Once you've got a console window to type into, you can just type
5480       `plink' on its own to bring up a usage message. This tells you the
5481       version of Plink you're using, and gives you a brief summary of how
5482       to use Plink:
5483
5484         Z:\sysosd>plink
5485         Plink: command-line connection utility
5486         Release 0.70
5487         Usage: plink [options] [user@]host [command]
5488                ("host" can also be a PuTTY saved session name)
5489         Options:
5490           -V        print version information and exit
5491           -pgpfp    print PGP key fingerprints and exit
5492           -v        show verbose messages
5493           -load sessname  Load settings from saved session
5494           -ssh -telnet -rlogin -raw -serial
5495                     force use of a particular protocol
5496           -P port   connect to specified port
5497           -l user   connect with specified username
5498           -batch    disable all interactive prompts
5499           -proxycmd command
5500                     use 'command' as local proxy
5501           -sercfg configuration-string (e.g. 19200,8,n,1,X)
5502                     Specify the serial configuration (serial only)
5503         The following options only apply to SSH connections:
5504           -pw passw login with specified password
5505           -D [listen-IP:]listen-port
5506                     Dynamic SOCKS-based port forwarding
5507           -L [listen-IP:]listen-port:host:port
5508                     Forward local port to remote address
5509           -R [listen-IP:]listen-port:host:port
5510                     Forward remote port to local address
5511           -X -x     enable / disable X11 forwarding
5512           -A -a     enable / disable agent forwarding
5513           -t -T     enable / disable pty allocation
5514           -1 -2     force use of particular protocol version
5515           -4 -6     force use of IPv4 or IPv6
5516           -C        enable compression
5517           -i key    private key file for user authentication
5518           -noagent  disable use of Pageant
5519           -agent    enable use of Pageant
5520           -hostkey aa:bb:cc:...
5521                     manually specify a host key (may be repeated)
5522           -m file   read remote command(s) from file
5523           -s        remote command is an SSH subsystem (SSH-2 only)
5524           -N        don't start a shell/command (SSH-2 only)
5525           -nc host:port
5526                     open tunnel in place of session (SSH-2 only)
5527           -sshlog file
5528           -sshrawlog file
5529                     log protocol details to a file
5530           -shareexists
5531                     test whether a connection-sharing upstream exists
5532
5533       Once this works, you are ready to use Plink.
5534
5535 7.2.1 Using Plink for interactive logins
5536
5537       To make a simple interactive connection to a remote server, just
5538       type `plink' and then the host name:
5539
5540         Z:\sysosd>plink login.example.com
5541         
5542         Debian GNU/Linux 2.2 flunky.example.com
5543         flunky login:
5544
5545       You should then be able to log in as normal and run a session. The
5546       output sent by the server will be written straight to your command
5547       prompt window, which will most likely not interpret terminal control
5548       codes in the way the server expects it to. So if you run any full-
5549       screen applications, for example, you can expect to see strange
5550       characters appearing in your window. Interactive connections like
5551       this are not the main point of Plink.
5552
5553       In order to connect with a different protocol, you can give the
5554       command line options `-ssh', `-telnet', `-rlogin' or `-raw'. To make
5555       an SSH connection, for example:
5556
5557         Z:\sysosd>plink -ssh login.example.com
5558         login as:
5559
5560       If you have already set up a PuTTY saved session, then instead of
5561       supplying a host name, you can give the saved session name. This
5562       allows you to use public-key authentication, specify a user name,
5563       and use most of the other features of PuTTY:
5564
5565         Z:\sysosd>plink my-ssh-session
5566         Sent username "fred"
5567         Authenticating with public key "fred@winbox"
5568         Last login: Thu Dec  6 19:25:33 2001 from :0.0
5569         fred@flunky:~$
5570
5571       (You can also use the `-load' command-line option to load a saved
5572       session; see section 3.8.3.1. If you use `-load', the saved session
5573       exists, and it specifies a hostname, you cannot also specify a
5574       `host' or `user@host' argument - it will be treated as part of the
5575       remote command.)
5576
5577 7.2.2 Using Plink for automated connections
5578
5579       More typically Plink is used with the SSH protocol, to enable you
5580       to talk directly to a program running on the server. To do this you
5581       have to ensure Plink is _using_ the SSH protocol. You can do this in
5582       several ways:
5583
5584        -  Use the `-ssh' option as described in section 7.2.1.
5585
5586        -  Set up a PuTTY saved session that describes the server you are
5587           connecting to, and that also specifies the protocol as SSH.
5588
5589        -  Set the Windows environment variable `PLINK_PROTOCOL' to the
5590           word `ssh'.
5591
5592       Usually Plink is not invoked directly by a user, but run
5593       automatically by another process. Therefore you typically do not
5594       want Plink to prompt you for a user name or a password.
5595
5596       Next, you are likely to need to avoid the various interactive
5597       prompts Plink can produce. You might be prompted to verify the host
5598       key of the server you're connecting to, to enter a user name, or to
5599       enter a password.
5600
5601       To avoid being prompted for the server host key when using Plink for
5602       an automated connection, you should first make a _manual_ connection
5603       (using either of PuTTY or Plink) to the same server, verify the host
5604       key (see section 2.2 for more information), and select Yes to add
5605       the host key to the Registry. After that, Plink commands connecting
5606       to that server should not give a host key prompt unless the host key
5607       changes.
5608
5609       To avoid being prompted for a user name, you can:
5610
5611        -  Use the `-l' option to specify a user name on the command line.
5612           For example, `plink login.example.com -l fred'.
5613
5614        -  Set up a PuTTY saved session that describes the server you are
5615           connecting to, and that also specifies the username to log in as
5616           (see section 4.14.1).
5617
5618       To avoid being prompted for a password, you should almost certainly
5619       set up public-key authentication. (See chapter 8 for a general
5620       introduction to public-key authentication.) Again, you can do this
5621       in two ways:
5622
5623        -  Set up a PuTTY saved session that describes the server you
5624           are connecting to, and that also specifies a private key file
5625           (see section 4.22.8). For this to work without prompting, your
5626           private key will need to have no passphrase.
5627
5628        -  Store the private key in Pageant. See chapter 9 for further
5629           information.
5630
5631       Once you have done all this, you should be able to run a remote
5632       command on the SSH server machine and have it execute automatically
5633       with no prompting:
5634
5635         Z:\sysosd>plink login.example.com -l fred echo hello, world
5636         hello, world
5637         
5638         Z:\sysosd>
5639
5640       Or, if you have set up a saved session with all the connection
5641       details:
5642
5643         Z:\sysosd>plink mysession echo hello, world
5644         hello, world
5645         
5646         Z:\sysosd>
5647
5648       Then you can set up other programs to run this Plink command and
5649       talk to it as if it were a process on the server machine.
5650
5651 7.2.3 Plink command line options
5652
5653       Plink accepts all the general command line options supported by the
5654       PuTTY tools. See section 3.8.3 for a description of these options.
5655
5656       Plink also supports some of its own options. The following sections
5657       describe Plink's specific command-line options.
5658
56597.2.3.1 `-batch': disable all interactive prompts
5660
5661       If you use the `-batch' option, Plink will never give an interactive
5662       prompt while establishing the connection. If the server's host key
5663       is invalid, for example (see section 2.2), then the connection will
5664       simply be abandoned instead of asking you what to do next.
5665
5666       This may help Plink's behaviour when it is used in automated
5667       scripts: using `-batch', if something goes wrong at connection time,
5668       the batch job will fail rather than hang.
5669
56707.2.3.2 `-s': remote command is SSH subsystem
5671
5672       If you specify the `-s' option, Plink passes the specified command
5673       as the name of an SSH `subsystem' rather than an ordinary command
5674       line.
5675
5676       (This option is only meaningful with the SSH-2 protocol.)
5677
56787.2.3.3 `-shareexists': test for connection-sharing upstream
5679
5680       This option does not make a new connection; instead it allows
5681       testing for the presence of an existing connection that can
5682       be shared. (See section 4.18.5 for more information about SSH
5683       connection sharing.)
5684
5685       A Plink invocation of the form:
5686
5687         plink -shareexists <session>
5688
5689       will test whether there is currently a viable `upstream' for the
5690       session in question, which can be specified using any syntax you'd
5691       normally use with Plink to make an actual connection (a host/port
5692       number, a bare saved session name, `-load', etc). It returns a zero
5693       exit status if a usable `upstream' exists, nonzero otherwise.
5694
5695       (This option is only meaningful with the SSH-2 protocol.)
5696
5697   7.3 Using Plink in batch files and scripts
5698
5699       Once you have set up Plink to be able to log in to a remote server
5700       without any interactive prompting (see section 7.2.2), you can use
5701       it for lots of scripting and batch purposes. For example, to start a
5702       backup on a remote machine, you might use a command like:
5703
5704         plink root@myserver /etc/backups/do-backup.sh
5705
5706       Or perhaps you want to fetch all system log lines relating to a
5707       particular web area:
5708
5709         plink mysession grep /~fred/ /var/log/httpd/access.log > fredlog
5710
5711       Any non-interactive command you could usefully run on the server
5712       command line, you can run in a batch file using Plink in this way.
5713
5714   7.4 Using Plink with CVS
5715
5716       To use Plink with CVS, you need to set the environment variable
5717       `CVS_RSH' to point to Plink:
5718
5719         set CVS_RSH=\path\to\plink.exe
5720
5721       You also need to arrange to be able to connect to a remote host
5722       without any interactive prompts, as described in section 7.2.2.
5723
5724       You should then be able to run CVS as follows:
5725
5726         cvs -d :ext:user@sessionname:/path/to/repository co module
5727
5728       If you specified a username in your saved session, you don't even
5729       need to specify the `user' part of this, and you can just say:
5730
5731         cvs -d :ext:sessionname:/path/to/repository co module
5732
5733   7.5 Using Plink with WinCVS
5734
5735       Plink can also be used with WinCVS. Firstly, arrange for Plink to be
5736       able to connect to a remote host non-interactively, as described in
5737       section 7.2.2.
5738
5739       Then, in WinCVS, bring up the `Preferences' dialogue box from the
5740       _Admin_ menu, and switch to the `Ports' tab. Tick the box there
5741       labelled `Check for an alternate rsh name' and in the text entry
5742       field to the right enter the full path to `plink.exe'. Select `OK'
5743       on the `Preferences' dialogue box.
5744
5745       Next, select `Command Line' from the WinCVS `Admin' menu, and type a
5746       CVS command as in section 7.4, for example:
5747
5748         cvs -d :ext:user@hostname:/path/to/repository co module
5749
5750       or (if you're using a saved session):
5751
5752         cvs -d :ext:user@sessionname:/path/to/repository co module
5753
5754       Select the folder you want to check out to with the `Change Folder'
5755       button, and click `OK' to check out your module. Once you've got
5756       modules checked out, WinCVS will happily invoke plink from the GUI
5757       for CVS operations.
5758
5759Chapter 8: Using public keys for SSH authentication
5760---------------------------------------------------
5761
5762   8.1 Public key authentication - an introduction
5763
5764       Public key authentication is an alternative means of identifying
5765       yourself to a login server, instead of typing a password. It is more
5766       secure and more flexible, but more difficult to set up.
5767
5768       In conventional password authentication, you prove you are who you
5769       claim to be by proving that you know the correct password. The
5770       only way to prove you know the password is to tell the server what
5771       you think the password is. This means that if the server has been
5772       hacked, or _spoofed_ (see section 2.2), an attacker can learn your
5773       password.
5774
5775       Public key authentication solves this problem. You generate a _key
5776       pair_, consisting of a public key (which everybody is allowed to
5777       know) and a private key (which you keep secret and do not give
5778       to anybody). The private key is able to generate _signatures_. A
5779       signature created using your private key cannot be forged by anybody
5780       who does not have that key; but anybody who has your public key can
5781       verify that a particular signature is genuine.
5782
5783       So you generate a key pair on your own computer, and you copy the
5784       public key to the server. Then, when the server asks you to prove
5785       who you are, PuTTY can generate a signature using your private key.
5786       The server can verify that signature (since it has your public key)
5787       and allow you to log in. Now if the server is hacked or spoofed, the
5788       attacker does not gain your private key or password; they only gain
5789       one signature. And signatures cannot be re-used, so they have gained
5790       nothing.
5791
5792       There is a problem with this: if your private key is stored
5793       unprotected on your own computer, then anybody who gains access to
5794       _that_ will be able to generate signatures as if they were you. So
5795       they will be able to log in to your server under your account. For
5796       this reason, your private key is usually _encrypted_ when it is
5797       stored on your local machine, using a passphrase of your choice. In
5798       order to generate a signature, PuTTY must decrypt the key, so you
5799       have to type your passphrase.
5800
5801       This can make public-key authentication less convenient than
5802       password authentication: every time you log in to the server,
5803       instead of typing a short password, you have to type a longer
5804       passphrase. One solution to this is to use an _authentication
5805       agent_, a separate program which holds decrypted private keys and
5806       generates signatures on request. PuTTY's authentication agent is
5807       called Pageant. When you begin a Windows session, you start Pageant
5808       and load your private key into it (typing your passphrase once).
5809       For the rest of your session, you can start PuTTY any number of
5810       times and Pageant will automatically generate signatures without you
5811       having to do anything. When you close your Windows session, Pageant
5812       shuts down, without ever having stored your decrypted private key on
5813       disk. Many people feel this is a good compromise between security
5814       and convenience. See chapter 9 for further details.
5815
5816       There is more than one public-key algorithm available. The most
5817       common are RSA and ECDSA, but others exist, notably DSA (otherwise
5818       known as DSS), the USA's federal Digital Signature Standard. The key
5819       types supported by PuTTY are described in section 8.2.2.
5820
5821   8.2 Using PuTTYgen, the PuTTY key generator
5822
5823       PuTTYgen is a key generator. It generates pairs of public and
5824       private keys to be used with PuTTY, PSCP, and Plink, as well as
5825       the PuTTY authentication agent, Pageant (see chapter 9). PuTTYgen
5826       generates RSA, DSA, ECDSA, and Ed25519 keys.
5827
5828       When you run PuTTYgen you will see a window where you have two
5829       choices: `Generate', to generate a new public/private key pair, or
5830       `Load' to load in an existing private key.
5831
5832 8.2.1 Generating a new key
5833
5834       This is a general outline of the procedure for generating a new key
5835       pair. The following sections describe the process in more detail.
5836
5837        -  First, you need to select which type of key you want to
5838           generate, and also select the strength of the key. This is
5839           described in more detail in section 8.2.2 and section 8.2.3.
5840
5841        -  Then press the `Generate' button, to actually generate the key.
5842           Section 8.2.4 describes this step.
5843
5844        -  Once you have generated the key, select a comment field (section
5845           8.2.6) and a passphrase (section 8.2.7).
5846
5847        -  Now you're ready to save the private key to disk; press the
5848           `Save private key' button. (See section 8.2.8).
5849
5850       Your key pair is now ready for use. You may also want to copy the
5851       public key to your server, either by copying it out of the `Public
5852       key for pasting into authorized_keys file' box (see section 8.2.10),
5853       or by using the `Save public key' button (section 8.2.9). However,
5854       you don't need to do this immediately; if you want, you can load the
5855       private key back into PuTTYgen later (see section 8.2.11) and the
5856       public key will be available for copying and pasting again.
5857
5858       Section 8.3 describes the typical process of configuring PuTTY to
5859       attempt public-key authentication, and configuring your SSH server
5860       to accept it.
5861
5862 8.2.2 Selecting the type of key
5863
5864       Before generating a key pair using PuTTYgen, you need to select
5865       which type of key you need. PuTTYgen currently supports these types
5866       of key:
5867
5868        -  An RSA key for use with the SSH-1 protocol.
5869
5870        -  An RSA key for use with the SSH-2 protocol.
5871
5872        -  A DSA key for use with the SSH-2 protocol.
5873
5874        -  An ECDSA (elliptic curve DSA) key for use with the SSH-2
5875           protocol.
5876
5877        -  An Ed25519 key (another elliptic curve algorithm) for use with
5878           the SSH-2 protocol.
5879
5880       The SSH-1 protocol only supports RSA keys; if you will be connecting
5881       using the SSH-1 protocol, you must select the first key type or your
5882       key will be completely useless.
5883
5884       The SSH-2 protocol supports more than one key type. The types
5885       supported by PuTTY are RSA, DSA, ECDSA, and Ed25519.
5886
5887 8.2.3 Selecting the size (strength) of the key
5888
5889       The `Number of bits' input box allows you to choose the strength of
5890       the key PuTTYgen will generate.
5891
5892        -  For RSA, 2048 bits should currently be sufficient for most
5893           purposes.
5894
5895        -  For ECDSA, only 256, 384, and 521 bits are supported. (ECDSA
5896           offers equivalent security to RSA with smaller key sizes.)
5897
5898        -  For Ed25519, the only valid size is 256 bits.
5899
5900 8.2.4 The `Generate' button
5901
5902       Once you have chosen the type of key you want, and the strength of
5903       the key, press the `Generate' button and PuTTYgen will begin the
5904       process of actually generating the key.
5905
5906       First, a progress bar will appear and PuTTYgen will ask you to move
5907       the mouse around to generate randomness. Wave the mouse in circles
5908       over the blank area in the PuTTYgen window, and the progress bar
5909       will gradually fill up as PuTTYgen collects enough randomness. You
5910       don't need to wave the mouse in particularly imaginative patterns
5911       (although it can't hurt); PuTTYgen will collect enough randomness
5912       just from the fine detail of _exactly_ how far the mouse has moved
5913       each time Windows samples its position.
5914
5915       When the progress bar reaches the end, PuTTYgen will begin creating
5916       the key. The progress bar will reset to the start, and gradually
5917       move up again to track the progress of the key generation. It will
5918       not move evenly, and may occasionally slow down to a stop; this
5919       is unfortunately unavoidable, because key generation is a random
5920       process and it is impossible to reliably predict how long it will
5921       take.
5922
5923       When the key generation is complete, a new set of controls will
5924       appear in the window to indicate this.
5925
5926 8.2.5 The `Key fingerprint' box
5927
5928       The `Key fingerprint' box shows you a fingerprint value for the
5929       generated key. This is derived cryptographically from the _public_
5930       key value, so it doesn't need to be kept secret; it is supposed to
5931       be more manageable for human beings than the public key itself.
5932
5933       The fingerprint value is intended to be cryptographically secure,
5934       in the sense that it is computationally infeasible for someone to
5935       invent a second key with the same fingerprint, or to find a key with
5936       a particular fingerprint. So some utilities, such as the Pageant key
5937       list box (see section 9.2.1) and the Unix `ssh-add' utility, will
5938       list key fingerprints rather than the whole public key.
5939
5940 8.2.6 Setting a comment for your key
5941
5942       If you have more than one key and use them for different purposes,
5943       you don't need to memorise the key fingerprints in order to tell
5944       them apart. PuTTYgen allows you to enter a _comment_ for your key,
5945       which will be displayed whenever PuTTY or Pageant asks you for the
5946       passphrase.
5947
5948       The default comment format, if you don't specify one, contains the
5949       key type and the date of generation, such as `rsa-key-20011212'.
5950       Another commonly used approach is to use your name and the name of
5951       the computer the key will be used on, such as `simon@simons-pc'.
5952
5953       To alter the key comment, just type your comment text into the `Key
5954       comment' box before saving the private key. If you want to change
5955       the comment later, you can load the private key back into PuTTYgen,
5956       change the comment, and save it again.
5957
5958 8.2.7 Setting a passphrase for your key
5959
5960       The `Key passphrase' and `Confirm passphrase' boxes allow you to
5961       choose a passphrase for your key. The passphrase will be used to
5962       encrypt the key on disk, so you will not be able to use the key
5963       without first entering the passphrase.
5964
5965       When you save the key, PuTTYgen will check that the `Key passphrase'
5966       and `Confirm passphrase' boxes both contain exactly the same
5967       passphrase, and will refuse to save the key otherwise.
5968
5969       If you leave the passphrase fields blank, the key will be saved
5970       unencrypted. You should _not_ do this without good reason; if you
5971       do, your private key file on disk will be all an attacker needs to
5972       gain access to any machine configured to accept that key. If you
5973       want to be able to log in without having to type a passphrase every
5974       time, you should consider using Pageant (chapter 9) so that your
5975       decrypted key is only held in memory rather than on disk.
5976
5977       Under special circumstances you may genuinely _need_ to use a key
5978       with no passphrase; for example, if you need to run an automated
5979       batch script that needs to make an SSH connection, you can't be
5980       there to type the passphrase. In this case we recommend you generate
5981       a special key for each specific batch script (or whatever) that
5982       needs one, and on the server side you should arrange that each
5983       key is _restricted_ so that it can only be used for that specific
5984       purpose. The documentation for your SSH server should explain how to
5985       do this (it will probably vary between servers).
5986
5987       Choosing a good passphrase is difficult. Just as you shouldn't use
5988       a dictionary word as a password because it's easy for an attacker
5989       to run through a whole dictionary, you should not use a song
5990       lyric, quotation or other well-known sentence as a passphrase.
5991       DiceWare (www.diceware.com) recommends using at least five words
5992       each generated randomly by rolling five dice, which gives over
5993       2^64 possible passphrases and is probably not a bad scheme. If you
5994       want your passphrase to make grammatical sense, this cuts down the
5995       possibilities a lot and you should use a longer one as a result.
5996
5997       _Do not forget your passphrase_. There is no way to recover it.
5998
5999 8.2.8 Saving your private key to a disk file
6000
6001       Once you have generated a key, set a comment field and set a
6002       passphrase, you are ready to save your private key to disk.
6003
6004       Press the `Save private key' button. PuTTYgen will put up a dialog
6005       box asking you where to save the file. Select a directory, type in a
6006       file name, and press `Save'.
6007
6008       This file is in PuTTY's native format (`*.PPK'); it is the one you
6009       will need to tell PuTTY to use for authentication (see section
6010       4.22.8) or tell Pageant to load (see section 9.2.2).
6011
6012 8.2.9 Saving your public key to a disk file
6013
6014       RFC 4716 specifies a standard format for storing SSH-2 public keys
6015       on disk. Some SSH servers (such as ssh.com's) require a public
6016       key in this format in order to accept authentication with the
6017       corresponding private key. (Others, such as OpenSSH, use a different
6018       format; see section 8.2.10.)
6019
6020       To save your public key in the SSH-2 standard format, press the
6021       `Save public key' button in PuTTYgen. PuTTYgen will put up a dialog
6022       box asking you where to save the file. Select a directory, type in a
6023       file name, and press `Save'.
6024
6025       You will then probably want to copy the public key file to your
6026       SSH server machine. See section 8.3 for general instructions on
6027       configuring public-key authentication once you have generated a key.
6028
6029       If you use this option with an SSH-1 key, the file PuTTYgen saves
6030       will contain exactly the same text that appears in the `Public key
6031       for pasting' box. This is the only existing standard for SSH-1
6032       public keys.
6033
60348.2.10 `Public key for pasting into authorized_keys file'
6035
6036       All SSH-1 servers require your public key to be given to it in a
6037       one-line format before it will accept authentication with your
6038       private key. The OpenSSH server also requires this for SSH-2.
6039
6040       The `Public key for pasting into authorized_keys file' gives the
6041       public-key data in the correct one-line format. Typically you will
6042       want to select the entire contents of the box using the mouse, press
6043       Ctrl+C to copy it to the clipboard, and then paste the data into a
6044       PuTTY session which is already connected to the server.
6045
6046       See section 8.3 for general instructions on configuring public-key
6047       authentication once you have generated a key.
6048
60498.2.11 Reloading a private key
6050
6051       PuTTYgen allows you to load an existing private key file into
6052       memory. If you do this, you can then change the passphrase and
6053       comment before saving it again; you can also make extra copies of
6054       the public key.
6055
6056       To load an existing key, press the `Load' button. PuTTYgen will put
6057       up a dialog box where you can browse around the file system and find
6058       your key file. Once you select the file, PuTTYgen will ask you for a
6059       passphrase (if necessary) and will then display the key details in
6060       the same way as if it had just generated the key.
6061
6062       If you use the Load command to load a foreign key format, it will
6063       work, but you will see a message box warning you that the key you
6064       have loaded is not a PuTTY native key. See section 8.2.12 for
6065       information about importing foreign key formats.
6066
60678.2.12 Dealing with private keys in other formats
6068
6069       Most SSH-1 clients use a standard format for storing private keys on
6070       disk. PuTTY uses this format as well; so if you have generated an
6071       SSH-1 private key using OpenSSH or ssh.com's client, you can use it
6072       with PuTTY, and vice versa.
6073
6074       However, SSH-2 private keys have no standard format. OpenSSH and
6075       ssh.com have different formats, and PuTTY's is different again. So
6076       a key generated with one client cannot immediately be used with
6077       another.
6078
6079       Using the `Import' command from the `Conversions' menu, PuTTYgen can
6080       load SSH-2 private keys in OpenSSH's format and ssh.com's format.
6081       Once you have loaded one of these key types, you can then save it
6082       back out as a PuTTY-format key (`*.PPK') so that you can use it with
6083       the PuTTY suite. The passphrase will be unchanged by this process
6084       (unless you deliberately change it). You may want to change the key
6085       comment before you save the key, since OpenSSH's SSH-2 key format
6086       contains no space for a comment and ssh.com's default comment format
6087       is long and verbose.
6088
6089       PuTTYgen can also export private keys in OpenSSH format and in
6090       ssh.com format. To do so, select one of the `Export' options from
6091       the `Conversions' menu. Exporting a key works exactly like saving
6092       it (see section 8.2.8) - you need to have typed your passphrase in
6093       beforehand, and you will be warned if you are about to save a key
6094       without a passphrase.
6095
6096       For OpenSSH there are two options. Modern OpenSSH actually has two
6097       formats it uses for storing private keys. `Export OpenSSH key' will
6098       automatically choose the oldest format supported for the key type,
6099       for maximum backward compatibility with older versions of OpenSSH;
6100       for newer key types like Ed25519, it will use the newer format as
6101       that is the only legal option. If you have some specific reason for
6102       wanting to use OpenSSH's newer format even for RSA, DSA, or ECDSA
6103       keys, you can choose `Export OpenSSH key (force new file format)'.
6104
6105       Note that since only SSH-2 keys come in different formats, the
6106       export options are not available if you have generated an SSH-1 key.
6107
6108   8.3 Getting ready for public key authentication
6109
6110       Connect to your SSH server using PuTTY with the SSH protocol. When
6111       the connection succeeds you will be prompted for your user name and
6112       password to login. Once logged in, you must configure the server to
6113       accept your public key for authentication:
6114
6115        -  If your server is using the SSH-1 protocol, you should change
6116           into the `.ssh' directory and open the file `authorized_keys'
6117           with your favourite editor. (You may have to create this file if
6118           this is the first key you have put in it). Then switch to the
6119           PuTTYgen window, select all of the text in the `Public key for
6120           pasting into authorized_keys file' box (see section 8.2.10), and
6121           copy it to the clipboard (`Ctrl+C'). Then, switch back to the
6122           PuTTY window and insert the data into the open file, making sure
6123           it ends up all on one line. Save the file.
6124
6125        -  If your server is OpenSSH and is using the SSH-2 protocol,
6126           you should follow the same instructions, except that
6127           in earlier versions of OpenSSH 2 the file might be
6128           called `authorized_keys2'. (In modern versions the same
6129           `authorized_keys' file is used for both SSH-1 and SSH-2 keys.)
6130
6131        -  If your server is ssh.com's product and is using SSH-2, you need
6132           to save a _public_ key file from PuTTYgen (see section 8.2.9),
6133           and copy that into the `.ssh2' directory on the server. Then you
6134           should go into that `.ssh2' directory, and edit (or create) a
6135           file called `authorization'. In this file you should put a line
6136           like `Key mykey.pub', with `mykey.pub' replaced by the name of
6137           your key file.
6138
6139        -  For other SSH server software, you should refer to the manual
6140           for that server.
6141
6142       You may also need to ensure that your home directory, your `.ssh'
6143       directory, and any other files involved (such as `authorized_keys',
6144       `authorized_keys2' or `authorization') are not group-writable or
6145       world-writable. You can typically do this by using a command such as
6146
6147         chmod go-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys
6148
6149       Your server should now be configured to accept authentication using
6150       your private key. Now you need to configure PuTTY to _attempt_
6151       authentication using your private key. You can do this in any of
6152       three ways:
6153
6154        -  Select the private key in PuTTY's configuration. See section
6155           4.22.8 for details.
6156
6157        -  Specify the key file on the command line with the `-i' option.
6158           See section 3.8.3.18 for details.
6159
6160        -  Load the private key into Pageant (see chapter 9). In this case
6161           PuTTY will automatically try to use it for authentication if it
6162           can.
6163
6164Chapter 9: Using Pageant for authentication
6165-------------------------------------------
6166
6167       Pageant is an SSH authentication agent. It holds your private keys
6168       in memory, already decoded, so that you can use them often without
6169       needing to type a passphrase.
6170
6171   9.1 Getting started with Pageant
6172
6173       Before you run Pageant, you need to have a private key in `*.PPK'
6174       format. See chapter 8 to find out how to generate and use one.
6175
6176       When you run Pageant, it will put an icon of a computer wearing a
6177       hat into the System tray. It will then sit and do nothing, until you
6178       load a private key into it.
6179
6180       If you click the Pageant icon with the right mouse button, you will
6181       see a menu. Select `View Keys' from this menu. The Pageant main
6182       window will appear. (You can also bring this window up by double-
6183       clicking on the Pageant icon.)
6184
6185       The Pageant window contains a list box. This shows the private keys
6186       Pageant is holding. When you start Pageant, it has no keys, so the
6187       list box will be empty. After you add one or more keys, they will
6188       show up in the list box.
6189
6190       To add a key to Pageant, press the `Add Key' button. Pageant will
6191       bring up a file dialog, labelled `Select Private Key File'. Find
6192       your private key file in this dialog, and press `Open'.
6193
6194       Pageant will now load the private key. If the key is protected by
6195       a passphrase, Pageant will ask you to type the passphrase. When
6196       the key has been loaded, it will appear in the list in the Pageant
6197       window.
6198
6199       Now start PuTTY and open an SSH session to a site that accepts your
6200       key. PuTTY will notice that Pageant is running, retrieve the key
6201       automatically from Pageant, and use it to authenticate. You can now
6202       open as many PuTTY sessions as you like without having to type your
6203       passphrase again.
6204
6205       (PuTTY can be configured not to try to use Pageant, but it will
6206       try by default. See section 4.22.3 and section 3.8.3.9 for more
6207       information.)
6208
6209       When you want to shut down Pageant, click the right button on the
6210       Pageant icon in the System tray, and select `Exit' from the menu.
6211       Closing the Pageant main window does _not_ shut down Pageant.
6212
6213   9.2 The Pageant main window
6214
6215       The Pageant main window appears when you left-click on the Pageant
6216       system tray icon, or alternatively right-click and select `View
6217       Keys' from the menu. You can use it to keep track of what keys are
6218       currently loaded into Pageant, and to add new ones or remove the
6219       existing keys.
6220
6221 9.2.1 The key list box
6222
6223       The large list box in the Pageant main window lists the private
6224       keys that are currently loaded into Pageant. The list might look
6225       something like this:
6226
6227         ssh-rsa 2048 22:d6:69:c9:22:51:ac:cb:b9:15:67:47:f7:65:6d:d7 k1
6228         ssh-dss 2048 e4:6c:69:f3:4f:fc:cf:fc:96:c0:88:34:a7:1e:59:d7 k2
6229
6230       For each key, the list box will tell you:
6231
6232        -  The type of the key. Currently, this can be `ssh1' (an RSA key
6233           for use with the SSH-1 protocol), `ssh-rsa' (an RSA key for use
6234           with the SSH-2 protocol), `ssh-dss' (a DSA key for use with the
6235           SSH-2 protocol), `ecdsa-sha2-*' (an ECDSA key for use with the
6236           SSH-2 protocol), or `ssh-ed25519' (an Ed25519 key for use with
6237           the SSH-2 protocol).
6238
6239        -  The size (in bits) of the key.
6240
6241        -  The fingerprint for the public key. This should be the same
6242           fingerprint given by PuTTYgen, and (hopefully) also the same
6243           fingerprint shown by remote utilities such as `ssh-keygen' when
6244           applied to your `authorized_keys' file.
6245
6246        -  The comment attached to the key.
6247
6248 9.2.2 The `Add Key' button
6249
6250       To add a key to Pageant by reading it out of a local disk file,
6251       press the `Add Key' button in the Pageant main window, or
6252       alternatively right-click on the Pageant icon in the system tray and
6253       select `Add Key' from there.
6254
6255       Pageant will bring up a file dialog, labelled `Select Private Key
6256       File'. Find your private key file in this dialog, and press `Open'.
6257       If you want to add more than one key at once, you can select
6258       multiple files using Shift-click (to select several adjacent files)
6259       or Ctrl-click (to select non-adjacent files).
6260
6261       Pageant will now load the private key(s). If a key is protected by a
6262       passphrase, Pageant will ask you to type the passphrase.
6263
6264       (This is not the only way to add a private key to Pageant. You can
6265       also add one from a remote system by using agent forwarding; see
6266       section 9.4 for details.)
6267
6268 9.2.3 The `Remove Key' button
6269
6270       If you need to remove a key from Pageant, select that key in the
6271       list box, and press the `Remove Key' button. Pageant will remove the
6272       key from its memory.
6273
6274       You can apply this to keys you added using the `Add Key' button, or
6275       to keys you added remotely using agent forwarding (see section 9.4);
6276       it makes no difference.
6277
6278   9.3 The Pageant command line
6279
6280       Pageant can be made to do things automatically when it starts up,
6281       by specifying instructions on its command line. If you're starting
6282       Pageant from the Windows GUI, you can arrange this by editing the
6283       properties of the Windows shortcut that it was started from.
6284
6285       If Pageant is already running, invoking it again with the options
6286       below causes actions to be performed with the existing instance, not
6287       a new one.
6288
6289 9.3.1 Making Pageant automatically load keys on startup
6290
6291       Pageant can automatically load one or more private keys when it
6292       starts up, if you provide them on the Pageant command line. Your
6293       command line might then look like:
6294
6295         C:\PuTTY\pageant.exe d:\main.ppk d:\secondary.ppk
6296
6297       If the keys are stored encrypted, Pageant will request the
6298       passphrases on startup.
6299
6300       If Pageant is already running, this syntax loads keys into the
6301       existing Pageant.
6302
6303 9.3.2 Making Pageant run another program
6304
6305       You can arrange for Pageant to start another program once it has
6306       initialised itself and loaded any keys specified on its command
6307       line. This program (perhaps a PuTTY, or a WinCVS making use of
6308       Plink, or whatever) will then be able to use the keys Pageant has
6309       loaded.
6310
6311       You do this by specifying the `-c' option followed by the command,
6312       like this:
6313
6314         C:\PuTTY\pageant.exe d:\main.ppk -c C:\PuTTY\putty.exe
6315
6316   9.4 Using agent forwarding
6317
6318       Agent forwarding is a mechanism that allows applications on your SSH
6319       server machine to talk to the agent on your client machine.
6320
6321       Note that at present, agent forwarding in SSH-2 is only available
6322       when your SSH server is OpenSSH. The ssh.com server uses a different
6323       agent protocol, which PuTTY does not yet support.
6324
6325       To enable agent forwarding, first start Pageant. Then set up a
6326       PuTTY SSH session in which `Allow agent forwarding' is enabled (see
6327       section 4.22.6). Open the session as normal. (Alternatively, you can
6328       use the `-A' command line option; see section 3.8.3.10 for details.)
6329
6330       If this has worked, your applications on the server should now have
6331       access to a Unix domain socket which the SSH server will forward
6332       back to PuTTY, and PuTTY will forward on to the agent. To check that
6333       this has actually happened, you can try this command on Unix server
6334       machines:
6335
6336         unixbox:~$ echo $SSH_AUTH_SOCK
6337         /tmp/ssh-XXNP18Jz/agent.28794
6338         unixbox:~$
6339
6340       If the result line comes up blank, agent forwarding has not been
6341       enabled at all.
6342
6343       Now if you run `ssh' on the server and use it to connect through to
6344       another server that accepts one of the keys in Pageant, you should
6345       be able to log in without a password:
6346
6347         unixbox:~$ ssh -v otherunixbox
6348         [...]
6349         debug: next auth method to try is publickey
6350         debug: userauth_pubkey_agent: trying agent key my-putty-key
6351         debug: ssh-userauth2 successful: method publickey
6352         [...]
6353
6354       If you enable agent forwarding on _that_ SSH connection as well (see
6355       the manual for your server-side SSH client to find out how to do
6356       this), your authentication keys will still be available on the next
6357       machine you connect to - two SSH connections away from where they're
6358       actually stored.
6359
6360       In addition, if you have a private key on one of the SSH servers,
6361       you can send it all the way back to Pageant using the local `ssh-
6362       add' command:
6363
6364         unixbox:~$ ssh-add ~/.ssh/id_rsa
6365         Need passphrase for /home/fred/.ssh/id_rsa
6366         Enter passphrase for /home/fred/.ssh/id_rsa:
6367         Identity added: /home/fred/.ssh/id_rsa (/home/simon/.ssh/id_rsa)
6368         unixbox:~$
6369
6370       and then it's available to every machine that has agent forwarding
6371       available (not just the ones downstream of the place you added it).
6372
6373   9.5 Security considerations
6374
6375       Using Pageant for public-key authentication gives you the
6376       convenience of being able to open multiple SSH sessions without
6377       having to type a passphrase every time, but also gives you the
6378       security benefit of never storing a decrypted private key on disk.
6379       Many people feel this is a good compromise between security and
6380       convenience.
6381
6382       It _is_ a compromise, however. Holding your decrypted private keys
6383       in Pageant is better than storing them in easy-to-find disk files,
6384       but still less secure than not storing them anywhere at all. This is
6385       for two reasons:
6386
6387        -  Windows unfortunately provides no way to protect pieces of
6388           memory from being written to the system swap file. So if Pageant
6389           is holding your private keys for a long period of time, it's
6390           possible that decrypted private key data may be written to the
6391           system swap file, and an attacker who gained access to your hard
6392           disk later on might be able to recover that data. (However,
6393           if you stored an unencrypted key in a disk file they would
6394           _certainly_ be able to recover it.)
6395
6396        -  Although, like most modern operating systems, Windows prevents
6397           programs from accidentally accessing one another's memory space,
6398           it does allow programs to access one another's memory space
6399           deliberately, for special purposes such as debugging. This means
6400           that if you allow a virus, trojan, or other malicious program
6401           on to your Windows system while Pageant is running, it could
6402           access the memory of the Pageant process, extract your decrypted
6403           authentication keys, and send them back to its master.
6404
6405       Similarly, use of agent _forwarding_ is a security improvement on
6406       other methods of one-touch authentication, but not perfect. Holding
6407       your keys in Pageant on your Windows box has a security advantage
6408       over holding them on the remote server machine itself (either in an
6409       agent or just unencrypted on disk), because if the server machine
6410       ever sees your unencrypted private key then the sysadmin or anyone
6411       who cracks the machine can steal the keys and pretend to be you for
6412       as long as they want.
6413
6414       However, the sysadmin of the server machine can always pretend to
6415       be you _on that machine_. So if you forward your agent to a server
6416       machine, then the sysadmin of that machine can access the forwarded
6417       agent connection and request signatures from any of your private
6418       keys, and can therefore log in to other machines as you. They
6419       can only do this to a limited extent - when the agent forwarding
6420       disappears they lose the ability - but using Pageant doesn't
6421       actually _prevent_ the sysadmin (or hackers) on the server from
6422       doing this.
6423
6424       Therefore, if you don't trust the sysadmin of a server machine, you
6425       should _never_ use agent forwarding to that machine. (Of course you
6426       also shouldn't store private keys on that machine, type passphrases
6427       into it, or log into other machines from it in any way at all;
6428       Pageant is hardly unique in this respect.)
6429
6430Chapter 10: Common error messages
6431---------------------------------
6432
6433       This chapter lists a number of common error messages which PuTTY and
6434       its associated tools can produce, and explains what they mean in
6435       more detail.
6436
6437       We do not attempt to list _all_ error messages here: there are many
6438       which should never occur, and some which should be self-explanatory.
6439       If you get an error message which is not listed in this chapter and
6440       which you don't understand, report it to us as a bug (see appendix
6441       B) and we will add documentation for it.
6442
6443  10.1 `The server's host key is not cached in the registry'
6444
6445       This error message occurs when PuTTY connects to a new SSH server.
6446       Every server identifies itself by means of a host key; once PuTTY
6447       knows the host key for a server, it will be able to detect if a
6448       malicious attacker redirects your connection to another machine.
6449
6450       If you see this message, it means that PuTTY has not seen this host
6451       key before, and has no way of knowing whether it is correct or not.
6452       You should attempt to verify the host key by other means, such as
6453       asking the machine's administrator.
6454
6455       If you see this message and you know that your installation of PuTTY
6456       _has_ connected to the same server before, it may have been recently
6457       upgraded to SSH protocol version 2. SSH protocols 1 and 2 use
6458       separate host keys, so when you first use SSH-2 with a server you
6459       have only used SSH-1 with before, you will see this message again.
6460       You should verify the correctness of the key as before.
6461
6462       See section 2.2 for more information on host keys.
6463
6464  10.2 `WARNING - POTENTIAL SECURITY BREACH!'
6465
6466       This message, followed by `The server's host key does not match
6467       the one PuTTY has cached in the registry', means that PuTTY has
6468       connected to the SSH server before, knows what its host key _should_
6469       be, but has found a different one.
6470
6471       This may mean that a malicious attacker has replaced your server
6472       with a different one, or has redirected your network connection
6473       to their own machine. On the other hand, it may simply mean that
6474       the administrator of your server has accidentally changed the key
6475       while upgrading the SSH software; this _shouldn't_ happen but it is
6476       unfortunately possible.
6477
6478       You should contact your server's administrator and see whether they
6479       expect the host key to have changed. If so, verify the new host key
6480       in the same way as you would if it was new.
6481
6482       See section 2.2 for more information on host keys.
6483
6484  10.3 `SSH protocol version 2 required by our configuration but server
6485       only provides (old, insecure) SSH-1'
6486
6487       By default, PuTTY only supports connecting to SSH servers that
6488       implement SSH protocol version 2. If you see this message, the
6489       server you're trying to connect to only supports the older SSH-1
6490       protocol.
6491
6492       If the server genuinely only supports SSH-1, then you need to either
6493       change the `SSH protocol version' setting (see section 4.18.4), or
6494       use the `-1' command-line option; in any case, you should not treat
6495       the resulting connection as secure.
6496
6497       You might start seeing this message with new versions of PuTTY
6498       (from 0.68 onwards) where you didn't before, because it used to be
6499       possible to configure PuTTY to automatically fall back from SSH-2 to
6500       SSH-1. This is no longer supported, to prevent the possibility of a
6501       downgrade attack.
6502
6503  10.4 `The first cipher supported by the server is ... below the
6504       configured warning threshold'
6505
6506       This occurs when the SSH server does not offer any ciphers which you
6507       have configured PuTTY to consider strong enough. By default, PuTTY
6508       puts up this warning only for single-DES and Arcfour encryption.
6509
6510       See section 4.21 for more information on this message.
6511
6512  10.5 `Server sent disconnect message type 2 (protocol error): "Too many
6513       authentication failures for root"'
6514
6515       This message is produced by an OpenSSH (or Sun SSH) server if it
6516       receives more failed authentication attempts than it is willing to
6517       tolerate.
6518
6519       This can easily happen if you are using Pageant and have a large
6520       number of keys loaded into it, since these servers count each offer
6521       of a public key as an authentication attempt. This can be worked
6522       around by specifying the key that's required for the authentication
6523       in the PuTTY configuration (see section 4.22.8); PuTTY will ignore
6524       any other keys Pageant may have, but will ask Pageant to do the
6525       authentication, so that you don't have to type your passphrase.
6526
6527       On the server, this can be worked around by disabling public-key
6528       authentication or (for Sun SSH only) by increasing `MaxAuthTries' in
6529       `sshd_config'.
6530
6531  10.6 `Out of memory'
6532
6533       This occurs when PuTTY tries to allocate more memory than the system
6534       can give it. This _may_ happen for genuine reasons: if the computer
6535       really has run out of memory, or if you have configured an extremely
6536       large number of lines of scrollback in your terminal. PuTTY is
6537       not able to recover from running out of memory; it will terminate
6538       immediately after giving this error.
6539
6540       However, this error can also occur when memory is not running out at
6541       all, because PuTTY receives data in the wrong format. In SSH-2 and
6542       also in SFTP, the server sends the length of each message before the
6543       message itself; so PuTTY will receive the length, try to allocate
6544       space for the message, and then receive the rest of the message.
6545       If the length PuTTY receives is garbage, it will try to allocate
6546       a ridiculous amount of memory, and will terminate with an `Out of
6547       memory' error.
6548
6549       This can happen in SSH-2, if PuTTY and the server have not enabled
6550       encryption in the same way (see question A.7.3 in the FAQ).
6551
6552       This can also happen in PSCP or PSFTP, if your login scripts on the
6553       server generate output: the client program will be expecting an
6554       SFTP message starting with a length, and if it receives some text
6555       from your login scripts instead it will try to interpret them as a
6556       message length. See question A.7.4 for details of this.
6557
6558  10.7 `Internal error', `Internal fault', `Assertion failed'
6559
6560       Any error beginning with the word `Internal' should _never_ occur.
6561       If it does, there is a bug in PuTTY by definition; please see
6562       appendix B and report it to us.
6563
6564       Similarly, any error message starting with `Assertion failed' is a
6565       bug in PuTTY. Please report it to us, and include the exact text
6566       from the error message box.
6567
6568  10.8 `Unable to use this private key file', `Couldn't load private key',
6569       `Key is of wrong type'
6570
6571       Various forms of this error are printed in the PuTTY window, or
6572       written to the PuTTY Event Log (see section 3.1.3.1) when trying
6573       public-key authentication, or given by Pageant when trying to load a
6574       private key.
6575
6576       If you see one of these messages, it often indicates that you've
6577       tried to load a key of an inappropriate type into PuTTY, Plink,
6578       PSCP, PSFTP, or Pageant.
6579
6580       You may have specified a key that's inappropriate for the connection
6581       you're making. The SSH-1 and SSH-2 protocols require different
6582       private key formats, and a SSH-1 key can't be used for a SSH-2
6583       connection (or vice versa).
6584
6585       Alternatively, you may have tried to load an SSH-2 key in a
6586       `foreign' format (OpenSSH or ssh.com) directly into one of the PuTTY
6587       tools, in which case you need to import it into PuTTY's native
6588       format (`*.PPK') using PuTTYgen - see section 8.2.12.
6589
6590  10.9 `Server refused our public key' or `Key refused'
6591
6592       Various forms of this error are printed in the PuTTY window, or
6593       written to the PuTTY Event Log (see section 3.1.3.1) when trying
6594       public-key authentication.
6595
6596       If you see one of these messages, it means that PuTTY has sent a
6597       public key to the server and offered to authenticate with it, and
6598       the server has refused to accept authentication. This usually means
6599       that the server is not configured to accept this key to authenticate
6600       this user.
6601
6602       This is almost certainly not a problem with PuTTY. If you see
6603       this type of message, the first thing you should do is check your
6604       _server_ configuration carefully. Common errors include having the
6605       wrong permissions or ownership set on the public key or the user's
6606       home directory on the server. Also, read the PuTTY Event Log; the
6607       server may have sent diagnostic messages explaining exactly what
6608       problem it had with your setup.
6609
6610       Section 8.3 has some hints on server-side public key setup.
6611
6612 10.10 `Access denied', `Authentication refused'
6613
6614       Various forms of this error are printed in the PuTTY window,
6615       or written to the PuTTY Event Log (see section 3.1.3.1) during
6616       authentication.
6617
6618       If you see one of these messages, it means that the server has
6619       refused all the forms of authentication PuTTY has tried and it has
6620       no further ideas.
6621
6622       It may be worth checking the Event Log for diagnostic messages from
6623       the server giving more detail.
6624
6625       This error can be caused by buggy SSH-1 servers that fail to cope
6626       with the various strategies we use for camouflaging passwords in
6627       transit. Upgrade your server, or use the workarounds described in
6628       section 4.27.1 and possibly section 4.27.2.
6629
6630 10.11 `No supported authentication methods available'
6631
6632       This error indicates that PuTTY has run out of ways to authenticate
6633       you to an SSH server. This may be because PuTTY has TIS or keyboard-
6634       interactive authentication disabled, in which case section 4.22.4
6635       and section 4.22.5.
6636
6637 10.12 `Incorrect CRC received on packet' or `Incorrect MAC received on
6638       packet'
6639
6640       This error occurs when PuTTY decrypts an SSH packet and its checksum
6641       is not correct. This probably means something has gone wrong in the
6642       encryption or decryption process. It's difficult to tell from this
6643       error message whether the problem is in the client, in the server,
6644       or in between.
6645
6646       In particular, if the network is corrupting data at the TCP level,
6647       it may only be obvious with cryptographic protocols such as SSH,
6648       which explicitly check the integrity of the transferred data and
6649       complain loudly if the checks fail. Corruption of protocols without
6650       integrity protection (such as HTTP) will manifest in more subtle
6651       failures (such as misdisplayed text or images in a web browser)
6652       which may not be noticed.
6653
6654       Occasionally this has been caused by server bugs. An example is the
6655       bug described at section 4.27.6, although you're very unlikely to
6656       encounter that one these days.
6657
6658       In this context MAC stands for Message Authentication Code. It's a
6659       cryptographic term, and it has nothing at all to do with Ethernet
6660       MAC (Media Access Control) addresses, or with the Apple computer.
6661
6662 10.13 `Incoming packet was garbled on decryption'
6663
6664       This error occurs when PuTTY decrypts an SSH packet and the
6665       decrypted data makes no sense. This probably means something has
6666       gone wrong in the encryption or decryption process. It's difficult
6667       to tell from this error message whether the problem is in the
6668       client, in the server, or in between.
6669
6670       If you get this error, one thing you could try would be to fiddle
6671       with the setting of `Miscomputes SSH-2 encryption keys' (see section
6672       4.27.7) or `Ignores SSH-2 maximum packet size' (see section 4.27.11)
6673       on the Bugs panel.
6674
6675 10.14 `PuTTY X11 proxy: _various errors_'
6676
6677       This family of errors are reported when PuTTY is doing X forwarding.
6678       They are sent back to the X application running on the SSH server,
6679       which will usually report the error to the user.
6680
6681       When PuTTY enables X forwarding (see section 3.4) it creates a
6682       virtual X display running on the SSH server. This display requires
6683       authentication to connect to it (this is how PuTTY prevents other
6684       users on your server machine from connecting through the PuTTY proxy
6685       to your real X display). PuTTY also sends the server the details it
6686       needs to enable clients to connect, and the server should put this
6687       mechanism in place automatically, so your X applications should just
6688       work.
6689
6690       A common reason why people see one of these messages is because they
6691       used SSH to log in as one user (let's say `fred'), and then used
6692       the Unix `su' command to become another user (typically `root').
6693       The original user, `fred', has access to the X authentication data
6694       provided by the SSH server, and can run X applications which are
6695       forwarded over the SSH connection. However, the second user (`root')
6696       does not automatically have the authentication data passed on to it,
6697       so attempting to run an X application as that user often fails with
6698       this error.
6699
6700       If this happens, _it is not a problem with PuTTY_. You need to
6701       arrange for your X authentication data to be passed from the user
6702       you logged in as to the user you used `su' to become. How you do
6703       this depends on your particular system; in fact many modern versions
6704       of `su' do it automatically.
6705
6706 10.15 `Network error: Software caused connection abort'
6707
6708       This is a generic error produced by the Windows network code when
6709       it kills an established connection for some reason. For example, it
6710       might happen if you pull the network cable out of the back of an
6711       Ethernet-connected computer, or if Windows has any other similar
6712       reason to believe the entire network has become unreachable.
6713
6714       Windows also generates this error if it has given up on the machine
6715       at the other end of the connection ever responding to it. If the
6716       network between your client and server goes down and your client
6717       then tries to send some data, Windows will make several attempts
6718       to send the data and will then give up and kill the connection. In
6719       particular, this can occur even if you didn't type anything, if you
6720       are using SSH-2 and PuTTY attempts a key re-exchange. (See section
6721       4.19.2 for more about key re-exchange.)
6722
6723       (It can also occur if you are using keepalives in your connection.
6724       Other people have reported that keepalives _fix_ this error for
6725       them. See section 4.13.1 for a discussion of the pros and cons of
6726       keepalives.)
6727
6728       We are not aware of any reason why this error might occur that would
6729       represent a bug in PuTTY. The problem is between you, your Windows
6730       system, your network and the remote system.
6731
6732 10.16 `Network error: Connection reset by peer'
6733
6734       This error occurs when the machines at each end of a network
6735       connection lose track of the state of the connection between them.
6736       For example, you might see it if your SSH server crashes, and
6737       manages to reboot fully before you next attempt to send data to it.
6738
6739       However, the most common reason to see this message is if you are
6740       connecting through a firewall or a NAT router which has timed the
6741       connection out. See question A.7.8 in the FAQ for more details.
6742       You may be able to improve the situation by using keepalives; see
6743       section 4.13.1 for details on this.
6744
6745       Note that Windows can produce this error in some circumstances
6746       without seeing a connection reset from the server, for instance if
6747       the connection to the network is lost.
6748
6749 10.17 `Network error: Connection refused'
6750
6751       This error means that the network connection PuTTY tried to make to
6752       your server was rejected by the server. Usually this happens because
6753       the server does not provide the service which PuTTY is trying to
6754       access.
6755
6756       Check that you are connecting with the correct protocol (SSH, Telnet
6757       or Rlogin), and check that the port number is correct. If that
6758       fails, consult the administrator of your server.
6759
6760 10.18 `Network error: Connection timed out'
6761
6762       This error means that the network connection PuTTY tried to make to
6763       your server received no response at all from the server. Usually
6764       this happens because the server machine is completely isolated from
6765       the network, or because it is turned off.
6766
6767       Check that you have correctly entered the host name or IP address
6768       of your server machine. If that fails, consult the administrator of
6769       your server.
6770
6771       Unix also generates this error when it tries to send data down a
6772       connection and contact with the server has been completely lost
6773       during a connection. (There is a delay of minutes before Unix gives
6774       up on receiving a reply from the server.) This can occur if you type
6775       things into PuTTY while the network is down, but it can also occur
6776       if PuTTY decides of its own accord to send data: due to a repeat key
6777       exchange in SSH-2 (see section 4.19.2) or due to keepalives (section
6778       4.13.1).
6779
6780 10.19 `Network error: Cannot assign requested address'
6781
6782       This means that the operating system rejected the parameters of the
6783       network connection PuTTY tried to make, usually without actually
6784       trying to connect to anything, because they were simply invalid.
6785
6786       A common way to provoke this error is to accidentally try to connect
6787       to port 0, which is not a valid port number.
6788
6789Appendix A: PuTTY FAQ
6790---------------------
6791
6792       This FAQ is published on the PuTTY web site, and also provided as an
6793       appendix in the manual.
6794
6795   A.1 Introduction
6796
6797 A.1.1 What is PuTTY?
6798
6799       PuTTY is a client program for the SSH, Telnet and Rlogin network
6800       protocols.
6801
6802       These protocols are all used to run a remote session on a computer,
6803       over a network. PuTTY implements the client end of that session: the
6804       end at which the session is displayed, rather than the end at which
6805       it runs.
6806
6807       In really simple terms: you run PuTTY on a Windows machine, and
6808       tell it to connect to (for example) a Unix machine. PuTTY opens a
6809       window. Then, anything you type into that window is sent straight
6810       to the Unix machine, and everything the Unix machine sends back is
6811       displayed in the window. So you can work on the Unix machine as if
6812       you were sitting at its console, while actually sitting somewhere
6813       else.
6814
6815   A.2 Features supported in PuTTY
6816
6817       In general, if you want to know if PuTTY supports a particular
6818       feature, you should look for it on the PuTTY web site. In
6819       particular:
6820
6821        -  try the changes page, and see if you can find the feature on
6822           there. If a feature is listed there, it's been implemented. If
6823           it's listed as a change made _since_ the latest version, it
6824           should be available in the development snapshots, in which case
6825           testing will be very welcome.
6826
6827        -  try the Wishlist page, and see if you can find the feature
6828           there. If it's on there, and not in the `Recently fixed'
6829           section, it probably _hasn't_ been implemented.
6830
6831 A.2.1 Does PuTTY support SSH-2?
6832
6833       Yes. SSH-2 support has been available in PuTTY since version 0.50.
6834
6835       Public key authentication (both RSA and DSA) in SSH-2 is new in
6836       version 0.52.
6837
6838 A.2.2 Does PuTTY support reading OpenSSH or ssh.com SSH-2 private key
6839       files?
6840
6841       PuTTY doesn't support this natively (see the wishlist entry for
6842       reasons why not), but as of 0.53 PuTTYgen can convert both OpenSSH
6843       and ssh.com private key files into PuTTY's format.
6844
6845 A.2.3 Does PuTTY support SSH-1?
6846
6847       Yes. SSH-1 support has always been available in PuTTY.
6848
6849       However, the SSH-1 protocol has many weaknesses and is no longer
6850       considered secure; you should use SSH-2 instead if at all possible.
6851
6852       As of 0.68, PuTTY will no longer fall back to SSH-1 if the server
6853       doesn't appear to support SSH-2; you must explicitly ask for SSH-1.
6854
6855 A.2.4 Does PuTTY support local echo?
6856
6857       Yes. Version 0.52 has proper support for local echo.
6858
6859       In version 0.51 and before, local echo could not be separated from
6860       local line editing (where you type a line of text locally, and it
6861       is not sent to the server until you press Return, so you have the
6862       chance to edit it and correct mistakes _before_ the server sees it).
6863       New in version 0.52, local echo and local line editing are separate
6864       options, and by default PuTTY will try to determine automatically
6865       whether to enable them or not, based on which protocol you have
6866       selected and also based on hints from the server. If you have a
6867       problem with PuTTY's default choice, you can force each option to be
6868       enabled or disabled as you choose. The controls are in the Terminal
6869       panel, in the section marked `Line discipline options'.
6870
6871 A.2.5 Does PuTTY support storing settings, so I don't have to change them
6872       every time?
6873
6874       Yes, all of PuTTY's settings can be saved in named session profiles.
6875       You can also change the default settings that are used for new
6876       sessions. See section 4.1.2 in the documentation for how to do this.
6877
6878 A.2.6 Does PuTTY support storing its settings in a disk file?
6879
6880       Not at present, although section 4.29 in the documentation gives a
6881       method of achieving the same effect.
6882
6883 A.2.7 Does PuTTY support full-screen mode, like a DOS box?
6884
6885       Yes; this is a new feature in version 0.52.
6886
6887 A.2.8 Does PuTTY have the ability to remember my password so I don't have
6888       to type it every time?
6889
6890       No, it doesn't.
6891
6892       Remembering your password is a bad plan for obvious security
6893       reasons: anyone who gains access to your machine while you're away
6894       from your desk can find out the remembered password, and use it,
6895       abuse it or change it.
6896
6897       In addition, it's not even _possible_ for PuTTY to automatically
6898       send your password in a Telnet session, because Telnet doesn't
6899       give the client software any indication of which part of the login
6900       process is the password prompt. PuTTY would have to guess, by
6901       looking for words like `password' in the session data; and if your
6902       login program is written in something other than English, this won't
6903       work.
6904
6905       In SSH, remembering your password would be possible in theory,
6906       but there doesn't seem to be much point since SSH supports public
6907       key authentication, which is more flexible and more secure. See
6908       chapter 8 in the documentation for a full discussion of public key
6909       authentication.
6910
6911 A.2.9 Is there an option to turn off the annoying host key prompts?
6912
6913       No, there isn't. And there won't be. Even if you write it yourself
6914       and send us the patch, we won't accept it.
6915
6916       Those annoying host key prompts are the _whole point_ of SSH.
6917       Without them, all the cryptographic technology SSH uses to secure
6918       your session is doing nothing more than making an attacker's job
6919       slightly harder; instead of sitting between you and the server with
6920       a packet sniffer, the attacker must actually subvert a router and
6921       start modifying the packets going back and forth. But that's not all
6922       that much harder than just sniffing; and without host key checking,
6923       it will go completely undetected by client or server.
6924
6925       Host key checking is your guarantee that the encryption you put
6926       on your data at the client end is the _same_ encryption taken off
6927       the data at the server end; it's your guarantee that it hasn't
6928       been removed and replaced somewhere on the way. Host key checking
6929       makes the attacker's job _astronomically_ hard, compared to packet
6930       sniffing, and even compared to subverting a router. Instead of
6931       applying a little intelligence and keeping an eye on Bugtraq, the
6932       attacker must now perform a brute-force attack against at least one
6933       military-strength cipher. That insignificant host key prompt really
6934       does make _that_ much difference.
6935
6936       If you're having a specific problem with host key checking - perhaps
6937       you want an automated batch job to make use of PSCP or Plink, and
6938       the interactive host key prompt is hanging the batch process -
6939       then the right way to fix it is to add the correct host key to the
6940       Registry in advance, or if the Registry is not available, to use the
6941       -hostkey command-line option. That way, you retain the _important_
6942       feature of host key checking: the right key will be accepted and the
6943       wrong ones will not. Adding an option to turn host key checking off
6944       completely is the wrong solution and we will not do it.
6945
6946       If you have host keys available in the common `known_hosts' format,
6947       we have a script called `kh2reg.py' to convert them to a Windows
6948       .REG file, which can be installed ahead of time by double-clicking
6949       or using `REGEDIT'.
6950
6951A.2.10 Will you write an SSH server for the PuTTY suite, to go with the
6952       client?
6953
6954       No. The only reason we might want to would be if we could easily re-
6955       use existing code and significantly cut down the effort. We don't
6956       believe this is the case; there just isn't enough common ground
6957       between an SSH client and server to make it worthwhile.
6958
6959       If someone else wants to use bits of PuTTY in the process of writing
6960       a Windows SSH server, they'd be perfectly welcome to of course, but
6961       I really can't see it being a lot less effort for us to do that than
6962       it would be for us to write a server from the ground up. We don't
6963       have time, and we don't have motivation. The code is available if
6964       anyone else wants to try it.
6965
6966A.2.11 Can PSCP or PSFTP transfer files in ASCII mode?
6967
6968       Unfortunately not.
6969
6970       Until recently, this was a limitation of the file transfer
6971       protocols: the SCP and SFTP protocols had no notion of transferring
6972       a file in anything other than binary mode. (This is still true of
6973       SCP.)
6974
6975       The current draft protocol spec of SFTP proposes a means of
6976       implementing ASCII transfer. At some point PSCP/PSFTP may implement
6977       this proposal.
6978
6979   A.3 Ports to other operating systems
6980
6981       The eventual goal is for PuTTY to be a multi-platform program, able
6982       to run on at least Windows, Mac OS and Unix.
6983
6984       Porting will become easier once PuTTY has a generalised porting
6985       layer, drawing a clear line between platform-dependent and platform-
6986       independent code. The general intention was for this porting layer
6987       to evolve naturally as part of the process of doing the first port;
6988       a Unix port has now been released and the plan seems to be working
6989       so far.
6990
6991 A.3.1 What ports of PuTTY exist?
6992
6993       Currently, release versions of PuTTY tools only run on Windows
6994       systems and Unix.
6995
6996       As of 0.68, the supplied PuTTY executables run on versions of
6997       Windows from XP onwards, up to and including Windows 10; and
6998       we know of no reason why PuTTY should not continue to work on
6999       future versions of Windows. We provide 32-bit and 64-bit Windows
7000       executables; see question A.6.10 for discussion of the compatibility
7001       issues around that.
7002
7003       (We used to also provide executables for Windows for the Alpha
7004       processor, but stopped after 0.58 due to lack of interest.)
7005
7006       In the development code, a partial port to Mac OS exists (see
7007       question A.3.6).
7008
7009       Currently PuTTY does _not_ run on Windows CE (see question A.3.4).
7010
7011       We do not have release-quality ports for any other systems at the
7012       present time. If anyone told you we had an Android port, or an iOS
7013       port, or any other port of PuTTY, they were mistaken. We don't.
7014
7015       There are some third-party ports to various platforms, mentioned on
7016       the Links page of our website.
7017
7018 A.3.2 Is there a port to Unix?
7019
7020       As of 0.54, there are Unix ports of most of the traditional PuTTY
7021       tools, and also one entirely new application.
7022
7023       If you look at the source release, you should find a `unix'
7024       subdirectory. There are a couple of ways of building it, including
7025       the usual `configure'/`make'; see the file `README' in the source
7026       distribution. This should build you Unix ports of Plink, PuTTY
7027       itself, PuTTYgen, PSCP, PSFTP, Pageant, and also `pterm' - an xterm-
7028       type program which supports the same terminal emulation as PuTTY.
7029
7030       If you don't have Gtk, you should still be able to build the
7031       command-line tools.
7032
7033 A.3.3 What's the point of the Unix port? Unix has OpenSSH.
7034
7035       All sorts of little things. `pterm' is directly useful to anyone who
7036       prefers PuTTY's terminal emulation to `xterm''s, which at least some
7037       people do. Unix Plink has apparently found a niche among people who
7038       find the complexity of OpenSSL makes OpenSSH hard to install (and
7039       who don't mind Plink not having as many features). Some users want
7040       to generate a large number of SSH keys on Unix and then copy them
7041       all into PuTTY, and the Unix PuTTYgen should allow them to automate
7042       that conversion process.
7043
7044       There were development advantages as well; porting PuTTY to Unix
7045       was a valuable path-finding effort for other future ports, and also
7046       allowed us to use the excellent Linux tool Valgrind to help with
7047       debugging, which has already improved PuTTY's stability on _all_
7048       platforms.
7049
7050       However, if you're a Unix user and you can see no reason to switch
7051       from OpenSSH to PuTTY/Plink, then you're probably right. We don't
7052       expect our Unix port to be the right thing for everybody.
7053
7054 A.3.4 Will there be a port to Windows CE or PocketPC?
7055
7056       We once did some work on such a port, but it only reached an early
7057       stage, and certainly not a useful one. It's no longer being actively
7058       worked on.
7059
7060 A.3.5 Is there a port to Windows 3.1?
7061
7062       PuTTY is a 32-bit application from the ground up, so it won't run on
7063       Windows 3.1 as a native 16-bit program; and it would be _very_ hard
7064       to port it to do so, because of Windows 3.1's vile memory allocation
7065       mechanisms.
7066
7067       However, it is possible in theory to compile the existing PuTTY
7068       source in such a way that it will run under Win32s (an extension to
7069       Windows 3.1 to let you run 32-bit programs). In order to do this
7070       you'll need the right kind of C compiler - modern versions of Visual
7071       C at least have stopped being backwards compatible to Win32s. Also,
7072       the last time we tried this it didn't work very well.
7073
7074 A.3.6 Will there be a port to the Mac?
7075
7076       We hope so!
7077
7078       We attempted one around 2005, written as a native Cocoa application,
7079       but it turned out to be very slow to redraw its window for some
7080       reason we never got to the bottom of.
7081
7082       In 2015, after porting the GTK front end to work with GTK 3, we
7083       began another attempt based on making small changes to the GTK
7084       code and building it against the OS X Quartz version of GTK 3.
7085       This doesn't seem to have the window redrawing problem any more,
7086       so it's already got further than the last effort, but it is still
7087       substantially unfinished.
7088
7089       If any OS X and/or GTK programming experts are keen to have a
7090       finished version of this, we urge them to help out with some of the
7091       remaining problems!
7092
7093 A.3.7 Will there be a port to EPOC?
7094
7095       I hope so, but given that ports aren't really progressing very fast
7096       even on systems the developers _do_ already know how to program for,
7097       it might be a long time before any of us get round to learning a new
7098       system and doing the port for that.
7099
7100       However, some of the work has been done by other people; see the
7101       Links page of our website for various third-party ports.
7102
7103 A.3.8 Will there be a port to the iPhone?
7104
7105       We have no plans to write such a port ourselves; none of us has an
7106       iPhone, and developing and publishing applications for it looks
7107       awkward and expensive.
7108
7109       However, there is a third-party SSH client for the iPhone and
7110       iPod Touch called pTerm, which is apparently based on PuTTY. (This
7111       is nothing to do with our similarly-named `pterm', which is a
7112       standalone terminal emulator for Unix systems; see question A.3.2.)
7113
7114   A.4 Embedding PuTTY in other programs
7115
7116 A.4.1 Is the SSH or Telnet code available as a DLL?
7117
7118       No, it isn't. It would take a reasonable amount of rewriting for
7119       this to be possible, and since the PuTTY project itself doesn't
7120       believe in DLLs (they make installation more error-prone) none of us
7121       has taken the time to do it.
7122
7123       Most of the code cleanup work would be a good thing to happen in
7124       general, so if anyone feels like helping, we wouldn't say no.
7125
7126       See also the wishlist entry.
7127
7128 A.4.2 Is the SSH or Telnet code available as a Visual Basic component?
7129
7130       No, it isn't. None of the PuTTY team uses Visual Basic, and none of
7131       us has any particular need to make SSH connections from a Visual
7132       Basic application. In addition, all the preliminary work to turn it
7133       into a DLL would be necessary first; and furthermore, we don't even
7134       know how to write VB components.
7135
7136       If someone offers to do some of this work for us, we might consider
7137       it, but unless that happens I can't see VB integration being
7138       anywhere other than the very bottom of our priority list.
7139
7140 A.4.3 How can I use PuTTY to make an SSH connection from within another
7141       program?
7142
7143       Probably your best bet is to use Plink, the command-line connection
7144       tool. If you can start Plink as a second Windows process, and
7145       arrange for your primary process to be able to send data to the
7146       Plink process, and receive data from it, through pipes, then you
7147       should be able to make SSH connections from your program.
7148
7149       This is what CVS for Windows does, for example.
7150
7151   A.5 Details of PuTTY's operation
7152
7153 A.5.1 What terminal type does PuTTY use?
7154
7155       For most purposes, PuTTY can be considered to be an xterm terminal.
7156
7157       PuTTY also supports some terminal control sequences not supported by
7158       the real xterm: notably the Linux console sequences that reconfigure
7159       the colour palette, and the title bar control sequences used by
7160       DECterm (which are different from the xterm ones; PuTTY supports
7161       both).
7162
7163       By default, PuTTY announces its terminal type to the server as
7164       `xterm'. If you have a problem with this, you can reconfigure it to
7165       say something else; `vt220' might help if you have trouble.
7166
7167 A.5.2 Where does PuTTY store its data?
7168
7169       On Windows, PuTTY stores most of its data (saved sessions, SSH host
7170       keys) in the Registry. The precise location is
7171
7172         HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
7173
7174       and within that area, saved sessions are stored under `Sessions'
7175       while host keys are stored under `SshHostKeys'.
7176
7177       PuTTY also requires a random number seed file, to improve the
7178       unpredictability of randomly chosen data needed as part of the
7179       SSH cryptography. This is stored by default in a file called
7180       `PUTTY.RND'; this is stored by default in the `Application Data'
7181       directory, or failing that, one of a number of fallback locations.
7182       If you want to change the location of the random number seed file,
7183       you can put your chosen pathname in the Registry, at
7184
7185         HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\RandSeedFile
7186
7187       You can ask PuTTY to delete all this data; see question A.8.2.
7188
7189       On Unix, PuTTY stores all of this data in a directory ~/.putty by
7190       default.
7191
7192   A.6 HOWTO questions
7193
7194 A.6.1 What login name / password should I use?
7195
7196       This is not a question you should be asking _us_.
7197
7198       PuTTY is a communications tool, for making connections to other
7199       computers. We maintain the tool; we _don't_ administer any computers
7200       that you're likely to be able to use, in the same way that the
7201       people who make web browsers aren't responsible for most of the
7202       content you can view in them. We cannot help with questions of this
7203       sort.
7204
7205       If you know the name of the computer you want to connect to, but
7206       don't know what login name or password to use, you should talk to
7207       whoever administers that computer. If you don't know who that is,
7208       see the next question for some possible ways to find out.
7209
7210 A.6.2 What commands can I type into my PuTTY terminal window?
7211
7212       Again, this is not a question you should be asking _us_. You need
7213       to read the manuals, or ask the administrator, of _the computer you
7214       have connected to_.
7215
7216       PuTTY does not process the commands you type into it. It's only a
7217       communications tool. It makes a connection to another computer; it
7218       passes the commands you type to that other computer; and it passes
7219       the other computer's responses back to you. Therefore, the precise
7220       range of commands you can use will not depend on PuTTY, but on what
7221       kind of computer you have connected to and what software is running
7222       on it. The PuTTY team cannot help you with that.
7223
7224       (Think of PuTTY as being a bit like a telephone. If you phone
7225       somebody up and you don't know what language to speak to make them
7226       understand you, it isn't _the telephone company_'s job to find that
7227       out for you. We just provide the means for you to get in touch;
7228       making yourself understood is somebody else's problem.)
7229
7230       If you are unsure of where to start looking for the administrator
7231       of your server, a good place to start might be to remember how you
7232       found out the host name in the PuTTY configuration. If you were
7233       given that host name by e-mail, for example, you could try asking
7234       the person who sent you that e-mail. If your company's IT department
7235       provided you with ready-made PuTTY saved sessions, then that IT
7236       department can probably also tell you something about what commands
7237       you can type during those sessions. But the PuTTY maintainer team
7238       does not administer any server you are likely to be connecting to,
7239       and cannot help you with questions of this type.
7240
7241 A.6.3 How can I make PuTTY start up maximised?
7242
7243       Create a Windows shortcut to start PuTTY from, and set it as `Run
7244       Maximized'.
7245
7246 A.6.4 How can I create a Windows shortcut to start a particular saved
7247       session directly?
7248
7249       To run a PuTTY session saved under the name `mysession', create a
7250       Windows shortcut that invokes PuTTY with a command line like
7251
7252         \path\name\to\putty.exe -load "mysession"
7253
7254       (Note: prior to 0.53, the syntax was `@session'. This is now
7255       deprecated and may be removed at some point.)
7256
7257 A.6.5 How can I start an SSH session straight from the command line?
7258
7259       Use the command line `putty -ssh host.name'. Alternatively, create a
7260       saved session that specifies the SSH protocol, and start the saved
7261       session as shown in question A.6.4.
7262
7263 A.6.6 How do I copy and paste between PuTTY and other Windows
7264       applications?
7265
7266       Copy and paste works similarly to the X Window System. You use the
7267       left mouse button to select text in the PuTTY window. The act of
7268       selection _automatically_ copies the text to the clipboard: there
7269       is no need to press Ctrl-Ins or Ctrl-C or anything else. In fact,
7270       pressing Ctrl-C will send a Ctrl-C character to the other end of
7271       your connection (just like it does the rest of the time), which may
7272       have unpleasant effects. The _only_ thing you need to do, to copy
7273       text to the clipboard, is to select it.
7274
7275       To paste the clipboard contents into a PuTTY window, by default you
7276       click the right mouse button. If you have a three-button mouse and
7277       are used to X applications, you can configure pasting to be done by
7278       the middle button instead, but this is not the default because most
7279       Windows users don't have a middle button at all.
7280
7281       You can also paste by pressing Shift-Ins.
7282
7283 A.6.7 How do I use all PuTTY's features (public keys, proxying, cipher
7284       selection, etc.) in PSCP, PSFTP and Plink?
7285
7286       Most major features (e.g., public keys, port forwarding) are
7287       available through command line options. See the documentation.
7288
7289       Not all features are accessible from the command line yet, although
7290       we'd like to fix this. In the meantime, you can use most of PuTTY's
7291       features if you create a PuTTY saved session, and then use the name
7292       of the saved session on the command line in place of a hostname.
7293       This works for PSCP, PSFTP and Plink (but don't expect port
7294       forwarding in the file transfer applications!).
7295
7296 A.6.8 How do I use PSCP.EXE? When I double-click it gives me a command
7297       prompt window which then closes instantly.
7298
7299       PSCP is a command-line application, not a GUI application. If you
7300       run it without arguments, it will simply print a help message and
7301       terminate.
7302
7303       To use PSCP properly, run it from a Command Prompt window. See
7304       chapter 5 in the documentation for more details.
7305
7306 A.6.9 How do I use PSCP to copy a file whose name has spaces in?
7307
7308       If PSCP is using the traditional SCP protocol, this is confusing. If
7309       you're specifying a file at the local end, you just use one set of
7310       quotes as you would normally do:
7311
7312         pscp "local filename with spaces" user@host:
7313         pscp user@host:myfile "local filename with spaces"
7314
7315       But if the filename you're specifying is on the _remote_ side, you
7316       have to use backslashes and two sets of quotes:
7317
7318         pscp user@host:"\"remote filename with spaces\"" local_filename
7319         pscp local_filename user@host:"\"remote filename with spaces\""
7320
7321       Worse still, in a remote-to-local copy you have to specify the local
7322       file name explicitly, otherwise PSCP will complain that they don't
7323       match (unless you specified the `-unsafe' option). The following
7324       command will give an error message:
7325
7326         c:\>pscp user@host:"\"oo er\"" .
7327         warning: remote host tried to write to a file called 'oo er'
7328                  when we requested a file called '"oo er"'.
7329
7330       Instead, you need to specify the local file name in full:
7331
7332         c:\>pscp user@host:"\"oo er\"" "oo er"
7333
7334       If PSCP is using the newer SFTP protocol, none of this is a problem,
7335       and all filenames with spaces in are specified using a single pair
7336       of quotes in the obvious way:
7337
7338         pscp "local file" user@host:
7339         pscp user@host:"remote file" .
7340
7341A.6.10 Should I run the 32-bit or the 64-bit version?
7342
7343       If you're not sure, the 32-bit version is generally the safe option.
7344       It will run perfectly well on all processors and on all versions of
7345       Windows that PuTTY supports. PuTTY doesn't require to run as a 64-
7346       bit application to work well, and having a 32-bit PuTTY on a 64-bit
7347       system isn't likely to cause you any trouble.
7348
7349       The 64-bit version (first released in 0.68) will only run if you
7350       have a 64-bit processor _and_ a 64-bit edition of Windows (both of
7351       these things are likely to be true of any recent Windows PC). It
7352       will run somewhat faster (in particular, the cryptography will be
7353       faster, especially during link setup), but it will consume slightly
7354       more memory.
7355
7356       If you need to use an external DLL for GSSAPI authentication, that
7357       DLL may only be available in a 32-bit or 64-bit form, and that will
7358       dictate the version of PuTTY you need to use. (You will probably
7359       know if you're doing this; see section 4.23.2 in the documentation.)
7360
7361   A.7 Troubleshooting
7362
7363 A.7.1 Why do I see `Fatal: Protocol error: Expected control record' in
7364       PSCP?
7365
7366       This happens because PSCP was expecting to see data from the server
7367       that was part of the PSCP protocol exchange, and instead it saw data
7368       that it couldn't make any sense of at all.
7369
7370       This almost always happens because the startup scripts in your
7371       account on the server machine are generating output. This is
7372       impossible for PSCP, or any other SCP client, to work around. You
7373       should never use startup files (`.bashrc', `.cshrc' and so on) which
7374       generate output in non-interactive sessions.
7375
7376       This is not actually a PuTTY problem. If PSCP fails in this way,
7377       then all other SCP clients are likely to fail in exactly the same
7378       way. The problem is at the server end.
7379
7380 A.7.2 I clicked on a colour in the Colours panel, and the colour didn't
7381       change in my terminal.
7382
7383       That isn't how you're supposed to use the Colours panel.
7384
7385       During the course of a session, PuTTY potentially uses _all_ the
7386       colours listed in the Colours panel. It's not a question of using
7387       only one of them and you choosing which one; PuTTY will use them
7388       _all_. The purpose of the Colours panel is to let you adjust the
7389       appearance of all the colours. So to change the colour of the
7390       cursor, for example, you would select `Cursor Colour', press the
7391       `Modify' button, and select a new colour from the dialog box that
7392       appeared. Similarly, if you want your session to appear in green,
7393       you should select `Default Foreground' and press `Modify'. Clicking
7394       on `ANSI Green' won't turn your session green; it will only allow
7395       you to adjust the _shade_ of green used when PuTTY is instructed by
7396       the server to display green text.
7397
7398 A.7.3 After trying to establish an SSH-2 connection, PuTTY says `Out of
7399       memory' and dies.
7400
7401       If this happens just while the connection is starting up, this often
7402       indicates that for some reason the client and server have failed to
7403       establish a session encryption key. Somehow, they have performed
7404       calculations that should have given each of them the same key, but
7405       have ended up with different keys; so data encrypted by one and
7406       decrypted by the other looks like random garbage.
7407
7408       This causes an `out of memory' error because the first encrypted
7409       data PuTTY expects to see is the length of an SSH message. Normally
7410       this will be something well under 100 bytes. If the decryption has
7411       failed, PuTTY will see a completely random length in the region of
7412       two _gigabytes_, and will try to allocate enough memory to store
7413       this non-existent message. This will immediately lead to it thinking
7414       it doesn't have enough memory, and panicking.
7415
7416       If this happens to you, it is quite likely to still be a PuTTY bug
7417       and you should report it (although it might be a bug in your SSH
7418       server instead); but it doesn't necessarily mean you've actually run
7419       out of memory.
7420
7421 A.7.4 When attempting a file transfer, either PSCP or PSFTP says `Out of
7422       memory' and dies.
7423
7424       This is almost always caused by your login scripts on the server
7425       generating output. PSCP or PSFTP will receive that output when they
7426       were expecting to see the start of a file transfer protocol, and
7427       they will attempt to interpret the output as file-transfer protocol.
7428       This will usually lead to an `out of memory' error for much the same
7429       reasons as given in question A.7.3.
7430
7431       This is a setup problem in your account on your server, _not_ a
7432       PSCP/PSFTP bug. Your login scripts should _never_ generate output
7433       during non-interactive sessions; secure file transfer is not the
7434       only form of remote access that will break if they do.
7435
7436       On Unix, a simple fix is to ensure that all the parts of your login
7437       script that might generate output are in `.profile' (if you use a
7438       Bourne shell derivative) or `.login' (if you use a C shell). Putting
7439       them in more general files such as `.bashrc' or `.cshrc' is liable
7440       to lead to problems.
7441
7442 A.7.5 PSFTP transfers files much slower than PSCP.
7443
7444       The throughput of PSFTP 0.54 should be much better than 0.53b and
7445       prior; we've added code to the SFTP backend to queue several blocks
7446       of data rather than waiting for an acknowledgement for each. (The
7447       SCP backend did not suffer from this performance issue because SCP
7448       is a much simpler protocol.)
7449
7450 A.7.6 When I run full-colour applications, I see areas of black space
7451       where colour ought to be, or vice versa.
7452
7453       You almost certainly need to change the `Use background colour to
7454       erase screen' setting in the Terminal panel. If there is too much
7455       black space (the commoner situation), you should enable it, while
7456       if there is too much colour, you should disable it. (See section
7457       4.3.5.)
7458
7459       In old versions of PuTTY, this was disabled by default, and would
7460       not take effect until you reset the terminal (see question A.7.7).
7461       Since 0.54, it is enabled by default, and changes take effect
7462       immediately.
7463
7464 A.7.7 When I change some terminal settings, nothing happens.
7465
7466       Some of the terminal options (notably Auto Wrap and background-
7467       colour screen erase) actually represent the _default_ setting,
7468       rather than the currently active setting. The server can send
7469       sequences that modify these options in mid-session, but when the
7470       terminal is reset (by server action, or by you choosing `Reset
7471       Terminal' from the System menu) the defaults are restored.
7472
7473       In versions 0.53b and prior, if you change one of these options in
7474       the middle of a session, you will find that the change does not
7475       immediately take effect. It will only take effect once you reset the
7476       terminal.
7477
7478       In version 0.54, the behaviour has changed - changes to these
7479       settings take effect immediately.
7480
7481 A.7.8 My PuTTY sessions unexpectedly close after they are idle for a
7482       while.
7483
7484       Some types of firewall, and almost any router doing Network Address
7485       Translation (NAT, also known as IP masquerading), will forget about
7486       a connection through them if the connection does nothing for too
7487       long. This will cause the connection to be rudely cut off when
7488       contact is resumed.
7489
7490       You can try to combat this by telling PuTTY to send _keepalives_:
7491       packets of data which have no effect on the actual session, but
7492       which reassure the router or firewall that the network connection is
7493       still active and worth remembering about.
7494
7495       Keepalives don't solve everything, unfortunately; although they
7496       cause greater robustness against this sort of router, they can also
7497       cause a _loss_ of robustness against network dropouts. See section
7498       4.13.1 in the documentation for more discussion of this.
7499
7500 A.7.9 PuTTY's network connections time out too quickly when network
7501       connectivity is temporarily lost.
7502
7503       This is a Windows problem, not a PuTTY problem. The timeout value
7504       can't be set on per application or per session basis. To increase
7505       the TCP timeout globally, you need to tinker with the Registry.
7506
7507       On Windows 95, 98 or ME, the registry key you need to create or
7508       change is
7509
7510         HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\
7511           MSTCP\MaxDataRetries
7512
7513       (it must be of type DWORD in Win95, or String in Win98/ME). (See MS
7514       Knowledge Base article 158474 for more information.)
7515
7516       On Windows NT, 2000, or XP, the registry key to create or change is
7517
7518         HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\
7519           Parameters\TcpMaxDataRetransmissions
7520
7521       and it must be of type DWORD. (See MS Knowledge Base articles 120642
7522       and 314053 for more information.)
7523
7524       Set the key's value to something like 10. This will cause Windows to
7525       try harder to keep connections alive instead of abandoning them.
7526
7527A.7.10 When I cat a binary file, I get `PuTTYPuTTYPuTTY' on my command
7528       line.
7529
7530       Don't do that, then.
7531
7532       This is designed behaviour; when PuTTY receives the character
7533       Control-E from the remote server, it interprets it as a request
7534       to identify itself, and so it sends back the string `PuTTY' as if
7535       that string had been entered at the keyboard. Control-E should only
7536       be sent by programs that are prepared to deal with the response.
7537       Writing a binary file to your terminal is likely to output many
7538       Control-E characters, and cause this behaviour. Don't do it. It's a
7539       bad plan.
7540
7541       To mitigate the effects, you could configure the answerback string
7542       to be empty (see section 4.3.7); but writing binary files to your
7543       terminal is likely to cause various other unpleasant behaviour, so
7544       this is only a small remedy.
7545
7546A.7.11 When I cat a binary file, my window title changes to a nonsense
7547       string.
7548
7549       Don't do that, then.
7550
7551       It is designed behaviour that PuTTY should have the ability
7552       to adjust the window title on instructions from the server.
7553       Normally the control sequence that does this should only be sent
7554       deliberately, by programs that know what they are doing and intend
7555       to put meaningful text in the window title. Writing a binary file to
7556       your terminal runs the risk of sending the same control sequence by
7557       accident, and cause unexpected changes in the window title. Don't do
7558       it.
7559
7560A.7.12 My keyboard stops working once PuTTY displays the password prompt.
7561
7562       No, it doesn't. PuTTY just doesn't display the password you type, so
7563       that someone looking at your screen can't see what it is.
7564
7565       Unlike the Windows login prompts, PuTTY doesn't display the password
7566       as a row of asterisks either. This is so that someone looking at
7567       your screen can't even tell how _long_ your password is, which might
7568       be valuable information.
7569
7570A.7.13 One or more function keys don't do what I expected in a server-side
7571       application.
7572
7573       If you've already tried all the relevant options in the PuTTY
7574       Keyboard panel, you may need to mail the PuTTY maintainers and ask.
7575
7576       It is _not_ usually helpful just to tell us which application,
7577       which server operating system, and which key isn't working; in
7578       order to replicate the problem we would need to have a copy of
7579       every operating system, and every application, that anyone has ever
7580       complained about.
7581
7582       PuTTY responds to function key presses by sending a sequence of
7583       control characters to the server. If a function key isn't doing what
7584       you expect, it's likely that the character sequence your application
7585       is expecting to receive is not the same as the one PuTTY is sending.
7586       Therefore what we really need to know is _what_ sequence the
7587       application is expecting.
7588
7589       The simplest way to investigate this is to find some other terminal
7590       environment, in which that function key _does_ work; and then
7591       investigate what sequence the function key is sending in that
7592       situation. One reasonably easy way to do this on a Unix system is
7593       to type the command `cat', and then press the function key. This is
7594       likely to produce output of the form `^[[11~'. You can also do this
7595       in PuTTY, to find out what sequence the function key is producing in
7596       that. Then you can mail the PuTTY maintainers and tell us `I wanted
7597       the F1 key to send `^[[11~', but instead it's sending `^[OP', can
7598       this be done?', or something similar.
7599
7600       You should still read the Feedback page on the PuTTY website (also
7601       provided as appendix B in the manual), and follow the guidelines
7602       contained in that.
7603
7604A.7.14 Why do I see `Couldn't load private key from ...'? Why can PuTTYgen
7605       load my key but not PuTTY?
7606
7607       It's likely that you've generated an SSH protocol 2 key with
7608       PuTTYgen, but you're trying to use it in an SSH-1 connection. SSH-
7609       1 and SSH-2 keys have different formats, and (at least in 0.52)
7610       PuTTY's reporting of a key in the wrong format isn't optimal.
7611
7612       To connect using SSH-2 to a server that supports both versions, you
7613       need to change the configuration from the default (see question
7614       A.2.1).
7615
7616A.7.15 When I'm connected to a Red Hat Linux 8.0 system, some characters
7617       don't display properly.
7618
7619       A common complaint is that hyphens in man pages show up as a-acute.
7620
7621       With release 8.0, Red Hat appear to have made UTF-8 the default
7622       character set. There appears to be no way for terminal emulators
7623       such as PuTTY to know this (as far as we know, the appropriate
7624       escape sequence to switch into UTF-8 mode isn't sent).
7625
7626       A fix is to configure sessions to RH8 systems to use UTF-8
7627       translation - see section 4.10.1 in the documentation. (Note that if
7628       you use `Change Settings', changes may not take place immediately -
7629       see question A.7.7.)
7630
7631       If you really want to change the character set used by the server,
7632       the right place is `/etc/sysconfig/i18n', but this shouldn't be
7633       necessary.
7634
7635A.7.16 Since I upgraded to PuTTY 0.54, the scrollback has stopped working
7636       when I run `screen'.
7637
7638       PuTTY's terminal emulator has always had the policy that when the
7639       `alternate screen' is in use, nothing is added to the scrollback.
7640       This is because the usual sorts of programs which use the alternate
7641       screen are things like text editors, which tend to scroll back and
7642       forth in the same document a lot; so (a) they would fill up the
7643       scrollback with a large amount of unhelpfully disordered text, and
7644       (b) they contain their _own_ method for the user to scroll back to
7645       the bit they were interested in. We have generally found this policy
7646       to do the Right Thing in almost all situations.
7647
7648       Unfortunately, `screen' is one exception: it uses the alternate
7649       screen, but it's still usually helpful to have PuTTY's scrollback
7650       continue working. The simplest solution is to go to the Features
7651       control panel and tick `Disable switching to alternate terminal
7652       screen'. (See section 4.6.4 for more details.) Alternatively, you
7653       can tell `screen' itself not to use the alternate screen: the
7654       `screen' FAQ suggests adding the line `termcapinfo xterm ti@:te@' to
7655       your .screenrc file.
7656
7657       The reason why this only started to be a problem in 0.54 is because
7658       `screen' typically uses an unusual control sequence to switch to the
7659       alternate screen, and previous versions of PuTTY did not support
7660       this sequence.
7661
7662A.7.17 Since I upgraded Windows XP to Service Pack 2, I can't use addresses
7663       like 127.0.0.2.
7664
7665       Some people who ask PuTTY to listen on localhost addresses other
7666       than 127.0.0.1 to forward services such as SMB and Windows Terminal
7667       Services have found that doing so no longer works since they
7668       upgraded to WinXP SP2.
7669
7670       This is apparently an issue with SP2 that is acknowledged by
7671       Microsoft in MS Knowledge Base article 884020. The article links to
7672       a fix you can download.
7673
7674       (_However_, we've been told that SP2 _also_ fixes the bug that means
7675       you need to use non-127.0.0.1 addresses to forward Terminal Services
7676       in the first place.)
7677
7678A.7.18 PSFTP commands seem to be missing a directory separator (slash).
7679
7680       Some people have reported the following incorrect behaviour with
7681       PSFTP:
7682
7683         psftp> pwd
7684         Remote directory is /dir1/dir2
7685         psftp> get filename.ext
7686         /dir1/dir2filename.ext: no such file or directory
7687
7688       This is not a bug in PSFTP. There is a known bug in some versions of
7689       portable OpenSSH (bug 697) that causes these symptoms; it appears
7690       to have been introduced around 3.7.x. It manifests only on certain
7691       platforms (AIX is what has been reported to us).
7692
7693       There is a patch for OpenSSH attached to that bug; it's also fixed
7694       in recent versions of portable OpenSSH (from around 3.8).
7695
7696A.7.19 Do you want to hear about `Software caused connection abort'?
7697
7698       In the documentation for PuTTY 0.53 and 0.53b, we mentioned that
7699       we'd like to hear about any occurrences of this error. Since the
7700       release of PuTTY 0.54, however, we've been convinced that this error
7701       doesn't indicate that PuTTY's doing anything wrong, and we don't
7702       need to hear about further occurrences. See section 10.15 for our
7703       current documentation of this error.
7704
7705A.7.20 My SSH-2 session locks up for a few seconds every so often.
7706
7707       Recent versions of PuTTY automatically initiate repeat key exchange
7708       once per hour, to improve session security. If your client or server
7709       machine is slow, you may experience this as a delay of anything up
7710       to thirty seconds or so.
7711
7712       These delays are inconvenient, but they are there for your
7713       protection. If they really cause you a problem, you can choose to
7714       turn off periodic rekeying using the `Kex' configuration panel (see
7715       section 4.19), but be aware that you will be sacrificing security
7716       for this. (Falling back to SSH-1 would also remove the delays, but
7717       would lose a _lot_ more security still. We do not recommend it.)
7718
7719A.7.21 PuTTY fails to start up. Windows claims that `the application
7720       configuration is incorrect'.
7721
7722       This is caused by a bug in certain versions of Windows XP which is
7723       triggered by PuTTY 0.58. This was fixed in 0.59. The `xp-wont-run'
7724       entry in PuTTY's wishlist has more details.
7725
7726A.7.22 When I put 32-bit PuTTY in C:\WINDOWS\SYSTEM32 on my 64-bit Windows
7727       system, `Duplicate Session' doesn't work.
7728
7729       The short answer is not to put the PuTTY executables in that
7730       location.
7731
7732       On 64-bit systems, C:\WINDOWS\SYSTEM32 is intended to contain
7733       only 64-bit binaries; Windows' 32-bit binaries live in
7734       C:\WINDOWS\SYSWOW64. When a 32-bit PuTTY executable runs on a 64-
7735       bit system, it cannot by default see the `real' C:\WINDOWS\SYSTEM32
7736       at all, because the File System Redirector arranges that the running
7737       program sees the appropriate kind of binaries in SYSTEM32. Thus,
7738       operations in the PuTTY suite that involve it accessing its own
7739       executables, such as `New Session' and `Duplicate Session', will not
7740       work.
7741
7742   A.8 Security questions
7743
7744 A.8.1 Is it safe for me to download PuTTY and use it on a public PC?
7745
7746       It depends on whether you trust that PC. If you don't trust the
7747       public PC, don't use PuTTY on it, and don't use any other software
7748       you plan to type passwords into either. It might be watching your
7749       keystrokes, or it might tamper with the PuTTY binary you download.
7750       There is _no_ program safe enough that you can run it on an actively
7751       malicious PC and get away with typing passwords into it.
7752
7753       If you do trust the PC, then it's probably OK to use PuTTY on it
7754       (but if you don't trust the network, then the PuTTY download might
7755       be tampered with, so it would be better to carry PuTTY with you on a
7756       USB stick).
7757
7758 A.8.2 What does PuTTY leave on a system? How can I clean up after it?
7759
7760       PuTTY will leave some Registry entries, and a random seed file, on
7761       the PC (see question A.5.2). Windows 7 and up also remember some
7762       information about recently launched sessions for the `jump list'
7763       feature.
7764
7765       If you are using PuTTY on a public PC, or somebody else's PC, you
7766       might want to clean this information up when you leave. You can do
7767       that automatically, by running the command `putty -cleanup'. See
7768       section 3.8.2 in the documentation for more detail. (Note that this
7769       only removes settings for the currently logged-in user on multi-user
7770       systems.)
7771
7772       If PuTTY was installed from the installer package, it will also
7773       appear in `Add/Remove Programs'. Current versions of the installer
7774       do not offer to remove the above-mentioned items, so if you want
7775       them removed you should run `putty -cleanup' before uninstalling.
7776
7777 A.8.3 How come PuTTY now supports DSA, when the website used to say how
7778       insecure it was?
7779
7780       DSA has a major weakness _if badly implemented_: it relies on a
7781       random number generator to far too great an extent. If the random
7782       number generator produces a number an attacker can predict, the DSA
7783       private key is exposed - meaning that the attacker can log in as you
7784       on all systems that accept that key.
7785
7786       The PuTTY policy changed because the developers were informed of
7787       ways to implement DSA which do not suffer nearly as badly from this
7788       weakness, and indeed which don't need to rely on random numbers at
7789       all. For this reason we now believe PuTTY's DSA implementation is
7790       probably OK.
7791
7792       The recently added elliptic-curve signature methods are also DSA-
7793       style algorithms, so they have this same weakness in principle. Our
7794       ECDSA implementation uses the same defence as DSA, while our Ed25519
7795       implementation uses the similar system (but different in details)
7796       that the Ed25519 spec mandates.
7797
7798 A.8.4 Couldn't Pageant use VirtualLock() to stop private keys being
7799       written to disk?
7800
7801       Unfortunately not. The VirtualLock() function in the Windows API
7802       doesn't do a proper job: it may prevent small pieces of a process's
7803       memory from being paged to disk while the process is running, but
7804       it doesn't stop the process's memory as a whole from being swapped
7805       completely out to disk when the process is long-term inactive. And
7806       Pageant spends most of its time inactive.
7807
7808   A.9 Administrative questions
7809
7810 A.9.1 Would you like me to register you a nicer domain name?
7811
7812       No, thank you. Even if you can find one (most of them seem to
7813       have been registered already, by people who didn't ask whether we
7814       actually wanted it before they applied), we're happy with the PuTTY
7815       web site being exactly where it is. It's not hard to find (just type
7816       `putty' into google.com and we're the first link returned), and we
7817       don't believe the administrative hassle of moving the site would be
7818       worth the benefit.
7819
7820       In addition, if we _did_ want a custom domain name, we would want to
7821       run it ourselves, so we knew for certain that it would continue to
7822       point where we wanted it, and wouldn't suddenly change or do strange
7823       things. Having it registered for us by a third party who we don't
7824       even know is not the best way to achieve this.
7825
7826 A.9.2 Would you like free web hosting for the PuTTY web site?
7827
7828       We already have some, thanks.
7829
7830 A.9.3 Would you link to my web site from the PuTTY web site?
7831
7832       Only if the content of your web page is of definite direct interest
7833       to PuTTY users. If your content is unrelated, or only tangentially
7834       related, to PuTTY, then the link would simply be advertising for
7835       you.
7836
7837       One very nice effect of the Google ranking mechanism is that by and
7838       large, the most popular web sites get the highest rankings. This
7839       means that when an ordinary person does a search, the top item in
7840       the search is very likely to be a high-quality site or the site they
7841       actually wanted, rather than the site which paid the most money for
7842       its ranking.
7843
7844       The PuTTY web site is held in high esteem by Google, for precisely
7845       this reason: lots of people have linked to it simply because they
7846       like PuTTY, without us ever having to ask anyone to link to us. We
7847       feel that it would be an abuse of this esteem to use it to boost the
7848       ranking of random advertisers' web sites. If you want your web site
7849       to have a high Google ranking, we'd prefer that you achieve this the
7850       way we did - by being good enough at what you do that people will
7851       link to you simply because they like you.
7852
7853       In particular, we aren't interested in trading links for money
7854       (see above), and we _certainly_ aren't interested in trading links
7855       for other links (since we have no advertising on our web site, our
7856       Google ranking is not even directly worth anything to us). If we
7857       don't want to link to you for free, then we probably won't want to
7858       link to you at all.
7859
7860       If you have software based on PuTTY, or specifically designed to
7861       interoperate with PuTTY, or in some other way of genuine interest to
7862       PuTTY users, then we will probably be happy to add a link to you on
7863       our Links page. And if you're running a particularly valuable mirror
7864       of the PuTTY web site, we might be interested in linking to you from
7865       our Mirrors page.
7866
7867 A.9.4 Why don't you move PuTTY to SourceForge?
7868
7869       Partly, because we don't want to move the web site location (see
7870       question A.9.1).
7871
7872       Also, security reasons. PuTTY is a security product, and as such it
7873       is particularly important to guard the code and the web site against
7874       unauthorised modifications which might introduce subtle security
7875       flaws. Therefore, we prefer that the Git repository, web site and
7876       FTP site remain where they are, under the direct control of system
7877       administrators we know and trust personally, rather than being run
7878       by a large organisation full of people we've never met and which is
7879       known to have had breakins in the past.
7880
7881       No offence to SourceForge; I think they do a wonderful job. But
7882       they're not ideal for everyone, and in particular they're not ideal
7883       for us.
7884
7885 A.9.5 Why can't I subscribe to the putty-bugs mailing list?
7886
7887       Because you're not a member of the PuTTY core development team. The
7888       putty-bugs mailing list is not a general newsgroup-like discussion
7889       forum; it's a contact address for the core developers, and an
7890       _internal_ mailing list for us to discuss things among ourselves.
7891       If we opened it up for everybody to subscribe to, it would turn
7892       into something more like a newsgroup and we would be completely
7893       overwhelmed by the volume of traffic. It's hard enough to keep up
7894       with the list as it is.
7895
7896 A.9.6 If putty-bugs isn't a general-subscription mailing list, what is?
7897
7898       There isn't one, that we know of.
7899
7900       If someone else wants to set up a mailing list or other forum for
7901       PuTTY users to help each other with common problems, that would
7902       be fine with us, though the PuTTY team would almost certainly not
7903       have the time to read it. It's probably better to use one of the
7904       established newsgroups for this purpose (see section B.1.2).
7905
7906 A.9.7 How can I donate to PuTTY development?
7907
7908       Please, _please_ don't feel you have to. PuTTY is completely free
7909       software, and not shareware. We think it's very important that
7910       _everybody_ who wants to use PuTTY should be able to, whether they
7911       have any money or not; so the last thing we would want is for a
7912       PuTTY user to feel guilty because they haven't paid us any money. If
7913       you want to keep your money, please do keep it. We wouldn't dream of
7914       asking for any.
7915
7916       Having said all that, if you still really _want_ to give us money,
7917       we won't argue :-) The easiest way for us to accept donations is if
7918       you send money to <anakin@pobox.com> using PayPal (www.paypal.com).
7919       If you don't like PayPal, talk to us; we can probably arrange some
7920       alternative means.
7921
7922       Small donations (tens of dollars or tens of euros) will probably
7923       be spent on beer or curry, which helps motivate our volunteer team
7924       to continue doing this for the world. Larger donations will be
7925       spent on something that actually helps development, if we can find
7926       anything (perhaps new hardware, or a copy of Windows XP), but if we
7927       can't find anything then we'll just distribute the money among the
7928       developers. If you want to be sure your donation is going towards
7929       something worthwhile, ask us first. If you don't like these terms,
7930       feel perfectly free not to donate. We don't mind.
7931
7932 A.9.8 Can I have permission to put PuTTY on a cover disk / distribute it
7933       with other software / etc?
7934
7935       Yes. For most things, you need not bother asking us explicitly for
7936       permission; our licence already grants you permission.
7937
7938       See section B.8 for more details.
7939
7940 A.9.9 Can you sign an agreement indemnifying us against security problems
7941       in PuTTY?
7942
7943       No!
7944
7945       A vendor of physical security products (e.g. locks) might plausibly
7946       be willing to accept financial liability for a product that failed
7947       to perform as advertised and resulted in damage (e.g. valuables
7948       being stolen). The reason they can afford to do this is because they
7949       sell a _lot_ of units, and only a small proportion of them will
7950       fail; so they can meet their financial liability out of the income
7951       from all the rest of their sales, and still have enough left over
7952       to make a profit. Financial liability is intrinsically linked to
7953       selling your product for money.
7954
7955       There are two reasons why PuTTY is not analogous to a physical
7956       lock in this context. One is that software products don't exhibit
7957       random variation: _if_ PuTTY has a security hole (which does happen,
7958       although we do our utmost to prevent it and to respond quickly
7959       when it does), every copy of PuTTY will have the same hole, so
7960       it's likely to affect all the users at the same time. So even if
7961       our users were all paying us to use PuTTY, we wouldn't be able to
7962       _simultaneously_ pay every affected user compensation in excess of
7963       the amount they had paid us in the first place. It just wouldn't
7964       work.
7965
7966       The second, much more important, reason is that PuTTY users _don't_
7967       pay us. The PuTTY team does not have an income; it's a volunteer
7968       effort composed of people spending their spare time to try to write
7969       useful software. We aren't even a company or any kind of legally
7970       recognised organisation. We're just a bunch of people who happen to
7971       do some stuff in our spare time.
7972
7973       Therefore, to ask us to assume financial liability is to ask us to
7974       assume a risk of having to pay it out of our own _personal_ pockets:
7975       out of the same budget from which we buy food and clothes and pay
7976       our rent. That's more than we're willing to give. We're already
7977       giving a lot of our spare _time_ to developing software for free; if
7978       we had to pay our own _money_ to do it as well, we'd start to wonder
7979       why we were bothering.
7980
7981       Free software fundamentally does not work on the basis of financial
7982       guarantees. Your guarantee of the software functioning correctly is
7983       simply that you have the source code and can check it before you
7984       use it. If you want to be sure there aren't any security holes, do
7985       a security audit of the PuTTY code, or hire a security engineer if
7986       you don't have the necessary skills yourself: instead of trying to
7987       ensure you can get compensation in the event of a disaster, try to
7988       ensure there isn't a disaster in the first place.
7989
7990       If you _really_ want financial security, see if you can find a
7991       security engineer who will take financial responsibility for the
7992       correctness of their review. (This might be less likely to suffer
7993       from the everything-failing-at-once problem mentioned above, because
7994       such an engineer would probably be reviewing a lot of _different_
7995       products which would tend to fail independently.) Failing that,
7996       see if you can persuade an insurance company to insure you against
7997       security incidents, and if the insurer demands it as a condition
7998       then get our code reviewed by a security engineer they're happy
7999       with.
8000
8001A.9.10 Can you sign this form granting us permission to use/distribute
8002       PuTTY?
8003
8004       If your form contains any clause along the lines of `the undersigned
8005       represents and warrants', we're not going to sign it. This is
8006       particularly true if it asks us to warrant that PuTTY is secure;
8007       see question A.9.9 for more discussion of this. But it doesn't
8008       really matter what we're supposed to be warranting: even if it's
8009       something we already believe is true, such as that we don't infringe
8010       any third-party copyright, we will not sign a document accepting
8011       any legal or financial liability. This is simply because the PuTTY
8012       development project has no income out of which to satisfy that
8013       liability, or pay legal costs, should it become necessary. We cannot
8014       afford to be sued. We are assuring you that _we have done our best_;
8015       if that isn't good enough for you, tough.
8016
8017       The existing PuTTY licence document already gives you permission
8018       to use or distribute PuTTY in pretty much any way which does not
8019       involve pretending you wrote it or suing us if it goes wrong. We
8020       think that really ought to be enough for anybody.
8021
8022       See also question A.9.12 for another reason why we don't want to do
8023       this sort of thing.
8024
8025A.9.11 Can you write us a formal notice of permission to use PuTTY?
8026
8027       We could, in principle, but it isn't clear what use it would be. If
8028       you think there's a serious chance of one of the PuTTY copyright
8029       holders suing you (which we don't!), you would presumably want a
8030       signed notice from _all_ of them; and we couldn't provide that even
8031       if we wanted to, because many of the copyright holders are people
8032       who contributed some code in the past and with whom we subsequently
8033       lost contact. Therefore the best we would be able to do _even
8034       in theory_ would be to have the core development team sign the
8035       document, which wouldn't guarantee you that some other copyright
8036       holder might not sue.
8037
8038       See also question A.9.12 for another reason why we don't want to do
8039       this sort of thing.
8040
8041A.9.12 Can you sign _anything_ for us?
8042
8043       Not unless there's an incredibly good reason.
8044
8045       We are generally unwilling to set a precedent that involves us
8046       having to enter into individual agreements with PuTTY users.
8047       We estimate that we have literally _millions_ of users, and we
8048       absolutely would not have time to go round signing specific
8049       agreements with every one of them. So if you want us to sign
8050       something specific for you, you might usefully stop to consider
8051       whether there's anything special that distinguishes you from 999,999
8052       other users, and therefore any reason we should be willing to sign
8053       something for you without it setting such a precedent.
8054
8055       If your company policy requires you to have an individual agreement
8056       with the supplier of any software you use, then your company policy
8057       is simply not well suited to using popular free software, and we
8058       urge you to consider this as a flaw in your policy.
8059
8060A.9.13 If you won't sign anything, can you give us some sort of assurance
8061       that you won't make PuTTY closed-source in future?
8062
8063       Yes and no.
8064
8065       If what you want is an assurance that some _current version_ of
8066       PuTTY which you've already downloaded will remain free, then you
8067       already have that assurance: it's called the PuTTY Licence. It
8068       grants you permission to use, distribute and copy the software to
8069       which it applies; once we've granted that permission (which we
8070       have), we can't just revoke it.
8071
8072       On the other hand, if you want an assurance that _future_ versions
8073       of PuTTY won't be closed-source, that's more difficult. We could
8074       in principle sign a document stating that we would never release a
8075       closed-source PuTTY, but that wouldn't assure you that we _would_
8076       keep releasing _open_-source PuTTYs: we would still have the option
8077       of ceasing to develop PuTTY at all, which would surely be even worse
8078       for you than making it closed-source! (And we almost certainly
8079       wouldn't _want_ to sign a document guaranteeing that we would
8080       actually continue to do development work on PuTTY; we certainly
8081       wouldn't sign it for free. Documents like that are called contracts
8082       of employment, and are generally not signed except in return for a
8083       sizeable salary.)
8084
8085       If we _were_ to stop developing PuTTY, or to decide to make all
8086       future releases closed-source, then you would still be free to copy
8087       the last open release in accordance with the current licence, and in
8088       particular you could start your own fork of the project from that
8089       release. If this happened, I confidently predict that _somebody_
8090       would do that, and that some kind of a free PuTTY would continue
8091       to be developed. There's already precedent for that sort of thing
8092       happening in free software. We can't guarantee that somebody _other
8093       than you_ would do it, of course; you might have to do it yourself.
8094       But we can assure you that there would be nothing _preventing_
8095       anyone from continuing free development if we stopped.
8096
8097       (Finally, we can also confidently predict that if we made PuTTY
8098       closed-source and someone made an open-source fork, most people
8099       would switch to the latter. Therefore, it would be pretty stupid of
8100       us to try it.)
8101
8102A.9.14 Can you provide us with export control information / FIPS
8103       certification for PuTTY?
8104
8105       Some people have asked us for an Export Control Classification
8106       Number (ECCN) for PuTTY. We don't know whether we have one, and as a
8107       team of free software developers based in the UK we don't have the
8108       time, money, or effort to deal with US bureaucracy to investigate
8109       any further. We believe that PuTTY falls under 5D002 on the US
8110       Commerce Control List, but that shouldn't be taken as definitive.
8111       If you need to know more you should seek professional legal advice.
8112       The same applies to any other country's legal requirements and
8113       restrictions.
8114
8115       Similarly, some people have asked us for FIPS certification of the
8116       PuTTY tools. Unless someone else is prepared to do the necessary
8117       work and pay any costs, we can't provide this.
8118
8119A.9.15 As one of our existing software vendors, can you just fill in this
8120       questionnaire for us?
8121
8122       We periodically receive requests like this, from organisations
8123       which have apparently sent out a form letter to everyone listed in
8124       their big spreadsheet of `software vendors' requiring them all to
8125       answer some long list of questions about supported OS versions, paid
8126       support arrangements, compliance with assorted local regulations
8127       we haven't heard of, contact phone numbers, and other such
8128       administrivia. Many of the questions are obviously meaningless when
8129       applied to PuTTY (we don't provide any paid support in the first
8130       place!), most of the rest could have been answered with only a very
8131       quick look at our website, and some we are actively unwilling to
8132       answer (we are private individuals, why would we want to give out
8133       our home phone numbers to large corporations?).
8134
8135       We don't make a habit of responding in full to these questionnaires,
8136       because _we are not a software vendor_.
8137
8138       A software _vendor_ is a company to which you are paying lots of
8139       money in return for some software. They know who you are, and they
8140       know you're paying them money; so they have an incentive to fill in
8141       your forms and questionnaires, to research any local regulations you
8142       cite if they don't already know about them, and generally to provide
8143       every scrap of information you might possibly need in the most
8144       convenient manner for you, because they want to keep being paid.
8145
8146       But we are a team of free software developers, and that means your
8147       relationship with us is nothing like that at all. If you once
8148       downloaded our software from our website, that's great and we hope
8149       you found it useful, but it doesn't mean we have the least idea who
8150       you are, or any incentive to do lots of unpaid work to support our
8151       `relationship' with you.
8152
8153       It's not that we are unwilling to _provide information_. We put as
8154       much of it as we can on our website for your convenience, and if you
8155       actually need to know some fact about PuTTY which you haven't been
8156       able to find on the website (and which is not obviously inapplicable
8157       to free software in the first place) then please do ask us, and
8158       we'll try to answer as best we can. But we put up the website and
8159       this FAQ precisely so that we _don't_ have to keep answering the
8160       same questions over and over again, so we aren't prepared to fill in
8161       completely generic form-letter questionnaires for people who haven't
8162       done their best to find the answers here first.
8163
8164       If you work for an organisation which you think might be at risk of
8165       making this mistake, we urge you to reorganise your list of software
8166       suppliers so that it clearly distinguishes paid vendors who know
8167       about you from free software developers who don't have any idea who
8168       you are. Then, only send out these mass mailings to the former.
8169
8170A.9.16 The `sha1sums' / `sha256sums' / etc files on your download page
8171       don't match the binaries.
8172
8173       People report this every so often, and usually the reason turns out
8174       to be that they've matched up the wrong checksums file with the
8175       wrong binaries.
8176
8177       The PuTTY download page contains more than one version of the
8178       software. There's a _latest release_ version; there are the
8179       _development snapshots_; and when we're in the run-up to making a
8180       release, there are also _pre-release_ builds of the upcoming new
8181       version. Each one has its own collection of binaries, and its own
8182       collection of checksums files to go with them.
8183
8184       So if you've downloaded the release version of the actual program,
8185       you need the release version of the checksums too, otherwise you
8186       will see a mismatch. Similarly, the development snapshot binaries go
8187       with the development snapshot checksums, and so on. (We've colour-
8188       coded the download page in an effort to reduce this confusion a
8189       bit.)
8190
8191       If you have double-checked that, and you still think there's a real
8192       mismatch, then please send us a report carefully quoting everything
8193       relevant:
8194
8195        -  the exact URL you got your binary from
8196
8197        -  the checksum of the binary after you downloaded
8198
8199        -  the exact URL you got your checksums file from
8200
8201        -  the checksum that file says the binary should have.
8202
8203  A.10 Miscellaneous questions
8204
8205A.10.1 Is PuTTY a port of OpenSSH, or based on OpenSSH or OpenSSL?
8206
8207       No, it isn't. PuTTY is almost completely composed of code written
8208       from scratch for PuTTY. The only code we share with OpenSSH is the
8209       detector for SSH-1 CRC compensation attacks, written by CORE SDI
8210       S.A; we share no code at all with OpenSSL.
8211
8212A.10.2 Where can I buy silly putty?
8213
8214       You're looking at the wrong web site; the only PuTTY we know about
8215       here is the name of a computer program.
8216
8217       If you want the kind of putty you can buy as an executive toy, the
8218       PuTTY team can personally recommend Thinking Putty, which you can
8219       buy from Crazy Aaron's Putty World, at www.puttyworld.com.
8220
8221A.10.3 What does `PuTTY' mean?
8222
8223       It's the name of a popular SSH and Telnet client. Any other meaning
8224       is in the eye of the beholder. It's been rumoured that `PuTTY' is
8225       the antonym of `getty', or that it's the stuff that makes your
8226       Windows useful, or that it's a kind of plutonium Teletype. We
8227       couldn't possibly comment on such allegations.
8228
8229A.10.4 How do I pronounce `PuTTY'?
8230
8231       Exactly like the English word `putty', which we pronounce /'pVti/.
8232
8233Appendix B: Feedback and bug reporting
8234--------------------------------------
8235
8236       This is a guide to providing feedback to the PuTTY development team.
8237       It is provided as both a web page on the PuTTY site, and an appendix
8238       in the PuTTY manual.
8239
8240       Section B.1 gives some general guidelines for sending any kind of e-
8241       mail to the development team. Following sections give more specific
8242       guidelines for particular types of e-mail, such as bug reports and
8243       feature requests.
8244
8245   B.1 General guidelines
8246
8247       The PuTTY development team gets a _lot_ of mail. If you can possibly
8248       solve your own problem by reading the manual, reading the FAQ,
8249       reading the web site, asking a fellow user, perhaps posting to a
8250       newsgroup (see section B.1.2), or some other means, then it would
8251       make our lives much easier.
8252
8253       We get so much e-mail that we literally do not have time to answer
8254       it all. We regret this, but there's nothing we can do about it.
8255       So if you can _possibly_ avoid sending mail to the PuTTY team, we
8256       recommend you do so. In particular, support requests (section B.6)
8257       are probably better sent to newsgroups, or passed to a local expert
8258       if possible.
8259
8260       The PuTTY contact email address is a private mailing list containing
8261       four or five core developers. Don't be put off by it being a mailing
8262       list: if you need to send confidential data as part of a bug report,
8263       you can trust the people on the list to respect that confidence.
8264       Also, the archives aren't publicly available, so you shouldn't be
8265       letting yourself in for any spam by sending us mail.
8266
8267       Please use a meaningful subject line on your message. We get a lot
8268       of mail, and it's hard to find the message we're looking for if they
8269       all have subject lines like `PuTTY bug'.
8270
8271 B.1.1 Sending large attachments
8272
8273       Since the PuTTY contact address is a mailing list, e-mails larger
8274       than 40Kb will be held for inspection by the list administrator, and
8275       will not be allowed through unless they really appear to be worth
8276       their large size.
8277
8278       If you are considering sending any kind of large data file to the
8279       PuTTY team, it's almost always a bad idea, or at the very least it
8280       would be better to ask us first whether we actually need the file.
8281       Alternatively, you could put the file on a web site and just send us
8282       the URL; that way, we don't have to download it unless we decide we
8283       actually need it, and only one of us needs to download it instead of
8284       it being automatically copied to all the developers.
8285
8286       (If the file contains confidential information, then you could
8287       encrypt it with our Secure Contact Key; see section E.1 for
8288       details.)
8289
8290       Some people like to send mail in MS Word format. Please _don't_
8291       send us bug reports, or any other mail, as a Word document. Word
8292       documents are roughly fifty times larger than writing the same
8293       report in plain text. In addition, most of the PuTTY team read their
8294       e-mail on Unix machines, so copying the file to a Windows box to run
8295       Word is very inconvenient. Not only that, but several of us don't
8296       even _have_ a copy of Word!
8297
8298       Some people like to send us screen shots when demonstrating a
8299       problem. Please don't do this without checking with us first
8300       - we almost never actually need the information in the screen
8301       shot. Sending a screen shot of an error box is almost certainly
8302       unnecessary when you could just tell us in plain text what the
8303       error was. (On some versions of Windows, pressing Ctrl-C when the
8304       error box is displayed will copy the text of the message to the
8305       clipboard.) Sending a full-screen shot is _occasionally_ useful, but
8306       it's probably still wise to check whether we need it before sending
8307       it.
8308
8309       If you _must_ mail a screen shot, don't send it as a .BMP file. BMPs
8310       have no compression and they are _much_ larger than other image
8311       formats such as PNG, TIFF and GIF. Convert the file to a properly
8312       compressed image format before sending it.
8313
8314       Please don't mail us executables, at all. Our mail server blocks all
8315       incoming e-mail containing executables, as a defence against the
8316       vast numbers of e-mail viruses we receive every day. If you mail us
8317       an executable, it will just bounce.
8318
8319       If you have made a tiny modification to the PuTTY code, please
8320       send us a _patch_ to the source code if possible, rather than
8321       sending us a huge .ZIP file containing the complete sources plus
8322       your modification. If you've only changed 10 lines, we'd prefer to
8323       receive a mail that's 30 lines long than one containing multiple
8324       megabytes of data we already have.
8325
8326 B.1.2 Other places to ask for help
8327
8328       There are two Usenet newsgroups that are particularly relevant to
8329       the PuTTY tools:
8330
8331        -  `comp.security.ssh', for questions specific to using the SSH
8332           protocol;
8333
8334        -  `comp.terminals', for issues relating to terminal emulation (for
8335           instance, keyboard problems).
8336
8337       Please use the newsgroup most appropriate to your query, and
8338       remember that these are general newsgroups, not specifically about
8339       PuTTY.
8340
8341       If you don't have direct access to Usenet, you can access these
8342       newsgroups through Google Groups (groups.google.com).
8343
8344   B.2 Reporting bugs
8345
8346       If you think you have found a bug in PuTTY, your first steps should
8347       be:
8348
8349        -  Check the Wishlist page on the PuTTY website, and see if we
8350           already know about the problem. If we do, it is almost certainly
8351           not necessary to mail us about it, unless you think you have
8352           extra information that might be helpful to us in fixing it. (Of
8353           course, if we actually _need_ specific extra information about a
8354           particular bug, the Wishlist page will say so.)
8355
8356        -  Check the Change Log on the PuTTY website, and see if we have
8357           already fixed the bug in the development snapshots.
8358
8359        -  Check the FAQ on the PuTTY website (also provided as appendix
8360           A in the manual), and see if it answers your question. The FAQ
8361           lists the most common things which people think are bugs, but
8362           which aren't bugs.
8363
8364        -  Download the latest development snapshot and see if the problem
8365           still happens with that. This really is worth doing. As a
8366           general rule we aren't very interested in bugs that appear in
8367           the release version but not in the development version, because
8368           that usually means they are bugs we have _already fixed_. On the
8369           other hand, if you can find a bug in the development version
8370           that doesn't appear in the release, that's likely to be a new
8371           bug we've introduced since the release and we're definitely
8372           interested in it.
8373
8374       If none of those options solved your problem, and you still need
8375       to report a bug to us, it is useful if you include some general
8376       information:
8377
8378        -  Tell us what version of PuTTY you are running. To find this
8379           out, use the `About PuTTY' option from the System menu. Please
8380           _do not_ just tell us `I'm running the latest version'; e-mail
8381           can be delayed and it may not be obvious which version was the
8382           latest at the time you sent the message.
8383
8384        -  PuTTY is a multi-platform application; tell us what version of
8385           what OS you are running PuTTY on. (If you're running on Unix, or
8386           Windows for Alpha, tell us, or we'll assume you're running on
8387           Windows for Intel as this is overwhelmingly the case.)
8388
8389        -  Tell us what protocol you are connecting with: SSH, Telnet,
8390           Rlogin or Raw mode.
8391
8392        -  Tell us what kind of server you are connecting to; what OS, and
8393           if possible what SSH server (if you're using SSH). You can get
8394           some of this information from the PuTTY Event Log (see section
8395           3.1.3.1 in the manual).
8396
8397        -  Send us the contents of the PuTTY Event Log, unless you have a
8398           specific reason not to (for example, if it contains confidential
8399           information that you think we should be able to solve your
8400           problem without needing to know).
8401
8402        -  Try to give us as much information as you can to help us see
8403           the problem for ourselves. If possible, give us a step-by-step
8404           sequence of _precise_ instructions for reproducing the fault.
8405
8406        -  Don't just tell us that PuTTY `does the wrong thing'; tell us
8407           exactly and precisely what it did, and also tell us exactly
8408           and precisely what you think it should have done instead. Some
8409           people tell us PuTTY does the wrong thing, and it turns out that
8410           it was doing the right thing and their expectations were wrong.
8411           Help to avoid this problem by telling us exactly what you think
8412           it should have done, and exactly what it did do.
8413
8414        -  If you think you can, you're welcome to try to fix the
8415           problem yourself. A patch to the code which fixes a bug is an
8416           excellent addition to a bug report. However, a patch is never a
8417           _substitute_ for a good bug report; if your patch is wrong or
8418           inappropriate, and you haven't supplied us with full information
8419           about the actual bug, then we won't be able to find a better
8420           solution.
8421
8422        -  https://www.chiark.greenend.org.uk/~sgtatham/bugs.html is an
8423           article on how to report bugs effectively in general. If your
8424           bug report is _particularly_ unclear, we may ask you to go away,
8425           read this article, and then report the bug again.
8426
8427       It is reasonable to report bugs in PuTTY's documentation, if you
8428       think the documentation is unclear or unhelpful. But we do need
8429       to be given exact details of _what_ you think the documentation
8430       has failed to tell you, or _how_ you think it could be made
8431       clearer. If your problem is simply that you don't _understand_ the
8432       documentation, we suggest posting to a newsgroup (see section B.1.2)
8433       and seeing if someone will explain what you need to know. _Then_, if
8434       you think the documentation could usefully have told you that, send
8435       us a bug report and explain how you think we should change it.
8436
8437   B.3 Reporting security vulnerabilities
8438
8439       If you've found a security vulnerability in PuTTY, you might well
8440       want to notify us using an encrypted communications channel, to
8441       avoid disclosing information about the vulnerability before a fixed
8442       release is available.
8443
8444       For this purpose, we provide a GPG key suitable for encryption: the
8445       Secure Contact Key. See section E.1 for details of this.
8446
8447       (Of course, vulnerabilities are also bugs, so please do include as
8448       much information as possible about them, the same way you would with
8449       any other bug report.)
8450
8451   B.4 Requesting extra features
8452
8453       If you want to request a new feature in PuTTY, the very first things
8454       you should do are:
8455
8456        -  Check the Wishlist page on the PuTTY website, and see if your
8457           feature is already on the list. If it is, it probably won't
8458           achieve very much to repeat the request. (But see section B.5 if
8459           you want to persuade us to give your particular feature higher
8460           priority.)
8461
8462        -  Check the Wishlist and Change Log on the PuTTY website, and
8463           see if we have already added your feature in the development
8464           snapshots. If it isn't clear, download the latest development
8465           snapshot and see if the feature is present. If it is, then it
8466           will also be in the next release and there is no need to mail us
8467           at all.
8468
8469       If you can't find your feature in either the development snapshots
8470       _or_ the Wishlist, then you probably do need to submit a feature
8471       request. Since the PuTTY authors are very busy, it helps if you try
8472       to do some of the work for us:
8473
8474        -  Do as much of the design as you can. Think about `corner cases';
8475           think about how your feature interacts with other existing
8476           features. Think about the user interface; if you can't come
8477           up with a simple and intuitive interface to your feature, you
8478           shouldn't be surprised if we can't either. Always imagine
8479           whether it's possible for there to be more than one, or less
8480           than one, of something you'd assumed there would be one of.
8481           (For example, if you were to want PuTTY to put an icon in the
8482           System tray rather than the Taskbar, you should think about what
8483           happens if there's more than one PuTTY active; how would the
8484           user tell which was which?)
8485
8486        -  If you can program, it may be worth offering to write the
8487           feature yourself and send us a patch. However, it is likely to
8488           be helpful if you confer with us first; there may be design
8489           issues you haven't thought of, or we may be about to make big
8490           changes to the code which your patch would clash with, or
8491           something. If you check with the maintainers first, there is a
8492           better chance of your code actually being usable. Also, read the
8493           design principles listed in appendix D: if you do not conform to
8494           them, we will probably not be able to accept your patch.
8495
8496   B.5 Requesting features that have already been requested
8497
8498       If a feature is already listed on the Wishlist, then it usually
8499       means we would like to add it to PuTTY at some point. However, this
8500       may not be in the near future. If there's a feature on the Wishlist
8501       which you would like to see in the _near_ future, there are several
8502       things you can do to try to increase its priority level:
8503
8504        -  Mail us and vote for it. (Be sure to mention that you've seen
8505           it on the Wishlist, or we might think you haven't even _read_
8506           the Wishlist). This probably won't have very _much_ effect; if
8507           a huge number of people vote for something then it may make a
8508           difference, but one or two extra votes for a particular feature
8509           are unlikely to change our priority list immediately. Offering a
8510           new and compelling justification might help. Also, don't expect
8511           a reply.
8512
8513        -  Offer us money if we do the work sooner rather than later. This
8514           sometimes works, but not always. The PuTTY team all have full-
8515           time jobs and we're doing all of this work in our free time; we
8516           may sometimes be willing to give up some more of our free time
8517           in exchange for some money, but if you try to bribe us for a
8518           _big_ feature it's entirely possible that we simply won't have
8519           the time to spare - whether you pay us or not. (Also, we don't
8520           accept bribes to add _bad_ features to the Wishlist, because
8521           our desire to provide high-quality software to the users comes
8522           first.)
8523
8524        -  Offer to help us write the code. This is probably the _only_ way
8525           to get a feature implemented quickly, if it's a big one that we
8526           don't have time to do ourselves.
8527
8528   B.6 Support requests
8529
8530       If you're trying to make PuTTY do something for you and it isn't
8531       working, but you're not sure whether it's a bug or not, then
8532       _please_ consider looking for help somewhere else. This is one of
8533       the most common types of mail the PuTTY team receives, and we simply
8534       don't have time to answer all the questions. Questions of this type
8535       include:
8536
8537        -  If you want to do something with PuTTY but have no idea where to
8538           start, and reading the manual hasn't helped, try posting to a
8539           newsgroup (see section B.1.2) and see if someone can explain it
8540           to you.
8541
8542        -  If you have tried to do something with PuTTY but it hasn't
8543           worked, and you aren't sure whether it's a bug in PuTTY or a bug
8544           in your SSH server or simply that you're not doing it right,
8545           then try posting to a newsgroup (see section B.1.2) and see if
8546           someone can solve your problem. Or try doing the same thing with
8547           a different SSH client and see if it works with that. Please do
8548           not report it as a PuTTY bug unless you are really sure it _is_
8549           a bug in PuTTY.
8550
8551        -  If someone else installed PuTTY for you, or you're using PuTTY
8552           on someone else's computer, try asking them for help first.
8553           They're more likely to understand how they installed it and what
8554           they expected you to use it for than we are.
8555
8556        -  If you have successfully made a connection to your server and
8557           now need to know what to type at the server's command prompt,
8558           or other details of how to use the server-end software, talk to
8559           your server's system administrator. This is not the PuTTY team's
8560           problem. PuTTY is only a communications tool, like a telephone;
8561           if you can't speak the same language as the person at the other
8562           end of the phone, it isn't the telephone company's job to teach
8563           it to you.
8564
8565       If you absolutely cannot get a support question answered any other
8566       way, you can try mailing it to us, but we can't guarantee to have
8567       time to answer it.
8568
8569   B.7 Web server administration
8570
8571       If the PuTTY web site is down (Connection Timed Out), please don't
8572       bother mailing us to tell us about it. Most of us read our e-mail on
8573       the same machines that host the web site, so if those machines are
8574       down then we will notice _before_ we read our e-mail. So there's no
8575       point telling us our servers are down.
8576
8577       Of course, if the web site has some other error (Connection Refused,
8578       404 Not Found, 403 Forbidden, or something else) then we might _not_
8579       have noticed and it might still be worth telling us about it.
8580
8581       If you want to report a problem with our web site, check that you're
8582       looking at our _real_ web site and not a mirror. The real web site
8583       is at `https://www.chiark.greenend.org.uk/~sgtatham/putty/'; if
8584       that's not where you're reading this, then don't report the problem
8585       to us until you've checked that it's really a problem with the
8586       main site. If it's only a problem with the mirror, you should try
8587       to contact the administrator of that mirror site first, and only
8588       contact us if that doesn't solve the problem (in case we need to
8589       remove the mirror from our list).
8590
8591   B.8 Asking permission for things
8592
8593       PuTTY is distributed under the MIT Licence (see appendix C for
8594       details). This means you can do almost _anything_ you like with our
8595       software, our source code, and our documentation. The only things
8596       you aren't allowed to do are to remove our copyright notices or the
8597       licence text itself, or to hold us legally responsible if something
8598       goes wrong.
8599
8600       So if you want permission to include PuTTY on a magazine cover disk,
8601       or as part of a collection of useful software on a CD or a web site,
8602       then _permission is already granted_. You don't have to mail us and
8603       ask. Just go ahead and do it. We don't mind.
8604
8605       (If you want to distribute PuTTY alongside your own application for
8606       use with that application, or if you want to distribute PuTTY within
8607       your own organisation, then we recommend, but do not insist, that
8608       you offer your own first-line technical support, to answer questions
8609       about the interaction of PuTTY with your environment. If your users
8610       mail us directly, we won't be able to tell them anything useful
8611       about your specific setup.)
8612
8613       If you want to use parts of the PuTTY source code in another
8614       program, then it might be worth mailing us to talk about technical
8615       details, but if all you want is to ask permission then you don't
8616       need to bother. You already have permission.
8617
8618       If you just want to link to our web site, just go ahead. (It's not
8619       clear that we _could_ stop you doing this, even if we wanted to!)
8620
8621   B.9 Mirroring the PuTTY web site
8622
8623       If you want to set up a mirror of the PuTTY website, go ahead and
8624       set one up. Please don't bother asking us for permission before
8625       setting up a mirror. You already have permission.
8626
8627       If the mirror is in a country where we don't already have plenty
8628       of mirrors, we may be willing to add it to the list on our mirrors
8629       page. Read the guidelines on that page, make sure your mirror works,
8630       and email us the information listed at the bottom of the page.
8631
8632       Note that we do not _promise_ to list your mirror: we get a lot of
8633       mirror notifications and yours may not happen to find its way to the
8634       top of the list.
8635
8636       Also note that we link to all our mirror sites using the
8637       `rel="nofollow"' attribute. Running a PuTTY mirror is not intended
8638       to be a cheap way to gain search rankings.
8639
8640       If you have technical questions about the process of mirroring, then
8641       you might want to mail us before setting up the mirror (see also the
8642       guidelines on the Mirrors page); but if you just want to ask for
8643       permission, you don't need to. You already have permission.
8644
8645  B.10 Praise and compliments
8646
8647       One of the most rewarding things about maintaining free software
8648       is getting e-mails that just say `thanks'. We are always happy to
8649       receive e-mails of this type.
8650
8651       Regrettably we don't have time to answer them all in person. If you
8652       mail us a compliment and don't receive a reply, _please_ don't think
8653       we've ignored you. We did receive it and we were happy about it; we
8654       just didn't have time to tell you so personally.
8655
8656       To everyone who's ever sent us praise and compliments, in the past
8657       and the future: _you're welcome_!
8658
8659  B.11 E-mail address
8660
8661       The actual address to mail is <putty@projects.tartarus.org>.
8662
8663Appendix C: PuTTY Licence
8664-------------------------
8665
8666       PuTTY is copyright 1997-2017 Simon Tatham.
8667
8668       Portions copyright Robert de Bath, Joris van Rantwijk, Delian
8669       Delchev, Andreas Schultz, Jeroen Massar, Wez Furlong, Nicolas Barry,
8670       Justin Bradford, Ben Harris, Malcolm Smith, Ahmad Khalifa, Markus
8671       Kuhn, Colin Watson, Christopher Staite, and CORE SDI S.A.
8672
8673       Permission is hereby granted, free of charge, to any person
8674       obtaining a copy of this software and associated documentation files
8675       (the `Software'), to deal in the Software without restriction,
8676       including without limitation the rights to use, copy, modify, merge,
8677       publish, distribute, sublicense, and/or sell copies of the Software,
8678       and to permit persons to whom the Software is furnished to do so,
8679       subject to the following conditions:
8680
8681       The above copyright notice and this permission notice shall be
8682       included in all copies or substantial portions of the Software.
8683
8684       THE SOFTWARE IS PROVIDED `AS IS', WITHOUT WARRANTY OF ANY KIND,
8685       EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
8686       OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
8687       NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE
8688       FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
8689       CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
8690       WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
8691
8692Appendix D: PuTTY hacking guide
8693-------------------------------
8694
8695       This appendix lists a selection of the design principles applying
8696       to the PuTTY source code. If you are planning to send code
8697       contributions, you should read this first.
8698
8699   D.1 Cross-OS portability
8700
8701       Despite Windows being its main area of fame, PuTTY is no longer a
8702       Windows-only application suite. It has a working Unix port; a Mac
8703       port is in progress; more ports may or may not happen at a later
8704       date.
8705
8706       Therefore, embedding Windows-specific code in core modules such as
8707       ssh.c is not acceptable. We went to great lengths to _remove_ all
8708       the Windows-specific stuff from our core modules, and to shift it
8709       out into Windows-specific modules. Adding large amounts of Windows-
8710       specific stuff in parts of the code that should be portable is
8711       almost guaranteed to make us reject a contribution.
8712
8713       The PuTTY source base is divided into platform-specific modules
8714       and platform-generic modules. The Unix-specific modules are all in
8715       the `unix' subdirectory; the Mac-specific modules are in the `mac'
8716       subdirectory; the Windows-specific modules are in the `windows'
8717       subdirectory.
8718
8719       All the modules in the main source directory - notably _all_ of the
8720       code for the various back ends - are platform-generic. We want to
8721       keep them that way.
8722
8723       This also means you should stick to what you are guaranteed by
8724       ANSI/ISO C (that is, the original C89/C90 standard, not C99). Try
8725       not to make assumptions about the precise size of basic types such
8726       as `int' and `long int'; don't use pointer casts to do endianness-
8727       dependent operations, and so on.
8728
8729       (There are one or two aspects of ANSI C portability which we _don't_
8730       care about. In particular, we expect PuTTY to be compiled on 32-
8731       bit architectures _or bigger_; so it's safe to assume that `int' is
8732       at least 32 bits wide, not just the 16 you are guaranteed by ANSI
8733       C. Similarly, we assume that the execution character encoding is
8734       a superset of the printable characters of ASCII, though we don't
8735       assume the numeric values of control characters, particularly '\n'
8736       and '\r'. Also, the X forwarding code assumes that `time_t' has the
8737       Unix format and semantics, i.e. an integer giving the number of
8738       seconds since 1970.)
8739
8740   D.2 Multiple backends treated equally
8741
8742       PuTTY is not an SSH client with some other stuff tacked on the side.
8743       PuTTY is a generic, multiple-backend, remote VT-terminal client
8744       which happens to support one backend which is larger, more popular
8745       and more useful than the rest. Any extra feature which can possibly
8746       be general across all backends should be so: localising features
8747       unnecessarily into the SSH back end is a design error. (For example,
8748       we had several code submissions for proxy support which worked by
8749       hacking ssh.c. Clearly this is completely wrong: the network.h
8750       abstraction is the place to put it, so that it will apply to all
8751       back ends equally, and indeed we eventually put it there after
8752       another contributor sent a better patch.)
8753
8754       The rest of PuTTY should try to avoid knowing anything about
8755       specific back ends if at all possible. To support a feature which is
8756       only available in one network protocol, for example, the back end
8757       interface should be extended in a general manner such that _any_
8758       back end which is able to provide that feature can do so. If it so
8759       happens that only one back end actually does, that's just the way it
8760       is, but it shouldn't be relied upon by any code.
8761
8762   D.3 Multiple sessions per process on some platforms
8763
8764       Some ports of PuTTY - notably the in-progress Mac port - are
8765       constrained by the operating system to run as a single process
8766       potentially managing multiple sessions.
8767
8768       Therefore, the platform-independent parts of PuTTY never use global
8769       variables to store per-session data. The global variables that do
8770       exist are tolerated because they are not specific to a particular
8771       login session: `flags' defines properties that are expected to apply
8772       equally to _all_ the sessions run by a single PuTTY process, the
8773       random number state in sshrand.c and the timer list in timing.c
8774       serve all sessions equally, and so on. But most data is specific to
8775       a particular network session, and is therefore stored in dynamically
8776       allocated data structures, and pointers to these structures are
8777       passed around between functions.
8778
8779       Platform-specific code can reverse this decision if it likes. The
8780       Windows code, for historical reasons, stores most of its data as
8781       global variables. That's OK, because _on Windows_ we know there is
8782       only one session per PuTTY process, so it's safe to do that. But
8783       changes to the platform-independent code should avoid introducing
8784       global variables, unless they are genuinely cross-session.
8785
8786   D.4 C, not C++
8787
8788       PuTTY is written entirely in C, not in C++.
8789
8790       We have made _some_ effort to make it easy to compile our code using
8791       a C++ compiler: notably, our `snew', `snewn' and `sresize' macros
8792       explicitly cast the return values of malloc and realloc to the
8793       target type. (This has type checking advantages even in C: it means
8794       you never accidentally allocate the wrong size piece of memory for
8795       the pointer type you're assigning it to. C++ friendliness is really
8796       a side benefit.)
8797
8798       We want PuTTY to continue being pure C, at least in the platform-
8799       independent parts and the currently existing ports. Patches which
8800       switch the Makefiles to compile it as C++ and start using classes
8801       will not be accepted. Also, in particular, we disapprove of //
8802       comments, at least for the moment. (Perhaps once C99 becomes
8803       genuinely widespread we might be more lenient.)
8804
8805       The one exception: a port to a new platform may use languages other
8806       than C if they are necessary to code on that platform. If your
8807       favourite PDA has a GUI with a C++ API, then there's no way you can
8808       do a port of PuTTY without using C++, so go ahead and use it. But
8809       keep the C++ restricted to that platform's subdirectory; if your
8810       changes force the Unix or Windows ports to be compiled as C++, they
8811       will be unacceptable to us.
8812
8813   D.5 Security-conscious coding
8814
8815       PuTTY is a network application and a security application. Assume
8816       your code will end up being fed deliberately malicious data by
8817       attackers, and try to code in a way that makes it unlikely to be a
8818       security risk.
8819
8820       In particular, try not to use fixed-size buffers for variable-size
8821       data such as strings received from the network (or even the user).
8822       We provide functions such as dupcat and dupprintf, which dynamically
8823       allocate buffers of the right size for the string they construct.
8824       Use these wherever possible.
8825
8826   D.6 Independence of specific compiler
8827
8828       Windows PuTTY can currently be compiled with any of four Windows
8829       compilers: MS Visual C, Borland's freely downloadable C compiler,
8830       the Cygwin / mingw32 GNU tools, and lcc-win32.
8831
8832       This is a really useful property of PuTTY, because it means people
8833       who want to contribute to the coding don't depend on having a
8834       specific compiler; so they don't have to fork out money for MSVC if
8835       they don't already have it, but on the other hand if they _do_ have
8836       it they also don't have to spend effort installing gcc alongside it.
8837       They can use whichever compiler they happen to have available, or
8838       install whichever is cheapest and easiest if they don't have one.
8839
8840       Therefore, we don't want PuTTY to start depending on which compiler
8841       you're using. Using GNU extensions to the C language, for example,
8842       would ruin this useful property (not that anyone's ever tried
8843       it!); and more realistically, depending on an MS-specific library
8844       function supplied by the MSVC C library (_snprintf, for example)
8845       is a mistake, because that function won't be available under the
8846       other compilers. Any function supplied in an official Windows DLL
8847       as part of the Windows API is fine, and anything defined in the C
8848       library standard is also fine, because those should be available
8849       irrespective of compilation environment. But things in between,
8850       available as non-standard library and language extensions in only
8851       one compiler, are disallowed.
8852
8853       (_snprintf in particular should be unnecessary, since we provide
8854       dupprintf; see section D.5.)
8855
8856       Compiler independence should apply on all platforms, of course, not
8857       just on Windows.
8858
8859   D.7 Small code size
8860
8861       PuTTY is tiny, compared to many other Windows applications. And
8862       it's easy to install: it depends on no DLLs, no other applications,
8863       no service packs or system upgrades. It's just one executable. You
8864       install that executable wherever you want to, and run it.
8865
8866       We want to keep both these properties - the small size, and the ease
8867       of installation - if at all possible. So code contributions that
8868       depend critically on external DLLs, or that add a huge amount to the
8869       code size for a feature which is only useful to a small minority of
8870       users, are likely to be thrown out immediately.
8871
8872       We do vaguely intend to introduce a DLL plugin interface for PuTTY,
8873       whereby seriously large extra features can be implemented in plugin
8874       modules. The important thing, though, is that those DLLs will be
8875       _optional_; if PuTTY can't find them on startup, it should run
8876       perfectly happily and just won't provide those particular features.
8877       A full installation of PuTTY might one day contain ten or twenty
8878       little DLL plugins, which would cut down a little on the ease of
8879       installation - but if you really needed ease of installation you
8880       _could_ still just install the one PuTTY binary, or just the DLLs
8881       you really needed, and it would still work fine.
8882
8883       Depending on _external_ DLLs is something we'd like to avoid if
8884       at all possible (though for some purposes, such as complex SSH
8885       authentication mechanisms, it may be unavoidable). If it can't be
8886       avoided, the important thing is to follow the same principle of
8887       graceful degradation: if a DLL can't be found, then PuTTY should run
8888       happily and just not supply the feature that depended on it.
8889
8890   D.8 Single-threaded code
8891
8892       PuTTY and its supporting tools, or at least the vast majority of
8893       them, run in only one OS thread.
8894
8895       This means that if you're devising some piece of internal mechanism,
8896       there's no need to use locks to make sure it doesn't get called by
8897       two threads at once. The only way code can be called re-entrantly is
8898       by recursion.
8899
8900       That said, most of Windows PuTTY's network handling is triggered
8901       off Windows messages requested by WSAAsyncSelect(), so if you call
8902       MessageBox() deep within some network event handling code you should
8903       be aware that you might be re-entered if a network event comes in
8904       and is passed on to our window procedure by the MessageBox() message
8905       loop.
8906
8907       Also, the front ends (in particular Windows Plink) can use multiple
8908       threads if they like. However, Windows Plink keeps _very_ tight
8909       control of its auxiliary threads, and uses them pretty much
8910       exclusively as a form of select(). Pretty much all the code outside
8911       windows/winplink.c is _only_ ever called from the one primary
8912       thread; the others just loop round blocking on file handles and
8913       send messages to the main thread when some real work needs doing.
8914       This is not considered a portability hazard because that bit of
8915       windows/winplink.c will need rewriting on other platforms in any
8916       case.
8917
8918       One important consequence of this: PuTTY has only one thread in
8919       which to do everything. That `everything' may include managing
8920       more than one login session (section D.3), managing multiple data
8921       channels within an SSH session, responding to GUI events even when
8922       nothing is happening on the network, and responding to network
8923       requests from the server (such as repeat key exchange) even when the
8924       program is dealing with complex user interaction such as the re-
8925       configuration dialog box. This means that _almost none_ of the PuTTY
8926       code can safely block.
8927
8928   D.9 Keystrokes sent to the server wherever possible
8929
8930       In almost all cases, PuTTY sends keystrokes to the server. Even
8931       weird keystrokes that you think should be hot keys controlling
8932       PuTTY. Even Alt-F4 or Alt-Space, for example. If a keystroke has a
8933       well-defined escape sequence that it could usefully be sending to
8934       the server, then it should do so, or at the very least it should be
8935       configurably able to do so.
8936
8937       To unconditionally turn a key combination into a hot key to control
8938       PuTTY is almost always a design error. If a hot key is really truly
8939       required, then try to find a key combination for it which _isn't_
8940       already used in existing PuTTYs (either it sends nothing to the
8941       server, or it sends the same thing as some other combination).
8942       Even then, be prepared for the possibility that one day that key
8943       combination might end up being needed to send something to the
8944       server - so make sure that there's an alternative way to invoke
8945       whatever PuTTY feature it controls.
8946
8947  D.10 640x480 friendliness in configuration panels
8948
8949       There's a reason we have lots of tiny configuration panels instead
8950       of a few huge ones, and that reason is that not everyone has a
8951       1600x1200 desktop. 640x480 is still a viable resolution for running
8952       Windows (and indeed it's still the default if you start up in safe
8953       mode), so it's still a resolution we care about.
8954
8955       Accordingly, the PuTTY configuration box, and the PuTTYgen control
8956       window, are deliberately kept just small enough to fit comfortably
8957       on a 640x480 display. If you're adding controls to either of these
8958       boxes and you find yourself wanting to increase the size of the
8959       whole box, _don't_. Split it into more panels instead.
8960
8961  D.11 Automatically generated Makefiles
8962
8963       PuTTY is intended to compile on multiple platforms, and with
8964       multiple compilers. It would be horrifying to try to maintain a
8965       single Makefile which handled all possible situations, and just as
8966       painful to try to directly maintain a set of matching Makefiles for
8967       each different compilation environment.
8968
8969       Therefore, we have moved the problem up by one level. In the PuTTY
8970       source archive is a file called `Recipe', which lists which source
8971       files combine to produce which binaries; and there is also a script
8972       called mkfiles.pl, which reads `Recipe' and writes out the real
8973       Makefiles. (The script also reads all the source files and analyses
8974       their dependencies on header files, so we get an extra benefit from
8975       doing it this way, which is that we can supply correct dependency
8976       information even in environments where it's difficult to set up an
8977       automated `make depend' phase.)
8978
8979       You should _never_ edit any of the PuTTY Makefiles directly.
8980       They are not stored in our source repository at all. They are
8981       automatically generated by mkfiles.pl from the file `Recipe'.
8982
8983       If you need to add a new object file to a particular binary, the
8984       right thing to do is to edit `Recipe' and re-run mkfiles.pl. This
8985       will cause the new object file to be added in every tool that
8986       requires it, on every platform where it matters, in every Makefile
8987       to which it is relevant, _and_ to get all the dependency data right.
8988
8989       If you send us a patch that modifies one of the Makefiles, you just
8990       waste our time, because we will have to convert it into a change
8991       to `Recipe'. If you send us a patch that modifies _all_ of the
8992       Makefiles, you will have wasted a lot of _your_ time as well!
8993
8994       (There is a comment at the top of every Makefile in the PuTTY source
8995       archive saying this, but many people don't seem to read it, so it's
8996       worth repeating here.)
8997
8998  D.12 Coroutines in ssh.c
8999
9000       Large parts of the code in ssh.c are structured using a set
9001       of macros that implement (something close to) Donald Knuth's
9002       `coroutines' concept in C.
9003
9004       Essentially, the purpose of these macros are to arrange that a
9005       function can call crReturn() to return to its caller, and the next
9006       time it is called control will resume from just after that crReturn
9007       statement.
9008
9009       This means that any local (automatic) variables declared in such
9010       a function will be corrupted every time you call crReturn. If you
9011       need a variable to persist for longer than that, you _must_ make it
9012       a field in one of the persistent state structures: either the local
9013       state structures `s' or `st' in each function, or the backend-wide
9014       structure `ssh'.
9015
9016       See `https://www.chiark.greenend.org.uk/~sgtatham/coroutines.html'
9017       for a more in-depth discussion of what these macros are for and how
9018       they work.
9019
9020  D.13 Single compilation of each source file
9021
9022       The PuTTY build system for any given platform works on the following
9023       very simple model:
9024
9025        -  Each source file is compiled precisely once, to produce a single
9026           object file.
9027
9028        -  Each binary is created by linking together some combination of
9029           those object files.
9030
9031       Therefore, if you need to introduce functionality to a particular
9032       module which is only available in some of the tool binaries (for
9033       example, a cryptographic proxy authentication mechanism which needs
9034       to be left out of PuTTYtel to maintain its usability in crypto-
9035       hostile jurisdictions), the _wrong_ way to do it is by adding
9036       #ifdefs in (say) proxy.c. This would require separate compilation
9037       of proxy.c for PuTTY and PuTTYtel, which means that the entire
9038       Makefile-generation architecture (see section D.11) would have to
9039       be significantly redesigned. Unless you are prepared to do that
9040       redesign yourself, _and_ guarantee that it will still port to any
9041       future platforms we might decide to run on, you should not attempt
9042       this!
9043
9044       The _right_ way to introduce a feature like this is to put the
9045       new code in a separate source file, and (if necessary) introduce
9046       a second new source file defining the same set of functions, but
9047       defining them as stubs which don't provide the feature. Then the
9048       module whose behaviour needs to vary (proxy.c in this example) can
9049       call the functions defined in these two modules, and it will either
9050       provide the new feature or not provide it according to which of your
9051       new modules it is linked with.
9052
9053       Of course, object files are never shared _between_ platforms; so it
9054       is allowable to use #ifdef to select between platforms. This happens
9055       in puttyps.h (choosing which of the platform-specific include files
9056       to use), and also in misc.c (the Windows-specific `Minefield' memory
9057       diagnostic system). It should be used sparingly, though, if at all.
9058
9059  D.14 Do as we say, not as we do
9060
9061       The current PuTTY code probably does not conform strictly to _all_
9062       of the principles listed above. There may be the occasional SSH-
9063       specific piece of code in what should be a backend-independent
9064       module, or the occasional dependence on a non-standard X library
9065       function under Unix.
9066
9067       This should not be taken as a licence to go ahead and violate the
9068       rules. Where we violate them ourselves, we're not happy about it,
9069       and we would welcome patches that fix any existing problems. Please
9070       try to help us make our code better, not worse!
9071
9072Appendix E: PuTTY download keys and signatures
9073----------------------------------------------
9074
9075       We create GPG signatures for all the PuTTY files distributed from
9076       our web site, so that users can be confident that the files have not
9077       been tampered with. Here we identify our public keys, and explain
9078       our signature policy so you can have an accurate idea of what each
9079       signature guarantees. This description is provided as both a web
9080       page on the PuTTY site, and an appendix in the PuTTY manual.
9081
9082       As of release 0.58, all of the PuTTY executables contain fingerprint
9083       material (usually accessed via the `-pgpfp' command-line option),
9084       such that if you have an executable you trust, you can use it to
9085       establish a trust path, for instance to a newer version downloaded
9086       from the Internet.
9087
9088       (Note that none of the keys, signatures, etc mentioned here have
9089       anything to do with keys used with SSH - they are purely for
9090       verifying the origin of files distributed by the PuTTY team.)
9091
9092   E.1 Public keys
9093
9094       We maintain multiple keys, stored with different levels of security
9095       due to being used in different ways. See section E.2 below for
9096       details.
9097
9098       The keys we provide are:
9099
9100       Snapshot Key
9101
9102           Used to sign routine development builds of PuTTY: nightly
9103           snapshots, pre-releases, and sometimes also custom diagnostic
9104           builds we send to particular users.
9105
9106       Release Key
9107
9108           Used to sign manually released versions of PuTTY.
9109
9110       Secure Contact Key
9111
9112           An encryption-capable key suitable for people to send
9113           confidential messages to the PuTTY team, e.g. reports of
9114           vulnerabilities.
9115
9116       Master Key
9117
9118           Used to tie all the above keys into the GPG web of trust. The
9119           Master Key signs all the other keys, and other GPG users have
9120           signed it in turn.
9121
9122       The current issue of those keys are available for download from the
9123       PuTTY website, and are also available on PGP keyservers using the
9124       key IDs listed below.
9125
9126       *Master Key*
9127
9128           RSA, 4096-bit. Key ID: 4096R/04676F7C (long
9129           version: 4096R/AB585DC604676F7C). Fingerprint:
9130           440D E3B5 B7A1 CA85 B3CC  1718 AB58 5DC6 0467 6F7C
9131
9132       *Release Key*
9133
9134           RSA, 2048-bit. Key ID: 2048R/B43434E4 (long
9135           version: 2048R/9DFE2648B43434E4). Fingerprint:
9136           0054 DDAA 8ADA 15D2 768A  6DE7 9DFE 2648 B434 34E4
9137
9138       *Secure Contact Key*
9139
9140           RSA, 2048-bit. Main key ID: 2048R/8A0AF00B (long version:
9141           2048R/C4FCAAD08A0AF00B). Encryption subkey ID: 2048R/50C2CF5C
9142           (long version: 2048R/9EB39CC150C2CF5C). Fingerprint:
9143           8A26 250E 763F E359 75F3  118F C4FC AAD0 8A0A F00B
9144
9145       *Snapshot Key*
9146
9147           RSA, 2048-bit. Key ID: 2048R/D15F7E8A (long
9148           version: 2048R/EEF20295D15F7E8A). Fingerprint:
9149           0A3B 0048 FE49 9B67 A234  FEB6 EEF2 0295 D15F 7E8A
9150
9151   E.2 Security details
9152
9153       The various keys have various different security levels. This
9154       section explains what those security levels are, and how far you can
9155       expect to trust each key.
9156
9157 E.2.1 The Development Snapshots key
9158
9159       The Development Snapshots private key is stored _without a
9160       passphrase_. This is necessary, because the snapshots are generated
9161       every night without human intervention, so nobody would be able to
9162       type a passphrase.
9163
9164       The snapshots are built and signed on a team member's home
9165       computers, before being uploaded to the web server from which you
9166       download them.
9167
9168       Therefore, a signature from the Development Snapshots key _DOES_
9169       protect you against:
9170
9171        -  People tampering with the PuTTY binaries between the PuTTY web
9172           site and you.
9173
9174        -  The maintainers of our web server attempting to abuse their root
9175           privilege to tamper with the binaries.
9176
9177       But it _DOES NOT_ protect you against:
9178
9179        -  People tampering with the binaries before they are uploaded to
9180           our download servers.
9181
9182        -  People tampering with the build machines so that the next set of
9183           binaries they build will be malicious in some way.
9184
9185        -  People stealing the unencrypted private key from the build
9186           machine it lives on.
9187
9188       Of course, we take all reasonable precautions to guard the build
9189       machines. But when you see a signature, you should always be certain
9190       of precisely what it guarantees and precisely what it does not.
9191
9192 E.2.2 The Releases key
9193
9194       The Releases key is more secure: because it is only used at release
9195       time, to sign each release by hand, we can store it encrypted.
9196
9197       The Releases private key is kept encrypted on the developers' own
9198       local machines. So an attacker wanting to steal it would have to
9199       also steal the passphrase.
9200
9201 E.2.3 The Secure Contact Key
9202
9203       The Secure Contact Key is stored with a similar level of security to
9204       the Release Key: it is stored with a passphrase, and no automated
9205       script has access to it.
9206
9207 E.2.4 The Master Keys
9208
9209       The Master Key signs almost nothing. Its purpose is to bind the
9210       other keys together and certify that they are all owned by the same
9211       people and part of the same integrated setup. The only signatures
9212       produced by the Master Key, _ever_, should be the signatures on the
9213       other keys.
9214
9215       The Master Key is especially long, and its private key and
9216       passphrase are stored with special care.
9217
9218       We have collected some third-party signatures on the Master Key, in
9219       order to increase the chances that you can find a suitable trust
9220       path to them.
9221
9222       We have uploaded our various keys to public keyservers, so that even
9223       if you don't know any of the people who have signed our keys, you
9224       can still be reasonably confident that an attacker would find it
9225       hard to substitute fake keys on all the public keyservers at once.
9226
9227   E.3 Key rollover
9228
9229       Our current keys were generated in September 2015, except for the
9230       Secure Contact Key which was generated in February 2016 (we didn't
9231       think of it until later).
9232
9233       Prior to that, we had a much older set of keys generated in 2000.
9234       For each of the key types above (other than the Secure Contact Key),
9235       we provided both an RSA key _and_ a DSA key (because at the time we
9236       generated them, RSA was not in practice available to everyone, due
9237       to export restrictions).
9238
9239       The new Master Key is signed with both of the old ones, to show
9240       that it really is owned by the same people and not substituted by
9241       an attacker. Also, we have retrospectively signed the old Release
9242       Keys with the new Master Key, in case you're trying to verify the
9243       signatures on a release prior to the rollover and can find a chain
9244       of trust to those keys from any of the people who have signed our
9245       new Master Key.
9246
9247       Future releases will be signed with the up-to-date keys shown above.
9248       Releases prior to the rollover are signed with the old Release Keys.
9249
9250       For completeness, those old keys are given here:
9251
9252       *Master Key* (original RSA)
9253
9254           RSA, 1024-bit. Key ID: 1024R/1E34AC41 (long
9255           version: 1024R/9D5877BF1E34AC41). Fingerprint:
9256           8F 15 97 DA 25 30 AB 0D  88 D1 92 54 11 CF 0C 4C
9257
9258       *Master Key* (original DSA)
9259
9260           DSA, 1024-bit. Key ID: 1024D/6A93B34E (long
9261           version: 1024D/4F5E6DF56A93B34E). Fingerprint:
9262           313C 3E76 4B74 C2C5 F2AE  83A8 4F5E 6DF5 6A93 B34E
9263
9264       *Release Key* (original RSA)
9265
9266           RSA, 1024-bit. Key ID: 1024R/B41CAE29 (long
9267           version: 1024R/EF39CCC0B41CAE29). Fingerprint:
9268           AE 65 D3 F7 85 D3 18 E0  3B 0C 9B 02 FF 3A 81 FE
9269
9270       *Release Key* (original DSA)
9271
9272           DSA, 1024-bit. Key ID: 1024D/08B0A90B (long
9273           version: 1024D/FECD6F3F08B0A90B). Fingerprint:
9274           00B1 1009 38E6 9800 6518  F0AB FECD 6F3F 08B0 A90B
9275
9276       *Snapshot Key* (original RSA)
9277
9278           RSA, 1024-bit. Key ID: 1024R/32B903A9 (long
9279           version: 1024R/FAAED21532B903A9). Fingerprint:
9280           86 8B 1F 79 9C F4 7F BD  8B 1B D7 8E C6 4E 4C 03
9281
9282       *Snapshot Key* (original DSA)
9283
9284           DSA, 1024-bit. Key ID: 1024D/7D3E4A00 (long
9285           version: 1024D/165E56F77D3E4A00). Fingerprint:
9286           63DD 8EF8 32F5 D777 9FF0  2947 165E 56F7 7D3E 4A00
9287
9288Appendix F: SSH-2 names specified for PuTTY
9289-------------------------------------------
9290
9291       There are various parts of the SSH-2 protocol where things
9292       are specified using a textual name. Names ending in
9293       @putty.projects.tartarus.org are reserved for allocation by the
9294       PuTTY team. Allocated names are documented here.
9295
9296   F.1 Connection protocol channel request names
9297
9298       These names can be sent in a SSH_MSG_CHANNEL_REQUEST message.
9299
9300       simple@putty.projects.tartarus.org
9301
9302           This is sent by a client to announce that it will not have more
9303           than one channel open at a time in the current connection (that
9304           one being the one the request is sent on). The intention is that
9305           the server, knowing this, can set the window on that one channel
9306           to something very large, and leave flow control to TCP. There is
9307           no message-specific data.
9308
9309       winadj@putty.projects.tartarus.org
9310
9311           PuTTY sends this request along with some
9312           SSH_MSG_CHANNEL_WINDOW_ADJUST messages as part of its window-
9313           size tuning. It can be sent on any type of channel. There is no
9314           message-specific data. Servers MUST treat it as an unrecognised
9315           request and respond with SSH_MSG_CHANNEL_FAILURE.
9316
9317           (Some SSH servers get confused by this message, so there is a
9318           bug-compatibility mode for disabling it. See section 4.27.5.)
9319
9320   F.2 Key exchange method names
9321
9322       rsa-sha1-draft-00@putty.projects.tartarus.org
9323
9324       rsa-sha256-draft-00@putty.projects.tartarus.org
9325
9326       rsa1024-sha1-draft-01@putty.projects.tartarus.org
9327
9328       rsa1024-sha256-draft-01@putty.projects.tartarus.org
9329
9330       rsa2048-sha256-draft-01@putty.projects.tartarus.org
9331
9332       rsa1024-sha1-draft-02@putty.projects.tartarus.org
9333
9334       rsa2048-sha512-draft-02@putty.projects.tartarus.org
9335
9336       rsa1024-sha1-draft-03@putty.projects.tartarus.org
9337
9338       rsa2048-sha256-draft-03@putty.projects.tartarus.org
9339
9340       rsa1024-sha1-draft-04@putty.projects.tartarus.org
9341
9342       rsa2048-sha256-draft-04@putty.projects.tartarus.org
9343
9344           These appeared in various drafts of what eventually became
9345           RFC 4432. They have been superseded by rsa1024-sha1 and rsa2048-
9346           sha256.
9347
9348   F.3 Encryption algorithm names
9349
9350       arcfour128-draft-00@putty.projects.tartarus.org
9351
9352       arcfour256-draft-00@putty.projects.tartarus.org
9353
9354           These were used in drafts of what eventually became RFC 4345.
9355           They have been superseded by arcfour128 and arcfour256.
9356
9357[PuTTY release 0.70]