From: Alan T. DeKok Date: Sun, 1 Feb 2026 19:01:43 +0000 (-0500) Subject: add initial very rough content for common errors X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9ed77de7ab7f6afabc9b420e3539e4111eec2b68;p=thirdparty%2Ffreeradius-server.git add initial very rough content for common errors --- diff --git a/doc/antora/modules/troubleshooting/nav.adoc b/doc/antora/modules/troubleshooting/nav.adoc index 75a7457da4c..d7eff986566 100644 --- a/doc/antora/modules/troubleshooting/nav.adoc +++ b/doc/antora/modules/troubleshooting/nav.adoc @@ -1,4 +1,30 @@ * xref:index.adoc[Troubleshooting] + +** xref:errors/index.adoc[Common Errors] +*** xref:errors/unknown_packet_code.adoc[Unknown packet code] +*** xref:errors/unexpected_request_code.adoc[Unexpected request code] +*** xref:errors/message_authenticator_missing.adoc[Message-Authenticator is missing] +*** xref:errors/message_authenticator_invalid.adoc[Message-Authenticator fail verification] +*** xref:errors/proxy_state_missing.adoc[Proxy-State is missing] +*** xref:errors/packet_fails_verification.adoc[Packet fails verification] +*** xref:errors/no_matching_request.adoc[Did not find request which matched response] + +** Less common errors +*** xref:errors/unexpected_response_code.adoc[Unexpected response code] +*** xref:errors/too_many_attributes.adoc[Packet contains too many attributes] +*** xref:errors/io_error.adoc[IO error] + +** Rare errors +*** xref:errors/packet_too_small.adoc[Packet is too small] +*** xref:errors/packet_too_large.adoc[Packet is too large] +*** xref:errors/mismatched_length.adoc[Header length does not match received packet length] +*** xref:errors/attribute_0.adoc[Attribute 0 is invalid] +*** xref:errors/attribute_invalid_length.adoc[Attribute has invalid length] +*** xref:errors/attribute_overflow.adoc[Attribute overflows the packet] +*** xref:errors/decode_failure.adoc[Failure decoding a packet] +*** xref:errors/message_authenticator_length.adoc[Message Authenticator has invalid length] + + ** xref:user.adoc[User Management] ** xref:server.adoc[Server Configuration] ** xref:client.adoc[Client Configuration] diff --git a/doc/antora/modules/troubleshooting/pages/errors/attribute_0.adoc b/doc/antora/modules/troubleshooting/pages/errors/attribute_0.adoc new file mode 100644 index 00000000000..58c294489f2 --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/attribute_0.adoc @@ -0,0 +1,6 @@ += Attribute 0 is Invalid + +Either the client is completely broken, or the packet is not RADIUS. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/attribute_invalid_length.adoc b/doc/antora/modules/troubleshooting/pages/errors/attribute_invalid_length.adoc new file mode 100644 index 00000000000..f69d0294af0 --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/attribute_invalid_length.adoc @@ -0,0 +1,6 @@ += Attribute has Invalid Length + +Either the client is completely broken, or the packet is not RADIUS. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/attribute_overflow.adoc b/doc/antora/modules/troubleshooting/pages/errors/attribute_overflow.adoc new file mode 100644 index 00000000000..8076abf7038 --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/attribute_overflow.adoc @@ -0,0 +1,6 @@ += Attribute Overflows the Packet + +The client is either completely broken, or the packet is not RADIUS. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/decode_failure.adoc b/doc/antora/modules/troubleshooting/pages/errors/decode_failure.adoc new file mode 100644 index 00000000000..20ac72824c7 --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/decode_failure.adoc @@ -0,0 +1,8 @@ += Failure Decoding the Packet + +The server is out of memory, or the packet has malformed VSAs, TLV +nesting is too deep, or any other "packet is malformed in a weird way" +problem. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/index.adoc b/doc/antora/modules/troubleshooting/pages/errors/index.adoc new file mode 100644 index 00000000000..24f24a11e0c --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/index.adoc @@ -0,0 +1,33 @@ += Errors + +== Server isn't receiving packets + +* Common errors +** xref:errors/unknown_packet_code.adoc[Unknown packet code] +** xref:errors/unexpected_request_code.adoc[Unexpected request code] +** xref:errors/message_authenticator_missing.adoc[Message-Authenticator is missing] +** xref:errors/message_authenticator_invalid.adoc[Message-Authenticator fail verification] +** xref:errors/proxy_state_missing.adoc[Proxy-State is missing] +** xref:errors/packet_fails_verification.adoc[Packet fails verification] +** xref:errors/no_matching_request.adoc[Did not find request which matched response] + +** Less common errors +** xref:errors/unexpected_response_code.adoc[Unexpected response code] +** xref:errors/too_many_attributes.adoc[Packet contains too many attributes] +** xref:errors/io_error.adoc[IO error] + +* Rare errors +** xref:errors/packet_too_small.adoc[Packet is too small] +** xref:errors/packet_too_large.adoc[Packet is too large] +** xref:errors/mismatched_length.adoc[Header length does not match received packet length] +** xref:errors/attribute_0.adoc[Attribute 0 is invalid] +** xref:errors/attribute_invalid_length.adoc[Attribute has invalid length] +** xref:errors/attribute_overflow.adoc[Attribute overflows the packet] +** xref:errors/decode_failure.adoc[Failure decoding a packet] +** xref:errors/message_authenticator_length.adoc[Message Authenticator has invalid length] + +== Authentication Failures + +== Issues with Databases +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/io_error.adoc b/doc/antora/modules/troubleshooting/pages/errors/io_error.adoc new file mode 100644 index 00000000000..1ac150eb0be --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/io_error.adoc @@ -0,0 +1,6 @@ += IO Error + +Some kind of network / OS error. These are hard to debug. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/message_authenticator_invalid.adoc b/doc/antora/modules/troubleshooting/pages/errors/message_authenticator_invalid.adoc new file mode 100644 index 00000000000..f2dcecc83aa --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/message_authenticator_invalid.adoc @@ -0,0 +1,6 @@ += Message-Authenticator Fails Verification + +The shared secret is wrong. Fix it. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/message_authenticator_length.adoc b/doc/antora/modules/troubleshooting/pages/errors/message_authenticator_length.adoc new file mode 100644 index 00000000000..270a6e7f7e6 --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/message_authenticator_length.adoc @@ -0,0 +1,7 @@ += Message-Authenticator has Invalid Length + +This will pretty much never happen. If it does, it means that the +client is completely broken, or that the packet is not RADIUS. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/message_authenticator_missing.adoc b/doc/antora/modules/troubleshooting/pages/errors/message_authenticator_missing.adoc new file mode 100644 index 00000000000..f4071c3a9ec --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/message_authenticator_missing.adoc @@ -0,0 +1,6 @@ += Message-Authenticator is Missing + +This is the BlastRADIUS stuff. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/mismatched_length.adoc b/doc/antora/modules/troubleshooting/pages/errors/mismatched_length.adoc new file mode 100644 index 00000000000..6da50fcfc4c --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/mismatched_length.adoc @@ -0,0 +1,6 @@ += Header 'Length' does not match received packet length + +The packet is likely not RADIUS. Block the source IP address. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/no_matching_request.adoc b/doc/antora/modules/troubleshooting/pages/errors/no_matching_request.adoc new file mode 100644 index 00000000000..ecf5538976d --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/no_matching_request.adoc @@ -0,0 +1,15 @@ += Did not find Request which matches Response + +This message is produced by the +xref:reference:raddb/mods-available/radius.adoc[`radius`] module. It means that the module: + +* sent a request +* never got a response +* gave up on the original request +* finally received a response + +This means that packet loss is occuring, or the next hop server is +taking 30+ seconds to respond. Fix it so that it responds quickly. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/packet_fails_verification.adoc b/doc/antora/modules/troubleshooting/pages/errors/packet_fails_verification.adoc new file mode 100644 index 00000000000..d1d92f70f80 --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/packet_fails_verification.adoc @@ -0,0 +1,6 @@ += Packet Fails Verification + +The shared secret is wrong. Fix it. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/packet_too_large.adoc b/doc/antora/modules/troubleshooting/pages/errors/packet_too_large.adoc new file mode 100644 index 00000000000..6d7818ddbea --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/packet_too_large.adoc @@ -0,0 +1,8 @@ += Packet Too Large + +RADIUS packets (with some caveats) are no more than 4K in size. This +error means that the client is sending too much data in one packet. +It is likely misconfigured. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/packet_too_small.adoc b/doc/antora/modules/troubleshooting/pages/errors/packet_too_small.adoc new file mode 100644 index 00000000000..fb6a5e4b3dc --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/packet_too_small.adoc @@ -0,0 +1,8 @@ += Packet Too Small + +RADIUS packets are at least 20 bytes. If you get this error, then +something is sending non-RADIUS packets to the RADIUS port. Update +any firewall rules to block traffic from that source IP. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/proxy_state_missing.adoc b/doc/antora/modules/troubleshooting/pages/errors/proxy_state_missing.adoc new file mode 100644 index 00000000000..1967c32a682 --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/proxy_state_missing.adoc @@ -0,0 +1,6 @@ += Proxy-State Missing + +this is for the BlastRADIUS stuff. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/too_many_attributes.adoc b/doc/antora/modules/troubleshooting/pages/errors/too_many_attributes.adoc new file mode 100644 index 00000000000..d8d2c1ea97a --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/too_many_attributes.adoc @@ -0,0 +1,14 @@ += Too Many Attributes + +Each `listen` section has a `max_attributes` configuration. This +prevents malicious clients from consuming large amounts of memory on +the server for each request. + +The value is large enough for nearly all common use-cases. Take care +before increasing it. + +If you see this error, it's likely that a client is either malicious, +or misconfigured. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/unexpected_request_code.adoc b/doc/antora/modules/troubleshooting/pages/errors/unexpected_request_code.adoc new file mode 100644 index 00000000000..30f3596dd0e --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/unexpected_request_code.adoc @@ -0,0 +1,13 @@ += Unexpected Request Code + +Each `listen` section accepts only a limited number of packet types. +This means that the client is sending packets that the server doesn't +expect to receive. + +Since there is no negotiation in RADIUS, the client has no way of +knowing that the server is configured to receive. Fix either the +client to not send those packets, or fix the server to accept those +packets. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/unexpected_response_code.adoc b/doc/antora/modules/troubleshooting/pages/errors/unexpected_response_code.adoc new file mode 100644 index 00000000000..d5fa7951bf8 --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/unexpected_response_code.adoc @@ -0,0 +1,7 @@ += Unexpected Response Code + +Each request which is sent has a small number of valid responses. A +next hop can send a bad / wrong response. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/errors/unknown_packet_code.adoc b/doc/antora/modules/troubleshooting/pages/errors/unknown_packet_code.adoc new file mode 100644 index 00000000000..9a9e3e54a47 --- /dev/null +++ b/doc/antora/modules/troubleshooting/pages/errors/unknown_packet_code.adoc @@ -0,0 +1,10 @@ += Unknown Packet Code + +The packet code is 0, or is larger than 53. + +The RFCs define a limited number of packet codes. + +This can also mean that something is sending non-RADIUS packets to the RADIUS port. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/troubleshooting/pages/index.adoc b/doc/antora/modules/troubleshooting/pages/index.adoc index 88890bff3c3..c1e7e8609ca 100644 --- a/doc/antora/modules/troubleshooting/pages/index.adoc +++ b/doc/antora/modules/troubleshooting/pages/index.adoc @@ -1,16 +1,51 @@ = Troubleshooting -Troubleshooting is a step-by-step method used to determine the root cause of a problem and the processes how to resolve and test the fix. The goal of this guide is to enable the users to help user resolve the current issue and get FreeRADIUS server back into production. +The guides in this section enable administrators to quickly determine +the root cause of an issue, to resolve it, and to get the FreeRADIUS +server back into production. The guides also provide information that +helps administrators easily debug changes to complex policies. -Some of the more common troubleshooting issues are covered in the xref:ROOT:faq.adoc[FAQ]. The section is divided into the following areas: +The most important thing to know about these guides is that _method is +more important than memorization_. That is, there is no one piece of +information you can remember that will somehow solve all problems. +FreeRADIUS has extensive documentation, and there is no need to +memorize it. -* xref:user.adoc[User Management] -* xref:server.adoc[Server Configuration] -* xref:client.adoc[Client Configuration] -* xref:connect_nas.adoc[Connectivity-NAS] -* xref:datastore.adoc[Datastores] +Instead of memorization things, you should carefully troubleshoot the +proble,. Troubleshooting is the step-by-step method that helps you to +determine the root cause of a problem. Once the root cause is +determined, you should use similar step-by-step methods to fix the +problem, and verify that the fix works. + +This process can see, slow, but it is much more productive than making +a bunch of changes, in the hope that one of the changes will fix the +issue. As the saying goes, **slow is fast, and fast is slow**. + +== General Rules + +Run the server in debugging mode (`radiusd -X`). Look at the debug +output. Don't look at the output of `radclient. You cannot debug +server policies by looking at a simple binary `Access-Accept` or +`Access-Reject` on the client. + +== Common Errors + +The xref:errors/index.adoc[common errors] page covers the most common +errors that people see when trying to configure the server. If you +see an error which is unclear to you, you should start on that page. -If your server starts up successfully, *save* a copy of the configuration so you always have a "known working" configuration. When the server doesn’t start up, go back and verify the configuration and read the entire debug output. +The error messages produced by FreeRADIUS are necessrily short, and +cannot contain a full explanation of the issue. The documentation +pages are larger, and therefore contain those descriptions. In many +cases, the debug output of the server will point you to a specific +documentation page! + +== How to make Changes + +If your server starts up successfully, *save* a copy of the +configuration so you always have a "known working" configuration. When +the server doesn’t start up, go back and verify the configuration and +read the entire debug output. Follow these recommended steps to troubleshoot your server: @@ -30,5 +65,17 @@ The debug output show the current configuration and relevant information such as * The response packets contain the attributes you expect to see. +== Common Issues + +Some of the more common issues are covered in the +xref:ROOT:faq.adoc[FAQ]. The section is divided into the following +areas: + +* xref:user.adoc[User Management] +* xref:server.adoc[Server Configuration] +* xref:client.adoc[Client Configuration] +* xref:connect_nas.adoc[Connectivity-NAS] +* xref:datastore.adoc[Datastores] + // Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS.