.What is mysqlRadius
.What mysqlRadius is not
.Intended Audience
.How to Install mysqlradiusd0.6-cistron-1.6.6.tar.gz
.How to Install mysqlRadius
.How to Add a NAS (Network Access Server)
.How to Add a User
.How to Test your RADIUS Server and mysqlRadius
.Coming Up
mysqlRadius is a web application that handles from one to hundreds of the tried and proven Cistron 1.6.6 RADIUS server. A MySQL database is used for all application and configuration data and ultimately used for configuring all the mysqlRadius controlled RADIUS servers.
In a nutshell, mysqlRadius is in charge of administering the following 5* files that can be as much on a local server as on a remote one. For example, if the raddb directory is in its mysqlRadius default location then these would be the 5* files:
/usr/local/etc/raddb/users
/usr/local/etc/raddb/clients
/usr/local/etc/raddb/naslist
/usr/local/etc/raddb/naspasswd
/usr/local/etc/raddb/realms (*Not yet but soon in 2.x series)
mysqlRadius also supports any type of RADIUS profiles that the Cistron radiusd supports by means of configurable and unlimited number of different templates (see mysqlRadius.tProfile and mysqlRadius.tProfileName.) These templates can be a default profile for all servers or be specified for each server and/or each user (and also if they are meant for CHAP or PAP.) It is also possible for the profile template system to be used creatively, for example in implementing advanced profiles like:
Calling-Station-Id (caller-id is used along with the user and passwd) for authentication.
Special DEFAULT per realm profiles for RADIUS proxy servers. (For proxy functionality see the raddb/realms file -you will have to edit it yourself in the mysqlRadius 1.X series.)
mysqlRadius is not patch of Cistron, nor depends on a RADIUS server that connects directly* to a MySQL database for authentication.
Experience has demonstrated that it is better to have static archives for servers in production status. This design facilitates the boot sequence and offers an extra backup of mission critical archives -also making migrations and clustering very simple.
...
*The related application mysqlRadacct uses a slighly altered version of the Cistron 1.6.6 RADIUS server -see next section- that enables it to store accounting data in what is usually a central data base -or mysql cluster- (this provides failover when using multiple backup RADIUS servers.) Our modified version of Cistron also can run SMTP-AFTER-AUTH in conjuntion with our mysqlSendmail mysqlISP subsystem (please note that mysqlISP subsystems also can work as complete standalone applications.) Furthermore, we also have a modified version of the highly regarded Qualcomm (tm) qpopper that also can implement SMTP-AFTER-POP also in conjuntion with our mysqlSendmail application.
Everybody that wants to run an ISP quality mysqlRadius Cistron RADIUS server system.
Webconsole setup: You will need to have an httpd daemon running on a non standard port and restricted to access only from your authorized intranet workstations and used in a switched hub setting for some security. For correct ISP security the httpd should be SSL. If you don't know how to setup all this or do not even know what we are talking about, find someone who can do it for you. The good part is that it can be easily replicated across all your ISP servers and used by all your mysqlISP subsystem or standalone cgi's. Use iptables for inter city server firewalling of mySQL ports. Use it anyway. Security is like an onion, it should have many layers.
You will have to have some BASH shell knowledge (or learn it) and be able to do simple file edits with "vi" - or another easier to learn editor like "pico."
Not required for basic linux setups on, for example, RH 9 with a full developer install: But you should have at least some experience with tar and compiling tar.gz software distributions. And some understanding of linking, paths to libs and include files will help if you are trying to install on non linux systems.
Before installing mysqlRadius it is advisable to install Cistron RADIUS server software. mysqlRadius works with any version of Cistron RADIUS server. Nevertheless, mysqlRadacct and mysqlSendmail, need this special Cistron version to take advantage of all their functionality. mysqlRadacct manages RADIUS accounting data, monthly reports, auto-hold and data warehousing of highly compressed month-year accounting data. mysqlSendmail requires our modified Cistron RADIUS server for a very effective and ISP workload reducing ISP mail relay control system called SMTP-AFTER-AUTH.
First download the source tar.gz (check for latest version. 0.8 is only an example version for use in this tutorial.)
$wget http://openisp.net/mysqlRadius/mysqlradiusd0.8-cistron-1.6.6.tar.gzExtract the files and change to correct directory:
$tar xzf mysqlradiusd0.8-cistron-1.6.6.tar.gz $cd mysqlradiusd-cistron-1.6.6Please read INSTALL and doc/README.mysqlradius
Change into the extracted directory src sub dir. Edit mysql.c if you will use SMTP-AFTER-AUTH: Edit the ConnectDb() function connection settings and uncomment the #define SMTP_RELAY at the top of the file.
$cd mysqlradiusd-cistron-1.6.6/src/ $vi mysql.c (Optionally)Compile the program (Experts only: At this time you may optionally edit the src/conf.h file and define some parameters of the program to your needs. For example the directory default of the RADIUS server):
$makeInstall the executable binaries, configuration files and man pages. By default in our distribution the binary executables are installed in /usr/local/bin and /usr/local/sbin. And the man pages are installed in /usr/local/man and the configuration files in /usr/local/etc/raddb. Nevertheless these paths can be modified in the Makefile (before executing make install of course!) Change variables BINDIR, SBINDIR, MANDIR, RADIUS_DIR to suit your needs. !Beware you may also have to change mysqlRadius tConfiguration name/value pairs and maybe even some source code files that have not been made configurable yet!
$make installIf using mysqlRadacct with this RADIUS server you will have to verify -and change inaccordance with your mysqlRadacct local.h file- the raddb/sqlserver file by default in /usr/local/etc/raddb/sqlserver*.) Example configuration:
server localhost login mysqlradacct password wsxedc acct_db mysqlradacct acct_table tRadacct doacct yes keepopen yes---
*There have been reports of the need to install this file in /etc/raddb (or someother Cistron default install dir.) We have not had time to test this.
Download software from the OpenISP/mysqlRadius page. Note that version 1.5 is this tutorial's example, this version can change at any time, but in general always announced at www.freshmeat.net. Sign up to get emailed update messages!
$wget http://openisp.net/mysqlRadius/mysqlRadius1.5.tar.gzUnpack software
$tar xzf mysqlRadius1.5.tar.gzSet the environment variables ISMROOT and CGIDIR. ISMROOT will be the path to the directory where the mysqlRadius resides after unpacking. Let us suppose as an example that the the software was unpacked into /home/openisp/mysqlRadius then ISMROOT will be equal to /home/openisp. CGIDIR will be the path to the directory in where mysqlRadius.cgi will run via the webconsole httpd daemon. This directory will have to be set in the configuration files of the web server (Ex. Apache) with permissions to execute cgi's and should also be protected for intranet only access or for remote SSL httpd access.
It is necessary to finalize the CGIDIR path with "/", see examples.Example 1 (bash shell):
$export ISMROOT=/home/openisp $export CGIDIR=/home/openisp/cgi-bin/
Example 2 (csh or tcsh shell):
$setenv ISMROOT /home/openisp $setenv CGIDIR /home/openisp/cgi-bin/Typical lines of Apache httpd.conf file (where ISP workstations are 192.168.0.222, 225 and 226:)
<Directory "/home/openisp/webconsole/../cgi-bin/" > AllowOverride None Options FollowSymLinks Order allow, deny #openisp.net intranet only. Could easily be extended to certain workstations #(users) or class C's easily Allow from 192.168.0.222 Allow from 192.168.0.225 Allow from 192.168.0.226 </Directory >Verify that the source code DEFINES of the file local.h are set correctly:
DBIP: IP of the mySQL server. NULL for mySQL same server socket (fastest!)
DBNAME: Name of the database, usually "mysqlradius".
DBLOGIN: Name of the mysql user with GRANT permissions to access the database above, usually "mysqlradius".
DBPASSWD: The password used by user DBLOGIN to access the database.
All this can be checked easily via a shell session on the server in question with the mysql command line client program.
Ex 1. For local server mysql database using NULL (socket file.)
$mysql -u mysqlradius -p mysqlradiusEx 2. For remote server mysql database.
$mysql -h 192.168.0.45 -u mysqlradius -p mysqlradiusWe highly recommend that you learn the basic use of mysql, mysqladmin, myisamchk and that your learn how to clean up the mysql database and use GRANT SQL statements correctly. See mySQL docs.
To compile the program use make within the correct directory:
$cd $ISMROOT/mysqlRadius; makeTo install (smaller symbol stripped) executable files:
$make installInitialize mysqlradius and install default distribution data. First make sure that (mysqld) has access to the mysqlRadius/data directory (this has to done by verifiying the permissions of the complete path and maybe using chmod and chown commands. Supposing that the data is in /home/openisp/mysqlRadius/data then the permissions of the other directories should be somthing like (using $ls -l):
drwxr-xr-x 7 root root 4096 Aug 20 18:18 /home drwx-----x 12 openisp root 4096 Oct 3 15:58 /home/openisp drwxr-xr-x 3 openisp openisp 4096 Oct 3 15:58 /home/openisp/mysqlRadius drwxrwxr-x 2 openisp openisp 4096 Oct 3 16:02 /home/openisp/mysqlRadius/dataThe files contained in the data directory will have to be able to be read by mysqld, in general this is the default.
Once this is checked out run the mysqlRadius.cgi in command line mode (note that it is bith a cgi and a command line program. If run with no arguments it will display a short menu and exit.)
Examples:
$/home/openisp/cgi-bin/mysqlRadius.cgi $/home/openisp/cgi-bin/mysqlRadius.cgi Initialize wsxedcWhere "wsxedc" is the mysql root user passwd. Please note at this time that if anything fails you will have to login to the mysql database and "DROP DATABASE mysqlradius." Correct permission problems or environment variable settings and then try again.
Once the "Initialize" is done we can begin to setup our application so that the Cistron RADIUS Cistron works with it.
mysqlRadius is a powerful and well tested tool, that handles from 1 to 100's of RADIUS servers. Therefore there will be individual configurations for each server and global configuration settings that affect all servers.
First thing that we must do is add the name(s) (or a short alias name with which we will use to always identify it) of the RADIUS server(s). To do this we will use the browser interface and change to the tServer table (for the curious the small letter t is for table, u for unsigned int, c for char string, some u values you will see are keys into other tables cLabel). For our example the single server will be "localhost." This now comes all preconfigured for you but read on anyway since it will be very educational for adding more servers or just changing the name from localhost to radius0 etc.
Press the [New] (or [Modify]) button on the top right, to start setting up a new record. Our simple objective is to setup a server with the correct cLabel (note that this can be done even after the server is running since we actually use the uServer index value.) with the name by which we will identify the server which we are building, To finish press the button [Create New Record] (or [Confirm Modify]).
Then we will need to change over to the tConfiguration panel, in same we will setup or modify the following name/variable pairs: The name is cLabel, the value is in the cValue tConfiguration row field (techncially SQL speaking: mysqlradius.tConfiguration.cValue.)
(Please note that all this comes preconfigured and that the cComment field should provide complete and updated documentation on the tConfiguration name or label/value pairs and their significance.)
cRADDBDir: Is the full path to the raddb directory where the configuration files are kept for the Cistron radiusd (usually /usr/local/etc/raddb.) cRADIUSDPath: Is the full path to the command that executes the RADIUS server daemon program (usually /usr/local/sbin/radiusd). cRADIUSDArgs: Are the arguments with which the RADIUS daemon will be executed with. Example: "-D -y -i 192.168.0.226 -p 1645 -l /home/openisp/logs". cRADIUSDPID: Is the path to the file that keeps the PID (process id) if the running or last running RADIUS daemon server instance. cRADIUSDUID: Contains the UID (user ID -see /etc/passwd) that the RADIUS server runs as. Make sure it is correct or the system will not start. cCRYPTMethod: Specifies the method of encryption to be used to store non clear text passwords in the users file -if that can of profile is bieng used (note CHAP/PAP differences in regards to clear text vs. encrypted users passwd entries.) Methods of encryption supported at the moment are DES and MD5.If you use more than one server you can setup all these values for each by appending to each "-<cLabel of server>." For example for a tServer cLabel "radius23" you would create a new tConfiguration record called "cRADIUSDUID-radius23."
You could setup a whole "family" of tConfiguration entries for the server in question. As in the example above you would create:
cRADDBDir-radius23 cRADIUSDPath-radius23 cRADIUSDArgs-radius23 cRADIUSDPID-radius23 cCRYPTMethod-radius23 cRADIUSDUID-radius23But usually only the cRADIUSDArgs-radius23 and possibly the cRADIUSDUID-radius23 would be needed if all servers have the same setup, which is the recommended method. This illustrates an important point the name/value pairs not associated with a given tServer.cLabel will act as the global defaults for all servers! Or put in another way only if a -radius23 tConfiguration.cLabel exists will it override the tConfiguration.cLabel non -radius23 default.To start the new server with the args in cRADIUSDArgs-radius23 for example you would use:
$mysqlRadius.cgi Start radius23Note that these are equivalent now:
$/cgi-bin/mysqlRadius.cgi Start localhost $/cgi-bin/mysqlRadius.cgi StartBefore using the system we need to setup the async job queue crontab entries. You can edit or create a new crontab with the following command: You need to be root (or su as some say) -or maybe just openisp- to create a crontab for openisp if openisp is running the radiusd and can change the files in /usr/local/etc/raddb for example.
$crontab -eWe would add the following line to the crontab in question. Advance sysadmins could use root /etc/ based crontab files if they wish.
*/10 * * * * /home/openisp/cgi-bin/mysqlRadius.cgi ProcessJobQueue localhost >>/home/openisp/logs/mysqlRadius.log 2>&1;This line would run only the localhost jobs in the tJob queue every 10 mins. The interval (10 minutes) should and can be adjusted for each ISP workload and server response time.) The rest of the /bin/sh crontab entry deals with putting all output and error output into the logfile. See man crontab for much more info.
We should always backup our data regularly and in many places: This is one simple way. The ISMROOT could be adjusted to use another drive or even another NFS mounted filesystem if reliable enough.
20 4 * * * export ISMROOT=/home/openisp;/cgi-bin/mysqlRadius.cgi Backup <mysql root passwd> > /dev/nullNow we are almost ready to use our system...
In order to start using our new mysqlRadius system the next thing that needs to be done is to setup the list of NASs. The tNAS table (get to it via the top menu item link) allows this to be accomplished. What this section of the mysqlRadius webconsole cgi does is configure the raddb/nas, naspasswd and clients files so that the NASs configured here may communicate with the RADIUS server. And in some cases allow the Cistron system to connect to the NASs via SNMP, telnet or tftp. Some example NAS entries come preconfigured and the cInfo field should provide valuable information so browse through these entries and read them.
To add a new NAS we use the [New] button, fill in the fields and then the [Create New Record] button to finalize. Next we list the field names and their purpose briefly.
.cLabel: The name that is used to identify the NAS. Note that it can be a short name and not the actual FQDN of your DNS system. .cKey: In this field we save the important shared secret or better described as the encryption key set both here and in the NAS itself. .cType: This is not too important unless you use Cistron to connect to the NAS. See the original Cistron raddb/naspasswd file for more details. .cIP: IP number of the NAS in standard dotted 4 octet notation. Ex. 192.168.0.43 .cLogin y cPasswd: The login and passwd used to access some types of NASs.To configure our RADIUS server to work with the supplied nph-radtest.cgi (explained in detail below) we need to make sure that we can connect to it from the IP used by this script cgi. A useful entry "localhost" comes preconfigured but you will have to change the cIP field to fit your system. An easy way to find out which IP needs to be used is to setup the nph-radtest.cgi and run it -it may take quite some time to finish. Then look at the radius.log for the non authorized IP attempt to access our radiusd. Example of the tNAS record and how to setup. First locate the localhost record or add a new test record with [New] or [Modify]. Then enter the following field data.
.cLabel: localhost .cKey: testing123 .cType: radtest .cIP: 192.168.0.1 .cLogin y cPasswd: (Leave empty)After all is entered correctly finalize with [Create New Record] or [Confirm Modify]. After this is done. If the job queue crontab is running we can wait, or force it by running it from the shell. A final option is too [Make Local Clients File] and then [Make Local NASlist File], then finally go to tUser and [Reload Radius Files].
Adding or modifying an existing tNAS entry modifies and/or creates the following files:
raddb/naslist raddb/naspasswd raddb/clientsPlease note that in the left panel one can set which mysqlRadius managed RADIUS server that this NAS entry is applied to. You can also add more than one RADIUS server to this NAS entry with the [Add Server] button. The [Remove Server] button should be self explanatory :)
Quick step by step recipe:
.Start creation of a new user in tUser with [New].
.Set cLogin field with the login to be used.
.Set cEnterPasswd with the password to be used with the cLogin above.
.Select an adequate profile. For now select the preconfigured Unlimited.
.Set uSimulUse to 1 unless expert.
.Set uClearText to 0 for starters.
.Set cIP if using a static IP profile. Experts only, other should leave blank.
.!As an advance topic make sure that the profile name and profile exist for the uClearText and cIP settings you have used!
.Hit the [Create New Record] button.
Then...
.Make sure the user has been assigned to correct server or servers. If not use the left panel buttons and drop down server select to make sure.
.Make sure the job is run, or if impatient use the [Make Local Users] button and check the /raddb/file and/or also use [Reload Radius Files] ands run from your browser the nph-radtest.cgi script explained in detail below. .Verify by examining the radius.log file and tJob that everything is ok.
To check our RADIUS server we will use the Cistron supplied radtest script. It is very easy to run and very useful for debugging.
Usage: radtest user passwd radius-server nas-port-id secret [ppphint] [nasname]
See man radtest for much more info.Let us say we have added a user "tester" who's passwd is also "tester." (In a real production RADIUS server this would be a very dumb idea.)
Let us also say we have a tNAS entry with a cKey=testing123 and cIP set correctly. If not set correctly the radius.log file will show you the way.
Let's also assume that the user is in the raddb/users file and that the radiusd was reloaded. Again we can check the crontab log and/or the radius.log and the tJob queue entries to make sure.
We are now ready to test...
$radtest tester tester 192.168.0.226:1645 4 testing123If everything worked out we should see something like this (as the expert mysqlRadius user you have become we leave this an exercise, verify this result against the profile assigned to this user):
Sending request to server 192.168.0.226, port 1645. radrecv: Packet from host 192.168.0.226 code=2, id=149, length=56 Service-Type = Framed-User Framed-Protocol = PPP Framed-IP-Address = 255.255.255.254 Framed-IP-Netmask = 255.255.255.255 Framed-Routing = None Framed-MTU = 1500If the user tester or the passwd is wrong we should see something like this:
Sending request to server 192.168.0.226, port 1645. radrecv: Packet from host 192.168.0.226 code=3, id=161, length=20 Access denied.This can be verified in the radius.log file if the correct tConfiguration cRadiusdArgs for the server in question has the correct logging options.
If the IP source of our radtest is wrong or the tNAS cKey is incorrectly configured we should see something like this:
Sending request to server 192.168.0.226, port 1645. Re-sending request. Re-sending request. Re-sending request. Re-sending request. Re-sending request.This again can be debugged easily by reading the radius.log file
An operationally identical but more daily ISP useful method of checking a user for authentication is to setup and use the nph-radtest.cgi script that comes with the distribution in the scripts dir. The script should be copied to the webconsole cgi-bin (or similar location) and then edited as follows:
.SERVER1=IP of RADIUS server .SERVER1PORT=Port used by RADIUS authentication server. Usually 1812 or older 1645. .TITLE1=An optional title for the page displayed.As per our example above these variables would be set as follows:
SERVER1="192.168.0.226" SERVER1PORT= "1645" TITLE1="Test radius server on host 192.168.0.226"To use this script you must enter in the location field of your browser (we recommend you use www.mozilla.org browsers for all mysqlISP webconsole applications) the correct URL to get to the nph-radtest.cgi script. It has it's own mini help information for use. But an example follows.
http://192.168.0.226:2596/cgi-bin/nph-radtest.cgi?tester+tester_passwd
In future docs releases we will expand on the complexities of profile templates and their use as well as fix any typos or style errors herein. You let us know how we are doing.
Have fun and don't take computers too seriously they are pretty much just dumb machines that only work if told to do so in exactly the right way. :)