nodogsplash README

0. The Nodogsplash project

Nodogsplash offers a simple way to open a free hotspot providing restricted access to an internet connection. It is intended for use on wireless access points running OpenWRT (but may also work on other Linux-based devices).

Its functionality is similar to Nocatsplash, but it is derived from the codebase of the Wifi Guard Dog project. Nodogsplash is released under the GNU General Public License.

Nodogsplash: http://kokoro.ucsd.edu/nodogsplash
OpenWRT: http://openwrt.org/
Wifidog: http://dev.wifidog.org/
Nocatsplash: http://nocat.net/
GNU GPL: http://www.gnu.org/copyleft/gpl.html

The following describes how Nodogsplash works, how to get it and run it, and how to customize its behavior for your application.

1. Overview

A simple hotspot controller like Nodogsplash is a solution to this problem: You want to provide controlled and reasonably secure public access to an internet connection; and while you want to require users to give some acknowledgment of the service you are providing, you don't need or want the complexity of user account names and passwords and maintaining a separate database-backed authentication server.

When installed and running, Nodogsplash implements a simple 'authentication' process. First, it detects any user attempting to use your internet connection to visit a website. It captures the request, and instead serves back a 'splash' web page using its own builtin libhttpd-based web server. The splash page provides a link which, when the user clicks on it, opens limited access for them to the internet via your connection, beginning by being redirected to their originally requested website. This access expires after a certain time interval.

Specific features of Nodogsplash are configurable, by editing the configuration file and the splash page. The default installed configuration may be all you need, though.

2. Installing and running nodogsplash

Have a router working with OpenWRT. Nodogsplash has been compiled against a OpenWRT White Russian 0.9 buildroot; it may or may not work on other versions of OpenWRT or on other kinds of Linux-based router firmware.
Make sure your router is basically working before you try to install nodogsplash. In particular, make sure your DHCP daemon is serving addresses on the interface that nodogsplash will manage (typically eth1), and for the following use ssh or telnet access to your router over a different interface.
To install nodogsplash, obtain the latest nodogsplash*.ipk package file from the project website, copy it to /tmp/ on your OpenWRT router, and, in as root on the router, run:
```
ipkg install /tmp/nodogsplash*.ipk
```
If the interface that you want nodogsplash to manage is not eth1, edit /etc/nodogsplash/nodogsplash.conf and set GatewayInterface.
To start nodogsplash, run the following, or just reboot the router:
```
/etc/init.d/S65nodogsplash start
```
To test the installation, connect a client machine to the interface on your router that is managed by nodogsplash (for example, connect to the router's wireless lan) and in a browser on that machine, attempt to visit any website. You should see the nodogsplash splash page instead. Click on the icon; the browser should redirect to the initially requested website.
To see the current status of your nodogsplash process, run:
```
/usr/bin/ndctl status
```
To stop nodogsplash, run:
```
/etc/init.d/S65nodogsplash stop
```
To uninstall nodogsplash, run:
```
ipkg remove nodogsplash
```

3. How nodogsplash works

A wireless router running OpenWRT has two or more interfaces; nodogsplash manages one of them. This will typically be eth1, which is conventionally bridged to both the wireless and wired LAN, or just the wireless LAN if the br0 bridge has been broken.

3.1 Packet filtering

Nodogsplash considers four kinds of packets coming into the router over the managed interface:

Blocked, if the source MAC address of the packet matches one listed in the BlockedMACList in the configuration file. These packets are dropped. (Caveat: this is not a particularly secure mechanism, since MAC addresses are easy to spoof.)
Trusted, if the source MAC address of the packet matches one listed in the TrustedMACList in the configuration file. These packets are accepted and routed to any destination address and port. (Caveat: this is not a particularly secure mechanism, since MAC addresses are easy to spoof.)
Authenticated, if the packet's IP and MAC source address has gone through the nodogsplash authentication process and has not yet expired. These packets are accepted and routed to a limited set of addresses and ports (see FirewallRuleSet authenticated-users in the nodogsplash.conf configuration file).
Unknown. Any other packet. These packets are accepted only to DHCP and DNS ports on the router, and to the DNS port at other addresses. Any other packet is dropped, except that a packet for destination port 80 at any address is redirected to port 2050 on the router, where nodogsplash's builtin web server is listening. This begins the 'authentication' process. The server will serve a splash page back to the source IP address of the packet. The user clicking the appropriate link on the splash page will complete the process, causing future packets from this IP/MAC address to be marked as Authenticated until the inactive or forced timeout is reached, and its packets revert to being Unknown.

Nodogsplash implements these actions by inserting rules in the router's iptables mangle PREROUTING table to mark packets, and by inserting rules in the nat PREROUTING, filter INPUT and filter FORWARD chains which match on those marks. Because it inserts its rules at the beginning of existing chains, nodogsplash should be insensitive to almost any existing firewall configuration.

3.2 Traffic control

Nodogsplash also optionally implements basic traffic control on its managed interface. This feature lets you specify the maximum aggregate upload and download bandwidth that can be taken by clients connected on that interface. This is done with simple rate-limited HTB qdiscs attached to intermediate queue devices; no packet classification or fairness queueing is done.

4. Customizing nodogsplash

The default shipped configuration is intended to be usable and reasonably secure as-is for basic internet sharing applications, but it is customizable.

To change basic nodogsplash settings, edit the configuration file:
```
/etc/nodogsplash/nodogsplash.conf
```
To change the contents of the splash page, edit the splash page file:
```
/etc/nodogsplash/htdocs/splash.html
```
When the splash page is served, the following variables in the page are replaced by their values:
- $gatewayname The value of GatewayName as set in nodogsplash.conf.
- $authtarget A URL which encodes a token and the URL of the user's original web request. When nodogsplash receives a request at this URL, it redirects them to their original web request, and subsequent packets from that user are marked as Authenticated.
- $imagesdir The directory in nodogsplash's web hierarchy where images to be displayed in the splash page must be located.

5. Debugging nodogsplash

To see verbose debugging output from nodogsplash, edit the /etc/init.d/S65nodogsplash file to set the OPTIONS variable to the flags "-s -d 7", restart or reboot, and view messages with logread. The -s flag logs to syslog; the -d 7 flag sets the maximally verbose level for debugging messages (see syslog.h). You don't want to run with these flags routinely, as it will quickly fill the syslog circular buffer, unless you enable remote logging.
Alternatively, you can set the flag -f instead of -s, and restart. This will run nodogsplash in the foreground, logging to stdout. However, if you do this, don't reboot the router; nodogsplash will not start at boot with the -f flag set.
When stopped, nodogsplash deletes its iptables rules, attempting to leave the router's firewall in its original state. If not (for example, after a crash) subsequently starting and stopping nodogsplash should remove its rules. To check to see all the rules in, for example, the filter table chains, run
```
iptables -t filter -L -v
```
For extensive suggestions on debugging iptables, see for example Oskar Andreasson's tutorial.

Email contact: nodogsplash (at) kokoro.ucsd.edu