Index of /nodogsplash

[ICO]NameLast modifiedSizeDescription

[DIR]Parent Directory  -  
[   ]CHANGELOG05-Nov-2013 18:07 4.6K 
[TXT]README.html05-Nov-2013 18:07 16K 
[   ]latest.ipk05-Nov-2013 18:07 64K 
[TXT]md5sums.txt05-Nov-2013 18:07 2.9K 
[   ]nodogsplash-0.9_beta9.9.3.tar.gz05-Nov-2013 18:07 824K 
[   ]nodogsplash-0.9_beta9.9.6.tar.gz05-Nov-2013 18:07 823K 
[   ]nodogsplash-0.9_beta9.9.tar.gz05-Nov-2013 18:07 819K 
[   ]nodogsplash_0.9_beta9.9.3_mipsel.ipk05-Nov-2013 18:07 66K 
[   ]nodogsplash_0.9_beta9.9.6_mipsel.ipk05-Nov-2013 18:07 64K 
[   ]nodogsplash_0.9_beta9.9_mipsel.ipk05-Nov-2013 18:07 60K 
[DIR]old/05-Nov-2013 17:51 -  

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

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

1. Overview

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 request a web page. It captures the request, and instead serves back a 'splash' web page using its own builtin web server. The splash page contains 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 page. This access expires after a certain time interval.

Nodogsplash also permits limiting the aggregate 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

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 may be named something else 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. Each packet is one of these kinds:
  1. Blocked, if the MAC mechanism is block, and the source MAC address of the packet matches one listed in the BlockedMACList; or if the MAC mechanism is allow, and source MAC address of the packet does not match one listed in the AllowedMACList or the TrustedMACList. These packets are dropped.
  2. Trusted, if the source MAC address of the packet matches one listed in the TrustedMACList. By default, these packets are accepted and routed to all destination addresses and ports. If desired, this behavior can be customized by FirewallRuleSet trusted-users and FirewallRuleSet trusted-users-to-router lists in the nodogsplash.conf configuration file, or by the EmptyRuleSetPolicy trusted-users EmptyRuleSetPolicy trusted-users-to-router directives.
  3. Authenticated, if the packet's IP and MAC source addresses have 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 and routed to a limited set of addresses and ports (see FirewallRuleSet preauthenticated-users and 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 chain 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.

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.

5. Site-wide username and password

Nodogsplash can be configured to require a username and/or password to be entered on the splash page as part of the authentication process. Since the username and password are site-wide (not per user), and they are sent in the clear using HTTP GET, this is not a secure mechanism.

To enable this, edit nodogsplash.conf to set parameters PasswordAuthentication, UsernameAuthentication, Password, Username, and PasswordAttempts as desired. Then the splash page must use a GET-method HTML form to send user-entered username and/or password as values of variables nodoguser and nodogpass respectively, along with others as required, to the server. For example:

<form method='GET' action='$authaction'>
<input type='hidden' name='tok' value='$tok'>
<input type='hidden' name='redir' value='$redir'>
username: <input type='text' name='nodoguser' value='' size=12 maxlength=12> <br>
password: <input type='password' name='nodogpass' value='' size=12 maxlength=10> <br>
<input type='submit' value='Enter'>

6. Using ndsctl

A nodogsplash install includes ndsctl, a separate application which provides some control over a running nodogsplash process by communicating with it over a unix socket. Some command line options: For more options, run ndsctl -h. (Note that if you want the effect of ndsctl commands to to persist across nodogsplash restarts, you have to edit the configuration file.)

7. Debugging nodogsplash

8. Using Nodogsplash with Kamikaze

Nodogsplash has been packaged for OpenWRT Kamikaze. A howto is here: Kamikaze Nodogsplash HOWTO.

Another explanation of steps that can be used to successfully install Nodogsplash on Kamikaze is available here: anarcat post on

Thanks to Tobias Pal and Jeff Allen and anarcat for early testing on Kamikaze.

Email contact: nodogsplash (at)