Getting Started with FreeRADIUS

6 min read

After FreeRADIUS has been installed it needs to be configured for our requirements. This article by Dirk van der Walt, author of FreeRADIUS Beginner’s Guide, will help you to get familiar with FreeRADIUS. It assumes that you already know the basics of the RADIUS protocol.

In this article we shall:

  • Perform a basic configuration of FreeRADIUS and test it
  • Discover ways of getting help
  • Learn the recommended way to configure and test FreeRADIUS
  • See how everything fits together with FreeRADIUS

(For more resources on this subject, see here.)

Before you start
This article assumes that you have a clean installation of FreeRADIUS. You will need root access to edit FreeRADIUS configuration files for the basic configuration and testing.

A simple setup

We start this article by creating a simple setup of FreeRADIUS with the following:

  • The localhost defined as an NAS device (RADIUS client)
  • Alice defined as a test user

After we have defined the client and the test user, we will use the radtest program to fill the role of a RADIUS client and test the authentication of Alice.

Time for action – configuring FreeRADIUS

FreeRADIUS is set up by modifying configuration files. The location of these files depends on how FreeRADIUS was installed:

  • If you have installed the standard FreeRADIUS packages that are provided with the distribution, it will be under /etc/raddb on CentOS and SLES. On Ubuntu it will be under /etc/freeradius.
  • If you have built and installed FreeRADIUS from source using the distribution’s package management system it will also be under /etc/raddb on CentOS and SLEs. On Ubuntu it will be under /etc/freeradius.
  • If you have compiled and installed FreeRADIUS using configure, make, make install it will be under /usr/local/etc/raddb.

The following instructions assume that the FreeRADIUS configuration directory is your current working directory:

  1. Ensure that you are root in order to be able to edit the configuration files.
  2. FreeRADIUS includes a default client called localhost. This client can be used by RADIUS client programs on the localhost to help with troubleshooting and testing. Confirm that the following entry exists in the clients.conf file:

    client localhost {
    ipaddr =
    secret = testing123
    require_message_authenticator = no
    nastype = other

  3. Define Alice as a FreeRADIUS test user. Add the following lines at the top of the users file. Make sure the second and third lines are indented by a single tab character:

    “alice” Cleartext-Password := “passme”
    Framed-IP-Address =,
    Reply-Message = “Hello, %{User-Name}”

  4. Start the FreeRADIUS server in debug mode. Make sure that there is no other instance running by shutting it down through the startup script. We assume Ubuntu in this case.

    $> sudo su
    #> /etc/init.d/freeradius stop
    #> freeradius -X

    You can also use the more brutal method of kill -9 $(pidof freeradius) or killall freeradius on Ubuntu and kill -9 $(pidof radius) or killall radiusd on CentOS and SLES if the startup script does not stop FreeRADIUS.

  5. Ensure FreeRADIUS has started correctly by confirming that the last line on your screen says the following:

    Ready to process requests.

    If this did not happen, read through the output of the FreeRADIUS server started in debug mode to see what problem was identified and a possible location thereof.

  6. Authenticate Alice using the following command:

    $> radtest alice passme 100 testing123

  7. The debug output of FreeRADIUS will show how the Access-Request packet arrives and how the FreeRADIUS server responds to this request.
  8. Radtest will also show the response of the FreeRADIUS server:

    Sending Access-Request of id 17 to port 1812
    User-Name = “alice”
    User-Password = “passme”
    NAS-IP-Address =
    NAS-Port = 100
    rad_recv: Access-Accept packet from host port 1812,
    id=147, length=40
    Framed-IP-Address =
    Reply-Message = “Hello, alice”

What just happened?

We have created a test user on the FreeRADIUS server. We have also used the radtest command as a client to the FreeRADIUS server to test authentication.

Let’s elaborate on some interesting and important points.

Configuring FreeRADIUS

Configuration of the FreeRADIUS server is logically divided into different files. These files are modified to configure a certain function, component, or module of FreeRADIUS. There is, however, a main configuration file that sources the various sub-files. This file is called radiusd.conf.

The default configuration is suitable for most installations. Very few changes are required to make FreeRADIUS useful in your environment.


Although there are many files inside the FreeRADIUS server configuration directory, only a few require further changes. The clients.conf file is used to define clients to the FreeRADIUS server.

Before an NAS can use the FreeRADIUS server it has to be defined as a client on the FreeRADIUS server. Let’s look at some points about client definitions.


A client is defined by a client section. FreeRADIUS uses sections to group and define various things. A section starts with a keyword indicating the section name. This is followed by enclosing brackets. Inside the enclosing brackets are various settings specific to that section. Sections can also be nested.

Sometimes the section’s keyword is followed by a single word to differentiate between sections of the same type. This allows us to have different client entries in clients.conf. Each client has a short name to distinguish it from the others.

The clients.conf file is not the only file where client sections can be defined although it is the usual and most logical place. The following image shows nested client definitions inside a server section:

(Move the mouse over the image to enlarge.)

Client identification

The FreeRADIUS server identifies a client by its IP Address. If an unknown client sends a request to the server, the request will be silently ignored.

Shared secret

The client and server also require to have a shared secret, which will be used to encrypt and decrypt certain AVPs. The value of the User-Password AVP is encrypted using this shared secret. When the shared secret differs between the client and server, FreeRADIUS server will detect it and warn you when running in debug mode:

Failed to authenticate the user.
WARNING: Unprintable characters in the password. Double-
check the shared secret on the server and the NAS!


When defining a client you can enforce the presence of the Message-Authenticator AVP in all the requests. Since we will be using the radtest program, which does not include it, we disable it for localhost by setting require_message_authenticator to no.


The nastype is set to other. The value of nastype will determine how the checkrad Perl script will behave. Checkrad is used to determine if a user is already using resources on an NAS. Since localhost does not have this function or need we will define it as other.

Common errors

If the server is down or the packets from radtest cannot reach the server because of a firewall between them, radtest will try three times and then give up with the following message:

radclient: no response from server for ID 133 socket 3

If you run radtest as a normal user it may complain about not having access to the FreeRADIUS dictionary file. This is required for normal operations. The way to solve this is either to change the permissions on the reported file or to run radtest as root.


Please enter your comment!
Please enter your name here