Chillispot with FreeRadius and MySQL

Introduction
Chillispot is a software which provides authentication and restricted network access to clients. Its primary use is in wireless (WiFi) networks.

For instance, suppose you are managing a wireless network in a hotel: the access points are connected via the wired LAN to a server which works as a gateway, firewall, DNS server, etc. Now you want the same server (either because it's desirable or because it's required by your nation's law) to require authentication from all clients, possibly without messing around with the configuration of the access points. And maybe you even want users to be able to browse some sites (i.e. an internal web server or the hotel web site) without the need to authenticate themselves. Chillispot lets you manage all of this, and some more.

Please take a look at Chillispot website to see how the software works. In a few words, Chillispot creates a virtual private network (192.168.182.0/24, but you can change this default setting) which it uses to dialogate with the clients and to decide who and how to let to see the outside network. Chillispot manages the allocation of dynamic IP addresses to clients, so you don't need other DHCP tools.

Requirements
The following software is required for this installation:


 * Chillispot 1.1.0
 * FreeRadius 1.1.x
 * Apache 2.x
 * MySQL 5.x

Apache 1.x and MySql 4.0.x or even 3.23.x would probably do, but the above specified versions are the latest stable ones available so you're encouraged to stick to them.

This tutorial will show how to run all this software on a single machine. However, you could install Apache and MySQL on a separate one, or even have 4 different machines: you'll just need to adjust the configuration parameters of each piece of software.

Also, you'll need your kernel configured for generic tunneling support (and for NAT probably but that will not be covered here). A 2.6.x kernel version is recommended.

Caveats
This HOWTO assumes you have an x86 machine. This might not work on AMD64, because both ChilliSpot and FreeRadius have bugs which prevent them to work as they should (last time I tried FreeRadius was 1.0.x and Chillispot 1.0, so now everything might work). I don't know the status of these software on other platforms. (Unless this problem is Gentoo specific, FreeRadius 1.1.3 (compiled from source) works with FC4 on AMD64, ChilliSpot is running on Router hence not sure of its status on AMD64).

Kernel configuration
Chillispot creates a VPN, that is to say an IP tunnel. Your kernel must support this: if you're using software such as OpenVPN chances are you're already fine. Anyhow, take a look at the following section in your kernel configuration: Linux Kernel Configuration: TUN/TAP support

Device Drivers ---> Network device support --->   Universal TUN/TAP device driver support

You can either compile the TUN/TAP support inside the kernel or (as is this example) build it as a module. The name of the module will be tun and may need to be manually inserted.

modprobe tun

You'll probably also need to enable IP masquerading, NAT or what is necessary in order to let the VPN clients surf the outside network. If you're reading this HOWTO it's likely that you already know all of this; if not, look around for specific documentation.

Network and Firewall configuration
Hi We are assuming 2 network interfaces,


 * eth0 is connected to the internet and should be configured for this purpose.
 * eth1 is the interface that other computers should connect to. This interface should not be configured, but should be brought up in master mode.

You should also need to enable IP packet forwarding in :

net.ipv4.ip_forward = 1

The services you're going to use require you to open a few ports on your firewall. This HOWTO assumes you have already protected your computer somehow, and therefore only lists the changes you need to do.

You basically need to do the following:


 * Open port 443/TCP at least to the 192.168.182.0/24 subnet: this is the Apache HTTPS port.
 * Open port 3990/TCP at least to the 192.168.182.0/24 subnet: this is the port of Chillispot web server.
 * Open port 1812/UDP to 127.0.0.1 (probably all ports are already open to localhost): this is the port FreeRadius listens to, and Chillispot connects to it using that.
 * Open port 67/UDP to the VPN (probably the tun0 interface): this is used by Chillispot DHCP server to get requests for IP address registration.

This can change very much depending on your configuration, but if you stick to this example that's it. You'll probably also want to configure NAT at this point.

You can use the firewall script in "/usr/share/doc/chillispot-1.0/firewall.iptables" as a starting point.

Installing the software
Provided your Gentoo distribution is in a "sane" state, you should have no problem with software installation.

Apache and MySQL
I assume you already installed Apache and MySQL, or - if not - that you are able to do that. If this is not the case, there are plenty of tutorials out there on how to accomplish these tasks.

The only important thing to do is to enable SSL features for apache, so add ssl to you USE flags in.

Chillispot
Chillispot is masked, so edit your and add this line:

Installing is as simple as this:

FreeRadius
You need MySQL support for FreeRadius, so, if you don't have it already in /etc/make.conf, add it there or append the following line to :

You can then emerge as usual:

Chillispot configuration
Chillispot configuration resides in a single file, which is. For a single server configuration something in the shape of this will do:

Let's discuss the file in detail.

Radius section
You need to specify two radius servers even if you only have one. Of course, you can enter the same server in both lines. In this case it's localhost, as FreeRadius is on the same machine of Chillispot.

The radiussecret directive contains a (secret) word which must match the one contained in the FreeRadius configuration file. This secret ensures we are allowed to make queries to the radius server. We'll see the radius configuration part later on.

Networking section
You need to specify the IP address of the DNS server, which will be told to clients as well. The local machine's one will be fine if the machine operates a DNS service, otherwise enter another one such as you provider's.

The interface to be specified is the one where the access points reside, which should be already configured with the working access points. Be sure to disable any DHCP server bound to that interface, as Chillispot doesn't want one.

UAM section
The above line states which hosts the clients are allowed to connect to without requring authentication. You must enter the IP address of the gateway (both the VPN address and the LAN address - This is very important! In fact, you must list at least these two addresses here, otherwise the chillispot will not work!), the IP address of the DNS server (if it's on another machine) and any other hosts you want.

This is the (secure) URL of the script which displays the login interface and manages the login. We'll discuss this further in the Apache configuration section.

This is the page where all clients will be redirected when they try to surf a web site which is not in the uamallowed list. This is quite handy, as you don't need to provide login URLs to your users: their browser gets automatically redirected here. The contents of this file are very customizable (you can provide a full featured web page with information and the login link), and also this will be discussed later on while talking of Apache configuration.

This is the shared secret between chillispot and hostspotlogin.cgi, which ensures that the CGI script is allowed to talk to Chillispot. It's different than the radius secret, but you can also set them all alike (not recommended, of course).

Using unsecure URIs
As you noticed above, all URIs are https, so SSL. If you don't get a valid certificate from a CA, this might be a PITA especially for wifi users who connect using modern browsers (IE 7+, FF 3+, ...), who will get a scary page stating that the certificate is not valid with a strong suggestion not to continue with the navigation.

So, you can use http instead of https and configure your Apache to use a standard connection on port 80. However, hotspotlogin.cgi (see below) will complain for this, so you'll need to comment out this block:

Here you can find a file which I patched for this purpose.

Apache configuration
Apache (or any other webserver you like) handles the welcome page and the login requests, and therefore requires a bit of configuration.

As told before, SSL support is required by Chillispot (if you don't have it, the login manager will complain and not work). When dealing with usernames and password and encryped connection is a good idea to use SSL in any case. So, if needed, add the appropriate SSL directive to your and restart the server.

At this point there are several options. What I did was to setup a virtual host bound to http://192.168.1.73/, which is also the content of uamhomepage variable in. As I wrote before, this page can contain anything you want the user to see before loggin in (information about your place, your network, the rules, ...), but in any case it should also feature a link to Chillispot server "prelogin" page. That is to say, in it's basic form the index.html file of your web site has to be:

Click here to login

The Chillispot server bound to port 3990 will redirect the browser to whatever you specified in the uamserver line of. In this case it's:

https://192.168.1.73/cgi-bin/hotspotlogin.cgi

(You can perform redirection using iptables instead of http redirection, "iptables -t nat -I PREROUTING 1 -s (local net) -m tcp -p tcp --dport 80 -j DNAT --to 192.168.182.1:3990")

The manages the actual login. The good thing is that you don't have to write it from scratch. Just type in:

This presumes your Apache is configured to run cgi-scripts of course.

There's only one change needed for : locate the $uamsecret assignement at the top of the file and set it to the value of uamsecret in. In our example:

You can then edit this file at your pleasure to customize the appearance of the login screen.

Authentication
FreeRadius is a complex piece of software but (luckily) the features needed for a basic or even common setup are a few, and therefore also the configuration is fairly straightforward.

The first file to look into is. You need to have something like this into it:

There should already be a client 127.0.0.1 section uncommented, so you may just need to edit that one. If you're not connecting from localhost you can vary the IP address accordingly, or even specify a class: the comments in the file explain everything.

The next file to edit is. It is already preconfigured for MySQL, but you can change it to work with Postgres, Oracle or MS-SQL. The other options are fairly intuitive, in the sense that you only have to specify the login data for the MySQL server and database. You can leave the remaining settings alone. In my example I have:

Difficult, huh?

The last file which requires some modification is. Browse the file, look for the sql directive in the authorize section, and uncomment it: this is needed in order to have FreeRadius use the SQL module for authentication.

Be sure to restart FreeRadius after these changes

Accounting
FreeRadius comes already preconfigured for accounting, and it stores that information in files under the directory. However. you might want to configure it to use MySQL instead of files for accounting also. To accomplish this task look for the accounting section in. It should be configured like this:

(I stripped all the commented out stuff)

I only made two changes:


 * I added the sql option, which causes FreeRadius to store accounting information on the table radacct of the SQL database it uses.
 * I removed the detail option, so that it doesn't log that information on files anymore. You can leave this where it is if you want both logs.

MySQL configuration
FreeRadius requires a MySQL database with a predefinied structure where to look for user/password pairs and (if desired) store accounting information. Log into the MySQL client with root privildges and launch the following commands, or a variation of them which suits your needs:

Then import the SQL schema:

cat /usr/share/doc/freeradius-(YOUR-VERSION)/examples/mysql.sql | mysql -D radius -u freeradius -p radius

Enter the password for your database and press enter.

As you will see, this creates several tables. You probably just need to use one of those: radcheck. This table has the following structure:

+---+--+--+-+-++ +---+--+--+-+-++ +---+--+--+-+-++
 * Field    | Type             | Null | Key | Default | Extra          |
 * id       | int(11) unsigned |      | PRI | NULL    | auto_increment |
 * UserName | varchar(64)      |      | MUL |         |                |
 * Attribute | varchar(32)     |      |     |         |                |
 * op       | varchar(2)       |      |     | ==      |                |
 * Value    | varchar(253)     |      |     |         |                |

The id is auto-incremented and op defaults to the correct value, so you just need to enter the other fields in this fashion:

That should be enough. You can then use whatever client or interface you want to populate the users database.

Tips

 * Launch Chillispot using to see what's happening while it works.

Other resources

 * 1) Chillispot web site, here you can find useful FAQs and a discussion forum.
 * 2) FreeRadius home page.
 * 3) SQL Howto in FreeRadius wiki.
 * 4) A very useful tutorial on using FreeRadius and MySQL together. (outdated, redirects to #3)
 * 5) First thread on Chillispot/Freeradius in the forums.
 * 6) Some free contrib scripts which can help with authentication, logging, ...

Authors
This document is written and maintained by Michele Beltrame. If you want to contact me I'm LordArthas on Gentoo Forums, you can just send a PM to me.

Minor edits by Alex James, anjames (Gentoo forums) regarding mysql setup and master card config.