ChilliSpot

ChilliSpot 0.97 Release Notes

These release notes describe system requirements, installation instructions, and known issues for ChilliSpot 0.97. These release notes are updated when we receive feedback, so please check back for new information.


What's new in ChilliSpot 0.97

Free Radius Hosting

ChilliSpot radius hosting is now available. The service is a limited functionality of the commercial HotRadius service by Mondru AB, and can be used for home hotspots and for testing of ChilliSpot. Hosting is free for non-commercial use. Check it out at http://radius.chillispot.org. Please support ChilliSpot development by using HotRadius for your commercial hotspot.

Improved hotspotlogin.cgi

Radius attributes

What's new in ChilliSpot 0.96

New configuration options

Source code review, bug fixes and additional logging.

The limitation in version 0.95 which limited the number of concurrent clients has been removed and the code has been optimized for large hotspots. Thanks to Alexander Papadakis for reviewing the code.

Additional logging has been introduced. Thanks to Vladimir Vuksan.

What's new in ChilliSpot 0.95

Browsing some web sites without authenticating

A new "uamallowed" configuration option is included in this release. It allows the user to communicate with a specified list of domain names, IP addresses or network segments without first authenticating. The new option can be used for several purposes:
Thanks to Dan Strohschein.

Improved makefiles

Changes to makefiles and some of the source code has been modified in order to improve the install experience on Gentoo.

Thanks to Ned Lud.

More information to perl cgi script

More information is transferred to the perl cgi script. Upon successful authentication the perl script will now be provided with the following additional information:
Note that the "userurl" cgi parameter is set to the first URL the client tries to connect to. Some browsers connect to multiple URLs at the same time. This might result in unexpected browser compatibility problems.

Configuration of network interface

ChilliSpot will now bring up the network interface if it has not already been configured.

What's new in ChilliSpot 0.94

What's new in ChilliSpot 0.93

What's new in ChilliSpot 0.92

What's new in ChilliSpot 0.91

What's new in ChilliSpot 0.90

New Additions to the Release Notes

Introduction

ChilliSpot is used as an access point controller in a wireless LAN. A typical network architecture is shown in the figure below. A wireless client can establish a wireless connection to an access point, but in to reach the External Network it first has to authenticate with Chilli.


Architecture

Three different networks are involved in the architecture:
In order to function properly Chilli is dependent on a few external servers:
Generally the access points should be configured with open authentication and no encryption. Authentication is handled by Chilli. For better security the access points should be configured for Wireless Protected Access.

Installing on RedHat 9, Fedora 1 or Fedora 2

Requirements

Before you start

Before you start installing ChilliSpot you will need the following hardware and software:
You also need to determine the layout of your network. Use the figure shown in the introduction as a starting point. For the wireless network and internal network you can use the IP addresses given in the introduction.

The IP addresses of the external network is normally determined by an existing configuration, so you need to find the IP address as well as netmask for this network. Furthermore a gateway IP address is normally required. If you are using dynamic IP address you do not need to configure the IP address and gateway information.

Installing Redhat or Fedora

Redhat or Fedora is installed as described in the documentation provided with the distribution. In this sections the parts of the installation which requires special attention is further described.

During the installation you will be asked a to select a number of options.

Under "Installation Type" choose "Server"

Under "Network Configuration" configure the interfaces as appropiate.
You need to manually set the hostname of the server. In this example we use "chilli".

If you use DHCP for the external interface you do normally not have to configure anything under "Miscellaneous Settings". If you use static IP you will need to fill in "Gateway" as well as "Primary DNS". You may optionally fill in "Secondary DNS" and "Tertiary DNS".

Under "Firewall Configuration" choose "Enable Firewall" (Redhat 9: Security level "Medium"). We will customize the firewall rules later during the installation, so for now you can leave the other firewall options as they are.

Under "Package Group Selection" select the following packages:
For for RedHat 9 you need to download and compile freeradius manually from www.freeradius.org. No other packages are needed by Chilli. The above installation requires approximately 850 MB of hard disk space. You might also want to install a graphical user interface or other packages. This however is not required by Chilli.

After you install Linux the system will reboot. Log in as root, and you are ready to install the rest of the software.

Installing and Configuring ChilliSpot

ChilliSpot is installed by issuing the commands:
rpm -i http://www.chillispot.org/download/chillispot-0.97.i386.rpm

During installation of ChilliSpot a configuration file was copied to /etc/chilli.conf. You need to edit this file. A description of each option is given in the man page (man chilli).

