Difference between revisions of "Bering-uClibc 4.x - User Guide - Advanced Topics - Setting Up a RADIUS Server"

From bering-uClibc
Jump to: navigation, search
(Expanded initial skeleton)
(Tidyup)
 
(3 intermediate revisions by the same user not shown)
Line 9: Line 9:
  
  
'''Warning:''' This page is written for the new FreeRADIUS version 2 variant of <code class="filename">radius.lrp</code>, not the old Cistron RADIUS v1.6.8  
+
'''Warning:''' This page is written for the new FreeRADIUS version 2 variant of <code class="filename">radius.lrp</code> introduced at [[Bering-uClibc 4.1]] and not the old Cistron RADIUS v1.6.8 <code class="filename">radius.lrp</code> which was included in [[Bering-uClibc 4.0]].
<code class="filename">radius.lrp</code> which is included in Bering-uClibc 4.0.
+
The new Package, based on FreeRADIUS version 2.1.10, is expected to be included in Bering-uClibc 4.1. [[User:Davidmbrooke|Davidmbrooke]] 14:15, 9 April 2011 (UTC)
+
  
 
==Introduction==
 
==Introduction==
Line 18: Line 16:
 
A RADIUS server provides an Authentication, Authorization and Accounting (AAA) service. Typical use cases include:
 
A RADIUS server provides an Authentication, Authorization and Accounting (AAA) service. Typical use cases include:
 
* Authenticating Wireless Network clients which use the "WPA-Enterprise" (as opposed to "WPA-PSK") authentication model where a Wireless Network Access Point is often configured to talk the RADIUS protocol to a server which knows how to authenticate users/clients.
 
* Authenticating Wireless Network clients which use the "WPA-Enterprise" (as opposed to "WPA-PSK") authentication model where a Wireless Network Access Point is often configured to talk the RADIUS protocol to a server which knows how to authenticate users/clients.
 +
