ChilliSpot Logo


  Home Features Release Notes FAQ man chilli Forum Download  

FAQ

 

General

Who maintains ChilliSpot?

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@www.chillispot.org.

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

What does ChilliSpot provide?

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:
If any of the above documents does not answer your question, you might be able to find your answer by browsing the ChilliSpot forum.

Who uses ChilliSpot?

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

What is the performance of ChilliSpot

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

Is support available for ChilliSpot

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.

I think I have found a bug in ChilliSpot. Where can I report it?

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

Usage

What should I tell my users?

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.

How can a user log off from the network?

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.

Why should I use User-Password?

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.

Why should I use CHAP-Challenge and CHAP-Password?

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.

What is a dictionary attack?

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

Installation

Which operating systems are supported?

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

Which versions of Linux are supported?

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.

Which versions of FreeBSD are supported?

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

Where can I download ChilliSpot?

http://www.chillispot.org

How do I install ChilliSpot under RedHat?

Issue the command:

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

How do I install ChilliSpot under Fedora?

Issue the command:

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

How do I install ChilliSpot under Debian?

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

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

How do I install ChilliSpot under Gentoo?

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

How do I Install ChilliSpot under OpenWRT?

ChilliSpot is installed under OpenWRT by issuing the commands:
wget http://www.chillispot.org/download/chillispot_1.0RC3-1_mipsel.ipk
ipkg install chillispot_1.0RC3-1_mipsel.ipk

How do I compile and install ChilliSpot from source?

Please see the release notes for further details.

Do I need to use NAT?

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.

Do I need to use a firewall?

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

Do you have a sample chilli.conf file for a setup with everything installed on the same machine?

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

Do you have a sample chilli.conf file for a setup using and external radius server?

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

Do you have a sample chilli.conf file for a setup using and external radius and web server?

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

Troubleshooting

Redirection does not work!

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

The wireless client did not receive a DHCP IP address!

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:

DNS on the wireless client does not work!

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

DHCP and DNS is working, but redirection does not!

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

Configuration

How do I use uamhomepage?

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.

How do I redirect users to something else than the homepage?

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.

How does keywords work?

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.www.chillispot.org.
  2. When the user types "exit" in the location bar the browser automatically looks up exit.key.www.chillispot.org.
  3. The web server at exit.key.www.chillispot.org redirects the browser to http://192.168.182.1:3990/logout
  4. When requested at http://192.168.182.1:3990/logout 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.

Working Keywords:

  • exit / logout: Logs you out from the hotspot.
  • splash: Redirects the browser to the splash page.

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

    domain key.www.chillispot.org

    What if a hotspot location has more than 256 users?

    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.

    How do I allow users to browse some web sites without first authenticating?

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

    uamallowed www.chillispot.org,10.11.12.0/24

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

    How do I allow users to connect to a VPN server without first authenticating?

    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.

    How do I enable VPN pass-through?

    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.

    How do I enable MAC authentication?

    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

    How do I enable static IP?

    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.

    How do I display an error message to the user?

    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.

    How do I make a "disclaimer page"

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

    How do I enable unauthenticated users to ping the gateway?

    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.

    How do I enable "Any-DNS"?

    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.

    How do I enable "Any-SMTP"?

    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.

    How do I enable "Any-IP"?

    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

    What is Radius?

    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.

    Why does ChilliSpot use Radius?

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

    Which Radius server should I choose?

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

    How do I authenticate users against an LDAP, MySQL, PostGreSQL, Oracle, Kerberos or PAM server?

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

    How do I authenticate users against a Unix password file or an SMB password file?

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

    What is Radius Accounting?

    For accounting purposes ChilliSpot generates accounting records which are forwarded to the radius server. The following types of accounting records are generated:
    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.

    I have noticed that ChilliSpot is not sending alive packages to the Radius server while user is logged in

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

    Who do I enable Simultaneous-Use

    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.

    Development

    What is the architecture of ChilliSpot?

    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:

    How can I help?

    How do I contribute a bug fix?

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

    How do I contribute a new module, larger patch or feature to ChilliSpot?

    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.

    License

    What kind of licenses exist for ChilliSpot?

    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

    Why did you decide to use GPL for ChilliSpot?

    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.