Wireless Hacks

Hack 90 NoCatSplash and Cheshire

If you need a simple "splash screen" for your wireless users, try either of these simple captive portals.

Some people find that Perl is too heavy of a requirement for their gateway hardware, making it impractical to use NoCatAuth. If you are only looking for a "click here to continue" sort of splash page (without the full authentication mechanism), you may be interested in NoCatSplash. It is a port of NoCatAuth entirely rewritten in C. Its requirements are quite small, but it supports only simple open mode portal functionality. The current version works under Linux, and portability to BSD and other systems is planned for the near future.

To install NoCatSplash, download the current CVS tree or just grab the archive available at http://nocat.net/download/NoCatSplash/. Unpack the archive, navigate to NoCatSplash-nightly/, and install it with a simple:

rob@florian:~/NoCatSplash-nightly$ ./configure; make; make install

This installs splashd to /usr/local/sbin/, and puts the nocat.conf configuration file in /usr/local/etc/. Edit the nocat.conf file to your tastes, taking note to set the ExternalDevice, InternalDevice, LocalNetwork, and DNSAddr options to fit your network layout. See the comments in the configuration file for details.

Start the portal by running splashd as root:

root@florian:~# /usr/local/sbin/splashd &

NoCatSplash uses the same firewall scripts as NoCatAuth to do the actual firewall manipulation. It installs these scripts to /usr/local/libexec/nocat/, making it simple to customize your firewall rules if you need to. With splashd running, any users whose traffic originates on InternalDevice will be captured and shown the splash page defined in nocat.conf. The default html files for the splash page are kept in /usr/local/share/nocat/htdocs/, but can be kept wherever you like by setting the DocumentRoot in nocat.conf.

Another possible alternative to NoCatAuth is Cheshire, a captive portal written completely in shell script. It is available at http://nocat.net/download/cheshire/. The goal of Cheshire is to provide the smallest possible captive portal, suitable for use with very tiny Linux installations. Without decent networking functions of its own, Cheshire needs a couple of helper apps to do the dirty work of actual networking. Notably, it needs the getpeername utility from NetPipes (http://freshmeat.net/projects/netpipes/). It also needs the faucet utility from the same package, or it can use the system's inetd if you have one installed.

Apart from this, standard system tools such as sed, awk, and cron are all you need. Cheshire works fine under the very lightweight ash shell. If you want to serve graphics on your splash page, and your gateway has a slow CPU, you will probably be happiest with a "real" web server rather than using Cheshire itself. I find that khttpd (the Kernel space http server available in Linux 2.4) works very well for this job, and is very tiny.

To install Cheshire, extract the archive into /usr/local/cheshire/. Edit the cheshire.conf file in this directory to your liking, and launch the script using faucet like this:

root@gateway:~# faucet 5280 --in --out --daemon /usr/local/cheshire/bin/grin

If you would rather not use faucet, you can run Cheshire out of your inetd. Add the port as a service in /etc/services by appending a line like this:

cheshire                5280/tcp

Add Cheshire itself to your /etc/inetd.conf with this line:

cheshire  stream  tcp  nowait  root  /usr/local/cheshire/bin/grin

Finally, you will probably want to boot your users out ever so often, to force them to see the splash page again. Use the system cron to accomplish this. I run it once a day at 4:00 in the morning. Put a line like this in the crontab for root:

0 4 * * *       /usr/local/cheshire/bin/grin -R

While Cheshire and NoCatSplash might not be as feature rich as NoCatAuth, their requirements are very simple. They can be ideal for situations where you simply want to give people an idea of whose network they are using, especially if the capabilities of your wireless gateway are limited.