*** Server does not start
**** xref:network/bind.adoc[Failed binding to socket]
-*** Common Errors*
+*** Common Errors
**** xref:network/shared_secret.adoc[Shared secret is incorrect]
**** xref:network/packet_fails_verification.adoc[Packet fails verification]
**** xref:network/message_authenticator_invalid.adoc[Message-Authenticator fail verification]
**** xref:network/unexpected_request_code.adoc[Unexpected request code]
**** xref:network/message_authenticator_missing.adoc[Message-Authenticator is missing]
**** xref:network/proxy_state_missing.adoc[Proxy-State is missing]
-**** xref:network/no_matching_request.adoc[Did not find request which matched response]
+**** xref:network/packet_fails_verification.adoc[Packet fails verification]
+**** xref:network/no_matching_request.adoc[Did not find request which matches response]
*** Other Errors
**** xref:network/unexpected_response_code.adoc[Unexpected response code]
-**** xref:network/too_many_attributes.adoc[Packet contains too many attributes]
+**** xref:network/too_many_attributes.adoc[Too many attributes]
**** xref:network/io_error.adoc[IO error]
*** Rare Errors
= Attribute 0 is Invalid
-Either the client is completely broken, or the packet is not RADIUS.
+This error indicates that a packet can't be processed as expected and means that:
+
+ * the client is completely broken, or
+
+ * the packet doesn't follow the RADIUS standards.
+
+RADIUS packets need to follow a format defined by RADIUS RFCs. These xref:developers:rfc/index.adoc[RFCs] standardise how users are authenticated on a network. If a packet doesn't meet the basic format requirements, it may show a problem with the client or the packet itself. For example, the client could send wrong or incomplete info. The packet might get corrupted during transmission or it could have come from a different protocol.
+
+To fix this issue, check that the client uses the RADIUS protocol. Also, ensure there are no software or hardware problems. Check that the client and server are communicating using the RADIUS protocol. To do this, check the packet capture or network traffic to confirm the packets being sent are properly formatted RADIUS packets.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Attribute Header Overflows the Packet
-The client is either completely broken, or the packet is not RADIUS.
+The server detected a serious issue with the structure of a received packet. The attribute header extends beyond the end of the packet, which is not valid. This occurs when the client sending the packet is broken or has an incorrect setup.
+
+Another possibility is that the server didn't receive a valid RADIUS packet. The server can't process the packet as a RADIUS message because of this structural error(s). Review your configurations and verify the network's stability and congestion.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Attribute has Invalid Length
-Either the client is completely broken, or the packet is not RADIUS.
+The server receives a network packet with an attribute that isn't the right length for the RADIUS protocol. The client sending the packet is broken and is sending invalid packets of the wrong size.
+
+Also, the data the server receives may not be a valid RADIUS packet. These packets may be some other network traffic that is unrelated or corrupted. In either case, the server can't process the packet as a valid RADIUS message because the attribute length is incorrect.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
The client is either completely broken, or the packet is not RADIUS.
+The server receives a network packet with an attribute that isn't the right length for the RADIUS protocol. The client sending the packet is broken and is sending invalid packets of the wrong size.
+
+Also, the data the server receives may not be a valid RADIUS packet. These packets may be some other network traffic that is unrelated or corrupted. In either case, the server can't process the packet as a valid RADIUS message because the attribute length is incorrect.
+
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Failed binding to socket
-This error message is produced when the server cannot open a socket on
-the specified port. There are a few reasons why this can happen, but
-the most common one is that there is already another instance of
-FreeRADIUS running.
+The FreeRADIUS server was unable to open a network socket on the specified port. The most common reason for this is that there's another FreeRADIUS instance running in the background.
-**Cause:** You are trying to run the server in
-xref:ROOT:debugging/radiusd_X.adoc[debug mode], without stopping the
-server that is running in the background.
+If you start the server in debug mode without stopping the current process, it can't bind to the port. To resolve this issue, stop any running FreeRADIUS server before you start it in debug mode.
-**Action:** Stop the server which is running in the background, and
-you can then run it in debug mode.
-
-**Cause:** The server does not have permission to open the given socket/port.
-
-**Action:** Check that the server has the correct UID/GID permissions.
-
-**Action:** Check that something like SeLinux is not preventing the
-server from opening sockets.
+Another possibility is that the server doesn't have the correct permissions (UID/GID) to open the socket. Security mechanisms like SeLinux can also block the server from accessing the port. To fix these issues, ensure the server has the correct permissions. Also, check your security settings to confirm that nothing is blocking socket access.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= 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.
+The message "Failure Decoding the Packet" means that the server can't interpret a received network packet. This failure may be caused by one of the following:
+
+* The server has run out of memory, preventing it from processing the packet.
+* There are malformed Vendor-Specific Attributes (VSAs) within the packet.
+* The Type-Length-Value (TLV) is too deep.
+* Unusual or unexpected packet structures cause packets to be malformed in some weird way.
+
+In all these cases, the server can't process the packet because its format is invalid or corrupt.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Errors
+= Network Errors
If the server isn't processing packets, this is due to two common
problems. Either it is either not receiving packets, or else it
= IO Error
-Some kind of network / OS error. These are hard to debug.
+Network or OS errors can happen due to hardware failures, network issues, or unexpected system behaviour. These factors make diagnosis and resolution difficult. For example, a company might experience frequent downtime from an unreliable internet provider. Similarly, a website may crash when traffic exceeds the server's capacity.
+
+A small mistake in the network settings can cause many errors which may cause more disruptions including system failure. Also, the lack of standardisation and interoperability between systems makes things difficult. It becomes hard to find and fix the root cause of errors.
+
+Administrators can reduce risks by taking these steps:
+
+* Invest in strong infrastructure.
+* Perform regular maintenance and updates.
+* Develop emergency and/or backup plans.
+
+These actions help minimise downtime and keep operations running smoothly.
+
+To identify the issue, you may need to review logs, check system resources, or talk to network administrators. Fixing network and OS errors requires careful troubleshooting and in-depth knowledge of the FreeRADIUS eco-system.
+
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Message-Authenticator Fails Verification
-The shared secret is wrong. Fix it.
+include::partial$secret_wrong.adoc[]
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Message-Authenticator has Invalid Length
+= 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.
-= Message-Authenticator is Missing
+= Message-Authenticator is missing
-This is the BlastRADIUS stuff.
+This error happens when the Message-Authenticator attribute is missing from the RADIUS packet. This attribute is used to check the integrity and authenticity of RADIUS messages. The Message-Authenticator stops malicious attacks. Without it, the server faces serious risks, like the BlastRADIUS attack. BlastRADIUS attacks happen when the Message-Authenticator is missing or used incorrectly. Unauthorised users gain access to network resources and services, putting the system's security and integrity at risk.
+
+The Message-Authenticator attribute acts like a digital fingerprint for RADIUS messages. It verifies that the messages are genuine. Sending a packet without it is like not having a tracking number. It's difficult to check who sent it or what's inside. This error indicates a potential security risk when it appears. The packet may not be trustworthy or follow best practices. This highlights the urgency to fix the issue to prevent security breaches.
+
+
+This error can stem from a misconfigured RADIUS server or a faulty client. To resolve it and avoid future problems, understanding the cause is important.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Header 'Length' does not match received packet length
-The packet is likely not RADIUS. Block the source IP address.
+The RADIUS protocol defines a header with a 'Length' value to indicate the packet's size. The packet header's 'Length' field shows a size that does not match the actual packet size. If this value and the packet's actual size do not match, the packet is likely malformed or not a valid RADIUS packet.
+
+Discrepancies can occur because of network errors, misconfigured clients, or malicious activity. To be safe, we recommend blocking the source IP address to prevent any issues or attacks.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Did not find Request which matches Response
+= 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:
+The xref:reference:raddb/mods-available/radius.adoc[radius] module shows this error message when it sends packets. The issue may occur when the server:
-* sent a request
-* never got a response
-* gave up on the original request
-* finally received a response
+* Sent a request.
+* Never received a response.
+* Timed-out or gave up on the original request.
+* Finally received a response.
-This means that packet loss is occurring, or the next hop server is
-taking 30+ seconds to respond. Fix it so that it responds quickly.
+This often indicates network issues and / or packet loss. Packets may
+be lost or delayed by the next hop server. If the server over 30
+seconds to reply, the original request fails. The late response cannot
+be linked to it.
+
+To resolve this, check the network for reliability and bandwidth
+availibility. Ensure the next hop server responds quickly, with
+minimal packet loss and delays.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Packet Fails Verification
+= Packet fails verification
-The shared secret is wrong. Fix it.
+include::partial$secret_wrong.adoc[]
+
+If a packet fails verification, the server can't confirm if the packet is authentic, so the authentication process fails. The mismatch can happen during setup or password updates not being the same.
+
+An example is when a network administrator sets up a RADIUS client with a shared secret. But they forget to update the server with the same secret. When the client tries to authenticate, the packet won't be verified, and authentication fails.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
+
= 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.
+The "Packet Too Large" error occurs when a client sends a RADIUS packet with too much data. The RADIUS protocol limits packet size to 4k, ensuring reliable communication and interoperability between network devices. If a packet exceeds this limit, the server can't process it and reports an error.
+
+This error means that the client is broken/misconfigured. Either the client sends too much data or doesn't follow the protocol guidelines. To fix this, check the client's setup and make sure it meets the RADIUS packet size limits.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Packet Too Small
+= 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.
+RADIUS packets must be at least 20 bytes in size. If you see this error, it means that non-RADIUS packets are being sent to the RADIUS port. Update your 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.
-= Proxy-State Missing
+= Proxy-State is missing
-this is for the BlastRADIUS stuff.
+This error occurs when the Proxy-State attribute is missing from a RADIUS packet. The Proxy-State attribute is vital for servers to track and manage requests. Without it, servers struggle to manage requests, which impacts authentication and performance.
+
+A missing Proxy-State attribute can pose serious security risks, including the BlastRADIUS attack. This attack can cause a denial-of-service or allow unauthorised network access. Without the Proxy-State attribute, the server is more open to attacks.
+
+The Proxy-State attribute also stops replay attacks. An intruder intercepts a real request and then resends it, thereby gaining unauthorized access. By including this attribute in RADIUS packets, servers can process requests securely.
+
+The Proxy-State attribute is critical for maintaining network security. It ensures RADIUS systems remain secure and reliable, but it requires proper configuration and management to function effectively.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Shared Secret is incorrect.
+= Shared secret is incorrect
+
+include::partial$secret_wrong.adoc[]
+
-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.
-= Too Many Attributes
+= 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.
+If you see an error about max_attributes, it usually means a client is sending too many attributes. It's probably due to a misconfigured client or a possible attack on the server. Either way, check what the client is doing before changing the configuration.
-The value is large enough for nearly all common use-cases. Take care
-before increasing it.
+The default value for max_attributes is high enough for most common use cases. However, if you do increase this limit, be careful. It might make the server vulnerable to resource exhaustion attacks.
-If you see this error, it's likely that a client is either malicious,
-or misconfigured.
+Each `listen` section has a `max_attributes` setting to limit the number of attributes that can be included in a single request. By enforcing this limit, the server protects itself from clients that might try to overload it. For example, malicious clients that consume large amounts of memory on the server for each request.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= 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.
+This error occurs when a RADIUS server is set up incorrectly. The listen section specifies which RADIUS packets the server accepts on a port or interface. If a client sends a packet that does not match the configuration, the server rejects it and returns an "Unexpected Request Code" error.
+
+A key aspect of the RADIUS protocol is that it does not have a negotiation phase between the client and server. This is different from other protocols. For example, HTTP allows a client to send an OPTIONS request to check a server's capabilities. In contrast, a RADIUS client cannot discover which packet types a server will accept. This means someone has to manually adjust settings if there’s a mismatch. These issues cause admin problems. Many forum posts show challenges with RADIUS setups. Support requests also highlight these troubles. For instance, in a university, various departments may use different RADIUS clients. Making sure these clients work with the central RADIUS server can be complex.
+
+To fix an Unexpected Request Code error, you have two options. First, change the client to send only the expected packet types. This may involve updating the client’s software or adjusting its configuration files. This ensures the client works within the limits set by the server's listen section.
+
+You can also change the server's listen section to accept the packet types sent by the client. This may mean adding new sections or adjusting existing ones. This flexibility helps network admins configure the RADIUS server to fit their clients' needs. It ensures smooth communication and authentication.
+
+For example, adding a new listen section for a VPN service lets users access the network securely from remote locations. This does not disrupt existing authentication flows. By fixing the Unexpected Request Code issue, admins can build stronger RADIUS configurations. This improves network security and reliability.
+
+
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Unexpected Response Code
+= Unexpected response code
-Each request which is sent has a small number of valid responses. A
-next hop can send a bad / wrong response.
+Each request sent has only a few valid responses that can be processed successfully. The next hop, such as a server or device, can send a bad or wrong response. When sending a request within a network protocol, only a limited set of responses is expected from the recipient. The invalid or incorrect response may be due to misconfiguration, software bugs, or unexpected network behavior.
+
+Receiving a bad or wrong response can disrupt normal operations and may need troubleshooting to find the cause and ensure systems communicate properly.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
= Unknown Packet Code
-The packet code is 0, or is larger than 53.
+This error occurs when the network processes RADIUS packets as part of the user authentication process. Each RADIUS packet has a "code" field that defines its type, like Access-Request or Access-Accept. The Internet Engineering Task Force (IETF) specifies valid codes in their documents. These codes must be between 1 and 53. Any code outside this range, such as 0 or above 53, is invalid and cannot be processed.
-The RFCs define a limited number of packet codes.
+When an invalid code appears, it usually means two things. First, the device or client sending the packet may not follow RADIUS rules. This can result in bad packets. It might happen if the manufacturer didn’t implement the protocol correctly or due to a software bug. For instance, a mistake in their RADIUS setup could lead to invalid codes.
-This can also mean that something is sending non-RADIUS packets to the RADIUS port.
+Second, the error might show that traffic not meant for RADIUS is sent to the RADIUS port. This often happens because of a misconfigured network or device. A network administrator may have set up a device to send extra traffic to the RADIUS port. This can overwhelm the server with bad packets.
+
+In both cases, the server cannot process the packet. This leads to authentication failures and potential network issues. To fix this, network administrators need to find the source of the problem, whether it's a faulty client or misconfigured settings. They must ensure only valid RADIUS packets reach the server. This may involve updating software, adjusting network settings, or blocking non-RADIUS traffic. By fixing the Unknown Packet Code error, administrators can stabilize the network and prevent future authentication issues.
// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
--- /dev/null
+The shared secret is wrong. Fix it! RADIUS uses a shared secret, a key security feature, to ensure that communications are secure across the network and devices. This is a password or key known only to the client and server.
+
+If you see this message, it means the shared secret on the client and server don’t match. To resolve this issue, check that the shared secret is identical on both the client and server.
projects / thirdparty / freeradius-server.git / commitdiff
