_Actually_ add the new-look PuTTY FAQ. When will I remember to run "cvs add"?

[u/mdw/putty] / doc / faq.but

\A{faq} PuTTY FAQ

This FAQ is published on the PuTTY web site, and also provided as an
appendix in the manual.

\H{faq-support} Features supported in PuTTY

In general, if you want to know if PuTTY supports a particular
feature, you should look for it on the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/}{PuTTY web site}.
In particular:

\b try the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{changes
page}, and see if you can find the feature on there. If a feature is
listed there, it's been implemented. If it's listed as a change made
\e{since} the latest version, it should be available in the
development snapshots, in which case testing will be very welcome.

\b try the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist.html}{Wishlist
page}, and see if you can find the feature there. If it's on there,
it probably \e{hasn't} been implemented.

\S{faq-ssh2} Does PuTTY support SSH v2?

Yes. SSH v2 support has been available in PuTTY since version 0.50.
However, currently the \e{default} SSH protocol is v1; to select SSH
v2 if your server supports both, go to the SSH panel and change the
\e{Preferred SSH protocol version} option.

Public key authentication (both RSA and DSA) in SSH v2 has been
added since version 0.51.

\S{faq-ssh2-keyfmt} Does PuTTY support reading OpenSSH or
\cw{ssh.com} SSHv2 private key files?

Not at present. OpenSSH and \cw{ssh.com} have totally different
formats for private key files, and neither one is particularly
pleasant, so PuTTY has its own. We do plan to write a converter at
some stage.

\S{faq-ssh1} Does PuTTY support SSH v1?

Yes. SSH 1 support has always been available in PuTTY.

\S{faq-localecho} Does PuTTY support local echo?

Yes.

In version 0.51 and before, local echo cannot be separated from
local line editing (where you type a line of text locally, and it is
not sent to the server until you press Return, so you have the
chance to edit it and correct mistakes \e{before} the server sees
it). The two features can be enabled and disabled from the Terminal
panel, using the checkbox marked \q{Use local terminal line
discipline}. Note that due to a bug in those versions of PuTTY,
changing this feature in mid-session will have no effect; you have
to enable it \e{before} you open the connection.

In later versions, local echo and local line editing are separate
options, and by default PuTTY will try to determine automatically
whether to enable them or not, based on which protocol you have
selected and also based on hints from the server. If you have a
problem with PuTTY's default choice, you can force each option to be
enabled or disabled as you choose. The controls are in the Terminal
panel, in the section marked \q{Line discipline options}.

\S{faq-disksettings} Does PuTTY support storing its settings in a
disk file?

Not at present, although \k{config-file} in the documentation gives
a method of achieving the same effect.

\S{faq-fullscreen} Does PuTTY support full-screen mode, like a DOS
box?

Not in the 0.51 release, but it has been added since then.

\S{faq-password} Does PuTTY have the ability to remember my password
so I don't have to type it every time?

No, it doesn't.

Remembering your password is a bad plan for obvious security
reasons: anyone who gains access to your machine while you're away
from your desk can find out the remembered password, and use it,
abuse it or change it.

In addition, it's not even \e{possible} for PuTTY to automatically
send your password in a Telnet session, because Telnet doesn't give
the client software any indication of which part of the login
process is the password prompt. PuTTY would have to guess, by
looking for words like \q{password} in the session data; and if your
login program is written in something other than English, this won't
work.

In SSH, remembering your password would be possible in theory, but
there doesn't seem to be much point since SSH supports public key
authentication, which is more flexible and more secure. See
\k{pubkey} in the documentation for a full discussion of public key
authentication.

\H{faq-ports} Ports to other operating systems

The eventual goal is for PuTTY to be a multi-platform program, able
to run on at least Windows, MacOS and Unix. Whether this will
actually ever happen I have no idea, but it is the plan. A Mac port
has been started, but is only half-finished and currently not moving
very fast.

Porting will become easier once PuTTY has a generalised porting
layer, drawing a clear line between platform-dependent and
platform-independent code. The general intention is for this porting
layer to evolve naturally as part of the process of doing the first
port. One particularly nasty part of this will be separating the
many configuration options into platform-dependent and
platform-independent ones; for example, the options controlling when
the Windows System menu appears will be pretty much meaningless
under X11 or perhaps other windowing systems, whereas Telnet Passive
Mode is universal and shouldn't need to be specified once for each
platform.

\S{faq-wince} Will there be a port to Windows CE?

Probably not in the particularly near future. Despite sharing large
parts of the Windows API, in practice WinCE doesn't appear to be
significantly easier to port to than a totally different operating
system.

However, PuTTY on portable devices would clearly be a useful thing,
so in the long term I hope there will be a WinCE port.

\S{faq-mac} Will there be a port to the Mac?

A Mac port was started once and is half-finished, but development
has been static for some time and the main PuTTY code has moved on,
so it's not clear how quickly development would resume even if
developer effort were available.

\S{faq-unix} Will there be a port to Unix?

I hope so, if only so that I can have an \cw{xterm}-like program
that supports exactly the same terminal emulation as PuTTY. If and
when we do do a Unix port, it will have a local-terminal back end so
it can be used like an \cw{xterm}, rather than only being usable as
a network utility.

\S{faq-epoc} Will there be a port to EPOC?

I hope so, but given that ports aren't really progressing very fast
even on systems the developers \e{do} already know how to program
for, it might be a long time before any of us get round to learning
a new system and doing the port for that.

\H{faq-embedding} Embedding PuTTY in other programs

\S{faq-dll} Is the SSH or Telnet code available as a DLL?

No, it isn't. It would take a reasonable amount of rewriting for
this to be possible, and since the PuTTY project itself doesn't
believe in DLLs (they make installation more error-prone) none of us
has taken the time to do it.

Most of the code cleanup work would be a good thing to happen in
general, so if anyone feels like helping, we wouldn't say no.

\S{faq-vb} Is the SSH or Telnet code available as a Visual Basic
component?

No, it isn't. None of the PuTTY team uses Visual Basic, and none of
us has any particular need to make SSH connections from a Visual
Basic application. In addition, all the preliminary work to turn it
into a DLL would be necessary first; and furthermore, we don't even
know how to write VB components.

If someone offers to do some of this work for us, we might consider
it, but unless that happens I can't see VB integration being
anywhere other than the very bottom of our priority list.

\S{faq-ipc} How can I use PuTTY to make an SSH connection from
within another program?

Probably your best bet is to use Plink, the command-line connection
tool. If you can start Plink as a second Windows process, and
arrange for your primary process to be able to send data to the
Plink process, and receive data from it, through pipes, then you
should be able to make SSH connections from your program.

This is what CVS for Windows does, for example.

\H{faq-details} Details of PuTTY's operation

\S{faq-term} What terminal type does PuTTY use?

For most purposes, PuTTY can be considered to be an \cw{xterm}
terminal, although full support for some of \cw{xterm}'s features,
such as passing mouse actions to the server-side program, is not
present in the 0.51 release (but has been added since).

PuTTY also supports some terminal control sequences not supported by
the real \cw{xterm}: notably the Linux console sequences that
reconfigure the colour palette, and the title bar control sequences
used by \cw{DECterm} (which are different from the \cw{xterm} ones;
PuTTY supports both).

By default, PuTTY announces its terminal type to the server as
\c{xterm}. If you have a problem with this, you can reconfigure it
to say something else; \c{vt220} might help if you have trouble.

\S{faq-settings} Where does PuTTY store its data?

PuTTY stores most of its data (saved sessions, SSH host keys) in the
Registry. The precise location is

\c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY

and within that area, saved sessions are stored under \c{Sessions}
while host keys are stored under \c{SshHostKeys}.

PuTTY also requires a random number seed file, to improve the
unpredictability of randomly chosen data needed as part of the SSH
cryptography. This is stored by default in your Windows home
directory (\c{%HOMEDRIVE%\\%HOMEPATH%}), or in the actual Windows
directory (such as \c{C:\\WINDOWS}) if the home directory doesn't
exist, for example if you're using Win95. If you want to change the
location of the random number seed file, you can put your chosen
pathname in the Registry, at

\c HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\RandSeedFile

\H{faq-howto} HOWTO questions

\S{faq-startmax} How can I make PuTTY start up maximised?

Create a Windows shortcut to start PuTTY from, and set it as \q{Run
Maximized}.

\S{faq-startsess} How can I create a Windows shortcut to start a
particular saved session directly?

To run a PuTTY session saved under the name \q{\cw{mysession}},
create a Windows shortcut that invokes PuTTY with a command line
like

\c \path\name\to\putty.exe @mysession

\S{faq-startssh} How can I start an SSH session straight from the
command line?

Use the command line \c{putty -ssh host.name}. Alternatively, create
a saved session that specifies the SSH protocol, and start the saved
session as shown in \k{faq-startsess}.

\S{faq-cutpaste} How do I copy and paste between PuTTY and other
Windows applications?

Copy and paste works similarly to the X Window System. You use the
left mouse button to select text in the PuTTY window. The act of
selection \e{automatically} copies the text to the clipboard: there
is no need to press Ctrl-Ins or Ctrl-C or anything else. In fact,
pressing Ctrl-C will send a Ctrl-C character to the other end of
your connection (just like it does the rest of the time), which may
have unpleasant effects. The \e{only} thing you need to do, to copy
text to the clipboard, is to select it.

To paste the clipboard contents into a PuTTY window, by default you
click the right mouse button. If you have a three-button mouse and
are used to X applications, you can configure pasting to be done by
the middle button instead, but this is not the default because most
Windows users don't have a middle button at all.

You can also paste by pressing Shift-Ins.

\S{faq-pscp} How do I use PSCP.EXE? When I double-click it gives me
a command prompt window which then closes instantly.

PSCP is a command-line application, not a GUI application. If you
run it without arguments, it will simply print a help message and
terminate.

To use PSCP properly, run it from a Command Prompt window. See
\k{pscp} in the documentation for more details.

\S{faq-pscp-spaces} How do I use PSCP to copy a file whose name has
spaces in?

If PSCP is using the traditional SCP protocol, this is confusing. If
you're specifying a file at the local end, you just use one set of
quotes as you would normally do:

\c pscp "local filename with spaces" user@host:
\c pscp user@host:myfile "local filename with spaces"

But if the filename you're specifying is on the \e{remote} side, you
have to use backslashes and two sets of quotes:

\c pscp user@host:"\"remote filename with spaces\"" local_filename
\c pscp local_filename user@host:"\"remote filename with spaces\""

Worse still, in a remote-to-local copy you have to specify the local
file name explicitly, otherwise PSCP will complain that they don't
match (unless you specified the \c{-unsafe} option). The following
command will give an error message:

\c c:\>pscp user@host:"\"oo er\"" .
\c warning: remote host tried to write to a file called 'a b'
\c          when we requested a file called '"a b"'.
\c          If this is a wildcard, consider upgrading to SSH 2 or using
\c          the '-unsafe' option. Renaming of this file has been disallowed.

If PSCP is using the newer SFTP protocol, none of this is a problem,
and all filenames with spaces in are specified using a single pair
of quotes in the obvious way:

\c pscp "local file" user@host:
\c pscp user@host:"remote file" .

\H{faq-trouble} Troubleshooting

\S{faq-mac} Why do I see \q{Incorrect MAC received on packet}?

This is due to a bug in old SSH 2 servers distributed by
\cw{ssh.com}. Version 2.3.0 and below of their SSH 2 server
constructs Message Authentication Codes in the wrong way, and
expects the client to construct them in the same wrong way. PuTTY
constructs the MACs correctly by default, and hence these old
servers will fail to work with it.

If you are using PuTTY version 0.51 or below, go to the SSH panel
and check the box labelled \q{Imitate SSH 2 MAC bug}. This will
cause PuTTY to construct its MACs in the same incorrect manner as
the buggy servers, so it will be able to work with them.

Since version 0.51, PuTTY has been enhanced to detect buggy servers
automatically (when they announce their version) and enable the
workaround without the user needing to ask. Therefore you \e{should}
never have to use this option again after 0.52, but it is still
provided just in case another buggy server shows up.

\S{faq-colours} I clicked on a colour in the Colours panel, and the
colour didn't change in my terminal.

That isn't how you're supposed to use the Colours panel.

During the course of a session, PuTTY potentially uses \e{all} the
colours listed in the Colours panel. It's not a question of using
only one of them and you choosing which one; PuTTY will use them
\e{all}. The purpose of the Colours panel is to let you adjust the
appearance of all the colours. So to change the colour of the
cursor, for example, you would select \q{Cursor Colour}, press the
\q{Modify} button, and select a new colour from the dialog box that
appeared. Similarly, if you want your session to appear in green,
you should select \q{Default Foreground} and press \q{Modify}.
Clicking on \q{ANSI Green} won't turn your session green; it will
only allow you to adjust the \e{shade} of green used when PuTTY is
instructed by the server to display green text.

\S{faq-winsock2} Plink on Windows 95 says it can't find \cw{WS2_32.DLL}.

Plink requires the extended Windows network library, WinSock version
2. This is installed as standard on Windows 98 and above, and on
Windows NT, and even on later versions of Windows 95; but early
Win95 installations don't have it.

In order to use Plink on these systems, you will need to download
the
\W{http://www.microsoft.com/windows95/downloads/contents/wuadmintools/s_wunetworkingtools/w95sockets2/}{WinSock 2 upgrade}:

\c http://www.microsoft.com/windows95/downloads/contents/wuadmintools/
\c   s_wunetworkingtools/w95sockets2/

\S{faq-rekey} My PuTTY sessions close after an hour and tell me
\q{Server failed host key check}.

This is a bug in all versions of PuTTY up to and including 0.51. SSH
v2 servers from \cw{ssh.com} will require the key exchange to be
repeated one hour after the start of the connection, and PuTTY will
get this wrong.

The bug has been fixed since version 0.51, so upgrading to a later
version or snapshot should solve the problem.

\S{faq-outofmem} After trying to establish an SSH connection, PuTTY
says \q{Out of memory} and dies.

If this happens just while the connection is starting up, this often
indicates that for some reason the client and server have failed to
establish a session encryption key. Somehow, they have performed
calculations that should have given each of them the same key, but
have ended up with different keys; so data encrypted by one and
decrypted by the other looks like random garbage.

This causes an \q{out of memory} error because the first encrypted
data PuTTY expects to see is the length of an SSH message. Normally
this will be something well under 100 bytes. If the decryption has
failed, PuTTY will see a completely random length in the region of
two \e{gigabytes}, and will try to allocate enough memory to store
this non-existent message. This will immediately lead to it thinking
it doesn't have enough memory, and panicking.

If this happens to you, it is quite likely to still be a PuTTY bug
and you should report it (although it might be a bug in your SSH
server instead); but it doesn't necessarily mean you've actually run
out of memory.

\S{faq-altgr} I can't type characters that require the AltGr key.

In PuTTY version 0.51, the AltGr key was broken. The bug has been
fixed since then.

\S{faq-idleout} My PuTTY sessions unexpectedly close after they
are idle for a while.

Some types of firewall, and almost any router doing Network Address
Translation (NAT, also known as IP masquerading), will forget about
a connection through them if the connection does nothing for too
long. This will cause the connection to be rudely cut off when
contact is resumed.

You can try to combat this by telling PuTTY to send \e{keepalives}:
packets of data which have no effect on the actual session, but
which reassure the router or firewall that the network connection is
still active and worth remembering about.

Keepalives don't solve everything, unfortunately; although they
cause greater robustness against this sort of router, they can also
cause a \e{loss} of robustness against network dropouts. See
\k{config-keepalive} in the documentation for more discussion of
this.

\S{faq-timeout} PuTTY's network connections time out too quickly
when network connectivity is temporarily lost.

This is a Windows problem, not a PuTTY problem. The timeout value
can't be set on per application or per session basis. To increase
the TCP timeout globally, you need to tinker with the Registry.

On Windows 95, 98 or ME, the registry key you need to change is

\c HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\
\c   MSTCP\MaxDataRetries

(it must be of type DWORD in Win95, or String in Win98/ME).

On Windows NT or 2000, the registry key is

\c HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\
\c   Parameters\TcpMaxDataRetransmissions

and it must be of type DWORD.

Set the key's value to something like 10. This will cause Windows to
try harder to keep connections alive instead of abandoning them.

\S{faq-puttyputty} When I \cw{cat} a binary file, I get
`PuTTYPuTTYPuTTY' on my command line.

Don't \cw{cat} binary files, then.

This is designed behaviour; when PuTTY receives the character
Control-E from the remote server, it interprets it as a request to
identify itself, and so it sends back the string \q{\cw{PuTTY}} as
if that string had been entered at the keyboard. Control-E should
only be sent by programs that are prepared to deal with the
response. Writing a binary file to your terminal is likely to output
many Control-E characters, and cause this behaviour. Don't do it.
It's a bad plan.

\S{faq-puttyputty} When I \cw{cat} a binary file, my window title
changes to a nonsense string.

Don't \cw{cat} binary files, then.

It is designed behaviour that PuTTY should have the ability to
adjust the window title on instructions from the server. Normally
the control sequence that does this should only be sent
deliberately, by programs that know what they are doing and intend
to put meaningful text in the window title. Writing a binary file to
your terminal runs the risk of sending the same control sequence by
accident, and cause unexpected changes in the window title. Don't do
it.

\H{faq-secure} Security questions

\S{faq-publicpc} Is it safe for me to download PuTTY and use it on a
public PC?

It depends on whether you trust that PC. If you don't trust the
public PC, don't use PuTTY on it, and don't use any other software
you plan to type passwords into either. It might be watching your
keystrokes, or it might tamper with the PuTTY binary you download.
There is \e{no} program safe enough that you can run it on an
actively malicious PC and get away with typing passwords into it.

If you do trust the PC, then it's probably OK to use PuTTY on it
(but if you don't trust the network, then the PuTTY download might
be tampered with, so it would be better to carry PuTTY with you on a
floppy).

\S{faq-cleanup} What does PuTTY leave on a system? How can I clean
up after it?

PuTTY will leave some Registry entries, and a random seed file, on
the PC (see \k{faq-settings}). If you are using PuTTY on a public
PC, or somebody else's PC, you might want to clean these up when you
leave. You can do that automatically, by running the command
\c{putty -cleanup}.

\S{faq-dsa} How come PuTTY now supports DSA, when the website used
to say how insecure it was?

DSA has a major weakness \e{if badly implemented}: it relies on a
random number generator to far too great an extent. If the random
number generator produces a number an attacker can predict, the DSA
private key is exposed - meaning that the attacker can log in as you
on all systems that accept that key.

The PuTTY policy changed because the developers were informed of
ways to implement DSA which do not suffer nearly as badly from this
weakness, and indeed which don't need to rely on random numbers at
all. For this reason we now believe PuTTY's DSA implementation is
probably OK. However, if you have the choice, we still recommend you
use RSA instead.

\H{faq-admin} Administrative questions

\S{faq-domain} Would you like me to register you a nicer domain name?

No, thank you. Even if you can find one (most of them seem to have
been registered already, by people who didn't ask whether we
actually wanted it before they applied), we're happy with the PuTTY
web site being exactly where it is. It's not hard to find (just type
\q{putty} into \W{http://www.google.com/}{google.com} and we're the
first link returned), and we don't believe the administrative hassle
of moving the site would be worth the benefit.

In addition, if we \e{did} want a custom domain name, we would want
to run it ourselves, so we knew for certain that it would continue
to point where we wanted it, and wouldn't suddenly change or do
strange things. Having it registered for us by a third party who we
don't even know is not the best way to achieve this.

\S{faq-webhosting} Would you like free web hosting for the PuTTY web
site?

We already have some, thanks.

\S{faq-sourceforge} Why don't you move PuTTY to SourceForge?

Partly, because we don't want to move the web site location (see
\k{faq-domain}).

Also, security reasons. PuTTY is a security product, and as such it
is particularly important to guard the code and the web site against
unauthorised modifications which might introduce subtle security
flaws. Therefore, we prefer that the CVS repository, web site and
FTP site remain where they are, under the direct control of system
administrators we know and trust personally, rather than being run
by a large organisation full of people we've never met and which is
known to have had breakins in the past.

No offence to SourceForge; I think they do a wonderful job. But
they're not ideal for everyone, and in particular they're not ideal
for us.

\S{faq-mailinglist1} Why can't I subscribe to the putty-bugs mailing
list?

Because you're not a member of the PuTTY core development team. The
putty-bugs mailing list is not a general newsgroup-like discussion
forum; it's a contact address for the core developers, and an
\e{internal} mailing list for us to discuss things among ourselves.
If we opened it up for everybody to subscribe to, it would turn into
something more like a newsgroup and we would be completely
overwhelmed by the volume of traffic. It's hard enough to keep up
with the list as it is.

\S{faq-mailinglist2} If putty-bugs isn't a general-subscription
mailing list, what is?

There isn't one, that we know of.

If someone else wants to set up a mailing list for PuTTY users to
help each other with common problems, that would be fine with us;
but the PuTTY team would almost certainly not have the time to read
it, so any questions the list couldn't answer would have to be
forwarded on to us by the questioner. In any case, it's probably
better to use the established newsgroup \cw{comp.security.ssh} for
this purpose.

\S{faq-donations} How can I donate to PuTTY development?

Please, \e{please} don't feel you have to. PuTTY is completely free
software, and not shareware. We think it's very important that
\e{everybody} who wants to use PuTTY should be able to, whether they
have any money or not; so the last thing we would want is for a
PuTTY user to feel guilty because they haven't paid us any money. If
you want to keep your money, please do keep it. We wouldn't dream of
asking for any.

Having said all that, if you still really \e{want} to give us money,
we won't argue :-) The easiest way for us to accept donations is if
you go to \W{http://www.e-gold.com}\cw{www.e-gold.com}, and deposit
your donation in account number 174769. Then send us e-mail to let
us know you've done so (otherwise we might not notice for months!).

Small donations (tens of dollars or tens of euros) will probably be
spent on beer or curry, which helps motivate our volunteer team to
continue doing this for the world. Larger donations will be spent on
something that actually helps development, if we can find anything
(perhaps new hardware, or a copy of Windows 2000), but if we can't
find anything then we'll just distribute the money among the
developers. If you want to be sure your donation is going towards
something worthwhile, ask us first. If you don't like these terms,
feel perfectly free not to donate. We don't mind.

\S{faq-pronounce} How do I pronounce PuTTY?

Exactly like the normal word \q{putty}. Just like the stuff you put
on window frames. (One of the reasons it's called PuTTY is because
it makes Windows usable. :-)