Getting Started with FreeRADIUS

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.


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


Users are defined in the users file under the FreeRADIUS configuration directory. The content of the users file is used for both Authorization and Authentication purposes. This file is not the only source of users but is a simple and effective way to begin. Let's look at some key points about users.

Files module

The files module (rlm_files) reads the contents of the users file to determine if the user specified in the Access-Request exists and is authorized to use the NAS. It also determines what attributes should be returned to the client.

The files module may set the Auth-Type. This will determine the authentication method to be used. If a user is defined with a Cleartext-Password check item it will set Auth-Type = PAP.

The files module also supplies other modules with a value of "known good password" if one is defined. In our example it supplied the pap module (rlm_pap) with the value specified in the Cleartext-Password check AVP.

PAP module

The pap module (rlm_pap) was used for authentication. If the Auth-Type is set to PAP it will look for a "known good password" and compare this with the User-Password AVP's value. If it is the same, the module will pass the authentication request.

The request may still fail because of other modules in the FreeRADIUS authentication chain.

Users file

The users file does not contain any sections like clients.conf. This is because it is specific to the files module and not directly related to the configuration of the FreeRADIUS server itself.

To add an entry in the users file you define a username followed by zero or more comma-separated check items. This is followed by zero or more tab-indented lines with comma-separated reply items.

We assume you are using the default setup without any changes to the sitesenabled/default virtual server. If you have, for instance, activated the unix module under the authorize section and Alice is also defined as a system user, the system user with its password will be the preferred user instead of the one defined in the users file. The result will be that an Access-Reject packet is returned in response to the Access-Request if the passwords differ between Alice the system user and Alice the user defined in the users file.

Check items

The following entry requires that the Access-Request packet contains an AVP for NAS-IP-Address with a value of

"alice" Cleartext-Password := "passme", NAS-IP-Address == ''

The radtest program will set the value of NAS-IP-Address by default to the IP of the hostname specified in the /etc/hosts file. Later in this article you will see how to change this value.

Some AVPs have a special meaning and are used internally by FreeRADIUS. Although the incoming Access-Request does not contain an AVP called Cleartext-Password, the files module uses it internally to adjust the value of Auth-Type and to create a known good password, which can be used by the pap module for authentication.

Another example of a special AVP is when you want to reject or accept a user based on the username, no matter what their password may be. The previous line will change to one of the following.

"alice" Cleartext-Password := "passme", Auth-Type := Reject
"alice" Cleartext-Password := "passme", Auth-Type := Accept

Although Auth-Type appears to be a standard AVP check item, it is internal to FreeRADIUS and used to control the way in which the authentication will be done.

Reply items

Reply items are preceded with a line containing a username and zero or more check items. Reply items are indented with a single tab. Multiple items can fit on a single line separated by commas. They can also span over multiple lines, but have to be separated by commas.


You may have noticed that we use different operators when assigning values to AVPs. There are various operators available, which determine the logical outcome of a check or reply action. Operators will be discussed in more detail in the chapter on Authorization. For now you can remember that all reply items contain = and check items that need to match incoming AVPs are == while others are :=.


The users file allows for substitution. The special sequence of %{<AVP>} will replace the AVP with its actual value. In our setup we return a message to the user by substituting the User-Name AVP with its value (%{User-Name}).


The users file has a special user called DEFAULT. This user can be defined multiple times with different checks and replies. This user matches any username.

Because of this you should always put DEFAULT entries at the end of the users file. You should also take note of the special reply value called Fall-Through. If Fall-Through is not defined it takes on the value of no.

If an entry matches and Fall-Through is set to no (default if not specified), the search process stops. This means that the default value of no will cause the files module to return on the first match of a specified requirement inside the users file.

When Fall-Through is set to yes, searching the users file for further matches continues after a match has been discovered. We will now discuss two commonly used internal check AVPs: Login-Time and Simultaneous-Use.


Login-Time is a very powerful internal check AVP. It allows flexible authorization and its value is used by the logintime (rlm_logintime) module to determine if a person is allowed to authenticate to the FreeRADIUS server or not. This value is also used to calculate the Session-Timeout reply value. Session-Timeout is subsequently used by the NAS to limit access time.

