Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



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 websiteto see how the software works. In a few words, Chillispot creates a virtual private network (, 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.


The following software is required for this installation:

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.


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 softwares 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  --->
  <M>   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

We are assuming 2 network interfaces,

echo config_eth1=(\"\") >> /etc/conf.d/net
ln -s /etc/init.d/net.lo /etc/init.d/net.eth1
/etc/init.d/net.eth1 start
rc-update add net.eth1 default

You should also need to enable IP packet forwarding.

echo 1 > /proc/sys/net/ipv4/ip_forward

Add this to /etc/sysctl.conf so it will enable IP forward at startup.

nano /etc/sysctl.conf
Add/Uncomment the following lines:
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:

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 /etc/make.conf.


Chillispot is masked, so edit your /etc/portage/package.keywords and add this line:

net-wireless/chillispot ~x86

Installing is as simple as this:

emerge -av chillispot


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 /etc/portage/package.use:

net-dialup/freeradius mysql

You can then emerge as usual:

emerge -av freeradius

Chillispot configuration

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

radiussecret theradiussecret
dhcpif eth1
uamsecret theuamsecret

Let's discuss the file in detail.

Radius section

radiussecret theradiussecret

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.

radiussecret theradiussecret

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.

dhcpif eth1

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.

uamsecret theuamsecret

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 Internet Explorer 7, 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:

if (!($ENV{HTTPS} =~ /^on$/)) {
  # [ a lot of code... ]

Here you can find an hotspotlogin.cgi 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 /etc/conf.d/apache and restart the server.

At this point there are several options. What I did was to setup a virtual host bound to, which is also the content of uamhomepage variable in /etc/chilli.conf. 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:

<a href="">Click here to login</a>

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

(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")

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

# cp /usr/share/doc/chillispot-1.0/hotspotlogin.cgi.gz /path/to/you/cgi-bin
# gunzip /path/to/you/cgi-bin/hotspotlogin.cgi.gz
# chmod 755 hotspotlogin.cgi

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

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

 $uamsecret = 'theuamsecret';

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

FreeRadius configuration


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 /etc/raddb/clients.conf. You need to have something like this into it:

client {
 secret     = theradiussecret
 shortname  = localhost
 nastype    = other

There should already be a client 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 /etc/raddb/sql.conf. 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:

# Connect info
server = "localhost"
login = "freeradius"
password = "mysuperpassword"
# Database table configuration
radius_db = "radius"

Difficult, huh?

The last file which requires some modification is /etc/raddb/radiusd.conf. 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


FreeRadius comes already preconfigured for accounting, and it stores that information in files under the /var/log/radius/radacct 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 /etc/raddb/radiusd.conf. It should be configured like this:

accounting {

(I stripped all the commented out stuff)

I only made two changes:

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:

> GRANT ALL PRIVILEGES ON radius.* to 'freeradius'@'localhost' IDENTIFIED BY 'mysuperpassword';

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:

> INSERT INTO radcheck (UserName, Attribute, Value) VALUES ('aika', 'Password', 'myaikapassword');
> INSERT INTO radcheck (UserName, Attribute, Value) VALUES ('aika', 'Auth-Type', 'Local');

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


Other resources

  1. - Chillispot web site, here you can find useful FAQs and a discussion forum.
  2. - FreeRadius home page
  3. - A very useful tutorial on using FreeRadius and MySQL together
  4. - First thread on Chillispot/Freeradius in the forums

Note: If setting up a radius server seems too complicated for you, you can have a look at the WorldSpot advanced hotspot management system, which is compatible with chillispot. It is free for free hotspots, and you just need a linux compatible router to make it work (like dd-wrt or openwrt). Or you go for a complete solution with HotSpot Systems which offers easy installation and a built-in revenue stream (commission based).


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.

Any authors who modify this may add their name if they wish, so we know who we are. ;-)

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

Retrieved from ""

Last modified: Tue, 19 Aug 2008 20:42:00 +0000 Hits: 51,738