Line discipline module now uses dynamically allocated data. Also

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

\versionid $Id: errors.but,v 1.1 2002/10/01 16:27:36 simon Exp $

\C{errors} Common error messages

This chapter lists a number of common error messages which PuTTY and
its associated tools can produce, and explains what they mean in
more detail.

We do not attempt to list \e{all} error messages here: there are
many which should never occur, and some which should be
self-explanatory. If you get an error message which is not listed in
this chapter and which you don't understand, report it to us as a
bug (see \k{feedback}) and we will add documentation for it.

\H{errors-hostkey-absent} \q{The server's host key is not cached in
the registry}

This error message occurs when PuTTY connects to a new SSH server.
Every server identifies itself by means of a host key; once PuTTY
knows the host key for a server, it will be able to detect if a
malicious attacker redirects your connection to another machine.

If you see this message, it means that PuTTY has not seen this host
key before, and has no way of knowing whether it is correct or not.
You should attempt to verify the host key by other means, such as
asking the machine's administrator.

If you see this message and you know that your installation of PuTTY
\e{has} connected to the same server before, it may have been
recently upgraded to SSH protocol version 2. SSH protocols 1 and 2
use separate host keys, so when you first use SSH 2 with a server
you have only used SSH 1 with before, you will see this message
again. You should verify the correctness of the key as before.

See \k{gs-hostkey} for more information on host keys.

\H{errors-hostkey-wrong} \q{WARNING - POTENTIAL SECURITY BREACH!}

This message, followed by \q{The server's host key does not match
the one PuTTY has cached in the registry}, means that PuTTY has
connected to the SSH server before, knows what its host key
\e{should} be, but has found a different one.

