chillispot FAQ

My name is Jens Jakobsen, and I am the current maintainer of ChilliSpot. I also wrote the original code, but many people have contributed with features and bug fixes. You can contact me by email at jj@chillispot.org.

Stefan Lengacher lemy@chillispot.org maintains the ChilliSpot forum at www.chillispot.info/chilliforum.

ChilliSpot provides the following 2 components:

chilli
User space application working as a captive portal. Handles ARP and DHCP requests from wireless clients, radius requests from access points as well as redirects http requests from unauthorized users.

hotspotlogin.cgi
A perl script which queries users for username and password. Once the password has been received it is encrypted and sent back to chilli.

hotspotlogin.cgi should be seen as the reference implementation. On the forum you will find many variants of this script. Implementations exist in php, asp and even a binary version written in C. These scripts have special features which makes it easier for you to modify the script.

Where is the documentation?

The ChilliSpot documentation is currently covered by 4 documents:

• The chilli man page: Documents the ChilliSpot daemon. It has all the information about the different options available.
• The features document: Describes the features available with ChilliSpot. In particular it describes all the radius attributes available.
• The release notes: Information about how to install and configure ChilliSpot under different platforms.
• This FAQ

If any of the above documents does not answer your question, you might be able to find your answer by browsing the ChilliSpot forum.

ChilliSpot is used by companies, universities and private users which wants to control access to their wireless networks.

A not very structured test showed 45 Mb/s on a 550 MHz Athlon.

On the forum pda wrote: “There’s about 30 simultaneous clients at this stage.. no chillispot problems at all. `top` shows chilli to be using around 10% ~ 25% CPU and about 20% MEM on the Linksys WRT54GS.”

On the forum riskable wrote: “I decided to do some basic benchmarks myself …. First of all, my WRT54G is Version 2 (200MHz)…. WITH Chillispot, bridged, LAN->WAN: 870k/sec (~7 megabits) … WITH Chillispot, non-bridged, LAN->WAN: 1MB/sec (8 megabits) … Seems (more than) good enough for a normal hotspot.”

On the ChilliSpot homepage you will find a web forum for general discussions and a mailing list for announcements. You should use the web forum for any support questions.

Please report to the Buglist forum. Remember to include following:

• Version number of ChilliSpot
• Operating system you are using (Linux distribution, kernel version)
• Relevant network traces (tcpdump -s 1500 -w dump)
• File names and line numbers if you know the offending code

General instructions for logging in using the universal access method from a Windows PC are:

1. Change the WLAN network to ChilliSpot (or whatever SSID you configured on the access point).
2. Start the web browser.
3. Enter username and password.
4. If anything goes wrong: Make sure to turn off WLAN web encryption and disable proxy settings in your browser. Restart the PC.

Users are logged off in a number of different ways:

1. Use the logoff button in the pop-up provided when the user logged in.
2. Use the logoff button in the reply page when the user logged in.
3. If the pop-up has been lost the user can return to the logout page by typing “exit” in the location bar.
4. Turn off the PC or leave WLAN coverage. If the DHCP IP address is not renewed ChilliSpot will log off the user.
5. If the radius attribute Session-Timeout is used the user will be logged out when this time has expired.
6. If the radius attribute Idle-Timeout is used the user will be logged out after an inactivity period.
7. If the radius attribute WISPr-Session-Terminate-Time is used the user will be logged off after the specified time.

User-Password is needed when you store the passwords as a hash in the radius server. This is the case when you authenticate against a unix password file, an SMB password file, or any other authentication method which requires the radius server to provide the actual password.

In order to enable User-Password you should uncomment the following lines in the file /var/www/cgi-bin/hotspotlogin.cgi:

$uamsecret = "ht2eb8ej6s4et3rg1ulp";

$userpassword=1;

You should set the secret to something only you know, and pass the same secret to chilli in the file /etc/chilli.conf:

uamsecret ht2eb8ej6s4et3rg1ulp

