I wrote this howto on setting up a hotspot system on ubuntu with user authentication about a year ago, but the site that hosted it seems to have gone down.

Here’s the original link:

And here’s the text as stolen from google cache (please excuse the horrible formatting):


The goal is to setup a gateway that will force users to login (via a captive portal web-page). Once setup the machine will have 2 network interfaces (we will use eth0 and eth1 in this example). One interface is connected to the internet (eth0) the other is an internal interface through which we connect our other machines (eth1) this could be a ethernet port with a switch to which we attach a number of other machines or wireless Access Points (layer 2 transparent bridges), or it could be a wireless interface, automatically turning the gateway i nto an access point.

The proccess
Chillispot takes control of the internal interface (eth1) using a vtun kernel module to bring up a virtual interface (tun0). In fact thr vtun kernel module is used to move IP packets from the kernel to user mode, in such a way that chillispot can function without any non-standard kernel modules. Chillispot then sets up a DHCP server (this can be disabled from the chillispot conf file) on the tun0 interface.

A client connecting to this interface has all packets rejected until it is authorized though the chillispot login page (acting as a supplicant for authentication). When a non-authenticated client tries to connect to a web-page (on port 80 or 443) the request is intercepted by chilli and redirected to a perl-script called hotspotlogin.cgi (served by apache over https).

hotspotlogin.cgi serves a page to the end-user with a username and password field. These authentication data are then forwarded to the freeradius server, which matches them with information in it’s backend (using either PAP or CHAP). The backend in this case is mysql, but could be any number of services such as LDAP, Kerberos, unix passwd files or even Active Directory (probably).

A user is then either rejected or authenticated by freeradius, prompting hotspotlogin.cgi to present either a rejection message or a page with a success message and a logout link to the user.

Hardware Requirements
Any PC with 2 network interfaces should work.

Software Installation
For this howto we start with an installation of Ubuntu Linux. We’ve used the Hoary release of ubuntu, but this should work equally well with other versions of ubuntu, and with other Gnu/Linux distributions such as Fedora Core, Mandriva etc.

This has been tested with both server and desktop installs of ubuntu. The base installation is beyond the scope of this document, but the Ubuntu Website has plenty of documentation on installing ubuntu from scratch.

Once ubuntu is installed, we need to install som extra packages that are not installed by default. If you do not know how to install software under ubuntu read this before proceeding, or if you’re familiar with the linux command-line read the manpage for the apt-get command. This is a Howto on adding the Universe repository to your ubuntu installation, which is required for some of the packages that need to be installed.

You need to install the following extra packages (and their dependencies) via synaptic or the apt-get command before proceeding. some of these may not be necessary, or may be installed already by default. Please update this page if you have further information.:

* mysql-server
* apache2
* freeradius
* freeradius-mysql