As a start you can leave most of the parameters as they are. If you use an external radius server you need to modify the parameters:
If you are not using an external radius server you can leave these parameters as they are, as we will install a radius server later during the installation.

If you use an external UAM server you need to modify this parameter:
If you are not using an external UAM server you can leave this parameters as it is, as we will install an UAM server later during the installation.

In order to automate startup of chilli issue the command:

chkconfig chilli on

ChilliSpot will start next time you reboot the system, or you can start it directly by issuing the command

/etc/init.d/chilli start

Firewall Setup

It is important to protect ChilliSpot from unauthorized traffic. No single firewall ruleset can satisfy all network configurations, and generally you should write your own set of rules. As a starting point you can use the script located in:

/usr/share/doc/chillispot-0.97/firewall.iptables

You can edit this file to suit your own configuration or simply use it without modification. Once you have edited the file install it by issuing the following commands:

/etc/init.d/iptables stop
/usr/share/doc/chillispot-0.97/firewall.iptables
/etc/init.d/iptables save

This will first clear the current firewall rules, install the new rules and finally save the rules so that they will be restored whenever the system is rebooted.
 
In order for ChilliSpot to forward network packets, IP forwarding must be turned on in the kernel. You need to change the line which reads net.ipv4.ip_forward = 0 in /etc/sysctl.conf to the following:

net.ipv4.ip_forward = 1

The changes take effect when you reboot the system, or you can activate them directly by issuing the command

/sbin/sysctl -p

If you use an external radius and UAM server this concludes the installation. You should now reboot the system in order to make sure that all the changes you made take effect.

If you are not using an external Radius and/or UAM server you need to install these as described below.

Using ChilliSpot Radius Hosting

If you are using the ChilliSpot Radius Hosting service you first need to sign up at http://radius.chillispot.org. Remember to print out the confirmation page as you will need the information for later. Once you have signed up you should log on to the service and create your first user.

Now it is time to configure the ChilliSpot configuration file in /etc/chilli.conf. You need to set the following parameters:

radiusserver1 rad01.chillispot.org
radiusserver2 rad02.chillispot.org
radiussecret set_to_secret_from_radius.chillispot.org
radiusnasid set_to_nasid_from_radius.chillispot.org
dhcpif eth1
uamserver https://radius.chillispot.org/hotspotlogin

Restart ChilliSpot by issuing the command:

/etc/init.d/chilli restart

You can test your configuration by using a wireless LAN laptop. Associate with the access point, and start a web browser. You should be able to login using the username and password you created above.

Installing and Configuring UAM Authentication Web Server

The web server Apache was installed as part of the Linux installation. We will now configure Apache to request username and password from the wireless clients.

During installation of ChilliSpot a cgi script was placed in /usr/share/doc/chillispot-0.97/hotspotlogin.cgi. You should copy this script to /var/www/cgi-bin/hotspotlogin.cgi on your web server.

In order to automate startup of Apache issue the command:

chkconfig httpd on

Apache will start next time you reboot the system, or you can start it directly by issuing the command

/etc/init.d/httpd start

You need to tell Chilli about the location of the authentication server. This is done by uncommenting and editing the following line in "/etc/chilli.conf":

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

You need to restart chilli in order for the configuration changes to take effect:

/etc/init.d/chilli restart

Installing and Configuring FreeRADIUS

The Radius server FreeRADIUS was installed as part of the Linux installation (For Redhat 9 you need to install FreeRADIUS manually).

We will now configure FreeRADIUS to authenticate the HotSpot users. Read the FreeRADIUS documentation in order to configure the server. As a minimum you will need to add users. This is done by editing the file "/etc/raddb/users". For testing purposes you can uncomment the entry called "steve", or you can use the file "/usr/share/doc/chillispot-0.97/freeradius.users" as a template.

You might also want to edit "/etc/raddb/clients.conf" in order to configure the IP address and shared secret of chilli. The secret configured in "/etc/raddb/clients.conf" must match the radiussecret parameter in "/etc/chilli.conf".

In order to automate startup of FreeRADIUS issue the command:

chkconfig radiusd on

FreeRADIUS will start next time you reboot the system, or you can start it directly by issuing the command:

/etc/init.d/radiusd start

You need to tell Chilli about the location of the radius server. This is done by uncommenting and editing the following line in "/etc/chilli.conf":

radiusserver1 127.0.0.1
radiusserver2 127.0.0.1
radiussecret testing123

