|
TITLE: |
IC-RADIUS Installation and Setup Procedures |
|
CURRENT
IC-RADIUS VERSION: |
0.17b |
|
AUTHORS: |
James Banks jbanks@sonet.net (original document) Brad Rathbun brad@computechnv.com |
|
DOCUMENT
MAINTAINER: |
Brad Rathbun |
|
COPYRIGHT: |
|
|
DOCUMENT REVISION DATE: |
May 1, 2001 |
TABLE OF CONTENTS
GNU FREE DOCUMENTATION LICENSE
Copyright (c) 2001 JAMES BANKS, BRAD RATHBUNPermission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
Read this entire document and the FAQ completely before posting
questions to the mailing list. Most questions posted to the list each day have
been asked repeatedly and are in the archives or in the FAQ. You stand a much
better chance of getting an answer quickly if you give everyone on the list the
courtesy of at least trying to find the answer yourself before posting.
Remember, ICRadius is user-supported software. That means that nobody is
obligated to help you, they are doing it as a favor. You can join the IC-RADIUS
mail list, icRADIUS-list@innercite.com, by sending a message to
'icRADIUS-list-request@innercite.com' with 'subscribe icRADIUS-list' in the
body.
This document is constantly changing so please re-read this
document after each new release to find out about any new changes and how they
affect the rest of the server.
This document did not create itself. It
took a lot of time from not just the people who are credited as the authors at
the top, but from many other people who have contributed greatly to the mailing
list and directly to this document. Your help is needed, too! If you see
something in this document that is incorrect, could be explained better, works
differently on your platform, etc., you can help the ICRadius community by sending
your revisions to the document maintainer. In particular, this document is
currently heavily weighted toward an installation on RedHat and more
documentation on other distributions would be a very nice addition. I prefer to
receive your updates in Word format if at all possible, but I’ll take it any
way you want to send it. If you are modifying sections of the existing
document, please include a short note telling me what section you changed so
that I can more easily locate it. Thanks!
In the past, many people have written scripts or small programs to
manipulate and extract various types of information from the standard RADIUS
detail files. Users total online time,
bandwidth usage, etc. that are available from analyzing the RADIUS detail file
can prove valuable in almost every aspect of business. However, most of these scripts slow down
exponentially as the size of the detail file increases.
This need for fast and efficient data management was the motivator
for InnerCite to develop IC-RADIUS. The
whole RADIUS system is basically in tabular format, and what better way to view
tabular data than in a database.
IC-RADIUS uses a MySQL database to store all of its essential information
such as the users file and the dictionary files, and also sends the accounting
information to the database. This, in
turn, allows for extremely fast and efficient data manipulation and extraction
with the ease and flexibility offered by MySQL. IC-RADIUS is completely free
(GPL) and is available for download from ftp://ftp.innercite.com/pub/icradius/.
In the following sections you will find information on setting up
IC-RADIUS as well as the general procedures for installing MySQL and the Perl
DBI and MySQL DBD modules, all of which are required for IC-RADIUS to operate
properly.
This is not intended to be a complete reference on MySQL, Perl, or
RADIUS, but hopefully enough information will be provided to get you through
the installation and have IC-RADIUS up and running as quickly and painlessly as
possible. Please note that unless you are pretty familiar with Linux, you
should be prepared to do a lot of reading! Installing this or any other RADIUS
package is not exactly a job for a beginner and certainly not something you
should undertake if you need it yesterday. However, every effort has been made
to insure that as much information as possible has been included in this
document so that you will have a smooth installation on your first try. This
document assumes only that you can read and follow instructions and have at
least a basic understanding of how Linux works. The more you know, obviously,
the easier the whole process will be.
In order to use IC-RADIUS, you must first have MySQL installed.
This is covered in the MySQL INSTALLATION section below. You will also need the Perl DBI and MySQL
DBD modules. You must also have a
version of Perl that is compatible with these modules. The latest DBI and DBD
modules, as well as MySQL can be found at http://www.mysql.net/.
Of course you can always go to
http://www.perl.com to get the
modules, but I like the one-stop convenience of using the MySQL homepage. Both the DBI and DBD installations will be
covered in their respective sections below.
RADIUS is an acronym which stands for “Remote Authentication Dial
In User Service”. This is defined as a protocol for carrying authentication,
authorization, and configuration information between a Network Access Server
(NAS) desiring to authenticate its links and a shared Authentication Server
(IC-RADIUS). This standard is described in great detail in RFC 2138 and 2139
available at http://www.freeRADIUS.org. It is strongly recommended that you read
these along with all of the documentation provided in each directory. About 90% of the questions that come across
the mail lists can be answered by simply taking the time to read the
documentation.
How does RADIUS work? Basically the process can be broken down
into 4 steps. First, the user dials into the NAS. Next, the NAS sends a request to the authentication server
(IC-RADIUS) via a standard set of attribute/value (a/v) pairs. Then, RADIUS checks to see if that user
exists and if so, can they log on.
Finally, the RADIUS server sends either an “accept” or a “reject” back
to the NAS, which determines whether or not the user is allowed access. That
should give a very basic understanding of how the authentication system works.
That’s what RADIUS does. Let’s spend a moment and talk about what
RADIUS does not do. Remember that the job of RADIUS is to do authentication and
accounting for a NAS. It is not the job of RADIUS to your billing. It is not a
word processor. It is not a spreadsheet. Many requests come across the mailing
list for this feature or that feature. Unfortunately, most of these misguided
requests don’t have the basic understanding of what RADIUS is for and are thus ignored
and occasionally ridiculed. In other words, if you want to request a feature,
please make sure that feature is reasonable in the context of what RADIUS is
supposed to do!
Now lets move on and see what IC-RADIUS needs to operate properly.
Many of the steps below may be skipped, as they are included only in the
interest of being thorough and over-explaining rather than under-explaining the
installation process. In all cases, I assume installation will occur from
source code distributions instead of RPMs. I chose this method because it
applies to the widest variety of distributions, offers the most flexibility and
security, and it seems to work better in most cases (at least for me). If you
prefer to use RPMs, feel free – they will probably work just fine for you. Just
don’t be surprised if you have trouble with the rest of the instructions below
as they all tie together.
Most, if not all, of the scripts that come with ICRadius are
written in Perl. This, of course, means that you must have Perl installed in
order to use them. Most Linux distributions already have Perl installed, so you
probably can skip this step if you want to. This section describes how to
install or upgrade to Perl 5.6.0, the latest stable release as of this writing.
There is nothing about ICRadius or the support scripts that come with it that
would require you to perform this upgrade.
1.
Download the Perl distribution to /usr/local/src. You can get the
latest Perl distribution from http://www.perl.com.
2.
Expand the archive: tar –zxvf perl5.6.0.tar.gz
3.
Optional step. Delete the archive to save space: rm –f
perl5.6.0.tar.gz
4.
Move to source directory: cd /usr/local/src/perl5.6.0
5.
Read the installation instructions: pico –w INSTALL
6.
rm –f config.sh Policy.sh
7.
sh Configure –de
8.
make
9.
make test
10.
make install
11.
If it installed correctly, you can confirm the correct version: perl
–v
This step is completely optional. The only good reason to do this
is if you intend to use MySQL database replication now or at some point in the
future. It doesn’t hurt anything to install it even if you don’t know what
replication is, so if you are unsure, go ahead and do it. There is absolutely
nothing about ICRadius or it’s support scripts that require this step to be
performed and ICRadius won’t care one way or the other if Berkley Sockets are
installed or not. My personal recommendation is that you install them now to
save yourself the hassle later when you discover that MySQL replication is a
good thing to have (because replication really is a good thing to have, trust
me).
1.
Download the Berkley Sockets distribution to /usr/local/src. You
can get the latest distribution from http://www.sleepycat.com/.
2.
Expand the archive: tar –zxvf Berkleydb-3.2.9a.tar.gz
3.
Optional step. Delete the archive to save space: rm –f
Berkleydb-3.2.9a.tar.gz
4.
Move to source directory: cd /usr/local/src/db-3.2.9a
5.
./configure
6.
make
7.
make install
This step is NOT optional unless you know what you are doing, in
which case you probably wouldn’t be reading this document. You must have MySQL
installed and running on your system in order to use ICRadius. It could be
running on a separate host than the one you are putting ICRadius on, but that
is a more advanced installation and is not how most first time installations
are done. There is nothing in ICRadius or any of the support scripts that
requires you to have MySQL running on the same host with ICRadius. Many
advanced installations (mine included) have a separate host for the database
for increased security and performance. Either way will work fine and you can
always change it later if you need to.
You will need at least version 3.22, but if you install the newer
versions, replication will be supported. As of this writing, version 3.23.33
was the latest release. Remember, it’s just as easy to install the current
version as an obsolete one. The upgrade you do now is one you don’t have to do
later when you have the system in production.
There are a lot of steps here and most of them are pretty
critical, so please follow them carefully. Most of the problems I had when
installing my own system came from problems with the MySQL installation. These
steps may be overkill, but they work.
1.
Download the latest MySQL distribution to /usr/local/src. You can
get the latest distribution from http://www.mysql.com.
2.
Expand the archive: tar –zxvf mysql-3.23.33
3.
Optional step. Delete the archive to save space: rm –f
mysql-3.23.33.tar.gz
4.
Move to source directory: cd /usr/local/src/mysql-3.23.33
5.
Add the group mysql: groupadd mysql
6.
Add the user mysql: useradd –g mysql mysql
7.
./configure –prefix=/usr/local/mysql
8.
make
9.
NOTE: On my installation, there was an error on the next step,
which was caused by make writing an error into the Makefile. You can fix this
bug if you edit the Makefile: pico –w Makefile and do a search: ctrl-w
for the offending line: install: all. This line has a comment that says
something to the effect of #Modified by MySQL. Remove this comment and keep
deleting until the next line is on the same line with the “install: all” so
that it reads something like this: “install: all install_include
uninstall_include install_documents uninstall_documents”. In other words, it
should all be on one line with a space separating each of the commands.
10.
make install
11.
scripts/mysql-install-db
Note: This will install the databases and at the end it will tell you to
change the root password. The way suggested never works for me and I have a
different method listed below. Your mileage may vary.
12.
Make sure libraries are visible to other programs:
A.
Pico –w /etc/ld.so.conf
B.
Add a line to the file pointing to the libs: /usr/local/mysql/lib/mysql
C.
Reload with update: ldconfig
D.
Copy the server init file: cp support-files/mysql.server
/etc/rc.d/init.d
13.
Make startup file executable: chmod 755
/etc/rc.d/init.d/mysql.server
14.
chown –R root /usr/local/bin/mysql
15.
chgrp –R mysql /usr/local/mysql
16.
Put mysql command in path: cp /usr/bin/mysql /usr/bin
17.
Copy config file: cp support-files/my-medium.cnf /etc/my.cnf
18.
Edit config file: pico –w /etc/my.cnf
A.
Under [client] section:
1.
Leave password blank for now
2.
user = root
19.
Secure the MySQL config file: chmod 600 /etc/my.cnf
20.
Start MySQL: /etc/rc.d/init.d/mysql.server start
21.
See if it works: mysql
22.
Change root password:
A.
use mysql;
B.
update user set password = PASSWORD(‘your-new-password’) where
user=’root’;
C.
flush privileges;
D.
exit
23.
Optional step for replication. If you think you might want this server
to be the master database for future replication, you can set it up now. To do
so:
A.
Pico –w /etc/my.cnf
B.
Under [mysqld] section:
1.
log-bin
2.
server-id = 1 (must be unique from all other MySQL servers)
24.
You can use root as the main user, but I highly recommend adding
another username and password, such as radius.
A.
This can be done by typing: INSERT INTO users' 'VALUES
('host','user','password',‘y','y','y','y','y','y','y','y','y','y','y','y','y','y');
B.
“Host” should be the machine that is running IC-RADIUS. Most likely
this will be the same one that MySQL is running on. In that case, you can put "localhost" here.
C.
“User” should be a username, such as radius.
D.
“Password” should be your password.
E.
That should get you going as far as MySQL is concerned. If you have any problems, check out the
MySQL documentation found on their homepage at http://www.mysql.com.
25.
Make sure that you update /etc/raddb/radius.conf to reflect this
same host, username, and password.
This module is not required by ICRadius or any of it’s scripts, so
you may skip this section if you want to. However, I find that life is
generally easier when using Perl with MySQL if this module is installed. And
it’s an easy one to install.
1.
Download the Data-Dumper distribution to /usr/local/src. You can
get the latest distribution from http://search.cpan.org.
2.
Expand the archive: tar –zxvf Data-Dumper-2.101
3.
Optional step. Delete the archive to save space: rm –f Data-Dumper-2.101.tar.gz
4.
Move to source directory: cd /usr/local/src/Data-Dumper-2.101
5.
perl Makefile.PL
6.
make
7.
Note: Do not run make test. The test suite is broken.
8.
make install
This module is not required by ICRadius or any of the scripts, so
you may skip this section if you want to. However, I find that life is
generally easier when using Perl with MySQL if this module is installed. And,
except for fixing a bug in the install script, it’s an easy one to install.
1.
Download the Data-ShowTable distribution to /usr/local/src. You
can get the latest distribution from http://search.cpan.org.
2.
Expand the archive: tar –zxvf Data-ShowTable-3.3.tar.gz
3.
Optional step. Delete the archive to save space: rm –f Data-ShowTable-3.3.tar.gz
4.
Move to source directory: cd /usr/local/src/Data-ShowTable-3.3
5.
perl Makefile.PL
6.
make
7.
Note: There is a bug in the Makefile after this runs. If you want
to see it, continue on. If you want to fix it before continuing, edit the Makefile
and go to line 724, which contains a long string of stuff like I<… , I<…,
and so on. Notice that the first two I<… are not terminated with matching
>. Insert the closing > marks and it will install perfectly. Sometimes,
it is helpful to run the make install just to see the error so you know what
you are looking for.
8.
make test
9.
make install
Lets start with a brief overview of what these modules are, and
why we need them. The DBI is a database interface module for Perl. It defines a
set of methods, variables and conventions that provide a consistent database
interface independent of the actual database being used. The MySQL DBD is the actual driver that is
used to access a MySQL database and run queries on it from Perl. It is important
that you install the DBI first because the DBD will not work, or even install
without it.
1.
Download the DBI distribution to /usr/local/src. You can get the
latest distribution from http://search.cpan.org.
2.
Expand the archive: tar –zxvf DBI-1.14.tar.gz
3.
Optional step. Delete the archive to save space: rm –f
DBI-1.14.tar.gz
4.
Move to source directory: cd /usr/local/src/DBI-1.14
5.
perl Makefile.PL
6.
make test
7.
make install
If you are going to have a problem, you will probably have it
here. This module is always difficult (at least for me). One thing to check
before you start this procedure is that you have a valid MySQL username and
password setup and that this username and password is defined in the
/etc/my.cnf file. Double check this before you start this installation and
you’ll save yourself some headaches.
1.
Download the DBD distribution to /usr/local/src. You can get the
latest distribution from http://search.cpan.org.
By the way, just to confuse things, it’s not named DBD – it’s named
Msql-Mysql-Modules!
2.
Expand the archive: tar –zxvf Msql-Mysql-1.2215.tar.gz
3.
Optional step. Delete the archive to save space: rm –f
Msql-Mysql-1.2215.tar.gz
4.
Move to source directory: cd /usr/local/src/Msql-Mysql-1.2215
5.
perl Makefile.PL
Note: the defaults are right for most of the questions. Be sure to give
the username and password you defined for MySQL when asked or the tests will
all fail!
8.
make test Download the DBI distribution to /usr/local/src. You can get the
latest distribution from http://search.cpan.org.
9.
Expand the archive: tar –zxvf DBI-1.14.tar.gz
10.
Optional step. Delete the archive to save space: rm –f
DBI-1.14.tar.gz
11.
Move to source directory: cd /usr/local/src/DBI-1.14
12.
perl Makefile.PL
13.
make test
14.
make install Note: if you don’t see “All tests successful”, backtrack and
figure out what you did wrong, because nothing is going to work right. Trust
me.
15.
make install
This is usually an optional step, but one you might wish to
perform. There are certain portions of ICRadius that use SNMP (to verify if a
user is on with more than one connection, for example). However, SNMP is also
probably already on your system. If you think it’s already installed, you can
skip this step. Otherwise, just do it and you’ll have the latest version. It’s
usually a pretty painless installation.
1.
Download the SNMP distribution to /usr/local/src. You can get the
latest distribution from http://search.cpan.org.
2.
Expand the archive: tar –zxvf ucd-snmp-4.1.tar.gz
3.
Optional step. Delete the archive to save space: rm –f
ucd-snmp.tar.gz
4.
Move to source directory: cd /usr/local/src/ucd-snmp-4.1
5.
./configure
6.
make
7.
make test
8.
make install
Finally! Once the above
items have been properly installed, you can install IC-RADIUS. It takes a lot of
other things to make ICRadius work, but it’s worth it when you finally get
there.
1.
Download the ICRadius distribution to /usr/local/src. You can get
the latest distribution from ftp://ftp.innercite.com/pub/icradius/.
2.
Expand the archive: tar –zxvf icradius-0.17b.tar.gz
3.
Optional step. Delete the archive to save space: rm –f
icradius-0.17b.tar.gz
4.
Move to source directory: cd /usr/local/src/icverify-0.17b
5.
cp Makefile.lnx Makefile
Note: if you use something other than Linux, be sure to copy the
Makefile that is appropriate for your distribution.
6.
The Redhat startup files are broken. Fix them by editing:
A.
pico –w redhat/rc.radiusd-redhat
B.
Near the top, you will see a line that says,
“RADIUSD=/usr/bin/radiusd”. Change it so say, “RADIUSD=/usr/sbin/radiusd”
instead.
7.
Copy the startup files: cp
redhat/rc.radiusd-redhat /etc/rc.d/init.d/radiusd
8.
make
9.
make test
10.
make install
11.
Copy the radius.conf file:
A.
Make sure directory exists: mkdir /etc/raddb
B.
Copy file: cp raddb/radius.conf /etc/raddb
C.
Secure the file: chmod 600 /etc/raddb/radius.conf
To be able to use IC-RADIUS you must now create a database in
MySQL, which is named RADIUS. Most of the installation can be done from a
script, but you must create the initial database from within MySQL.
1.
Start MySQL: mysql
2.
Create the database: CREATE DATABASE RADIUS;
3.
Exit MySQL: exit;
Next, we must create all of the tables that IC-RADIUS will need.
Fortunately, these have already been defined in the file “scripts/RADIUS.db”.
This makes it very easy to import the table structures into MySQL from the
command line.
1.
Enter this command from the shell prompt: mysql RADIUS < RADIUS.db
A.
Note: MySQL is quiet, so if it worked, you’ll get no messages.
2.
Test to see if it worked:
A.
Start MySQL: mysql
B.
Select the RADIUS database: use radius;
C.
Look at the tables: show tables;
D.
Exit MySQL: exit;
Now you will need to load the dictionary file found in the raddb
subdirectory into MySQL as well as the dictionary that matches your NAS. The
dictionaries are located in the raddb directory. These dictionaries are stored
with a format of “dictionary.NAS”, where NAS is the type of NAS equipment you
are supporting. For example, if you use Livingston PM3’s, you would select
dictionary.livingston. If you have a variety of equipment, load each dictionary
that ICRadius will be providing RADIUS for. I recommend you make a quick list
of the dictionaries you need to load before proceeding to the next step.
1.
Move to the scripts directory: cd scripts
2.
Edit the script: pico –w dictimport.pl
A.
Change $dbusername to match your MySQL username
B.
Change $dbpassword to match your MySQL password
3.
Run the script: ./dictimport.pl ../raddb/dictionary
4.
At a minimum, be sure to run step 3 exactly as shown to get the
generic dictionary loaded and then repeat step 3 as needed for each NAS
specific dictionary you need.
Note: A very common problem seen on the mailing list concerns
failure to load the proper dictionaries for your NAS equipment. Make sure you
are thorough with this step and you will save yourself a lot of headaches and generate
a lot less newbie noise on the list!
From this point forward, we will be editing several different
MySQL tables. For simplicity’s sake, this document explains how to edit MySQL
tables with what you have already installed in previous steps. However, if you
really want to make this and future steps easy on yourself, I highly recommend
you take a look at Webmin. Webmin is a product that lets you manage your server
(including MySQL) from a web browser. Webmin can be downloaded from http://www.webmin.com. In no way does
ICRadius require Webmin and you can certainly get along fine without it if you
choose to do so. However, for beginners it is really a very nice tool and the
installation is quick and easy.
You will need to manually add entries for your NAS hardware into
the nas table. This table replaces the need for both the naslist and the
clients file standard Cistron used. This is done by inserting records directly
into the MySQL table.
1.
See what columns are required for this table:
A.
Start MySQL: mysql
B.
Show the table structure: desc nas
2.
You should see (at least as of version 0.17b) the following
columns: id, nasname, shortname, ipaddr, type, ports, secret, and community.
3.
Add your nas: insert into nas values(‘’, ‘nas1.domain.com’,
‘nas1’, ‘192.168.1.1’, ‘livingston’, ‘48’, ‘mysecret’, ‘public’, ‘on’);
4.
Repeat step 3 as needed to add all your NAS to the table,
substituting your own settings for the values in the example.
5.
Important Note: Make sure the secret in your NAS matches
the entry for that NAS in the nas table. This is one of the most common
problems as to why you can’t authenticate a user when setting ICRadius up and
one of the most frequently asked newbie questions on the mailing list.
6.
Important Note #2: Make sure that you set up the ICRadius
server’s IP address as the authentication and/or accounting server on your NAS.
Also make sure that you have turned SNMP on, made the ICRadius server an snmp
reader, and that the SNMP community string is the same as what you defined in
the NAS table. Needless to say, anything SNMP related (like controlling
multiple logins) won’t work if you don’t do this.
7.
When you have finished setting all of your NAS entries up, restart
ICRadius. Changes don’t take effect until you do so as this table is read only
upon initialization.
Here’s a sample of what your nas table might look like (especially
if you viewed it from Webmin like I did to create this sample). Notice that I
have added my web server as a nas in the third entry. This is so that I can run
utilities such as the checkrad script from the web server. It’s optional, but
highly recommended.
|
id |
Nasname |
shortname |
Ipaddr |
type |
ports |
secret |
community |
snmp |
|
1 |
nas1.domain.com |
nas1 |
192.168.1.1 |
livingston |
48 |
mysecret |
public |
on |
|
2 |
nas2.domain.com |
nas2 |
192.168.1.2 |
livingston |
48 |
mysecret |
public |
on |
|
3 |
web |
192.168.1.3 |
Linux |
0 |
mysecret |
|
off |
Notice also that type is
set to lowercase on the NAS equipment. It seems to make a difference, at least
in my installation, so this is something you might want to watch out for. If it
doesn’t make a difference, no harm done. If it does make a difference, then
you’ll have done it right.
If you have installed
ICRadius correctly, it should start automatically when your server reboots.
However, since we don’t want to reboot the computer just to start ICRadius, we
can just run it from the init script we installed earlier. Remember, a prerequisite
for ICRadius to work is that MySQL must be running first.
1.
Start MySQL: /etc/rc.d/init.d/mysql.server
start
2.
Verify that it’s
running: ps –A | grep mysql
3.
Start ICRadius: /etc/rc.d/init.d/icradius
start
4.
See if it’s working
properly: cat /var/log/radius.log
- you should see something like the following:
Starting - reading configuration
files ...
SQL: Attempting to connect to radius@localhost:radius
Ready to process requests.
You can affect how ICRadius runs and outputs various things
with command line switches. You can put these switches after the start command
in your /etc/rc.d/init.d/radiusd file.
|
Switch |
Description |
Default |
|
-a <dir> |
Accounting directory. Where to place detail files |
/var/log/radacct |
|
-d <dir> |
Directory where hints, huntgroups and radius.conf are
located |
/etc |
|
-i <IP> |
IP to bind to |
INADDR_ANY |
|
-l <dir> |
Logs dir |
[/var/log |
|
-f |
Don't fork from the console to become a deamon |
fork and be a daemon |
|
-m <flags> |
Accounting method. s = SQL accounting, f = file
accounting. |
S |
|
-S |
Log stripped names. Only affects setups with
Strip-Username |
|
|
-p <port> |
Port IC-RADIUS will listen for auth requests. Accounting
will |
looks for /etc/services entry and then uses 1645 |
|
-r <dir> |
Directory to chroot() to before handling requests |
|
|
-t |
Use trusted proxies, eg all attributes from proxy will be
passed |
no trusted proxies |
|
-u <user> |
User to set user and group permissions to before accepting
connections |
current user |
|
-v |
Print version and exit |
|
|
-x |
Enable debugging. Use -xx for even more debugging. Turns
on –f |
no debugging |
|
-y |
Print message for each auth request, and password attempt
for |
don't log |
|
-z |
Print message for each auth request including password
(even for correct passwords!). Only takes affect with –y |
|
RADIUS.cgi is a complete web administration and reporting tool
that accesses the RADIUS database. You
will need to add a user manually first before you can use the web interface.
1.
Start MySQL: mysql
2.
Insert the user records:
A.
INSERT INTO radcheck VALUES
("","username","Password","yourpassword");
B.
INSERT INTO radcheck VALUES
("","username","RADIUS-Operator","Yes");
3.
Copy the RADIUS.cgi and usage.cgi files into the cgi-bin directory
of your web server. On mine it would look like this: cp *.cgi
/usr/local/apache/cgi-bin
4.
Edit both of these so that the $dbusername and $dbpassword are the
same as the one setup for the MySQL server.
Also change $cookiedomain to your domain name. For example: $cookiedomain
= domain.com If you don't have a
domain or you are working on a machine that is not listed in your DNS, you can
set it to null (i.e. "") You
can also edit some other features such as the log directory and the background
color.
Since the whole point of ICRadius is to authenticate users,
setting up those users is a pretty important thing. You can use the supplied
CGI web interface, you can edit directly from MySQL, you can use a third party
web interface such as Webmin, or you can write your own. As of this writing,
several third parties are working on fairly robust alternatives to the CGI that
comes with ICRadius. I wouldn’t be too surprised to see one of these make an
appearance in the distribution soon. Meanwhile, though let’s look at how we
might set up a user.
RADREPLY TABLE
|
id |
UserName |
Attribute |
Value |
|
1 |
alpha |
Framed-Compression |
Van-Jacobson-TCP-IP |
|
2 |
alpha |
Framed-IP-Address |
255.255.255.254 |
|
3 |
alpha |
Framed-Protocol |
PPP |
|
4 |
alpha |
Idle-Timeout |
1800 |
|
5 |
alpha |
Port-Limit |
1 |
|
6 |
alpha |
Service-Type |
Framed-User |
|
7 |
alpha |
Session-Timeout |
28800 |
RADCHECK TABLE
|
id |
UserName |
Attribute |
Value |
|
1 |
alpha |
Simultaneous-Use |
1 |
|
2 |
alpha |
Monthly-Time-Limit |
36000 |
That is a total of nine entries per user. And that’s without all
the possible attributes that you might want to use. Multiply that times 5000
customers and you have a real maintenance headache on your hands. There is an
easier way, fortunately.
One common use for groups is to set up the attributes of a
specific dialup plan such as Simultaneous-Use, Framed-Protocol,
Total-Time-Limit, etc. in a group setting and then add a user to the usergroup
table. This effectively makes the user inherit all of the attributes of the
group while only having to making a few entries for that user. It also makes it
easy to change the attributes of an entire group without having to edit each
member of the group. Consider the following example:
RADGROUPCHECK TABLE
|
id |
GroupName |
Attribute |
Value |
|
1 |
PLAN1 |
Simultaneous-Use |
1 |
|
2 |
PLAN2 |
Simultaneous-Use |
1 |
|
3 |
PLAN1 |
Monthly-Time-Limit |
36000 |
|
4 |
PLAN2 |
Monthly-Time-Limit |
720000 |
Here’s how our example works. You define the characteristics of
the groups (some ISP’s call these plans) you want in the radgroupcheck and
radgroupreply tables. This is done only once for each group you wish to define.
Notice that we have defined two groups: PLAN1 and PLAN2. Any check items which
we wish to define for all members of this group are defined in
radgroupcheck (above). Any reply items which we wish to define for all
members of this group are defined in radgroupreply (below).
RADGROUPREPLY TABLE
|
id |
GroupName |
Attribute |
Value |
|
1 |
PLAN1 |
Framed-Compression |
Van-Jacobson-TCP-IP |
|
2 |
PLAN1 |
Framed-IP-Address |
255.255.255.254 |
|
3 |
PLAN1 |
Framed-Protocol |
PPP |
|
4 |
PLAN1 |
Idle-Timeout |
1800 |
|
5 |
PLAN1 |
Port-Limit |
1 |
|
6 |
PLAN1 |
Service-Type |
Framed-User |
|
7 |
PLAN1 |
Session-Timeout |
28800 |
|
8 |
PLAN2 |
Framed-Compression |
Van-Jacobson-TCP-IP |
|
9 |
PLAN2 |
Framed-IP-Address |
255.255.255.254 |
|
10 |
PLAN2 |
Framed-Protocol |
PPP |
|
11 |
PLAN2 |
Idle-Timeout |
1800 |
|
12 |
PLAN2 |
Port-Limit |
1 |
|
13 |
PLAN2 |
Service-Type |
Framed-User |
|
14 |
PLAN2 |
Session-Timeout |
28800 |
Then, we add the user to the group (or, as an ISP, sell them a
dialing plan) by associating the username to the groups we created. We do this
by making an entry for each user we want in a group to the usergroup table
(below).
USERGROUP TABLE
|
id |
UserName |
GroupName |
|
1 |
alpha |
PLAN1 |
|
2 |
beta |
PLAN2 |
RADCHECK TABLE
|
id |
UserName |
Attribute |
Value |
|
1 |
alpha |
Password |
Alphapasswd |
|
2 |
beta |
Password |
Betapasswd |
We set the items which are specific to the user in either the
radcheck table (above) or the radreply table (below). Very little actually goes
in either of these tables normally because most of the settings are inherited
from the group tables. In our example, we only set up a password for the user
and in the case of username alpha, we gave them a fixed IP address. Notice that
by defining the same attribute in radreply as they user inherited from
radgroupreply, we have overridden the group values. In other words, the
attribute of Framed-IP-Address that was defined in the group was ignored
because we defined the same value for the specific user. This is useful for
things like overriding the number of logins for a specific user, assigning
fixed IP addresses, etc.
RADREPLY TABLE
|
id |
UserName |
Attribute |
Value |
|
1 |
Alpha |
Framed-IP-Address |
192.168.1.200 |
IC-RADIUS currently supports a single DEFAULT entry. To use the
DEFAULT feature, create a group in radgroupcheck and radgroupreply with the
items you wish to use. Then add an entry into usergroup with the username
DEFAULT and the groupname of the group you just created. Be sure to have an
Auth-Type as a check item for the group so it knows how to authenticate the
user, such as Auth-Type = System.
The web interface is self-explanatory to anyone who has worked
with the old Livingston RADIUS users file.
The biggest addition is groups. Groups, like users have check and reply
pairs. When you assign a user to a
group, they inherit the pairs from the group as well. Any pairs that exist in
both the user and the group will be overridden by the one assigned specifically
to the user.
Many reports can be run from within the web interface. Some of
these include when any user was on by date/time, username, IP address and
several other useful fields. A basic graph of port utilization is also
available. There is no longer the need to give everyone access to your server
to view the log files. You can continuously view the log from within the web
administrator by clicking auto scroll. Use the web interface to add entries for
all of your NAS hardware. When the web interface is complete there will be a
manual of its own. And it’s a good thing, too, because there are many options
in it that I am not familiar with.
There are several useful scripts in the script sub directory such
as one for loading an existing Livingston style users file or to dump your
ICRadius database to such a file. In each of these scripts, you will need to
change
the $dbusername and $dbpassword as described above. These scripts
all have comment headers in them which documents what they do and usually how
to use them. If you write a useful script which might be beneficial to others,
please submit it to the list and it will be considered for possible inclusion
in future releases.
There are two new attributes; Monthly-Time-Limit and
Total-Time-Limit. These attributes take a integer as an argument and limit the
user to that number of seconds. Monthly-Time-Limit is reset every month. When
the user gets close to their limit it will readjust their session-timeout to
the remaining time they have left. This prevents the user from being able to
use time over their allowance without any intervention by you.
|
Attribute |
Type
|
Description |
|
Simultaneous-Use |
integer |
Max # of concurrent logins |
|
Exec-Program |
string |
Program to execute
after authentication. Can take arguments. You can use macros in the
arguments: Taken from the original request: %p Port number %n NAS IP address %u User name %a Protocol (SLIP/PPP) %s Speed (connect string – eg:
28800/V42.BIS) %i Calling Station ID Taken from the reply as defined thus far: %f Framed IP address %c Callback-Number %t
MTU |
|
Exec-Program-Wait |
string |
Same as Exec-Program,
but wait for program to finish before sending back reply to NAS. The output from Exec-Program-Wait is
parsed by the RADIUS server. If it looks like Attribute/Value pairs, they are
decoded and added to the reply sent to the NAS. This way, you can for example
set Session-Timeout. For backwards compatibility, if the output doesn't look
like valid RADIUS A/V pairs, the output is taken as a message and added to
the reply sent to the NAS as Port-Message. If Exec-Program-Wait returns a
non-zero exit status, access will be denied to the user. With a zero-exit
status, access is granted. |
|
Login-Time |
string |
Defines the time span a user may login to the system. The format of a time string is like the format used by UUCP. A time string may be a list of simple time strings separated by "|" or ",". Each simple time string must begin with a day definition. That can be just one day, multiple days, or a range of days separated by a hyphen. A day is Mo, Tu, We, Th, Fr, Sa or Su, or Wk for Mo-Fr. "Any" or "Al" means all days. After that a range of hours follows in hhmm-hhmm format. For example, "Wk2305-0855,Sa,Su2305-1655". RADIUSd calculates the number of seconds left in the time span, and sets the Session-Timeout to that number of seconds. So if someone’s Login-Time is "Al0800-1800" and she logs in at 17:30, Session-Timeout is set to 1800 seconds so that she is kicked off at 18:00. |
|
Monthly-Time-Limit |
integer |
Number of seconds a
user may use within the current month. Resets on the 1st of each
month. adjust the Session-Timeout when the user approachs the end of their
time. |
|
Total-Time-Limit |
integer |
Total number of
seconds a user may use. Never resets. Adjusts the Session-Timeout when the
user approachs the end of their time. |
|
Activation |
date |
Date account becomes
active. The format of the Activation attribute is the same as the expiration.
Three letter month, two digit day and four digit year. Ex: 'Apr 26 2000'. |
|
Expiration |
date |
Date account becomes
inactive. |
Here’s an example of how you might use Exec-Program:
Use the following entry for someone who has BSMTP (queued SMTP)
service. "brunq" is the program that runs the SMTP queue.
RADCHECK TABLE
|
id |
UserName |
Attribute |
Value |
|
1 |
Robert |
Service-Type |
Framed-User |
|
2 |
Robert |
Exec-Program |
/usr/local/sbin/brunq
-h %f delta |
Here are links to other
things that might help you if you run into problems. These are provided because
there is no way we can include a thorough explanation of how to install
everything you need to make ICRadius run. Hopefully, if we didn’t give you what
you needed in this document, you can at least get some help on these sites.
http://www.perl.com/CPAN-local/modules/01modules.index.html
http://www.switch.ch/misc/leinen/snmp/perl/
http://www.iserver.com/support/virtual/perl/mod/install.html
http://www.mysql.com/documentation/index.html
http://www.mysql.com/doc/R/e/Replication_FAQ.html
http://www.mysqlwebring.com/faq.php?user_action=view_detail&faq_id=90&category_id=22
http://www.wizdom.org.uk/linux/mysql.shtml
http://www.freeradius.org/rfc/rfc2138.txt
http://www.freeradius.org/rfc/rfc2139.txt
http://www.livingston.com/tech/docs/radius/RADIUSTOC.html
http://www.miquels.cistron.nl/radius/README
http://icradius.hislora.com.au/
ftp://ftp.cheapnet.net/pub/icradius/README
http://www.kopower.com/pipermail/icradius-archive/
IC-RADIUS is not supported by InnerCite. InnerCite does not claim
responsibility of any kind for IC-RADIUS. IC-RADIUS is provided AS IS with no
warranty of any kind. The authors and document maintainer make no claims as to
the accuracy of this document. Any information contained herein is to be used
at your own risk.
InnerCite Inc.
GNU Free Documentation LicenseVersion 1.1, March 2000 Copyright (C) 2000 Free Software Foundation, Inc.59 Temple Place, Suite 330, Boston, MA 02111-1307 USAEveryone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLEThe purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONSThis License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. 2. VERBATIM COPYINGYou may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may acceptcompensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITYIf you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONSYou may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
M. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
O. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
P. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
Q. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTSYou may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTSYou may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKSA compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. 8. TRANSLATIONTranslation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. 9. TERMINATIONYou may not copy, modify, sublicense, or distribute the Document except as expressly provided or under this License. Any other attempt to copy, modify, sublicense or distribute the document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSEThe Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.