The following line will grant Alice access only between 08:00 and 18:00 each day.

"alice" Cleartext-Password := "passme", Login-Time := 'Al0800-1800'

The logintime module will calculate the reply value of Session-Timeout if Alice has logged in within the permitted timeslots to inform the NAS how long she is allowed to stay connected. If Alice tries to access the network when she is not permitted, the request will be rejected.


Simultaneous-Use is another internal AVP used to specify the number of concurrent logins a user is allowed to have.

"alice" Cleartext-Password := "passme", Simultaneous-Use := '1'

The Simultaneous-Use check is used by the session section, which is part of the FreeRADIUS configuration. The session section makes use of either flat files (rlm_radutmp) or SQL data (rlm_sql) to determine if a user is already logged into an NAS.


In our example we used the Framed-IP-Address as a return AVP. This attribute can, however, be used in both a request and a reply. If the NAS sends this along with the access request, it is a request to the RADIUS server that this IP address is preferred for the given client. The RADIUS server can then decide if it will allow the use of the requested IP address or suggest a different one to the NAS by including this AVP with the Access-Accept packet.


Details of the radtest command will not be discussed here because the next section will show you how to find it yourself.

Helping yourself

Open source projects are sometimes criticized because they lack documentation and support. FreeRADIUS has done a great job in supplying proper documentation and ways to get help.

Installed documentation

There is plenty of documentation, which installs with FreeRADIUS. It is in the form of man pages, comments inside configuration files, various README files, and also rfc files.

Man pages

You may not always be sure which man pages are available as part of the FreeRADIUS installation. The following section will show you how you can find this out.

Time for action – discovering available man pages for FreeRADIUS

The following commands can be used as a guideline to first determine which FreeRADIUS packages are installed and subsequently determine which files are contained in the package.

dpkg systems

To list all the installed FreeRADIUS packages:

$> dpkg -l | grep radius

Use each of the listed packages as the package argument to the dpkg -L command. Let's take the freeradius-common package for instance:

$> dpkg -L freeradius-common

From the previous output we see that there are many man pages installed under the /usr/share/man directory.

rpm systems

To list all the installed FreeRADIUS packages:

$> rpm -qa | grep radius

Take each of the listed packages and use it as the argument to rpm -ql as shown:

$> rpm -ql <package name>

From the previous output we can locate the man pages installed with FreeRADIUS under the /usr/share/man directory.

radtest revisited

To get more details on radtest the following command will display its man page:

$> man radclient

The Synopsis section contains two handy options:

  • ppphint: Adding a value greater than one will cause radtest to add the Framed-Protocol = PPP AVP to the Access-Request packet.
  • nasname: Adding a hostname or IP address will cause radtest to add the NAS-IP-Address = <IP Address> to the Access-Request packet.

The following command adds the Framed-Protocol = PPP and NAS-IP-ADDRESS = attributes to the Access-Request packet.

$> radtest alice passme 100 testing123 1

Now that you know where the man pages are located, let's explore the radclient command's man page.


Radclient is the real thing since the radtest man page mentions that it is simply a front-end to radclient. Let's see what radclient is all about:

$> man 1 radclient

From the man page we can see that radclient gives us much more power as compared to radtest. The following command can be used as an equivalent to the radtest command used at the start of this article:

$> echo "User-Name=alice,User-Password=passme" | radclient auth testing123

The response from radclient returns a code number and does not clearly indicate a pass or fail for an Access-Request. This is where you need to know the RADIUS packet codes.

Here is the response of an Access-Accept packet (Code 2):

Received response ID 32, code 2, length = 40
Framed-IP-Address =
Reply-Message = "Hello, alice"

Here is the response of an Access-Reject packet:

Received response ID 59, code 3, length = 34
Reply-Message = "Hello, alice"

Radclient also offers us the opportunity to send accounting, status, and disconnect packets.

What just happened?

You have just learned how to find and use the man pages, which are part of the FreeRADIUS installation on your server.

Have a go hero – adding more AVPs to the auth request