You need to restart chilli in order for the configuration changes to take effect:

/etc/init.d/chilli restart

You can test your configuration by using a wireless LAN laptop. Associate with the access point, and start a web browser. You should be able to login using the username "steve" and the password "testing".

If you want to integrate FreeRADIUS with MySQL, PostgreSQL or do something else advanced then www.freeradius.org is the best source of information.

Installing on Debian Sarge 

Requirements

ChilliSpot uses the tun package. You need at least tun version 1.1. With Linux tun is normally included from kernel version 2.4.7. On Debian you might need to manually create the tun device:

mkdir /dev/net
mknod /dev/net/tun c 10 200

To configure automatic loading you might also need to add the following line to /etc/modules.conf:
alias char-major-10-200 tun

Execute depmod -a to update the changes.

Get hold of the latest .deb package from www.chillispot.org.

Installation

Installation is performed by issuing the following command:

dpkg -i chillispot_0.97-1_i386.deb

Network Configuration

For most installations eth0 will be the interface connected to the Internet, and eth1 will be the interface connected to the access points.
In order to enable packet forwarding you should change the following line in /etc/network/options:
ip_forward=yes

Then you have to restart networking:
/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:
sh /usr/share/doc/chillispot-0.97/firewall.iptables

The firewall script needs to be executed every time the computer is restarted.

chilli.conf

If you are using the ChilliSpot Radius Hosting service you first need to sign up at http://radius.chillispot.org. Remember to print out the confirmation page as you will need the information for later. Once you have signed up you should log on to the service and create your first user.

Now it is time to configure the ChilliSpot configuration file in /etc/chilli.conf. You need to set the following parameters:

radiusserver1 rad01.chillispot.org
radiusserver2 rad02.chillispot.org
radiussecret set_to_secret_from_radius.chillispot.org
radiusnasid set_to_nasid_from_radius.chillispot.org
dhcpif eth1
uamserver https://radius.chillispot.org/hotspotlogin

Restart ChilliSpot by issuing the command:

/etc/init.d/chilli restart

You are now able to test your HotSpot. Start your wireless laptop. Once you start your web browser a login screen should appear. You should be able to login with the username and password you created above.

Web server

If you are using your own web server you should follow the instructions under Fedora on how to install hotspotlogin.cgi on the web server.

Radius server

If you are using your own  radius server you should follow the instructions under Fedora on how to install the radius server.

Installing on OpenWRT

The OpenWRT port is still experimental. Please test and report bug fixes. The instructions below is for testing ChilliSpot on the OpenWRT. Not for setting up a production system.

You should be familiar with OpenWRT before attempting to install ChilliSpot. With OpenWRT it is very easy to mis-configure the access point in a way which does not allow further modification.

Before you start

These installation notes assume that you are using OpenWRT on a Linksys WRT54G.

Before you start installing ChilliSpot you will need the following hardware and software:

Installing OpenWRT

Before you continue you really should set the boot_wait parameter. This enables you to install new firmware even if the old firmware was corrupted. Check out http://openwrt.org for details. Setting this parameter is a bit tricky, so the alternative solution is to simply buy another access point when something goes wrong. Old access points with corrupted firmware can always be used as spare parts :-)

Installing OpenWRT on the Linksys WRT54G might or might not void your warranty. Proceed at your own risk.

Connect your PC to LAN port 4 of the access point using a standard Ethernet cable. Assuming your PC is configured to use DHCP you should be allocated an IP address. Start a web browser and go to the access point homepage: 192.168.1.1. Password is "admin". Go to the Administration/Firmware section, and download the OpenWRT firmware.

Wait a while. Then telnet 192.168.1.1, which is the IP address of your OpenWRT installation.

If you have not configured boot_wait yet this is a good time to do it:

nvram set boot_wait=on
nvram commit

The following command is needed to initialize the access point:
firstboot

Now it is time to connect the access point "Internet" port to your Internet connection.

Disconnect power, and turn it on again.

Telnet back into the access point. You should now be able verify your configuration by pinging a connection in the Internet. If you are not able to access the Internet you need to fix this before proceeding.

Installing Tun/Tap

ChilliSpot uses the Tun/Tap driver. To install the driver change to the tmp directory:
cd /tmp/

The driver is installed by issuing the following commands:
wget http://www.wildcatwireless.net/wrt54g/tun-modules_2.4.20-wrt1_mipsel.ipk
ipkg install tun-modules_2.4.20-wrt1_mipsel.ipk