* Authenticating Wired Network clients using 802.1X.
  
 
Read the following in conjunction with the standard FreeRADIUS documentation located [http://freeradius.org/doc/ here].
 
Read the following in conjunction with the standard FreeRADIUS documentation located [http://freeradius.org/doc/ here].
 +
  
 
==Packages==
 
==Packages==
The main Package required is <code class="filename">radius.lrp</code>.
+
The main Package is <code class="filename">radius.lrp</code> which is dependent on the following Packages:
For normal operation the following Packages are also required.
+
 
* <code class="filename">lpthread.lrp</code>
 
* <code class="filename">lpthread.lrp</code>
 
* <code class="filename">libcrpto.lrp</code>
 
* <code class="filename">libcrpto.lrp</code>
 
* <code class="filename">libssl.lrp</code>
 
* <code class="filename">libssl.lrp</code>
 +
* <code class="filename">libtool.lrp</code>
 +
 +
There is a separate, optional Package <code class="filename">radutils.lrp</code> containing some RADIUS utilities, specifically:
 +
* radclient
 +
* radeapclient
 +
* radlast
 +
** This does not currently work because the Busybox "last" command does not accept command-line arguments
 +
* radsniff
 +
** This has a further dependency, on <code class="filename">libpcap.lrp</code>
 +
* radtest
 +
* radwho
 +
* radzap
  
 
When connecting to different types of back-end server further Packages are required:
 
When connecting to different types of back-end server further Packages are required:
 
; LDAP : <code class="filename">libldap.lrp</code>
 
; LDAP : <code class="filename">libldap.lrp</code>
 +
; SQL using MySQL : <code class="filename">libmysql.lrp</code>, <code class="filename">libz.lrp</code>
  
In addition, for installation and configuration of some aspects of FreeRADIUS the following additional Package is typically required. This may be removed once installation and configuration is complete:
+
In addition, for installation and configuration of some aspects of FreeRADIUS the following additional Package is typically required:
 
* <code class="filename">openssl.lrp</code>
 
* <code class="filename">openssl.lrp</code>
 +
  
 
==Installation==
 
==Installation==
Line 38: Line 51:
  
 
===Generate Digital Certificate Files===
 
===Generate Digital Certificate Files===
The "bootstrap" script needs to be run to generate files required to support Digital Certificate processing. This is the (only) step that needs the <code class="filename">openssl.lrp</code> Package to be installed:
+
The "bootstrap" script needs to be run to generate files required to support Digital Certificate processing.
 +
This is the (only) step that needs the <code class="filename">openssl.lrp</code> Package to be installed.
 +
 
 +
'''Tip:''' Do not add <code class="filename">openssl.lrp</code> to <code class="filename">leaf.cfg</code> but instead install it manually with a command like:
 +
apkg -i /mnt/openssl.lrp
 +
so that <code class="filename">openssl.lrp</code> will be removed at the next reboot.
 +
 
 +
Run the "bootstrap" script as follows:
 
  cd /etc/raddb/certs/
 
  cd /etc/raddb/certs/
 
  sh bootstrap
 
  sh bootstrap
 
This will create quite a number of "example" Digital Certificate files in directory <code class="filename">/etc/raddb/certs/</code>.
 
This will create quite a number of "example" Digital Certificate files in directory <code class="filename">/etc/raddb/certs/</code>.
 
FreeRADIUS will try to do this automatically the first time it runs but on [[Bering-uClibc 4.x]] this will fail, so the script must be run manually - or the relevant files installed by hand.
 
FreeRADIUS will try to do this automatically the first time it runs but on [[Bering-uClibc 4.x]] this will fail, so the script must be run manually - or the relevant files installed by hand.
 +
 +
In practice, the only files which seem to be required are:
 +
* <code class="filename">/etc/raddb/certs/dh</code> which can be created with the command:<pre>openssl dhparam -out dh 1024</pre>
 +
* <code class="filename">/etc/raddb/certs/random</code> which can be created with the command:<pre>dd if=/dev/urandom of=./random count=10</pre>
 +
* The files referenced by the "<tt>private_key_file</tt>", "<tt>certificate_file</tt>" and "<tt>CA_file</tt>" configuration fields in <code class="filename">eap.conf</code>. You probably want to create these using your own Certification Authority.
  
 
===Run RADIUS Daemon in Debug Mode===
 
===Run RADIUS Daemon in Debug Mode===
Line 48: Line 73:
 
  cd /root/
 
  cd /root/
 
  radiusd -X
 
  radiusd -X
 +
  
 
==Configuration==
 
==Configuration==
TODO
+
===Overview===
 +
FreeRADIUS has many configuration files stored in directory <code class="filename">/etc/raddb/</code> and its sub-directories.
 +
Some, but not all, of these are listed in the "<tt>radius</tt>" section of the LEAF Packages configuration menu.
 +
 
 +
All of the files under <code class="filename">/etc/raddb/</code> are backed up when the LEAF configuration is saved.
 +
 
 +
Filename paths below are relative to the <code class="filename">/etc/raddb/</code> directory.
 +
 
 +
===Clients===
 +
From a RADIUS perspective, a "client" is a device which connects to the RADIUS server using the RADIUS protocol.
 +
It is typically either a Network Access Server (NAS) or, for a Wireless Network, an Access Point (AP).
 +
 
 +
FreeRADIUS requires that clients are defined in configuration file <code class="filename">clients.conf</code>.
 +
Refer to the excellent comments in the sample file.
 +
 
 +
As an example, the 3com OfficeConnect Wireless 108Mbps 11g PoE Access Point has the following fields in its web-based administration interface:
 +
[[Image:3com_radius_client_example.png|center|frame|alt=Radius Server settings example|Radius Server settings for a 3com Access Point]]
 +
 
 +
Assuming this Access Point is at IP address 192.168.1.101 the corresponding FreeRADIUS client entry would look like:
 +
client SC55835A {
 +
        ipaddr = 192.168.1.101
 +
        secret = ''secret-password''
 +
        require_message_authenticator = yes
 +
}
 +
where "''secret-password''" matches the entry in the "Shared Key" field.
 +
 
 +
===Users===
 +
The most important, and the most variable, FreeRADIUS configuration element is for user accounts and passwords.
 +
The various methods listed below can be used in combination, if required.
 +
Multiple entries are present in the "<tt>authorize</tt>" section in file <code class="filename">sites-enabled/default</code> (actually a symbolic link to <code class="filename">sites-available/default</code>) and these are tried in sequence until a match is found.
 +
 
 +
====Text File "users"====
 +
The very simplest approach is to add user accounts to file <code class="filename">users</code>. Add one line per user near the top of the file (before any "<tt>DEFAULT</tt>" entries). For example:
 +
''username''    Cleartext-Password := "''password''"
 +
This is particularly useful for testing but is obviously difficult to maintain for large numbers of user accounts.
 +
 
 +
====SQL Database====
 +
Refer to the excellent [http://wiki.freeradius.org/SQL_HOWTO FreeRADIUS SQL HOWTO] and also the documentation for the [http://wiki.freeradius.org/Rlm_sql <tt>rlm_sql</tt>] FreeRADIUS module.
 +
 
 +
Note that FreeRADIUS can in principle connect to a wide variety of SQL database back-ends but the [[Bering-uClibc 4.x]] <code class="filename">radius.lrp</code> Package only supports MySQL.
 +
 
 +
At the step in the HOWTO where the database table structure is created use file <code class="filename">/etc/raddb/sql/mysql/schema.sql</code>.
 +
 
 +
====LDAP Directory====
 +
There does not seem to be an equivalent to the SQL HOWTO for LDAP but there is some good documentation for the [http://wiki.freeradius.org/Rlm_ldap <tt>rlm_ldap</tt>] FreeRADIUS module.
 +
 
 +
See also this [http://vuksan.com/linux/dot1x/802-1x-LDAP.html FreeRADIUS + 802.1x/WPA + OpenLDAP HOWTO] but note that it is rather old.
 +
 
 +
The main FreeRADIUS configuration file for LDAP is located at <code class="filename">/etc/raddb/modules/ldap</code>.
 +
 
 +
 
 +
==Logging==
 +
Except when started in debug mode (e.g. as "<tt>radiusd -X</tt>") the RADIUS daemon writes log output to file <code class="filename">/var/log/radius/radius.log</code>.
 +
 
 +
This log file is "rotated" on a daily basis by a RADIUS-specific cron script - <code class="filename">/etc/cron.daily/radiusd</code>.
 +
 
 +
Individual client authentication transactions are not logged by default. To enable this behaviour edit <code class="filename">radiusd.conf</code> and specify "<tt>auth = yes</tt>" in the "<tt>log</tt>" configuration section.
 +
 
 +
Further files are created in the <code class="filename">/var/log/radius/</code> directory:
 +
* radutmp
 +
* radwtmp
 +
The <code class="filename">radutmp</code> file contains a list of users ''currently'' logged in so it never grows to be large.
 +
The <code class="filename">radwtmp</code> file maintains a history of logins and does grow so this is "rotated" on a weekly basis by cron script <code class="filename">/etc/cron.weekly/radiusd</code>.
 +
 
 +
Still further files are created under the <code class="filename">/var/log/radius/radacct/</code> directory, in per-client sub-directories.
 +
These "<tt>detail</tt>" files are automatically created in date-stamped files (e.g. <code class="filename">detail-20110411</code>, for 11 Apr 2011).
 +
The configuration of the "<tt>detail</tt>" file logging behaviour is defined in <code class="filename">/etc/raddb/modules/detail</code>.
 +
 
 +
Files more than 7 days old are deleted by cron script <code class="filename">/etc/cron.daily/radiusd</code>.
 +
 
  
 
==Further Reading==
 
==Further Reading==
 
* Standard FreeRADIUS [http://freeradius.org/doc/ Documentation] and [http://wiki.freeradius.org/Main_Page Wiki]
 
* Standard FreeRADIUS [http://freeradius.org/doc/ Documentation] and [http://wiki.freeradius.org/Main_Page Wiki]
* [http://vuksan.com/linux/dot1x/802-1x-LDAP.html FreeRADIUS + 802.1x/WPA + OpenLDAP HOWTO]
+
* ''RADIUS'', by Jonathan Hassell. Copyright 2002 O'Reilly Media, Inc. ISBN 978-0-596-00322-7.  
  
  

Latest revision as of 08:22, 16 October 2011

Advanced Topics - Setting Up a RADIUS Server
Prev Bering-uClibc 4.x - User Guide Next


Warning: This page is written for the new FreeRADIUS version 2 variant of radius.lrp introduced at Bering-uClibc 4.1 and not the old Cistron RADIUS v1.6.8 radius.lrp which was included in Bering-uClibc 4.0.

Introduction

This page provides some guidance on setting up a Remote Authentication Dial In User Service (RADIUS) server on Bering-uClibc 4.x using the FreeRADIUS software.

A RADIUS server provides an Authentication, Authorization and Accounting (AAA) service. Typical use cases include:

  • Authenticating Wireless Network clients which use the "WPA-Enterprise" (as opposed to "WPA-PSK") authentication model where a Wireless Network Access Point is often configured to talk the RADIUS protocol to a server which knows how to authenticate users/clients.
  • Authenticating Wired Network clients using 802.1X.

Read the following in conjunction with the standard FreeRADIUS documentation located here.


Packages

The main Package is radius.lrp which is dependent on the following Packages:

  • lpthread.lrp
  • libcrpto.lrp
  • libssl.lrp
  • libtool.lrp

There is a separate, optional Package radutils.lrp containing some RADIUS utilities, specifically:

  • radclient
  • radeapclient
  • radlast
    • This does not currently work because the Busybox "last" command does not accept command-line arguments
  • radsniff
    • This has a further dependency, on libpcap.lrp
  • radtest
  • radwho
  • radzap

When connecting to different types of back-end server further Packages are required:

LDAP 
libldap.lrp
SQL using MySQL 
libmysql.lrp, libz.lrp

In addition, for installation and configuration of some aspects of FreeRADIUS the following additional Package is typically required:

  • openssl.lrp


Installation

Some manual installation steps are required before running FreeRADIUS for the first time.

Generate Digital Certificate Files

The "bootstrap" script needs to be run to generate files required to support Digital Certificate processing. This is the (only) step that needs the openssl.lrp Package to be installed.

Tip: Do not add openssl.lrp to leaf.cfg but instead install it manually with a command like:

apkg -i /mnt/openssl.lrp

so that openssl.lrp will be removed at the next reboot.

Run the "bootstrap" script as follows:

cd /etc/raddb/certs/
sh bootstrap

This will create quite a number of "example" Digital Certificate files in directory /etc/raddb/certs/. FreeRADIUS will try to do this automatically the first time it runs but on Bering-uClibc 4.x this will fail, so the script must be run manually - or the relevant files installed by hand.

In practice, the only files which seem to be required are:

  • /etc/raddb/certs/dh which can be created with the command:
    openssl dhparam -out dh 1024
  • /etc/raddb/certs/random which can be created with the command:
    dd if=/dev/urandom of=./random count=10
  • The files referenced by the "private_key_file", "certificate_file" and "CA_file" configuration fields in eap.conf. You probably want to create these using your own Certification Authority.

Run RADIUS Daemon in Debug Mode

To check the configuration settings it is highly recommended to run radiusd in debug mode, from the command line:

cd /root/
radiusd -X


Configuration

Overview

FreeRADIUS has many configuration files stored in directory /etc/raddb/ and its sub-directories. Some, but not all, of these are listed in the "radius" section of the LEAF Packages configuration menu.

All of the files under /etc/raddb/ are backed up when the LEAF configuration is saved.

Filename paths below are relative to the /etc/raddb/ directory.

Clients

From a RADIUS perspective, a "client" is a device which connects to the RADIUS server using the RADIUS protocol. It is typically either a Network Access Server (NAS) or, for a Wireless Network, an Access Point (AP).

FreeRADIUS requires that clients are defined in configuration file clients.conf. Refer to the excellent comments in the sample file.

As an example, the 3com OfficeConnect Wireless 108Mbps 11g PoE Access Point has the following fields in its web-based administration interface:

Radius Server settings example
Radius Server settings for a 3com Access Point

Assuming this Access Point is at IP address 192.168.1.101 the corresponding FreeRADIUS client entry would look like:

client SC55835A {
        ipaddr = 192.168.1.101
        secret = secret-password
        require_message_authenticator = yes
}

where "secret-password" matches the entry in the "Shared Key" field.

Users

The most important, and the most variable, FreeRADIUS configuration element is for user accounts and passwords. The various methods listed below can be used in combination, if required. Multiple entries are present in the "authorize" section in file sites-enabled/default (actually a symbolic link to sites-available/default) and these are tried in sequence until a match is found.

Text File "users"

The very simplest approach is to add user accounts to file users. Add one line per user near the top of the file (before any "DEFAULT" entries). For example:

username    Cleartext-Password := "password"

This is particularly useful for testing but is obviously difficult to maintain for large numbers of user accounts.

SQL Database

Refer to the excellent FreeRADIUS SQL HOWTO and also the documentation for the rlm_sql FreeRADIUS module.

Note that FreeRADIUS can in principle connect to a wide variety of SQL database back-ends but the Bering-uClibc 4.x radius.lrp Package only supports MySQL.

At the step in the HOWTO where the database table structure is created use file /etc/raddb/sql/mysql/schema.sql.

LDAP Directory

There does not seem to be an equivalent to the SQL HOWTO for LDAP but there is some good documentation for the rlm_ldap FreeRADIUS module.

See also this FreeRADIUS + 802.1x/WPA + OpenLDAP HOWTO but note that it is rather old.

The main FreeRADIUS configuration file for LDAP is located at /etc/raddb/modules/ldap.


Logging

Except when started in debug mode (e.g. as "radiusd -X") the RADIUS daemon writes log output to file /var/log/radius/radius.log.

This log file is "rotated" on a daily basis by a RADIUS-specific cron script - /etc/cron.daily/radiusd.

Individual client authentication transactions are not logged by default. To enable this behaviour edit radiusd.conf and specify "auth = yes" in the "log" configuration section.

Further files are created in the /var/log/radius/ directory:

  • radutmp
  • radwtmp

The radutmp file contains a list of users currently logged in so it never grows to be large. The radwtmp file maintains a history of logins and does grow so this is "rotated" on a weekly basis by cron script /etc/cron.weekly/radiusd.

Still further files are created under the /var/log/radius/radacct/ directory, in per-client sub-directories. These "detail" files are automatically created in date-stamped files (e.g. detail-20110411, for 11 Apr 2011). The configuration of the "detail" file logging behaviour is defined in /etc/raddb/modules/detail.

Files more than 7 days old are deleted by cron script /etc/cron.daily/radiusd.


Further Reading



Prev Up Next