The uamsecret parameter is used to encrypt the password when it is transferred from the web server to chilli. Note that when using User-Password chilli gets to know the passwords of the users. Any radius proxy servers between chilli and the “home” radius server also get to know the passwords of the users. This might be a problem in certain configurations.

By default chilli uses CHAP-Challenge and CHAP-Password. The advantage is that the actual passwords will only be known to the web server and the “home” radius server. Neither chilli nor any radius proxy servers get to know the actual password.

CHAP-Challenge and CHAP-Password authentication is generally vulnerable to dictionary attacks. To protect against dictionary attacks on the air interface you should uncomment the following line in the file /var/www/cgi-bin/hotspotlogin.cgi:

$uamsecret = "ht2eb8ej6s4et3rg1ulp";

You should set the secret to something only you know, and pass the same secret to chilli in the file /etc/chilli.conf:

uamsecret ht2eb8ej6s4et3rg1ulp

The uamsecret parameter is used to encrypt the challenge and response when it is transferred from the web server to chilli.

In order to not to transfer passwords over the network as clear text a challenge/response protocol is often used. With this protocol the authentication server sends a challenge to the client. Based on the challenge and the password entered by the user the client calculates a response and sends this back to the authentication server. The authentication server performs the same operation as the client and compares the two responses. If the responses match the user is authenticated.

The algorithm used to calculate the response is a one-way-hash function, such as MD5 or SHA1. A property of a one-way-hash function is that it is not possibly to reverse the operation and calculate the password even if the challenge and response is known. The challenge/response method is, however, vulnerable to dictionary attacks.

Assume that the user has chosen a weak password such as “alice”. If an attacker can guess the password of the user he can perform the same one-way-hash function on the guessed password and the challenge. If the calculated response matches the response sent over the network the attacker knows that his guess was correct. On the Internet it is possibly to download a database with the 40 million most commonly used passwords. All the attacker has to do is to try with all 40 million passwords, and he will most likely guess that the users password is “alice”.

ChilliSpot is available for Linux and FreeBSD. It should be relatively easy to port to NetBSD, OpenBSD and Apple OSX.

ChilliSpot is known to run under Debian, Gentoo, RedHat, Fedora, Mandrake and OpenWRT.

In more general terms you need a Linux system with at least kernel version 2.4.7.

This is a practical requirement as ChilliSpot uses the tun driver for the network interfaces. The tun driver is included with the Linux kernel from version 2.4.7 and later. It is however possible to install the tun package on older kernels as well and be able to compile ChilliSpot for these platforms.

ChilliSpot was tested under FreeBSD 5.3, but should work under other versions as well.

http://www.chillispot.info

Issue the command:

rpm -i http://www.chillispot.info/download/chillispot-1.0RC3.i386.rpm

Issue the command:

rpm -i http://www.chillispot.info/download/chillispot-1.0RC3.i386.rpm

Download the latest .deb file from www.chillispot.info. Then issue the command:

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

Gentoo users wishing to fetch, compile and install Chillispot simply need to type:

emerge chillispot

While the package is in the testing stage users will either have to add the proper ~arch keyword to the local /etc/make.conf or export it via an

ACCEPT_KEYWORDS="~x86" emerge chillispot

or

ACCEPT_KEYWORDS="~mips" emerge chillispot

ChilliSpot is installed under OpenWRT by issuing the commands:

wget http://www.chillispot.info/download/chillispot_1.0RC3-1_mipsel.ipk
ipkg install chillispot_1.0RC3-1_mipsel.ipk

• ./configure
• make
• make install

Please see the release notes for further details.

In most cases yes!

The long answer is that you do not need to use NAT if routing has been set up so that other machines on the Internet (or intranet) know how to reach your clients. For this to work you should ask your ISP for a range of public IP addresses. Wireless clients will be allocated these IP addresses by ChilliSpot. Routing tables configured for your particular setup should be set up as well.

No, but it is probably a good idea to protect the server running ChilliSpot from attacks from the wireless users and the Internet.