The tun module is loaded by issuing the following command:
insmod tun

The above line should be included in /etc/init.d/S10boot in order to load the module when the  access point is restarted. To edit /etc/init.d/S10boot you first need to remove the symlink, copy the file from rom, and use vi to edit the file:

rm /etc/init.d/S10boot
cp /rom/etc/init.d/S10boot /etc/init.d/S10boot
vi /etc/init.d/S10boot

Configure networking

OpenWRT is born with the following network interfaces:
Assuming that you only want to use ChilliSpot on the wireless interface you should remove eth1 this from the bridge:
nvram set lan_ifnames="vlan0 eth3"
nvram commit
/etc/init.d/S40network restart

Installing ChilliSpot

ChilliSpot is installed by issuing the commands:
wget http://www.chillispot.org/download/chillispot_0.97-1_mipsel.ipk
ipkg install chillispot_0.97-1_mipsel.ipk

If you are using the ChilliSpot Radius Hosting service you first need to sign up at http://radius.chillispot.org. Remember to print out the confirmation page as you will need the information for later. Once you have signed up you should log on to the service and create your first user.

Now it is time to configure the ChilliSpot configuration file in /etc/chilli.conf. You need to set the following parameters:

radiusserver1 rad01.chillispot.org
radiusserver2 rad02.chillispot.org
radiussecret set_to_secret_from_radius.chillispot.org
radiusnasid set_to_nasid_from_radius.chillispot.org
dhcpif eth1
uamserver https://radius.chillispot.org/hotspotlogin

Configure Firewall

Following the network configuration you should now review and modify the firewall rules. You can use the script in /etc/firewall.openwrt as a starting point:

rm /etc/init.d/S45firewall
cp /etc/init.d/firewall.openwrt /etc/init.d/S45firewall
vi /etc/init.d/S45firewall

As default the above firewall rules trust the LAN interface of the OpenWRT. You might want to change that, but be carefull not to configure the firewall so that you lose connectivity.

Final test

You are now ready to test your new installation:
chilli --debug --fg

If everything is working you can include the following line at the bottom of /etc/init.d/S50services in order to start ChilliSpot automatically at reboot:
sleep 5s
/usr/sbin/chilli

To do the final test you should now disconnect power, and turn the access point on again. Your HotSpot should be working once the access point has rebooted.

As mentioned above the OpenWRT port is still experimental. If you are not experienced with OpenWRT you should wait for the port to mature before installing.

Installing from source

Requirements

ChilliSpot uses the tun package. You need at least tun version 1.1. With Linux tun is normally included from kernel version 2.4.7, but you need to make sure that the "/dev/net/tun" device exists and that the tun module is loaded. For more information see the tun homepage.

Get hold of the ChilliSpot source code from www.chillispot.org.

Compilation

  Compilation and installation is performed by issuing the following commands:

tar -zxf chillispot-0.97.tar.gz
cd chillispot-0.97
./configure
make
make install

Network Interface Configuration

For most installations eth0 will be the interface connected to the Internet, and eth1 will be the interface connected to the access points.

NAT

For almost all types of installations you need to enable NAT on the external interface.

DHCP Server

Do not run a DHCP server. Chillispot will take care of IP address allocation.

chilli.conf

If ChilliSpot, Web server and Radius server is installed on the same machine you should use the following configuration file:

radiusserver1 127.0.0.1
radiusserver2 127.0.0.1
radiussecret testing123
dhcpif eth1
uamserver https://192.168.182.1/cgi-bin/hotspotlogin.cgi

Web server

See the instructions under Fedora on how to install hotspotlogin.cgi on the web server.

Radius server

See the instructions under Fedora on how to install the radius server.

Client Configuration

Universal Access Method

With universal access method (UAM) the wireless client is redirected to a login web page. Once a valid username and password is presented the wireless client is allowed to access the external network (Internet or intranet). Using UAM involves the following steps in the client:
After this the client is allowed to access the external network. The wireless client will be logged out by DHCP timeout, or by returning to the login page and issuing a logout.

With UAM the traffic between the wireless client and the access point is transmitted unencrypted. This means that anybody with the right equipment can monitor the communications, and it is also possible to hijack existing connections. For many usage scenarios this lack of security is not an issue, but for other usage scenarios UAM is not suitable.