Try some of these tasks as a further challenge:

  • The number of AVPs received by FreeRADIUS is fewer when we use radclient instead of radtest. See if you can add those missing ones to the standard input for the radclient.
  • Radtest also offers the option to read AVPs from a file. Create a file with the required AVPs and use it with radclient. Use the Packet-Type attribute in the file to specify the packet type inside the file.
  • If you use the Packet-Type inside a file remember the following important points:
    • Specify the packet type as auto on the command line.
    • The Packet-Type value is the numeric of the RADIUS packet code. This means that an Access-Request packet will have a value of 1.
    • You also need to specify an AVP for the destination port. Failing to do so will cause it not to be sent. Access-Request requires the following entry. Packet-Dst-Port=1812.

The following can be used as an example to work from:

User-Name = alice
User-Password = passme
NAS-IP-Address =
NAS-Port = 100
Packet-Type = 1
Packet-Dst-Port = 1812

Man pages are not the only source of information in the FreeRADIUS installation. The FreeRADIUS configuration files have many comments. This makes the configuration much easier.

Configuration file comments

The configuration files are filled with guidelines, tips, and pointers to more information. All this is contained in comments inside the configuration files.


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

Online documentation

There are many sources of information on FreeRADIUS available on the Internet. Some of this information is outdated or simply not correct. FreeRADIUS develops at a fast pace. Using outdated documentation can cause unexpected results leading to a lot of frustration.

The following is a list of recommended URLs to visit:

Getting Started with FreeRADIUS

Online help

If you have tried all the available documentation and still have problems you can make use of the FreeRADIUS mailing lists. This is a very effective way to get help, but you have to abide by a few basic rules for the benefit of everyone.

The FreeRADIUS home page has a Mailing Lists link, which you can follow for further instructions.

Once you have obtained the new knowledge it's time to apply it. The following section looks at recommended practices when configuring FreeRADIUS.

Golden rules

These golden rules are not my own, but the recommendations from the online documentation listed above. For best results follow them!

  • Do as little as possible—the default configuration should work as is.
  • Do not edit the default configuration files unless you understand what they do.
  • When you make changes, keep them small and make backups.
  • Confirm that the changes work as intended by running FreeRADIUS in debug mode and carefully observing the output during various scenarios.

Inside radiusd

This section gives a general overview on the workings of the FreeRADIUS server program called radiusd.

Configuration files

We've already said that the behavior of radiusd is determined by configuration files. The main configuration file for the FreeRADIUS server is radiusd.conf, which resides in the configuration directory. The location and name of the configuration directory depends on the Linux distribution and the manner in which FreeRADIUS was compiled and installed.

The radiusd.conf file consists of general items and various sections. Contents of other files and directories are included by using the special keyword $INCLUDE inside the radiusd.conf file.

Important includes

The following table lists important inclusions and their descriptions:

Getting Started with FreeRADIUS

Libraries and dictionaries

FreeRADIUS has many modules. Module file names are in the form of rlm_<module name>.

A module is a form of a library. All modules are libraries, but not all libraries are modules. These modules are located under a library directory, which is specified as libdir in radiusd.conf. Multiple locations can be listed by separating them with a colon character, for example:

libdir = /usr/lib/freeradius:/usr/local/my_freeradius

FreeRADIUS needs to resolve AVP names to numbers. This requirement is not only for AVPs, but also for VSAs. For this FreeRADIUS uses dictionary files. Dictionary files are text files which describe AVPs and VSAs.

There is a master dictionary file, which is used by both radiusd and client programs like radtest and radclient. This file is located under the configuration directory and called dictionary. This file has a $INCLUDE statement pointing to a directory, that contains many dictionary files. Files inside this dictionary directory are of the form dictionary.<vendor name>.

FreeRADIUS-specific AVPs

FreeRADIUS has its own special dictionary called dictionary.freeradius.internal. The AVPs in this dictionary are used internally by FreeRADIUS during operation. Internal AVPs that we have used up to now include Cleartext-Password, Auth-TypeX, and Login-Time.

Running as ...