If ChilliSpot, Web server and Radius server is installed on the same machine you should use the following chilli.conf 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

If ChilliSpot and Web server is installed on the same machine, but radius server installed on IP address 1.2.3.4 you should use the following chilli.conf configuration file:

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

If an external radius server is installed on IP address 1.2.3.4 and an external web server is installed on IP address 5.6.7.8 you should use the following chilli.conf configuration file:

radiusserver1 1.2.3.4
radiusserver2 1.2.3.4
radiussecret testing123
dhcpif eth1
uamserver https://5.6.7.8/cgi-bin/hotspotlogin.cgi

Good question, which can be caused by a number of reasons:

• DHCP is not working: See question below.
• DNS is not working: See question below.
• Both DHCP and DNS is working, but still no redirection occurs: See question below.

The IP address allocated to the client should be in the range 192.168.182.2 to 192.168.182.254. If the client was not given an IP address or were given an IP address outside this range you are most likely not communicating with ChilliSpot at all. Check the following:

• The dhcpif option should match the network interface you connected the access point to (usually eth1).
• The network interface should normally not be configured with an IP address. Take eth1 down by typing /sbin/ifdown eth1.
• No other DHCP server must be running on the network interface (ChilliSpot allocates the IP address).

Verify that DNS is working on your wireless client. You can do this by pinging a known server:

ping www.cisco.com

This should tell you that the client is trying to ping a specific IP address. If not something is wrong with the DNS setup (it is OK if you did not receive a ping reply as you have not yet authenticated).

• Check that DNS is working on the ChilliSpot server.
• Check the values for dns1 and dns2 options.
• Check the iptables script.

If both DHCP and DNS is working, but redirection still does not work it is time to start Ethereal. You should monitor the traffic on the following interfaces: eth0, eth1 and tun0.

When you start the client you should see a DHCP request and reply on eth1. When you start the web browser you should see a DNS request on all interfaces followed by a HTTP request on eth1. The HTTP request should be answered by a HTTP 302 redirect message.

It is also a good idea to run ChilliSpot in debug mode:

chilli --fg --debug

Normally unauthenticated users are forwarded to the URL given by the uamserver option. If you wish to redirect to another web server you can specify the uamhomepage option in /etc/chilli.conf, such as:

uamhomepage http://www.yourpage.com

This URL can display information about the hotspot, advertising or tourist information and should include a link to:

http://192.168.182.1:3990/prelogin

in order to allow the users to log in.

The uamhomepage option can be combined with the uamallowed option which enables the user to browse to a number of predefined web sites without first authenticating.

As standard ChilliSpot redirects users to their configured homepage once they have been successfully authenticated. To force redirect to a different URL you include the Radius attribute WISPr-Redirection-URL in the Access-Accept message.

If the pop-up has been lost the user can return to the logout page by typing “exit” in the location bar. It works the following way:

1. During dhcp the client is given a default domain of key.chillispot.info.
2. When the user types “exit” in the location bar the browser automatically looks up exit.key.chillispot.info.
3. The web server at exit.key.chillispot.info redirects the browser to http://192.168.182.1:3990/prelogin
4. When requested at http://192.168.182.1:3990/prelogin chillispot returns the logout page.

If you change either the domain option or the net option in /etc/chilli.conf you will have to setup a DNS server and a webserver for the keywords feature to work.

Important hotfix: If you have already installed chillispot, please verify that key.chillispot.info is set instead of key.chillispot.org.
You should see this in your config file:

domain key.chillispot.info

Just change the net option in /etc/chilli.conf:

net 192.168.182.0/20

gives you 4093 concurrent users, which should be enough for most hotspots.

You specify the uamallowed option in /etc/chilli.conf:

uamallowed www.chillispot.info,10.11.12.0/24

Will allow to user to browse www.chillispot.info as well as all IP addresses in the 10.11.12.0/24 network segment.

You specify the IP address if the VPN server in /etc/chilli.conf:

uamallowed 10.11.12.13

Will allow to user to connect to a VPN server at 10.11.12.13. See below for NAT functionality as well.

ChilliSpot relies on netfilter to do network address translation. This works well with some VPN protocols, but not very well with others.

Especially the Microsoft point-to-point protocol (PPTP) is known not to work with NAT gateways. In order to enable PPTP to work with iptables you should install the PPTP-CONNTRACK-NAT patch which is available from www.netfilter.org. Once you get NAT to work it should also work for ChilliSpot.

PPTP has been verified to work on Windows XP clients to VPN servers running Windows, Linux and Cisco. Be prepared to spend weeks of troubleshooting to get this to work. If you succeed please report on the forum.

You need to specify the macauth option in /etc/chilli.conf.

When this option is given ChilliSpot will first try to authenticate user based on her MAC address. For this the radius access-request will use the MAC address as username, and “password” as password. If mac authentication fails, the user will be redirected to the normal web login page.

The format of the MAC address is in pure hex, such as:

000a5e3c353a

With both WPA and MAC authentication you can include the Radius attribute Framed-IP-Address in the Access-Accept message sent back to ChilliSpot by the Radius server. For this to work

you also need to specify the statip option in /etc/chilli.conf.

If you specify the Radius attribute Reply-Message in the Access-Reject message sent back to ChilliSpot by the Radius server this message will be displayed to the user.

Normally ChilliSpot expects the user to type in a username and a password. In some cases however you simply what the users to accept a set of legal terms before allowing free browsing.

To achieve this you modify hotspotlogin.cgi to display the disclaimer. The normal username and password fields in hotspotlogin.cgi should be changed to hidden fields with username and password set to something like “guest”, “guest”.

In your radius server you need to create a user with username”guest” and password “guest”.

You include the gateway in the uamallowed option in /etc/chilli.conf:

uamallowed 192.168.182.1

And enable ICMP echo requests in the firewall script:

$IPTABLES -A INPUT -p icmp --icmp-type echo-request -j ACCEPT

With this setup the client will be able to ping the gateway IP address.

Normally the DHCP reply from ChilliSpot will include a set of DNS servers the client should use. Some users however have configured static DNS servers. To enable all DNS servers you should include the uamanydns option in /etc/chilli.conf:

uamanydns

This allows access to all IP addresses on port 53. This obviously can be abused by users for tunneling other types of traffic, so you might want to combine this with destination NAT in the firewall script:

$IPTABLES -t nat -A PREROUTING -s 192.168.182.0/24 -p udp --dport 53 -j DNAT --to 192.168.1.1

In the above example all DNS requests are forwarded to 192.168.1.1, which should be the IP address of a local DNS server. According to some line of thought using a local caching DNS server also speeds up Internet browsing.

Normally e-mail client in the wireless client is configured to use the “home” SMTP server. The home SMTP server will usually reject e-mails from “foreign” IP addresses. To circumvent this problem the firewall can be configured to forward all SMTP requests to a local SMTP server:

$IPTABLES -t nat -A PREROUTING -s 192.168.182.0/24 -p tcp --dport 25 -j DNAT --to 192.168.1.1

In the above example all SMTP requests are forwarded to 192.168.1.1, which should be the IP address of a local SMTP server. This also enables wireless users to send spam through your SMTP server, so you might not want to enable this feature.

The proper setup for the clients is to use their home SMTP server with username and password authentication. To protect user credentials the SMTP connection should use TLS or SSL. Alternatively the wireless users can always use webmail.

ChilliSpot only works with wireless clients which requests a dynamic IP address using DHCP. There is a patch by Alexander available on the forum which will enable the “Any-IP” feature.

Radius is the industry standard for Authentication, Authorization and Accounting most forms of Internet access devices. It is used by virtually all Internet service providers for dial-up modem pools, ADSL, Cable Modem, and for Wireless LAN.  The basic Radius protocol is specified in RFC 2865.

Radius support in ChilliSpot is required on order to be used by most ISPs.