This may mean that a malicious attacker has replaced your server
with a different one, or has redirected your network connection to
their own machine. On the other hand, it may simply mean that the
administrator of your server has accidentally changed the key while
upgrading the SSH software; this \e{shouldn't} happen but it is
unfortunately possible.

You should contact your server's administrator and see whether they
expect the host key to have changed. If so, verify the new host key
in the same way as you would if it was new.

See \k{gs-hostkey} for more information on host keys.

\H{errors-portfwd-space} \q{Out of space for port forwardings}

PuTTY has a fixed-size buffer which it uses to store the details of
all port forwardings you have set up in an SSH session. If you
specify too many port forwardings on the PuTTY or Plink command line
and this buffer becomes full, you will see this error message.

We need to fix this (fixed-size buffers are almost always a mistake)
but we haven't got round to it. If you actually have trouble with
this, let us know and we'll move it up our priority list.

\H{errors-cipher-warning} \q{The first cipher supported by the server is
... below the configured warning threshold}

This occurs when the SSH server does not offer any ciphers which you
have configured PuTTY to consider strong enough.

See \k{config-ssh-encryption} for more information on this message.

\H{errors-memory} \q{Out of memory}

This occurs when PuTTY tries to allocate more memory than the system
can give it. This \e{may} happen for genuine reasons: if the
computer really has run out of memory, or if you have configured an
extremely large number of lines of scrollback in your terminal.
PuTTY is not able to recover from running out of memory; it will
terminate immediately after giving this error.

However, this error can also occur when memory is not running out at
all, because PuTTY receives data in the wrong format. In SSH 2 and
also in SFTP, the server sends the length of each message before the
message itself; so PuTTY will receive the length, try to allocate
space for the message, and then receive the rest of the message. If
the length PuTTY receives is garbage, it will try to allocate a
ridiculous amount of memory, and will terminate with an \q{Out of
memory} error.

This can happen in SSH 2, if PuTTY and the server have not enabled
encryption in the same way (see \k{faq-outofmem} in the FAQ). Some
versions of OpenSSH have a knownq problem with this: see
\k{faq-openssh-bad-openssl}.

This can also happen in PSCP or PSFTP, if your login scripts on the
server generate output: the client program will be expecting an SFTP
message starting with a length, and if it receives some text from
your login scripts instead it will try to interpret them as a
message length. See \k{faq-outofmem2} for details of this.

\H{errors-internal} \q{Internal error}, \q{Internal fault},
\q{Assertion failed}

Any error beginning with the word \q{Internal} should \e{never}
occur. If it does, there is a bug in PuTTY by definition; please see
\k{feedback} and report it to us.

Similarly, any error message starting with \q{Assertion failed} is a
bug in PuTTY. Please report it to us, and include the exact text
from the error message box.

\H{errors-refused} \q{Server refused our public key} or \q{Key
refused}

Various forms of this error are printed in the PuTTY window, or
written to the PuTTY Event Log (see \k{using-eventlog}) when trying
public-key authentication.

If you see one of these messages, it means that PuTTY has sent a
public key to the server and offered to authenticate with it, and
the server has refused to accept authentication. This usually means
that the server is not configured to accept this key to authenticate
this user.

This is almost certainly not a problem with PuTTY. If you see this
type of message, the first thing you should do is check your
\e{server} configuration carefully. Also, read the PuTTY Event Log;
the server may have sent diagnostic messages explaining exactly what
problem it had with your setup.

\H{errors-crc} \q{Incorrect CRC received on packet} or \q{Incorrect
MAC received on packet}

This error occurs when PuTTY decrypts an SSH packet and its checksum
is not correct. This probably means something has gone wrong in the
encryption or decryption process. It's difficult to tell from this
error message whether the problem is in the client or in the server.

A known server problem which can cause this error is described in
\k{faq-openssh-bad-openssl} in the FAQ.

\H{errors-garbled} \q{Incoming packet was garbled on decryption}

This error occurs when PuTTY decrypts an SSH packet and the
decrypted data makes no sense. This probably means something has
gone wrong in the encryption or decryption process. It's difficult
to tell from this error message whether the problem is in the client
or in the server.

A known server problem which can cause this error is described in
\k{faq-openssh-bad-openssl} in the FAQ.

\H{errors-x11-proxy} \q{Authentication failed at PuTTY X11 proxy}

This error is reported when PuTTY is doing X forwarding. It is sent
back to the X application running on the SSH server, which will
usually report the error to the user.

When PuTTY enables X forwarding (see \k{using-x-forwarding}) it
creates a virtual X display running on the SSH server. This display
requires authentication to connect to it (this is how PuTTY prevents
other users on your server machine from connecting through the PuTTY
proxy to your real X display). PuTTY also sends the server the
details it needs to enable clients to connect, and the server should
put this mechanism in place automatically, so your X applications
should just work.

A common reason why people see this message is because they used SSH
to log in as one user (let's say \q{fred}), and then used the Unix
\c{su} command to become another user (typically \q{root}). The
original user, \q{fred}, has access to the X authentication data
provided by the SSH server, and can run X applications which are
forwarded over the SSH connection. However, the second user
(\q{root}) does not automatically have the authentication data
passed on to it, so attempting to run an X application as that user
often fails with this error.

If this happens, \e{it is not a problem with PuTTY}. You need to
arrange for your X authentication data to be passed from the user
you logged in as to the user you used \c{su} to become. How you do
this depends on your particular system; in fact many modern versions
of \c{su} do it automatically.

\H{errors-connaborted} \q{Network error: Software caused connection
abort}

In modern versions of PuTTY, you should not see this error.

Windows's documentation about this error condition is not very good,
but as far as we can tell, this error occurs when PuTTY is listening
on a port, another program makes a connection to that port, but
closes the connection so fast that PuTTY has no time to answer it.

PuTTY only ever listens on a port when it is doing local-to-remote
port forwarding (see \k{using-port-forwarding}); and if an incoming
connection on that port receives this error, PuTTY should simply
close the connection and continue without error.

If you see this error in PuTTY 0.53 or above, we would welcome a
report of the circumstances.

\H{errors-connreset} \q{Network error: Connection reset by peer}

This error occurs when the machines at each end of a network
connection lose track of the state of the connection between them.
For example, you might see it if your SSH server crashes, and
manages to reboot fully before you next attempt to send data to it.

However, the most common reason to see this message is if you are
connecting through a firewall or a NAT router which has timed the
connection out. See \k{faq-idleout} in the FAQ for more details. You
may be able to improve the situation by using keepalives; see
\k{config-keepalive} for details on this.

\H{errors-connrefused} \q{Network error: Connection refused}

This error means that the network connection PuTTY tried to make to
your server was rejected by the server. Usually this happens because
the server does not provide the service which PuTTY is trying to
access.

Check that you are connecting with the correct protocol (SSH, Telnet
or Rlogin), and check that the port number is correct. If that
fails, consult the administrator of your server.