From Gentoo Linux Wiki

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 web site[1] 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.0
• FreeRadius 1.0.x
• Apache 2.x
• MySQL 4.1.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 presumes you have an x86 machine. AFAIK (I tried) this is not going to work on AMD64, because both ChilliSpot and FreeRadius have bugs which prevent them to work as they should. I don't know the status of these softwares on other platforms.

Kernel configuration

Chillispot create 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:

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.

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,

• 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.

echo config_eth1=(\"0.0.0.0\") >> /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:

• 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 tutorial 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

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

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 /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:

radiusserver1 127.0.0.1
radiusserver2 127.0.0.1
radiussecret theradiussecret
dns1 192.168.1.73
dhcpif eth0
uamallowed 192.168.182.1,192.168.1.73,www.google.it
uamserver https://192.168.1.73/cgi-bin/hotspotlogin.cgi
uamhomepage https://192.168.1.73/
uamsecret theuamsecret

Let's discuss the file in detail.

Radius section

radiusserver1 127.0.0.1
radiusserver2 127.0.0.1
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 se the radius configuration part later on.

Networking section

dns1 192.168.1.73

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

uamallowed 192.168.182.1,192.168.1.73,www.google.it

The above line states which hosts the clients are allowed to connect 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.

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

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.

uamhomepage https://192.168.1.73/

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).

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 http://192.168.1.73/, 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="http://192.168.182.1:3990/prelogin">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:

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

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

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

client 127.0.0.1 {
 secret     = theradiussecret
 shortname  = localhost
 nastype    = other
}

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 /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

Accounting

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 {
    unix
    radutmp
    sql
}

(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:

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

Then import the SQL schema:

zcat /usr/share/doc/freeradius-1.05/sql.schemas/db_mysql.sql.gz | mysql -u freeradius -p mysuperpassword radius

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');

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

Tips

• Launch Chillispot using chilli --debug --fg to see what's happening while it works.

Other resources

1. http://www.chillispot.org/ - Chillispot web site, here you can find useful FAQs and a discussion forum.
2. http://www.freeradius.org/ - FreeRadius home page
3. http://www.frontios.com/freeradius.html - A very useful tutorial on using FreeRadius and MySQL together

Author

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. ;-)