A large number of vendors provide commercial Radius servers. For small installations you can use one of the Open Source Radius servers:

• FreeRADIUS
• OpenRadius
• Cistron
• IC-RADIUS

If you are using FreeRadius it is possible to authenticate against any of the above servers.

If you are using FreeRadius it is possible to authenticate against any of the above file formats.

For accounting purposes ChilliSpot generates accounting records which are forwarded to the radius server. The following types of accounting records are generated:

• Accounting start: A user was successfully authenticated by ChilliSpot.
• Accounting stop: A user logged off.
• Accounting interim: ChilliSpot can be configured to generate alive messages at fixed intervals.

The accounting records contain information such as User-Name, MAC Address, IP Address, number of bytes transferred as well as the number of seconds connected.

If you specify the Interim-Interval radius attribute in the Access-Accept message then interim accounting (alive packages) will be enabled.

FreeRADIUS has a feature called Simultaneous-Use, which limits the number of concurrent logins. It works when using an SQL server as backend. Basicly what happens is that for each Access-Request FreeRADIUS will count the number of active sessions in the accounting tables. If an existing session is already active FreeRADIUS will deny the user access.  To enable this feature you put Simultaneous-Use := 1 in the rad_check table.

It should work out of the box, but FreeRADIUS can sometimes be a bit difficult to configure.

You might want to modify the simul_count_query in /etc/raddb/sql.conf in order not to include accounting records which have the same MAC address. Something like the following:

simul_count_query = "SELECT COUNT(*) FROM ${acct_table1} WHERE UserName='%{SQL-User-Name}' AND AcctStopTime = 0" AND 'Calling-Station-Id<>%{Calling-Station-Id}'

Also you might also want to not include really old accounting records.

The primary platform for ChilliSpot is Linux and FreeBSD, but it should also be possible to port the software on other posix compliant platforms: OpenBSD, NetBSD Solaris and even Apple OSX.

The main design goals of ChilliSpot were stability, portability and scalability. This resulted in the following design choices:

• Programmed in (ANSI) C in order to improve portability to other platforms.
• Concurrency is implemented using a single select() loop in order to improve portability and at the same time achieve high throughput. A client process is created whenever a http authentication request from a client is received.
• Application was developed in user space only. Provides good portability at the cost of performance. Performance can be increased by implementing user plane handling in kernel space.
• Conservative handling of memory allocation and error checking. Helps improve stability, but should be optimized for performance at a later stage.

• Report bugs
• Port ChilliSpot to NetBSD, OpenBSD, Solaris and OS X.
• Propose new features
• Develop a new feature

If you found a bug in ChilliSpot, and you managed to correct the bug yourself and would like to contribute the bug fix to the ChilliSpot project you should do the following:

• Make a diff between the original version of ChilliSpot and your corrected version

  diff -aur chillispot.old chillispot.new > mychillispot.patch

• Send the patch to support@chillispot.org. In the mail you should state that you made the patch yourself and would like to contribute it to ChilliSpot. If your patch includes code from other projects you should include references to those projects.
• We will review your patch and most likely incorporate your changes in the code.

The above method applies to smaller patches affecting around 20 lines of code or less. If you would like to contribute a larger feature to ChilliSpot see below.

For larger contributions we ask you to sign a “joint copyright assignment form”. Your code will then be incorporated in ChilliSpot and released under the GNU General Public License (GPL). Before you start development it might be a good idea to discuss the feature with us in order to make sure that nobody else is working on this particular feature.

ChilliSpot is covered by the GNU General Public License (GPL) version 2. To cover the GNU GPL requirements, the basic rule is that if you give out any binaries, you must also make the source available. For the full details, be sure to read the text of the GNU GPL which is distributed with the software and also available at http://www.gnu.org/copyleft/gpl.html

We would like people to use and improve on ChilliSpot to the benefit of everybody. The advantage of the GPL over other open source licenses is that future developments of ChilliSpot by the community remains free.