Document that PSFTP's "open" command allows an optional port number.
[u/mdw/putty] / doc / errors.but
1 \define{versioniderrors} \versionid $Id$
2
3 \C{errors} Common \i{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 \cfg{winhelp-topic}{errors.hostkey.absent}
19
20 This error message occurs when PuTTY connects to a new SSH server.
21 Every server identifies itself by means of a host key; once PuTTY
22 knows the host key for a server, it will be able to detect if a
23 malicious attacker redirects your connection to another machine.
24
25 If you see this message, it means that PuTTY has not seen this host
26 key before, and has no way of knowing whether it is correct or not.
27 You should attempt to verify the host key by other means, such as
28 asking the machine's administrator.
29
30 If you see this message and you know that your installation of PuTTY
31 \e{has} connected to the same server before, it may have been
32 recently upgraded to SSH protocol version 2. SSH protocols 1 and 2
33 use separate host keys, so when you first use \i{SSH-2} with a server
34 you have only used SSH-1 with before, you will see this message
35 again. You should verify the correctness of the key as before.
36
37 See \k{gs-hostkey} for more information on host keys.
38
39 \H{errors-hostkey-wrong} \q{WARNING - POTENTIAL SECURITY BREACH!}
40
41 \cfg{winhelp-topic}{errors.hostkey.changed}
42
43 This message, followed by \q{The server's host key does not match
44 the one PuTTY has cached in the registry}, means that PuTTY has
45 connected to the SSH server before, knows what its host key
46 \e{should} be, but has found a different one.
47
48 This may mean that a malicious attacker has replaced your server
49 with a different one, or has redirected your network connection to
50 their own machine. On the other hand, it may simply mean that the
51 administrator of your server has accidentally changed the key while
52 upgrading the SSH software; this \e{shouldn't} happen but it is
53 unfortunately possible.
54
55 You should contact your server's administrator and see whether they
56 expect the host key to have changed. If so, verify the new host key
57 in the same way as you would if it was new.
58
59 See \k{gs-hostkey} for more information on host keys.
60
61 \H{errors-portfwd-space} \q{Out of space for port forwardings}
62
63 PuTTY has a fixed-size buffer which it uses to store the details of
64 all \i{port forwardings} you have set up in an SSH session. If you
65 specify too many port forwardings on the PuTTY or Plink command line
66 and this buffer becomes full, you will see this error message.
67
68 We need to fix this (fixed-size buffers are almost always a mistake)
69 but we haven't got round to it. If you actually have trouble with
70 this, let us know and we'll move it up our priority list.
71
72 \H{errors-cipher-warning} \q{The first cipher supported by the server is
73 ... below the configured warning threshold}
74
75 This occurs when the SSH server does not offer any ciphers which you
76 have configured PuTTY to consider strong enough. By default, PuTTY
77 puts up this warning only for \ii{single-DES} and \i{Arcfour} encryption.
78
79 See \k{config-ssh-encryption} for more information on this message.
80
81 \H{errors-toomanyauth} \q{Server sent disconnect message type 2
82 (protocol error): "Too many authentication failures for root"}
83
84 This message is produced by an \i{OpenSSH} (or \i{Sun SSH}) server if it
85 receives more failed authentication attempts than it is willing to
86 tolerate.
87
88 This can easily happen if you are using Pageant and have a
89 large number of keys loaded into it, since these servers count each
90 offer of a public key as an authentication attempt. This can be worked
91 around by specifying the key that's required for the authentication in
92 the PuTTY configuration (see \k{config-ssh-privkey}); PuTTY will ignore
93 any other keys Pageant may have, but will ask Pageant to do the
94 authentication, so that you don't have to type your passphrase.
95
96 On the server, this can be worked around by disabling public-key
97 authentication or (for Sun SSH only) by increasing \c{MaxAuthTries} in
98 \c{sshd_config}.
99
100 \H{errors-memory} \q{\ii{Out of memory}}
101
102 This occurs when PuTTY tries to allocate more memory than the system
103 can give it. This \e{may} happen for genuine reasons: if the
104 computer really has run out of memory, or if you have configured an
105 extremely large number of lines of scrollback in your terminal.
106 PuTTY is not able to recover from running out of memory; it will
107 terminate immediately after giving this error.
108
109 However, this error can also occur when memory is not running out at
110 all, because PuTTY receives data in the wrong format. In SSH-2 and
111 also in SFTP, the server sends the length of each message before the
112 message itself; so PuTTY will receive the length, try to allocate
113 space for the message, and then receive the rest of the message. If
114 the length PuTTY receives is garbage, it will try to allocate a
115 ridiculous amount of memory, and will terminate with an \q{Out of
116 memory} error.
117
118 This can happen in SSH-2, if PuTTY and the server have not enabled
119 encryption in the same way (see \k{faq-outofmem} in the FAQ). Some
120 versions of \i{OpenSSH} have a known problem with this: see
121 \k{faq-openssh-bad-openssl}.
122
123 This can also happen in PSCP or PSFTP, if your \i{login scripts} on the
124 server generate output: the client program will be expecting an SFTP
125 message starting with a length, and if it receives some text from
126 your login scripts instead it will try to interpret them as a
127 message length. See \k{faq-outofmem2} for details of this.
128
129 \H{errors-internal} \q{\ii{Internal error}}, \q{\ii{Internal fault}},
130 \q{\ii{Assertion failed}}
131
132 Any error beginning with the word \q{Internal} should \e{never}
133 occur. If it does, there is a bug in PuTTY by definition; please see
134 \k{feedback} and report it to us.
135
136 Similarly, any error message starting with \q{Assertion failed} is a
137 bug in PuTTY. Please report it to us, and include the exact text
138 from the error message box.
139
140 \H{errors-cant-load-key} \q{Unable to use this private key file},
141 \q{Couldn't load private key}, \q{Key is of wrong type}
142
143 \cfg{winhelp-topic}{errors.cantloadkey}
144
145 Various forms of this error are printed in the PuTTY window, or
146 written to the PuTTY Event Log (see \k{using-eventlog}) when trying
147 public-key authentication, or given by Pageant when trying to load a
148 private key.
149
150 If you see one of these messages, it often indicates that you've tried
151 to load a key of an inappropriate type into PuTTY, Plink, PSCP, PSFTP,
152 or Pageant.
153
154 You may have specified a key that's inappropriate for the connection
155 you're making. The SSH-1 and SSH-2 protocols require different private
156 key formats, and a SSH-1 key can't be used for a SSH-2 connection (or
157 vice versa).
158
159 Alternatively, you may have tried to load an SSH-2 key in a \q{foreign}
160 format (OpenSSH or \cw{ssh.com}) directly into one of the PuTTY tools,
161 in which case you need to import it into PuTTY's native format
162 (\c{*.PPK}) using PuTTYgen - see \k{puttygen-conversions}.
163
164 \H{errors-refused} \q{Server refused our public key} or \q{Key
165 refused}
166
167 Various forms of this error are printed in the PuTTY window, or
168 written to the PuTTY Event Log (see \k{using-eventlog}) when trying
169 public-key authentication.
170
171 If you see one of these messages, it means that PuTTY has sent a
172 public key to the server and offered to authenticate with it, and
173 the server has refused to accept authentication. This usually means
174 that the server is not configured to accept this key to authenticate
175 this user.
176
177 This is almost certainly not a problem with PuTTY. If you see this
178 type of message, the first thing you should do is check your
179 \e{server} configuration carefully. Common errors include having
180 the wrong permissions or ownership set on the public key or the
181 user's home directory on the server. Also, read the PuTTY Event Log;
182 the server may have sent diagnostic messages explaining exactly what
183 problem it had with your setup.
184
185 \H{errors-access-denied} \q{Access denied}, \q{Authentication refused}
186
187 Various forms of this error are printed in the PuTTY window, or
188 written to the PuTTY Event Log (see \k{using-eventlog}) during
189 authentication.
190
191 If you see one of these messages, it means that the server has refused
192 all the forms of authentication PuTTY has tried and it has no further
193 ideas.
194
195 It may be worth checking the Event Log for diagnostic messages from
196 the server giving more detail.
197
198 This error can be caused by buggy SSH-1 servers that fail to cope with
199 the various strategies we use for camouflaging passwords in transit.
200 Upgrade your server, or use the workarounds described in
201 \k{config-ssh-bug-ignore1} and possibly \k{config-ssh-bug-plainpw1}.
202
203 \H{errors-no-auth} \q{No supported authentication methods available}
204
205 This error indicates that PuTTY has run out of ways to authenticate
206 you to an SSH server. This may be because PuTTY has TIS or
207 keyboard-interactive authentication disabled, in which case
208 \k{config-ssh-tis} and \k{config-ssh-ki}.
209
210 \H{errors-crc} \q{Incorrect \i{CRC} received on packet} or \q{Incorrect
211 \i{MAC} received on packet}
212
213 This error occurs when PuTTY decrypts an SSH packet and its checksum
214 is not correct. This probably means something has gone wrong in the
215 encryption or decryption process. It's difficult to tell from this
216 error message whether the problem is in the client, in the server,
217 or in between.
218
219 In particular, if the network is corrupting data at the TCP level, it
220 may only be obvious with cryptographic protocols such as SSH, which
221 explicitly check the integrity of the transferred data and complain
222 loudly if the checks fail. Corruption of protocols without integrity
223 protection (such as HTTP) will manifest in more subtle failures (such
224 as misdisplayed text or images in a web browser) which may not be
225 noticed.
226
227 A known server problem which can cause this error is described in
228 \k{faq-openssh-bad-openssl} in the FAQ.
229
230 \H{errors-garbled} \q{Incoming packet was garbled on decryption}
231
232 This error occurs when PuTTY decrypts an SSH packet and the
233 decrypted data makes no sense. This probably means something has
234 gone wrong in the encryption or decryption process. It's difficult
235 to tell from this error message whether the problem is in the client,
236 in the server, or in between.
237
238 If you get this error, one thing you could try would be to fiddle with
239 the setting of \q{Miscomputes SSH-2 encryption keys} (see
240 \k{config-ssh-bug-derivekey2}) or \q{Ignores SSH-2 maximum packet
241 size} (see \k{config-ssh-bug-maxpkt2}) on the Bugs panel .
242
243 Another known server problem which can cause this error is described
244 in \k{faq-openssh-bad-openssl} in the FAQ.
245
246 \H{errors-x11-proxy} \q{PuTTY X11 proxy: \e{various errors}}
247
248 This family of errors are reported when PuTTY is doing X forwarding.
249 They are sent back to the X application running on the SSH server,
250 which will usually report the error to the user.
251
252 When PuTTY enables X forwarding (see \k{using-x-forwarding}) it
253 creates a virtual X display running on the SSH server. This display
254 requires authentication to connect to it (this is how PuTTY prevents
255 other users on your server machine from connecting through the PuTTY
256 proxy to your real X display). PuTTY also sends the server the
257 details it needs to enable clients to connect, and the server should
258 put this mechanism in place automatically, so your X applications
259 should just work.
260
261 A common reason why people see one of these messages is because they
262 used SSH to log in as one user (let's say \q{fred}), and then used
263 the Unix \c{su} command to become another user (typically \q{root}).
264 The original user, \q{fred}, has access to the X authentication data
265 provided by the SSH server, and can run X applications which are
266 forwarded over the SSH connection. However, the second user
267 (\q{root}) does not automatically have the authentication data
268 passed on to it, so attempting to run an X application as that user
269 often fails with this error.
270
271 If this happens, \e{it is not a problem with PuTTY}. You need to
272 arrange for your X authentication data to be passed from the user
273 you logged in as to the user you used \c{su} to become. How you do
274 this depends on your particular system; in fact many modern versions
275 of \c{su} do it automatically.
276
277 \H{errors-connaborted} \q{Network error: Software caused connection
278 abort}
279
280 This is a generic error produced by the Windows network code when it
281 kills an established connection for some reason. For example, it might
282 happen if you pull the network cable out of the back of an
283 Ethernet-connected computer, or if Windows has any other similar
284 reason to believe the entire network has become unreachable.
285
286 Windows also generates this error if it has given up on the machine
287 at the other end of the connection ever responding to it. If the
288 network between your client and server goes down and your client
289 then tries to send some data, Windows will make several attempts to
290 send the data and will then give up and kill the connection. In
291 particular, this can occur even if you didn't type anything, if you
292 are using SSH-2 and PuTTY attempts a key re-exchange. (See
293 \k{config-ssh-kex-rekey} for more about key re-exchange.)
294
295 (It can also occur if you are using keepalives in your connection.
296 Other people have reported that keepalives \e{fix} this error for
297 them. See \k{config-keepalive} for a discussion of the pros and cons
298 of keepalives.)
299
300 We are not aware of any reason why this error might occur that would
301 represent a bug in PuTTY. The problem is between you, your Windows
302 system, your network and the remote system.
303
304 \H{errors-connreset} \q{Network error: Connection reset by peer}
305
306 This error occurs when the machines at each end of a network
307 connection lose track of the state of the connection between them.
308 For example, you might see it if your SSH server crashes, and
309 manages to reboot fully before you next attempt to send data to it.
310
311 However, the most common reason to see this message is if you are
312 connecting through a \i{firewall} or a \i{NAT router} which has timed the
313 connection out. See \k{faq-idleout} in the FAQ for more details. You
314 may be able to improve the situation by using keepalives; see
315 \k{config-keepalive} for details on this.
316
317 Note that Windows can produce this error in some circumstances without
318 seeing a connection reset from the server, for instance if the
319 connection to the network is lost.
320
321 \H{errors-connrefused} \q{Network error: Connection refused}
322
323 This error means that the network connection PuTTY tried to make to
324 your server was rejected by the server. Usually this happens because
325 the server does not provide the service which PuTTY is trying to
326 access.
327
328 Check that you are connecting with the correct protocol (SSH, Telnet
329 or Rlogin), and check that the port number is correct. If that
330 fails, consult the administrator of your server.
331
332 \H{errors-conntimedout} \q{Network error: Connection timed out}
333
334 This error means that the network connection PuTTY tried to make to
335 your server received no response at all from the server. Usually
336 this happens because the server machine is completely isolated from
337 the network, or because it is turned off.
338
339 Check that you have correctly entered the host name or IP address of
340 your server machine. If that fails, consult the administrator of
341 your server.
342
343 \i{Unix} also generates this error when it tries to send data down a
344 connection and contact with the server has been completely lost
345 during a connection. (There is a delay of minutes before Unix gives
346 up on receiving a reply from the server.) This can occur if you type
347 things into PuTTY while the network is down, but it can also occur
348 if PuTTY decides of its own accord to send data: due to a repeat key
349 exchange in SSH-2 (see \k{config-ssh-kex-rekey}) or due to
350 keepalives (\k{config-keepalive}).