ICRADIUS Installation and Setup Procedures EVERYTHING YOU NEED TO KNOW TO SET UP ICRADIUS IS RIGHT HERE. READ THIS DOCUMENT COMPLETELY BEFORE POSTING QUESTIONS TO THE MAIL LIST. -1: NOTE When changing from ICRADIUS 0.8 to ICRADIUS 0.9 the radacct table has changed! You will need to issue the following commands in order to keep ICRADIUS from segfaulting because if the missing columns. 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; mysql> alter table nas add column community varchar(50); mysql> alter table nas add column snmp varchar(10); Make sure you are using the new web interface script (radius.cgi) because it has been changed to reflect the new table layout as well. Also there is a known problem with the USR dictionary that causes the server to segfault on startup. If you are using the USR dictionary issue the following commands at the MySQL prompt to fix up your dictionary BEFORE you load the USR dictionary. A perminant fix will be in a later release. mysql> insert into dictionary values ('','VENDOR','USR','429','',''); Then load the USR dictionary as normal and issue these commands: mysql> update dictionary set vendor = "USR" where type = "ATTRIB_NMC"; mysql> update dictionary set type = "ATTRIBUTE" where type = "ATTRIB_NMC"; 0. INTRODUCTION 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 driving force behind the ICRADIUS project. 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',password('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","youpassword"); 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. 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 by sending a message to majordomo@cheapnet.net with 'subscribe icradius-list' in the body. GOOD LUCK! Mike Machado mike@innercite.com InnerCite 1999-07-24 Re-Written by James Banks jbanks@sonet.net 1999-08-05