openNDS/README

0. The Nodogsplash project

Nodogsplash offers a simple way to provide 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 offers 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'
protocol. 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 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.
Nodogsplash also permits specifying the amount of bandwidth provided to users,
if you don't want to grant all of your available upload or download bandwidth.
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. For notes on
  using Nodogsplash with OpenWRT Kamikaze, see_below.
* 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 br0 or eth1), and
  for the following use ssh or telnet access to your router over a different
  interface.
* To install nodogsplash, obtain the nodogsplash*.ipk package you want to
  install 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

  Or, to install the latest version, you can just run:

    ipkg install http://kokoro.ucsd.edu/nodogsplash/latest.ipk

* If the interface that you want nodogsplash to manage is not br0, 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:

    /usr/bin/ndsctl status

* To stop nodogsplash:

    /etc/init.d/S65nodogsplash stop

* To uninstall nodogsplash:

    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 br0, the bridge to both the
wireless and wired LAN; or the wireless lan interface is typically named eth1
if you have broken the br0 bridge to separate the wired and wireless LAN's.

3.1 Packet filtering

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

  1. 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.)
  2. 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.)
  3. 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 and FirewallRuleSet users-to-
     router in the nodogsplash.conf configuration file).
  4. Preauthenticated. Any other packet. These packets are accepted only to the
     DNS port on addresses forwarded through the router, and to ports and
     protocols opened in FirewallRuleSet users-to-router in the
     nodogsplash.conf configuration file. 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 libhttpd-based 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 Preauthenticated.

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 most typical existing firewall
configurations.
Of course, there is the usual tradeoff between security and usability. For
example, not opening ports 25 and 80 in the FirewallRuleSet users-to-router
helps to prevent unauthorized administrative access to your router, but (if you
have an empty TrustedMACList) does this by blocking all ssh and http access to
the router from the managed interface.

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.
Nodogsplash implements this functionality by enabling two intermediate queue
devices (IMQ's), one for upload and one for download, and attaching simple
rate-limited HTB qdiscs to them. Rules are inserted in the router's iptables
mangle PREROUTING and POSTROUTING tables to jump to these IMQ's. The result is
simple but effective tail-drop rate limiting (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:

  o $gatewayname The value of GatewayName as set in nodogsplash.conf.
  o $authtarget A URL which encodes a unique token and the URL of the user's
    original web request. If nodogsplash receives a request at this URL, it
    completes the authentication process for the client and replies to the
    request with a "307 Temporary Redirect" to the encoded originally requested
    URL.
  o $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.
* When stopped, nodogsplash deletes its iptables rules, attempting to leave the
  router's firewall in its original state. If not (for example, if nodogsplash
  crashes instead of exiting cleanly) subsequently starting and stopping
  nodogsplash should remove its rules.
* Nodogsplash operates by marking packets (and, if traffic control is enabled,
  passing packets through intermediate queueing devices). Most QOS packages
  will also mark packets and use IMQ's. Therefore one or both of Nodgsplash and
  a QOS package may malfunction if used together. Potential conflicts may be
  investigated by looking at your overall iptables setup. To check to see all
  the rules in, for example, the mangle table chains, run

    iptables -t mangle -v -n -L

  For extensive suggestions on debugging iptables, see for example Oskar
  Andreasson's_tutorial.


Using Nodogsplash with Kamikaze

Eventually, new releases of Nodogsplash will be compiled against some stable
version of OpenWRT Kamikaze. Meanwhile, Nodogsplash has been tested on some
versions of Kamikaze and found to work, if these changes are made:

* The default name for the (wired and wireless) LAN interface in Kamikaze is
  br-lan. Edit /etc/nodogsplash/nodogsplash.conf and set GatewayInterface
  appropriately.
* Kamikaze moves to a different (more standard) way of organizing init scripts.
  Executable scripts reside in /etc/init.d, but appropriately named symlinks in
  /etc/rc.d determine the sequencing of scripts at boot. After installing
  Nodogsplash, do the following:

     cd /etc/init.d
     mv S65nodogsplash nodogsplash
     cd /etc/rc.d
     ln /etc/init.d/nodogsplash S65nodogsplash

  And then use /etc/init.d/nodogsplash to start and stop Nodogsplash from the
  command line.

Thanks to Tobias Pal and Jeff Allen for testing on Kamikaze.
-------------------------------------------------------------------------------
Email contact: nodogsplash (at) kokoro.ucsd.edu