ICRADIUS Installation and Setup Procedures

READ THIS DOCUMENT COMPLETELY BEFORE POSTING QUESTIONS TO THE MAIL LIST.


0. INTRODUCTION

This document is forever 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.

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 ICRADIUS.  The whole
radius system is basically in tabular format, and what better way
to view tabular data than in a database.  ICRADIUS 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.
ICRADIUS is available for download from 
ftp://ftp.cheapnet.net/pub/icradius/  

In the following sections you will find information on setting
up ICRADIUS as well as the general procedures for installing
mySQL and the Perl DBI and mySQL DBD modules, all of which are
required for ICRADIUS to operate properly.


1. PREREQUISITES

In order to use ICRADIUS, 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.


2. HOW IT ALL WORKS

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 ICRADIUS up and running as quickly
and painlessly as possible.  So lets get started with a general
overview of how things work.


2.1 RADIUS - 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) which desires to authenticate its links and a
shared Authentication Server (ICRADIUS). 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.

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 (ICRADIUS) 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.  Lastly, 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.  Now lets move on and see what 
ICRADIUS needs to operate properly.


2.2 PERL DBI AND mySQL DBD MODULES OVERVIEW
 
Needless to say, you must have Perl installed on your machine before
you can do this part.  If you don't have it, go to http://www.perl.com
and get it.  Again, I am assuming that you have read the above 
sections and have downloaded these modules already.  If you already
have a version of perl installed, you need to check the documentation
provided with the DBI and DBD.  This will specify the minimum version
of perl required for proper operation of the module.  If you have a 
version older than what is specified, you must upgrade to a newer one

Lets get started 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.


3 mySQL INSTALLATION PROCEDURE

The next thing that is required for ICRADIUS to operate is to have
mySQL installed and running on your system.  I am assuming that you
have already read the above sections and downloaded mySQL or that 
you already have a version of mySQL installed on your system.  You
will need at least version 3.22.  Now, if you have downloaded mySQL,
you should place the tarred and zipped file in the /usr/src directory
and do the following: 'tar zxvf mysql-version.tar.gz'  This will 
extract the files and create the directories needed to start the 
install.  Next, you should cd to the mysql.version directory, and
from there type './configure'  This will configure and create the 
Makefile for your system.  Now you need to type 'make'.  If it
compiles ok, you can type 'make install'.  If not, you may want to
go to the mySQL website at http://www.mysql.net and read the official
installation instructions.  Now you need to run 
'scripts/mysql_install_db'.  Once that is complete, you are ready to
start the mySQL server.  The command for this is 
'/usr/local/mysql/bin/safe_mysqld &'  

No, we're not through yet.  Now you must set the basic user
permissions for the server.  Initially, root is the only user
allowed to access the databases and this has no password, so 
anyone can do anything they want.  So we must first set the 
password for root.  This is done by typing 'mysql -u root mysql'
then type the commands:  
	'UPDATE user SET Password = PASSWORD ('new_password')'
	'WHERE user = 'root';'
	'FLUSH PRIVILEGES;'

Now you can use root as the main user, but I highly recommend
adding another username and password.  This can be done by typing:
'INSERT INTO users'
'VALUES ('host','user','passwd',
	'y','y','y','y','y','y','y','y','y','y','y','y','y','y');'

Host should be the machine that is running ICRADIUS.  Most likely
this will be the same one that mySQL is running on.  In that case,
you can put "localhost" here.  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. Now we will look at the Perl
modules.



4 INSTALLING THE DBI AND DBD MODULES

To install the perl DBI, you must first uncompress it.  Again, this
is done by typing the command 'tar zxvf DBI-version.tar.gz'  Now you
need to cd to the DBI-version directory and type the command 
'perl Makefile.PL'.  Next you type 'make' followed by 'make test'. 
If everything goes ok, you can type 'make install'.  If you get any
errors during make, or failed tests during make install, you should
carefully read the documentation provided with the module.  There are
some known problems, and they are listed there.  Once you
have succesfully installed the DBI, you need to delete the source
directory.

To install the mySQL DBD module, you again unpack it with 
'tar zxvf DBD-version.tar.gz' and cd to the DBD-version directory.
Next, type 'perl Makefile.PL' followed by 'make' and then 
'make test'.  Again, if you get errors during make, or failed tests
during make test, read the documentation provided with the module.
Again, there are some known problems, and most of them are listed in
the documentation.  If all goes well, you can type 'make install',
and be done with this part.


5 ICRADIUS INSTALLATION

Finally!  Once the above items have been properly installed, you can
begin to install ICRADIUS.  Again, you 'tar zxvf icradius.tar.gz'
and cd to the icradius directory. Now you will see several files of
the form Makefile.OS.  Edit the one that matches your system and be
sure that all the defined paths and assumptions about your system are
correct.  Now copy the Makefile.OS to Makefile and type 'make'.  If
there are no errors you can then type 'make install'.
  
