Log InIf you’re just getting started with FreeRADIUS, it can sometimes seem overwhelming when you run into problems. To the beginner, FreeRADIUS looks complex, but the debug troubleshooting information help to manage that complexity. In fact, your FreeRADIUS system is surprisingly straightforward if you know how to interpret the debug information.
This article will cover the most common error messages you are likely to encounter, and what to do about them.
How do I get debug information from FreeRADIUS?
From your command line, type
radiusd -X
or
freeradius -X
This starts FreeRADIUS in debug mode, which means that it will print useful information about what is happening as FreeRADIUS starts up and processes requests. This information will include not only which files it’s reading, but also the configuration items it’s reading from those files.
The server may already be running on your system, in which case you will need to stop the background process before running it in debug mode. The exact process for doing so is system-dependent, and we cannot document every system here.
If you run into problems with FreeRADIUS, running in debug mode should be the first thing you do.
If you ask for help on the FreeRADIUS mailing list (which we encourage!) without posting the debug output, our immediate response will usually be to ask for the output from radiusd -X. That’s because the debug output contains diagnostic information which almost always can identify the problem. If the experts need to read the debug output to solve issues, then you should be reading it, too!
The FreeRADIUS Wiki has a detailed guide available here. We recommend reading that page, as it has additional useful information which can help.
That being said, there are some common issues which come up a lot. We’ve summarized some common messages here, including what they mean, and how to solve them.
Message: Received packet from unknown client
What it means: Your NAS or Access Point hasn’t been defined as a client in your configuration.
Solution: Edit the raddb/clients.conf file, and make sure that your NAS is correctly defined as a client.The debug output will also show you which clients are being loaded, and you should check that, too. Sometimes people edit one file, when the server is loading a different one. Reading the debug output will tell you which file is being loaded, and which clients are being defined.
The out-of-the-box client.conf file is extensively commented with instructions on how to use it. You can also consult our additional documentation for more detail about how to define clients.
Message: invalid Message-Authenticator! (Shared secret is incorrect)
What it means: At the risk of sounding obvious, this error message means exactly what it says: The shared secret between FreeRADIUS and the NAS do not match. Either FreeRADIUS or the NAS is not using the shared secret you think they are.
Solution: Double check the raddb/clients.conf file and make sure that the shared secret is what you expect. Then double check your NAS or Access Point configuration for the shared secret and make sure that it is the same.
If you have checked both FreeRADIUS and the NAS and it appears that the shared secret is identical but you are still getting the same error, refer to this article for additional troubleshooting suggestions.
Message: ERROR: TLS Alert read:fatal:unknown CA
What it means: The CA (Certification Authority) is not recognized by the client.
Solution: Setting the correct CA is something that needs to be configured on the client machine, rather than on the FreeRADIUS server. Every client machine which performs EAP authentication must have the correct CA added to its configuration.
We’ve provided a detailed walkthrough with screenshots in this step-by-step guide.
Message: Unknown EAP type <eap type>
What it means: The client system is not using the expected EAP type, or the EAP type specified in the client is not compatible with what you have configured on FreeRADIUS.
Solution: In this situation you have two options.
1) Configure your client to use the expected EAP type. This is very client specific and outside the scope of this article. You will need to check the documentation for your client
2) Configure FreeRADIUS to allow that specific EAP type. To do this in FreeRADIUS, you need to edit the mods-available/eap file. The out-of-the-box file provides instructions and guidelines for correctly configuring the EAP type. You can view the file in GitHub, or consult our additional documentation.
Message: Instantiation failed for module <database>
What it means: FreeRADIUS is not able to connect to the database. Note that each database responds with slightly different wording when an attempt to connect to it fails. FreeRADIUS simply passes along those error messages. A typical series of error messages in the FreeRADIUS debug readout might read:
Instantiating module "sql" from file raddb/mods-enabled/sql rlm_sql (sql): Attempting to connect to database ... ... database-specific errors ... Instantiation failed for module "sql"
Solution: The correct credentials, hostname, and other parameters must be specified in the database configuration file located in the directory raddb/mods-enabled/. The files in this directory are usually symbolic links to the corresponding ones in the raddb/mods-available/ directory.
Each database has a separate configuration file that is named after the database. For example:
As a best practice, you should be checking connectivity to your database independently of the EAP communication with FreeRADIUS. Naturally, the methods for testing database connection depends on which database you’re using, and is independent from FreeRADIUS. You should consult your database documentation for information on how to test for connectivity.
Once you have established that your database is in fact up and running and can respond to queries, all you have to do with FreeRADIUS is to provide the database hostname and credentials in the appropriate configuration file.
When FreeRADIUS successfully connects with the database, the debug readout should display something like:
Connecting to database Searching for <the database name>
or
Performing query <the query>
or
Returning known good password <the password>
Message: Access denied for user <username@hostname>
What it means: FreeRADIUS can connect to the database, but is using incorrect credentials, or credentials that do not have the permission to read the password.
Note that, as in the previous error message, each database responds with slightly different wording when it receives faulty credentials. FreeRADIUS simply passes along those error messages.
Solution: The correct credentials must be specified in the database configuration file located in the directory raddb/mods-available/.
Double check that the credentials specified in the configuration file are given the correct admin privileges in the database. Consult your database documentation for guidance on creating and permissioning user credentials.
Message: No Cleartext-Password configured. Cannot create NT-Password
What it means: The authentication protocol used by FreeRADIUS and the password format are not designed to work together. In this case, FreeRADIUS can communicate with the database, and has the correct credentials to read the password, it just can’t understand the format that the password is stored in.
Passwords may be stored in a database in many forms. For example: Clear-text, MD5 hashed, crypt’d, NT hash.
You may see messages like No Cleartext-Password configured. Cannot create NT-Password
Unfortunately, authentication protocols used in RADIUS are not always compatible with the way the passwords have been stored in the database.
Solution: In this situation you have three options.
1) Change the authentication protocol you are using to something that is compatible with the storage format 2) Change the password storage format in the database. Unfortunately, this strategy often requires all users to change their passwords.
3) Use an intermediary (such as Samba) to communicate between the database and the authentication client. This is the approach we recommend when Active Directory is used for password storage.
For a more detailed discussion of this topic, see our article on password and protocol compatibility.
Problem: FreeRADIUS accepts a user, but they still don’t get on the network
What it means: The user has provided the correct credentials and has been authenticated, however, FreeRADIUS has not provided the AccessPoint with the information the AccessPoint needs in order to place that user on the network.
This can be challenging to detect, because so far as FreeRADIUS is concerned, the user has been correctly authenticated. And, told the AccessPoint to let the user on the network. Because FreeRADIUS thinks that everything is fine, there are no error messages to see in FreeRADIUS.. The only symptom is that the AccessPoint doesn’t do what is expected.
Unfortunately, there is no provision in the RADIUS protocol for the NAS to provide feedback to FreeRADIUS that there is a problem. As a result, these issues can be difficult to debug. Unlike FreeRADIUS, most NAS equipment offers little in the way of debug logs.
This situation sometimes arises when the network is separated into different VLANs (Virtual Networks) and needs specific information about which VLAN the user should be placed in.
Solution: Consult the log files on the NAS to get information about why the user was not let onto the network, and whether it needs additional information from FreeRADIUS in order to decide what to do with an authenticated user.
Debugging is a step-by-step process
When trying to solve issues with a FreeRADIUS configuration, the debug output provides valuable information about what is going wrong. Generally, a successful approach is to revert back to the default FreeRADIUS configuration and then change one thing at a time, using the debug mode as a way to understand what is working and what isn’t.
For example, the errors outlined above can help isolate the culprit if, for example, a user can’t connect to the WiFi network. A useful process of elimination might look like:
- Is the NAS or AccessPoint defined as a client?
- Is the Shared Secret between FreeRADIUS and the NAS correct?
- Is the correct certificate being used?
- Does the user system know about the CA (Certification Authority)?
- Is the user system using the expected EAP type?
- Can FreeRADIUS connect to the database?
- Does FreeRADIUS have the correct admin account and permissions to read the password in the database?
- Is the password in the database stored in a form that is compatible with what the user entered?
- Is FreeRADIUS returning the appropriate VLAN information (if applicable)?
If one or more of these elements are not working as expected, the FreeRadius debug output will provide clues to where the problem is. Once you know the problem, the solution is usually straightforward.
Need more help?
Network RADIUS has been helping clients around the world design and deploy their RADIUS infrastructure for 20 years. We specialize in complex systems and have seen pretty much every variation and problem out there. If you want help from the people who wrote FreeRADIUS, visit our quote page to contact us for a consultation.