Finally you need to get the [ http://chillispot.org/download.html chillispot package] (which is not in the ubuntu repositories) from the Chillispot webpage.

Once you have downloaded that file, open a terminal, go to the directory it was downloaded to and type:

$ sudo dpkg -i chillispot_1.0RC3-1_i386.deb

This should install the last piece of required software.

Configuring Apache2 for SSL
For security reasons we want to present the login page only via an encrypted (https) onnection, so we need to configure apache2 to serve SSL encrypted pages.

There is a HowTo on configuring apache2 for SSL on the Ubuntu Forums. NOTE! most of the commands in the howto require root privileges and should be preceeded by the sudo command. Please follow the above howto before proceeding.

Finally copy the chillispot cgi script to the default apache2 cgi-bin directory:

$ sudo cp /usr/share/doc/chillispot/hotspotlogin.cgi /usr/lib/cgi-bin/
$ sudo chmod +x /usr/lib/cgi-bin/hotspotlogin.cgi


Most of the following sections were manhandled from the install instrucions in the Release notes instructions for Debian Sarge (and parts of the Fedora Core instructions). All mistakes are MY fault, and not the errors of the original authors 😉

Network and Firewall Setup
We are assuming 2 network interfaces,

* eth0 is connected to the internet and should be configured for this purpose (use ifconfig, /etc/network/interfaces, or the graphical network configuration tool under System->Administration->Networking).
* eth1 is the interface that other computers should connect to. This interface should not be configured, but should be brought up.

$ sudo ifconfig eth1 up

or if it’s been previously configured use:

$ sudo ifconfig up

In order to enable packet forwarding you should change the following line in /etc/network/options:


Then you have to restart networking:

$ sudo /etc/init.d/network restart

In order to enable firewall and NAT you can use the firewall script in “/usr/share/doc/chillispot/firewall.iptables” as a starting point. After you have reviewed the firewall rules you execute the script by issuing the command:

$ sudo sh /usr/share/doc/chillispot/firewall.iptables

The firewall script needs to be executed every time the computer is restarted. One way to make sure this happens is to copy the file to /etc/init.d/

$ sudo cp /usr/share/doc/chillispot/firewall.iptables /etc/init.d/chili.iptables
$ sudo chmod u+x /etc/init.d/chilli.iptables
$ ln -s /etc/init.d/chilli.iptables /etc/rcS.d/S40chilli.iptables

Configuring the chillispot conf file

You need to tell Chilli about the location of the authentication server (which in this scenario is on the same machine as chillispot). This is done by uncommenting and editing the following line in “/etc/chilli.conf”:

uamserver is the default IP address that chillispot gives the tun0 interface. For added password security, we need to add a shared secret between the hotspotlogin.cgi and chilli. Find the line in “/etc/chilli.conf” that reads

#uamsecret ht2eb8ej6s4et3rg1ulp

Uncomment this line (remove the #) and CHANGE the secret to something equally weird but different. Remember the secret as it needs to also go into the hotspotlogin.cgi script (we will do this later).
Since we are also running the radius server (freeradius) on the same machine, we need to find and edit the lines that point to the radius server in “/etc/chilli.conf”. They should read:


You should also change the line in “/etc/chilli.conf” that starts radiussecret, so that it does not use the default secret to encrypt traffic between chilli and radius.

radiussecret somethingReallyDifficultToGuess

Remember this secret, as it needs to be added to the freeradius configuration files as well.

Configuring freeradius
The freeradius configuration files are all in the /etc/freeradius/ directory. To start with, and for testing purposes, we will use the “/etc/freeradius/users” text file, to enable a single test user (steve). Later we can change the configuration to use mysql for storing usernames and passwords, but first we want to make sure that the whole thing works in the simplest possible setup.

Edit “/etc/freeradius/clients.conf”.
Find the section that contains the line

client {

make sure it is uncommented, and then, in the section between the { and the following }, change the following lines:

secret = testing123

change testing123 to match the radiussecret you chose for “/etc/chilli.conf” (somethingReallyDifficultToGuess)

Edit “/etc/freeradius/users”
Uncomment the following line in the file

#steve Auth-Type := Local, User-Password == “testing”

This will be the test user and password we will use to make sure everything works.

Customizing hotspotlogin script
To improve password security, we need to add the “uamsecret” from “/etc/chilli.conf” to the hotspotlogin script. Edit “/usr/lib/cgi-bin/hotspotlogin.cgi”.
Find the line that reads:

#$uamsecret = “ht2eb8ej6s4et3rg1ulp”;

Uncomment this line and edit the secret to match the one in “/etc/chilli.conf” (The uamsecret, NOT the radiussecret).

Also uncomment the line that reads:


Now, just to be sure all these changes have taken effec, restart apache2, freeradius and chilli

$ /etc/init.d/apache2 force-reload
$ /etc/init.d/freeradius restart
$ /etc/init.d/chilli restart

Using chillispot
You should now have a simple authentication server that allows a computer to log in and gain access to the network. Plug a computer into the eth1 interface on the chillispot machine, either via a switch or hub, or using a crossover utp cable (or by plugging a transparent bridge wireless access point into the eth1 interface). We will call this machine the “client” machine.

On the client machine, bring up the network interface with DHCP. Chillispot should give you an ip address in the network.

Open your browser, and try to go to any webpage like google.com

You should be redirected to a login page with a field for username and password. Log in using “steve” and “testing”, and you should get a message that says you have successfully logged in. You should now have full access to the internet until you click the logout link in the chillispot webpage.

12 thoughts on “Chillispot Howto

  1. what happened to chillispot.org? it seems to redirect to a web hosts page. where else can one get the chilli packages?

  2. chillispot.info is up, however it seems that the forums were lost…as in all the example configs and everything else…sigh.

  3. thank’s for great article, but where is the myslq tutorial, this tutorial is not complete as its title

  4. I never got around to completing the tutorial with the mysql stuff. It’s pretty complicated, but if there’s an interest, i’ll try and setup the hardware again, and see if i can’t finish it some day soon.

  5. Hi, I have been trying for the past week or so to get chillispot working but have come stuck at the point where you propergate database with tables created by the maker’s of freeradius.

    Suppose to run the comand:
    zcat /usr/share/doc/freeradius/examples/mysql.sql.gz | mysql -u root -p radius

    Each time I try it it say the .gz file does not exist. Which is true and I have so far been unable to find it.

    Using ubuntu 9.04 Sever and stuck

    Pleaaaase help!!

  6. I found the file in the old repos from Ubuntu server 8.04. Download the source files for freeradius ( any version before 2 should have it ) and it would be in there.

  7. > Chillispot then sets up a DHCP server (this can be disabled from the chillispot conf file) on the tun0 interface.

    How to disable the DHCP server provided by chillispot ?

Leave a Reply