Add a chapter explaining common error messages

[originally from svn r1984]

doc/Makefile

@@ -1,5 +1,5 @@
 CHAPTERS := blurb intro gs using config pscp psftp plink pubkey pageant
-CHAPTERS += faq feedback licence
+CHAPTERS += errors faq feedback licence
 
 INPUTS = $(patsubst %,%.but,$(CHAPTERS))
 

doc/errors.but

@@ -0,0 +1,228 @@
+\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.