FreeRADIUS runs on non-privileged ports (N>1023), which means you do not have to be root to run it.

The FreeRADIUS authors highly recommend that you run FreeRADIUS with as few permissions possible. The only reason for you to run FreeRADIUS as a root user is when you need access to files that only root can access. This is for instance when you want to use the system users on the Linux server as a user store (rlm_unix and rlm_pam) instead of the users file used by the files module. There are, however, ways around this by changing permissions on those files.

The radiusd.conf file has two directives that are set to specify the name of the user and group under which FreeRADIUS will run. They are user and group. If you comment these values out, FreeRADIUS will run as the user who started it.

Listen section

FreeRADIUS listens on all the available interfaces by default. You can, however, change this by specifying that it should only listen on a particular NIC or even a VPN tied to TUN/TAP interface. Alternatively you can specify that it should only listen on a specified IP address. There are various possibilities that allow you to tie interface and IP address combinations to virtual servers or request types. This feature in itself makes the FreeRADIUS server incredibly versatile.

If you have a multihomed server there is usually one interface that runs a very strict firewall. If clients connect through this interface, make sure that they are allowed through the firewall.
If you are running FreeRADIUS on a VPN interface, confirm that the VPN is already up and running during start-up before FreeRADIUS is started.

Log files

Production environments do not allow FreeRADIUS to run in debug mode all the time. When we run FreeRADIUS as a normal daemon it writes certain data to log files.

Inspecting these log files at regular intervals is very important to detect potential problems in your environment. Let's have a look at them.


The usual location for the radiusd log file is /var/log/radius/radius.log. You can also specify what should be logged to this file in the radiusd.conf file. There is a dedicated log section to fine tune the logging.

Who was logged in and when?

The command last in Linux gives a history of who has logged into the machine as well as the duration of the session. This is done by reading the file /var/logwtmp.

FreeRADIUS has a similar feature where the radlast command will read the /var/log/radius/radwtmp file to show all the users that were logged in through an NAS using FreeRADIUS. For this to work unix must be listed in the accounting section of the virtual server (enabled by default).

Who is logged in right now?

The who command lists all the users that are logged in at a specific time. This is done by reading the /var/run/utmp file.

FreeRADIUS has a similar feature where the command radwho will read the /var/log/radius/sradutmp file to show the users with active sessions right now. The sradutmp file is not present by default and has to be activated by uncommenting the sradutmp line in the accounting section of the virtual server (disabled by default).

You may think that radwho should read a file called /var/log/radius/radutmp. This file does exists, but it contains sensitive information. You can read about the difference between the two on this Wiki page:

Knowing these log file locations and commands to extract important information will give you the edge in times of trouble.


This article gave us initial hands-on experience of FreeRADIUS. We have also learned more on documentation and the workings of the FreeRADIUS server called radiusd.

Specifically, we have covered:

  • Configuring FreeRADIUS: FreeRADIUS has a primary configuration file called radiusd.conf. Various other configuration files get sourced through the primary configuration file using the $INCLUDE keyword.
  • NAS devices: An NAS device is a RADIUS client and shares a secret with the RADIUS server. NAS devices are defined in the clients.conf file. The localhost is by default defined as a client. This enables us to do various tests with RADIUS client programs like radclient and radtest.
  • Defining users: The users file is a quick and simple way to define users and is used by the files module. Users defined in the users file have check and reply AVPs. Some of these AVPs have special meaning to FreeRADIUS and influence the behavior of the authentication and authorization outcomes.
  • Finding documentation: FreeRADIUS has local and online documentation. On our own machine we can use man pages and also read comments inside configuration files for guidance. There is also documentation available on the Internet specifically on the FreeRADIUS home page. There are also mailing lists to which we can post questions.
  • When we configure: There are a few rules to stick by when changing the configuration. Backup, make small changes, run in debug mode, and test.

We have also looked at various components and aspects of the radiusd program. This includes configuration files that are sourced, modules, dictionaries, AVPs specific to FreeRADIUS, log files, and running it with minimum rights.

Further resources on this subject:

You've been reading an excerpt of:

FreeRADIUS Beginner's Guide

Explore Title