To be able to use ICRADIUS you must now create a database in mySQL
named radius.  To do this you must first start a mySQL session by
typing mysql.  When the mysql command promt comes up, you type the
following: 'CREATE DATABASE radius'  You can now end the session by
typing QUIT.  

Next, we must create all of the tables that ICRADIUS will need,
fortunately these have already been defined in the file 
scripts/radius.db.  Type 'mysql radius < radius.db' and this will
build all the tables needed for both authentication and accounting.
Now you will need to load the dictionary file found in the raddb into
mysql as well as the dictionary.NAS that matches your NAS.  The script
dictimport.pl will do this for us. All you have to do is edit the
$dbusername and $dbpassword entires in this script to match the 
username and password you setup for the mySQL server and then run 
'dictimport.pl dictionary' for all the dictionaries you need.

You will need to manually add entries for your NAS hardware into the 
nas table. Do a 'desc nas' from the mysql prompt to see all the
columns that need to be filled in. This step replaces the need for
both the naslist and the clients file standard cistron used.  Next
copy radius.conf from raddb into /etc/raddb and set the values in
that file as needed.

The file 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. To do this you 
type 'mysql' and at the mysql prompt execute these commands:

INSERT INTO radcheck VALUES ("","username","Password","yourpassword");
INSERT INTO radcheck VALUES ("","username","Radius-Operator","Yes");

Now you should put the radius.cgi and usage.cgi files into the cgi-bin
directory of your web server.  Now 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.  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.

The web interface is very self explainitory to anyone who has worked
with the 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 ran from within
the web interface to 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 more need to give everyone
access to your server to view the logfiles. You can continueously 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.

There are several usefull scripts in the script sub directory such
as to load a existing users file or to dump your icradius database to
a users file. Work is progressing on a script to dump and load old 
style accounting records.  In each of these scripts, you will need to
change the $dbusername and $dbpassword as described above.

There is a new attribute type called Max-Hours. This attribute will
take a integer as an argument and limit the user to that number of 
hours per month. When the user gets close to their limit it will 
reajust their session-timeout to the remaining hours they have left.



6.	KNOWN PROBLEMS.

Here are some of the most commonly asked questions on the mail list,
and the answers to them.  


6.1	I HAVE INSTLLED MYSQL SUCCESSFULLY, BUT I GET A SEGMENTATION
	FAULT WHEN I TRY TO RUN ICRADIUS.

This is most likely a problem with the dictionary.usr file.  If you
use USR NAS's, then you must do the following to correct the problem:

 	BEFORE you try to load dictionary.usr execute the following
	queries.

	NOTE: If you have already loaded the file, then do this.
		DELETE FROM dictionary;
		This will remove everything from the table.

	insert into dictionary values ('','VENDOR','USR','429','','');

	Then run the dictimport on dictionary.usr

	Then execute the following sql queries:

	update dictionary set vendor = "USR" where type = "ATTRIB_NMC";
	update dictionary set type = "ATTRIBUTE" where type = "ATTRIB_NMC";

	Now go ahead and run dictimport on dictionary.


6.2	WHEN I RUN ICRADIUS I GET THE FOLLOWING ERROR.
		"could not find libmysqlclient.so.6"

This is a problem with /etc/ld.so.conf  To fix it, you must add a line
to this file that specifies the path to libmysqlclient.so.6  Then run
ldconfig as root.


6.3	WHEN I UPGRADED FROM 0.8 TO 0.9 I GET A SEGMENTATION FAULT

First if you use USR equipment, check 6.1 above. This could also be cause
by an old table nas table definition. Execute these queries to fix the problem.
This will also update the radacct table, since it has changed as well.

	mysql> alter table nas add column community varchar(50);
	mysql> alter table nas add column snmp varchar(10);
	mysql> update nas set community = 'public', snmp = 'on';

Fix radacct table:
	mysql> alter table radacct change column AcctDelayTime AcctStartDelay int(12);
	mysql> alter table radacct add column AcctStopDelay int(12);
	mysql> update radacct set AcctStopDelay = 0;




Many thanks go to Mike Machado at InnerCite for reworking the Cistron
code to give us ICRADIUS.  If you have any questions, you can e-mail
Mike: mike@innercite.com or James: jbanks@sonet.net.  You can also 
join the ICRADIUS mail list: icradius-list@cheapnet.net

Please visit InnerCite homepage at http://www.innercite.com

GOOD LUCK!

Mike Machado
mike@innercite.com
InnerCite
1999-07-24

Re-Written by
James Banks
jbanks@sonet.net
1999-10-06