From 91f80e36254e90f476cf5bcce0ef02af62ec9534 Mon Sep 17 00:00:00 2001 From: simon Date: Tue, 1 Oct 2002 16:27:36 +0000 Subject: [PATCH] Add a chapter explaining common error messages git-svn-id: svn://svn.tartarus.org/sgt/putty@1984 cda61777-01e9-0310-a592-d414129be87e --- doc/Makefile | 2 +- doc/errors.but | 228 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 229 insertions(+), 1 deletion(-) create mode 100644 doc/errors.but diff --git a/doc/Makefile b/doc/Makefile index 2d87e943..58e54be7 100644 --- a/doc/Makefile +++ b/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)) diff --git a/doc/errors.but b/doc/errors.but new file mode 100644 index 00000000..0c3e211a --- /dev/null +++ b/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. -- 2.11.0