The general user instructions are:
  1. Change the WLAN SSID to chillispot (or whatever SSID you configured on the access point). 
  2. The PC should connect to the access point automatically (at least if you are using MS Windows).
  3. Start the web browser. When the web browser is started chilli should redirect the user to your authentication web server.
  4. The user should type in his username and password (as configured in the radius server)
  5. The login is confirmed, and the user is free to browse the Internet.
  6. If anything goes wrong: Make sure that WLAN web encryption is turned off, and that the web browser proxy settings are enabled. Restart the PC. 

WPA

Wireless Protected Access (WPA) solves most of the security problems associated with the universal access method. WPA uses the Extensible Authentication Protocol (EAP) which offers a wide range of authentication methods. With WPA it is possible to encrypt the traffic between the wireless client and the access point.

WPA has to be supported by both the client wireless LAN card as well as the operating system. Microsoft provides a WPA package for Windows XP service pack 1.

Customizing ChilliSpot

The installation of ChilliSpot can be customized in a number of areas.

Universal Access Method

The web pages presented when logging in using UAM can be changed by modifying the perl script "/var/www/cgi-bin/hotspotlogin.cgi".

The perl script uses TLS encryption in order to protect username and password. As default Apache uses a self-signed server certificate. This causes the web browser to ask the user if the certificate should be accepted. In order to avoid this a properly signed server certificate needs to be installed. See the Apache documentations for information on how to obtain and install server certificated.

In this configuration we used a webserver installed on ChilliSpot. It is however also possible to use a separate web server. This might be an advantage if a server certificate is to be installed.

Protection against dictionary attacks

When a user has entered his username and password on the authentication web server a CHAP-MD5 response is calculated and send back to chilli. There is no way of calculating the users password from the response, but if a malicious hacker is able to guess the password he can validate the password against the response. This is known as a dictionary attack, and applies when a user uses a weak password (such as the name of her boyfriend). To protect against dictionary attacks ChilliSpot uses a shared secret between the web server and chilli. In hotspotlogin.cgi you should uncomment and edit the line which reads:

$uamsecret = "ht2eb8ej6s4et3rg1ulp";

You should modify this secret to some random string which only you know. The same secret should be inserted in the file /etc/chilli.conf:

uamsecret ht2eb8ej6s4et3rg1ulp

You need to restart chilli in order for the configuration changes to take effect:

/etc/init.d/chilli restart

WPA

In order to enable Wireless Protected Access (WPA) you need to configure your access point for this, and tell it to use chilli as the radius server. Then you need to modify the following parameters in the file /etc/chilli.conf: Also you need to upgrade your client to support WPA and to enable EAP on the radius server.

IP Address Ranges

IP address ranges can also be changed by modifying the configuration file /etc/chilli.conf.

Uninstalling ChilliSpot

ChilliSpot is uninstalled by issuing the command:

rpm -e chillispot

Furthermore the changes made to other parts of the system should be reversed as well (FreeRadius, Apache and the firewall).

Files Created or Used


Directories
/usr/share/doc/chillispot-0.97/ Directory of user documantation, example scripts and configuration files.



Files
/usr/sbin/chilli ChilliSpot executable
/etc/chilli.conf
ChilliSpot configuration file
/etc/rc.d/init.d/chilli
ChilliSpot System V initialization script.
/var/www/cgi-bin/hotspotlogin.cgi Perl cgi script performing universal access method login.



Manual pages
chilli (8)
ChilliSpot manual.

Known Problems

Client cannot log in after chilli is restarted

When chilli is restarted all information about existing client connections is lost. In order to log in again the client must first request a new IP address. This is normally only done automatically after 10 minutes when the current lease has expired. For the user this means that he can not connect to the network unless the computer is restarted, or a new address is requested by DHCP.

Workaround: Do not restart chilli when users are connected, or get the users to manually request a new DHCP address before starting the web browser.

Redirect does not work with Mozilla 1.0

For some reason Mozilla 1.0 does not redirect when asked to by ChilliSpot.

Workaround: This is probably a good excuse to upgrade to the latest version of Mozilla.

Login does not work with some versions of PalmOS

For some reason login does not work with the PalmOS web browser when javascript is enabled.

Workaround: Turn off javascript in the PalmOS browser.

ChilliSpot Daemon fails to start after OpenWRT is rebooted

This is caused by the DNS not working when the ChilliSpot daemon is started.

Workaround: Delay startup of the ChilliSpot daemon by inserting a sleep 5 in /etc/init.d/S50services.




Copyright © 2004 Mondru AB
Last modified October 19, 2004