Skip to content

Latest commit

 

History

History
229 lines (173 loc) · 8.92 KB

index.adoc

File metadata and controls

229 lines (173 loc) · 8.92 KB
Raw

Installation

FreeRADIUS is available from multiple sources:

We highly recommend using the official packages from Network RADIUS, where available.

The documents in this section cover details of the above installation methods, as well as instructions on building packages locally.

Getting Started

This page describes how to perform the initial configuration of FreeRADIUS. It assumes a basic knowledge of Unix system administration. No RADIUS knowledge is required.

Installing the Server

Where possible, while learning the basics, it is suggested that beginners use the packaging system that is used by your operating system. The version that is supplied by your OS might be out of date, but it is likely to work "out of the box". The only exception to this is if your operating system supplies an older major version, as you will then be learning an obsolete configuration.

Once you have learnt how FreeRADIUS works, it is then highly recommended to move to the latest released stable version before moving into production.

If you need to install it yourself, the Wiki building and installing(http://wiki.freeradius.org/building/Home) page contains detailed instructions for a number of platforms.

Otherwise, we assume that you can install the server via something like yum install freeradius, or apt-get install freeradius.

Note that in Debian-based systems, the server daemon is called freeradius instead of radiusd The configuration files are also located in /etc/freeradius/ instead of /etc/raddb/. We use radiusd and /etc/raddb/ in this guide, and trust that Debian administrators can translate to their system.

Some background

Once the server has been installed, the first thing to do is change as little as possible. The default configuration is designed to work everywhere, and to perform nearly every authentication method.

Do not edit the default configuration files until you understand what they do. This means reading the documentation contained in the comments of the configuration files.

Many common configurations are documented as suggestions or examples in the configuration files. Many common problems are discussed in the configuration files, along with suggested solutions.

We recommend reading the configuration files, in large part because most of the configuration items are documented only in the comments in the configuration files.

We recommend reading the debug output of the server. While it contains a lot of text, it describes exactly what is happening within the server and usually contains error messages which describe what went wrong, and how to fix it.

Starting the server

When the server has been installed on a new machine, the first step is to start it in debugging mode, as user root:

# radiusd -X

This step demonstrates that the server is installed and configured properly. If the output says Ready to process requests, then all is well.

Otherwise, typical errors include Address already in use, which means that there is another RADIUS server already running. You will need to find that one and stop it before running the server in debugging mode.

The output from radiusd -X can sometimes be confusing at first, so there is a page with an [explanation of the debug output](/radiusd-X).

Initial Tests

Testing authentication is simple. Edit the users file (in v3 this has been moved to raddb/mods-config/files/authorize), and add the following line of text at the top of the file, before anything else:

testing Cleartext-Password := "password"

Start the server in debugging mode (radiusd -X), and run radtest from another terminal window:

$ radtest testing password 127.0.0.1 0 testing123

You should see the server respond with an Access-Accept. If it doesn’t, the debug log will show why. In version 2, you can paste the output into the [debug form](http://networkradius.com/freeradius-debugging/), and a colorized HTML version will be produced. In version 3, the output will already be colorized in the terminal. Look for red or yellow text, and read the relevant messages. They should describe exactly what went wrong, and how to fix the problem.

If you do see an Access-Accept, then congratulations, the following authentication methods now work for the testing user:

PAP, CHAP, MS-CHAPv1, MS-CHAPv2, PEAP, EAP-TTLS, EAP-GTC, EAP-MD5.

The next step is to add more users, and to configure databases. Those steps are outside of the scope of this short web page, but the general method to use is important, and is outlined in the next section.

Adding a client

When we discuss clients, we mean clients of the RADIUS server, e.g. wireless access point, network switch or other form of NAS. NOT the network clients - such as laptops, tablets etc - they do not talk directly to the RADIUS server.

The above test runs radtest from localhost. It is useful to add a new client, which can be done by editing the clients.conf file. Add the following content:

client new {
    ipaddr = 192.0.2.1
    secret = testing123
}

You should change the IP address 192.0.2.1 to be the address of the client which will be sending Access-Request packets.

The client should also be configured to talk to the RADIUS server, by using the IP address of the machine running the RADIUS server. The client must use the same secret as configured above in the client section.

Then restart the server in debugging mode, and run a simple test using the testing user. You should see an Access-Accept in the server output

The following steps outline the best known method for configuring the server. Following them lets you create complex configurations with a minimum of effort. Failure to follow them leads to days of frustration and wasted effort.

Configuring the Server

Changing the server configuration should be done via the following steps:

  1. Start with a "known working" configuration, such as supplied by the default installation.

  2. Make one small change to the configuration files.

  3. Start the server in debugging mode (radiusd -X).

  4. Verify that the results are what you expect

    • The debug output shows any configuration changes you have made.

    • Databases (if used) are connected and operating.

    • Test packets are accepted by the server.

    • The debug output shows that the packets are being processed as you expect.

    • The response packets are contain the attributes you expect to see.

  5. If everything is OK, save a copy of the configuration, go back to step (2), and make another change.

  6. If anything goes wrong,

    • double-check the configuration;

    • read the entire debug output, looking for words like error or warning. These messages usually contain descriptions of what went wrong, and suggestions for how it can be fixed. Also see [an explanation of the debug output](/radiusd-X) and the [debug form](http://networkradius.com/freeradius-debugging/);

    • try replacing your configuration with a saved copy of a "known working" configuration, and start again. This process can clean up errors caused by temporary edits, or edits that you have forgotten about;

    • ask for help on the [freeradius-users](http://freeradius.org/support/) mailing list. Include a description of what you are trying to do, and the entire debugging output, especially output showing the server receiving and processing test packets. You may want to scrub "secret" information from the output before posting it (shared secrets, passwords, etc).

Warning!

These instructions cover installing FreeRADIUS 4.x, which is still in heavy development. Other than exceptional circumstances, you should use version 3.

FreeRADIUS 4 is actively used in multiple high profile client deployments (who have purchased a support contract from Network RADIUS). It, however, otherwise demands a user that seeks danger and enjoys deploying a highly volatile evolving codebase in environments where traditionally stability is sought. If this describes you, then version 4 is for you! (But don’t come complaining if it breaks.)

Hopefully it is clear, we recommend 99.9%+ of users use FreeRADIUS 3.2.x and the pre-built packages available from Network RADIUS.

Other Resources

A number of guides are available from Network RADIUS. In particular, we recommend the Technical Guide(http://networkradius.com/doc/FreeRADIUS%20Technical%20Guide.pdf), which should be read by every new RADIUS administrator. It explains RADIUS concepts, and covers how to perform introductory administation and maintenance. More in-depth guides are available on the same page.