Add section on "Access denied". This was mostly inspired by the password
[sgt/putty] / doc / errors.but
1 \versionid $Id: errors.but,v 1.7 2003/07/12 13:25:43 jacob Exp $
2
3 \C{errors} Common error messages
4
5 This chapter lists a number of common error messages which PuTTY and
6 its associated tools can produce, and explains what they mean in
7 more detail.
8
9 We do not attempt to list \e{all} error messages here: there are
10 many which should never occur, and some which should be
11 self-explanatory. If you get an error message which is not listed in
12 this chapter and which you don't understand, report it to us as a
13 bug (see \k{feedback}) and we will add documentation for it.
14
15 \H{errors-hostkey-absent} \q{The server's host key is not cached in
16 the registry}
17
18 This error message occurs when PuTTY connects to a new SSH server.
19 Every server identifies itself by means of a host key; once PuTTY
20 knows the host key for a server, it will be able to detect if a
21 malicious attacker redirects your connection to another machine.
22
23 If you see this message, it means that PuTTY has not seen this host
24 key before, and has no way of knowing whether it is correct or not.
25 You should attempt to verify the host key by other means, such as
26 asking the machine's administrator.
27
28 If you see this message and you know that your installation of PuTTY
29 \e{has} connected to the same server before, it may have been
30 recently upgraded to SSH protocol version 2. SSH protocols 1 and 2
31 use separate host keys, so when you first use SSH 2 with a server
32 you have only used SSH 1 with before, you will see this message
33 again. You should verify the correctness of the key as before.
34
35 See \k{gs-hostkey} for more information on host keys.
36
37 \H{errors-hostkey-wrong} \q{WARNING - POTENTIAL SECURITY BREACH!}
38
39 This message, followed by \q{The server's host key does not match
40 the one PuTTY has cached in the registry}, means that PuTTY has
41 connected to the SSH server before, knows what its host key
42 \e{should} be, but has found a different one.
43
44 This may mean that a malicious attacker has replaced your server
45 with a different one, or has redirected your network connection to
46 their own machine. On the other hand, it may simply mean that the
47 administrator of your server has accidentally changed the key while
48 upgrading the SSH software; this \e{shouldn't} happen but it is
49 unfortunately possible.
50
51 You should contact your server's administrator and see whether they
52 expect the host key to have changed. If so, verify the new host key
53 in the same way as you would if it was new.
54
55 See \k{gs-hostkey} for more information on host keys.
56
57 \H{errors-portfwd-space} \q{Out of space for port forwardings}
58
59 PuTTY has a fixed-size buffer which it uses to store the details of
60 all port forwardings you have set up in an SSH session. If you
61 specify too many port forwardings on the PuTTY or Plink command line
62 and this buffer becomes full, you will see this error message.
63
64 We need to fix this (fixed-size buffers are almost always a mistake)
65 but we haven't got round to it. If you actually have trouble with
66 this, let us know and we'll move it up our priority list.
67
68 \H{errors-cipher-warning} \q{The first cipher supported by the server is
69 ... below the configured warning threshold}
70
71 This occurs when the SSH server does not offer any ciphers which you
72 have configured PuTTY to consider strong enough.
73
74 See \k{config-ssh-encryption} for more information on this message.
75
76 \H{errors-toomanyauth} \q{Server sent disconnect message type 2
77 (SSH_DISCONNECT_PROTOCOL_ERROR): "Too many authentication failures for root"}
78
79 This message is produced by an OpenSSH (or Sun SSH) server if it
80 receives more failed authentication attempts than it is willing to
81 tolerate. This can easily happen if you are using Pageant and have a
82 large number of keys loaded into it. This can be worked around on the
83 server by disabling public-key authentication or (for Sun SSH only) by
84 increasing \c{MaxAuthTries} in \c{sshd_config}. Neither of these is a
85 really satisfactory solution, and we hope to provide a better one in a
86 future version of PuTTY.
87
88 \H{errors-memory} \q{Out of memory}
89
90 This occurs when PuTTY tries to allocate more memory than the system
91 can give it. This \e{may} happen for genuine reasons: if the
92 computer really has run out of memory, or if you have configured an
93 extremely large number of lines of scrollback in your terminal.
94 PuTTY is not able to recover from running out of memory; it will
95 terminate immediately after giving this error.
96
97 However, this error can also occur when memory is not running out at
98 all, because PuTTY receives data in the wrong format. In SSH 2 and
99 also in SFTP, the server sends the length of each message before the
100 message itself; so PuTTY will receive the length, try to allocate
101 space for the message, and then receive the rest of the message. If
102 the length PuTTY receives is garbage, it will try to allocate a
103 ridiculous amount of memory, and will terminate with an \q{Out of
104 memory} error.
105
106 This can happen in SSH 2, if PuTTY and the server have not enabled
107 encryption in the same way (see \k{faq-outofmem} in the FAQ). Some
108 versions of OpenSSH have a known problem with this: see
109 \k{faq-openssh-bad-openssl}.
110
111 This can also happen in PSCP or PSFTP, if your login scripts on the
112 server generate output: the client program will be expecting an SFTP
113 message starting with a length, and if it receives some text from
114 your login scripts instead it will try to interpret them as a
115 message length. See \k{faq-outofmem2} for details of this.
116
117 \H{errors-internal} \q{Internal error}, \q{Internal fault},
118 \q{Assertion failed}
119
120 Any error beginning with the word \q{Internal} should \e{never}
121 occur. If it does, there is a bug in PuTTY by definition; please see
122 \k{feedback} and report it to us.
123
124 Similarly, any error message starting with \q{Assertion failed} is a
125 bug in PuTTY. Please report it to us, and include the exact text
126 from the error message box.
127
128 \H{errors-refused} \q{Server refused our public key} or \q{Key
129 refused}
130
131 Various forms of this error are printed in the PuTTY window, or
132 written to the PuTTY Event Log (see \k{using-eventlog}) when trying
133 public-key authentication.
134
135 If you see one of these messages, it means that PuTTY has sent a
136 public key to the server and offered to authenticate with it, and
137 the server has refused to accept authentication. This usually means
138 that the server is not configured to accept this key to authenticate
139 this user.
140
141 This is almost certainly not a problem with PuTTY. If you see this
142 type of message, the first thing you should do is check your
143 \e{server} configuration carefully. Also, read the PuTTY Event Log;
144 the server may have sent diagnostic messages explaining exactly what
145 problem it had with your setup.
146
147 \H{errors-access-denied} \q{Access denied}, \q{Authentication refused}
148
149 Various forms of this error are printed in the PuTTY window, or
150 written to the PuTTY Event Log (see \k{using-eventlog}) during
151 authentication.
152
153 If you see one of these messages, it means that the server has refused
154 all the forms of authentication PuTTY has tried and it has no further
155 ideas.
156
157 It may be worth checking the Event Log for diagnostic messages from
158 the server giving more detail.
159
160 This error can be caused by buggy SSH-1 servers that fail to cope with
161 the various strategies we use for camouflaging passwords in transit.
162 Upgrade your server, or use the workarounds described in
163 \k{config-ssh-bug-ignore1} and possibly \k{config-ssh-bug-plainpw1}.
164
165 \H{errors-crc} \q{Incorrect CRC received on packet} or \q{Incorrect
166 MAC received on packet}
167
168 This error occurs when PuTTY decrypts an SSH packet and its checksum
169 is not correct. This probably means something has gone wrong in the
170 encryption or decryption process. It's difficult to tell from this
171 error message whether the problem is in the client or in the server.
172
173 A known server problem which can cause this error is described in
174 \k{faq-openssh-bad-openssl} in the FAQ.
175
176 \H{errors-garbled} \q{Incoming packet was garbled on decryption}
177
178 This error occurs when PuTTY decrypts an SSH packet and the
179 decrypted data makes no sense. This probably means something has
180 gone wrong in the encryption or decryption process. It's difficult
181 to tell from this error message whether the problem is in the client
182 or in the server.
183
184 If you get this error, one thing you could try would be to fiddle
185 with the setting of \q{Miscomputes SSH2 encryption keys} on the Bugs
186 panel (see \k{config-ssh-bug-derivekey2}).
187
188 Another known server problem which can cause this error is described
189 in \k{faq-openssh-bad-openssl} in the FAQ.
190
191 \H{errors-x11-proxy} \q{Authentication failed at PuTTY X11 proxy}
192
193 This error is reported when PuTTY is doing X forwarding. It is sent
194 back to the X application running on the SSH server, which will
195 usually report the error to the user.
196
197 When PuTTY enables X forwarding (see \k{using-x-forwarding}) it
198 creates a virtual X display running on the SSH server. This display
199 requires authentication to connect to it (this is how PuTTY prevents
200 other users on your server machine from connecting through the PuTTY
201 proxy to your real X display). PuTTY also sends the server the
202 details it needs to enable clients to connect, and the server should
203 put this mechanism in place automatically, so your X applications
204 should just work.
205
206 A common reason why people see this message is because they used SSH
207 to log in as one user (let's say \q{fred}), and then used the Unix
208 \c{su} command to become another user (typically \q{root}). The
209 original user, \q{fred}, has access to the X authentication data
210 provided by the SSH server, and can run X applications which are
211 forwarded over the SSH connection. However, the second user
212 (\q{root}) does not automatically have the authentication data
213 passed on to it, so attempting to run an X application as that user
214 often fails with this error.
215
216 If this happens, \e{it is not a problem with PuTTY}. You need to
217 arrange for your X authentication data to be passed from the user
218 you logged in as to the user you used \c{su} to become. How you do
219 this depends on your particular system; in fact many modern versions
220 of \c{su} do it automatically.
221
222 \H{errors-connaborted} \q{Network error: Software caused connection
223 abort}
224
225 This error occurs when the Windows network code decides that your
226 network connection is dead. For example, it will happen if you pull
227 the network cable out of the back of an Ethernet-connected computer,
228 or if Windows has any other similar reason to believe the entire
229 network has become unreachable.
230
231 We are not aware of any reason why this error might occur that would
232 represent a bug in PuTTY. The problem is between you, your Windows
233 system, your network and the remote system.
234
235 \H{errors-connreset} \q{Network error: Connection reset by peer}
236
237 This error occurs when the machines at each end of a network
238 connection lose track of the state of the connection between them.
239 For example, you might see it if your SSH server crashes, and
240 manages to reboot fully before you next attempt to send data to it.
241
242 However, the most common reason to see this message is if you are
243 connecting through a firewall or a NAT router which has timed the
244 connection out. See \k{faq-idleout} in the FAQ for more details. You
245 may be able to improve the situation by using keepalives; see
246 \k{config-keepalive} for details on this.
247
248 \H{errors-connrefused} \q{Network error: Connection refused}
249
250 This error means that the network connection PuTTY tried to make to
251 your server was rejected by the server. Usually this happens because
252 the server does not provide the service which PuTTY is trying to
253 access.
254
255 Check that you are connecting with the correct protocol (SSH, Telnet
256 or Rlogin), and check that the port number is correct. If that
257 fails, consult the administrator of your server.
258
259 \H{errors-conntimedout} \q{Network error: Connection timed out}
260
261 This error means that the network connection PuTTY tried to make to
262 your server received no response at all from the server. Usually
263 this happens because the server machine is completely isolated from
264 the network, or because it is turned off.
265
266 Check that you have correctly entered the host name or IP address of
267 your server machine. If that fails, consult the administrator of
268 your server.