Permalink
Fetching contributors…
Cannot retrieve contributors at this time
496 lines (481 sloc) 17.2 KB
<html>
<head> <title>nodogsplash README</title> </head>
<body>
<h3>0. The Nodogsplash project</h3>
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).
<p>
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.
<p>
<ul>
<li>
Nodogsplash:
<a href="http://kokoro.ucsd.edu/nodogsplash">http://kokoro.ucsd.edu/nodogsplash</a>
</li>
<li>
OpenWRT:
<a href="http://openwrt.org/">http://openwrt.org/</a>
</li>
<li>
Wifidog:
<a href="http://dev.wifidog.org/">http://dev.wifidog.org/</a>
</li>
<li>
Nocatsplash:
<a href="http://nocat.net/">http://nocat.net/</a>
</li>
<li>
GNU GPL:
<a href="http://www.gnu.org/copyleft/gpl.html">http://www.gnu.org/copyleft/gpl.html</a>
</li>
</ul>
<p>
The following describes what Nodogsplash does, how to get it and run it,
and how to customize its behavior for your application.
<h3>1. Overview</h3>
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.
<p>
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.
<p>
<p>
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.
<p>
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.
<h3>2. Installing and running nodogsplash</h3>
<ul>
<li>
Have a router working with
<a href="http://openwrt.org/">OpenWRT</a>.
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, <a href="#kamikaze">see below</a>.
</li>
<li>
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 <code>br0</code> or
<code>eth1</code>), and for the
following use ssh or telnet access to your router over a <em>different</em>
interface.
</li>
<li>
To install nodogsplash, obtain the <code>nodogsplash*.ipk</code> package you
want to install from the project website, copy it to
<code>/tmp/</code> on your OpenWRT router,
and, in as root on the router, run:
<pre>
ipkg install /tmp/nodogsplash*.ipk
</pre>
Or, to install the latest version, you can just run:
<pre>
ipkg install http://kokoro.ucsd.edu/nodogsplash/latest.ipk
</pre>
(Note: to prevent installation of an older package, you may have to
remove references to remote package repositories in your ipkg.conf file.)
</li>
<li>
If the interface that you want nodogsplash to manage is not <code>br0</code>,
edit <code>/etc/nodogsplash/nodogsplash.conf</code> and set
<code>GatewayInterface</code>.
</li>
<li>
To start nodogsplash, run the following, or just reboot the router:
<pre>
/etc/init.d/S65nodogsplash start
</pre>
</li>
<li>
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.
</li>
<li>
To stop nodogsplash:
<pre>
/etc/init.d/S65nodogsplash stop
</pre>
</li>
<li>
To uninstall nodogsplash:
<pre>
ipkg remove nodogsplash
</pre>
</li>
</ul>
<h3>3. How nodogsplash works</h3>
A wireless router running OpenWRT has two or more interfaces; nodogsplash
manages one of them. This will typically be <code>br0</code>,
the bridge to both the wireless and wired LAN; or the wireless lan
interface may be named something else
if you have broken the <code>br0</code> bridge to separate the wired and
wireless LAN's.
<p>
<h4>3.1 Packet filtering</h4>
Nodogsplash considers four
kinds of packets coming into the router
over the managed interface. Each packet is one of these kinds:
<ol>
<li>
<em>Blocked</em>, if the MAC mechanism is <code>block</code>, and
the source MAC address of the packet matches one
listed in the BlockedMACList; or if the MAC mechanism is <code>allow</code>,
and source MAC address of the packet does not match one
listed in the AllowedMACList or the TrustedMACList.
These packets are dropped.
</li>
<li>
<em>Trusted</em>, 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
<code>FirewallRuleSet trusted-users</code> and
<code>FirewallRuleSet trusted-users-to-router</code>
lists in the <code>nodogsplash.conf</code> configuration file,
or by the
<code>EmptyRuleSetPolicy trusted-users</code>
<code>EmptyRuleSetPolicy trusted-users-to-router</code> directives.
</li>
<li>
<em>Authenticated</em>, 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 <code>FirewallRuleSet authenticated-users</code>
and
<code>FirewallRuleSet users-to-router</code>
in the <code>nodogsplash.conf</code> configuration file).
</li>
<li>
<em>Preauthenticated</em>.
Any other packet.
These packets are accepted and routed to a limited set of
addresses and ports (see <code>FirewallRuleSet preauthenticated-users</code>
and
<code>FirewallRuleSet users-to-router</code>
in the <code>nodogsplash.conf</code> 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
<a href="http://www.hughes.com.au/products/libhttpd/">
libhttpd</a>-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
<em>Authenticated</em> until the inactive or forced timeout is reached,
and its packets revert to being <em>Preauthenticated</em>.
</li>
</ol>
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.
<p>
<h4>3.2 Traffic control</h4>
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.
<p>
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).
<h3>4. Customizing nodogsplash</h3>
The default shipped configuration is intended to be usable and reasonably
secure as-is for basic internet sharing applications, but it is
customizable.
<ul>
<li>
To change basic nodogsplash settings, edit the configuration file:
<pre>
/etc/nodogsplash/nodogsplash.conf
</pre>
In the configuration file, a <code>FirewallRule</code> has the form:
<pre>
FirewallRule <em>permission</em> [<em>protocol</em> [port <em>portrange</em>]] [to <em>ip</em>]
</pre>
where
<ul>
<li>
<code><em>permission</em></code> is required and
must be either <code>allow</code> or <code>block</code>.
</li>
<li>
<code><em>protocol</em></code> is optional. If present must be
<code>tcp</code>, <code>udp</code>, <code>icmp</code>, or <code>all</code>.
Defaults to <code>all</code>.
</li>
<li>
<code>port <em>portrange</em></code> is optional. If present,
<code><em>protocol</em></code> must be <code>tcp</code> or <code>udp</code>.
<code><em>portrange</em></code> can be a single integer port number, or a
colon-separated port range, e.g. <code>1024:1028</code>. Defaults to
all ports.
</li>
<li>
<code>to <em>ip</em></code> is optional. If present,
<code><em>ip</em></code> must be a decimal dotted-quad IP address
with optional mask. Defaults to <code>0.0.0.0/0</code>, i.e. all
addresses.
</li>
</ul>
<li>
To change the contents of the splash page, edit the splash page file:
<pre>
/etc/nodogsplash/htdocs/splash.html
</pre>
When the splash page is served, the following variables in the page are
replaced by their values:
<ul>
<li>
<code>$gatewayname</code> The value of
<code>GatewayName</code> as set in <code>nodogsplash.conf</code>.
</li>
<li>
<code>$authtarget</code> 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. (Alternatively, you can use a GET-method HTML form to
send this information to the nodogsplash server; see below.) As a simple
example:
<pre>
&lt;a href="$authtarget"&gt;Enter&lt;/a&gt;
</pre>
</li>
<li>
<code>$imagesdir</code> The directory in nodogsplash's web hierarchy
where images to be displayed in the splash page must be located.
</li>
<li>
<code>$tok</code>,<code>$redir</code>,<code>$authaction</code>, and
<code>$denyaction</code> are also available and can be useful if
you want to write the splash page to
use a GET-method
HTML form instead of using <code>$authtarget</code> as the value
of an href attribute to communicate with the
nodogsplash server. As a simple example:
<pre>
&lt;form method='GET' action='$authaction'&gt;
&lt;input type='hidden' name='tok' value='$tok'&gt;
&lt;input type='hidden' name='redir' value='$redir'&gt;
&lt;input type='submit' value='Click Here to Enter'&gt;
&lt;/form>
</pre>
</li>
</ul>
<li>
To change the appearance of informational and
error pages which may occasionally be served
by nodogsplash, edit the infoskel file:
<pre>
/etc/nodogsplash/htdocs/infoskel.html
</pre>
In this file, variables
<code>$gatewayname</code>,<code>$version</code>,<code>$title</code>, and
<code>$content</code> will be replaced by their values. <code>$title</code>
is a summary of the information or kind of error; <code>$content</code> is
the content of the information or error message.
</ul>
<h3>5. Site-wide username and password</h3>
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.
<p>
To enable this, edit <code>nodogsplash.conf</code> to set parameters
<code>PasswordAuthentication</code>,
<code>UsernameAuthentication</code>,
<code>Password</code>,
<code>Username</code>, and <code>PasswordAttempts</code> 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 <code>nodoguser</code> and <code>nodogpass</code>
respectively, along with others as required, to the server.
For example:
<pre>
&lt;form method='GET' action='$authaction'&gt;
&lt;input type='hidden' name='tok' value='$tok'&gt;
&lt;input type='hidden' name='redir' value='$redir'&gt;
username: &lt;input type='text' name='nodoguser' value='' size=12 maxlength=12&gt; &lt;br&gt;
password: &lt;input type='password' name='nodogpass' value='' size=12 maxlength=10&gt; &lt;br&gt;
&lt;input type='submit' value='Enter'&gt;
&lt;/form&gt;
</pre>
<h3>6. Using ndsctl</h3>
A nodogsplash install
includes <code>ndsctl</code>,
a separate application which provides some control over a
running
nodogsplash process by communicating with it over a unix socket.
Some command line options:
<ul>
<li>
To print to stdout
some information about your nodogsplash process:
<pre>
/usr/bin/ndsctl status
</pre>
</li>
<li>
To block a MAC address, when the MAC mechanism is <code>block</code>:
<pre>
/usr/bin/ndsctl block <em>MAC</em>
</pre>
</li>
<li>
To unblock a MAC address, when the MAC mechanism is <code>block</code>:
<pre>
/usr/bin/ndsctl unblock <em>MAC</em>
</pre>
</li>
<li>
To allow a MAC address, when the MAC mechanism is <code>allow</code>:
<pre>
/usr/bin/ndsctl allow <em>MAC</em>
</pre>
</li>
<li>
To unallow a MAC address, when the MAC mechanism is <code>allow</code>:
<pre>
/usr/bin/ndsctl unallow <em>MAC</em>
</pre>
</li>
<li>
To deauthenticate a currently authenticated user given their IP or MAC
address:
<pre>
/usr/bin/ndsctl deauth <em>IP</em>|<em>MAC</em>
</pre>
</li>
<li>
To set the verbosity of logged messages to <em>n</em>:
<pre>
/usr/bin/ndsctl loglevel <em>n</em>
</pre>
</li>
</ul>
For more options, run <code>ndsctl -h</code>. (Note that if you want
the effect of ndsctl commands to to persist across nodogsplash
restarts, you have to edit the configuration file.)
<h3>7. Debugging nodogsplash</h3>
<ul>
<li>
To see maximally verbose debugging output from nodogsplash,
edit the <code>/etc/init.d/S65nodogsplash</code> file to set the
<code>OPTIONS</code>
variable to the flags <code>"-s -d 7"</code>, restart or reboot, and
view messages with logread.
The <code>-s</code> flag logs to syslog; the <code>-d 7</code> flag
sets level 7, LOG_DEBUG, 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.
A lower level of logging, for example level 5, LOG_NOTICE,
is more appropriate for routine use (this is the default). Logging level
can also be set using <code>ndsctl</code> as shown above.
<p>
Alternatively, you can set the flag <code>-f</code> instead of <code>-s</code>,
and restart.
This will run nodogsplash in the foreground, logging to stdout.
</li>
<li>
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.
</li>
<li>
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
<pre>
iptables -t mangle -v -n -L
</pre>
For extensive suggestions on debugging iptables, see for example
<a href="http://www.frozentux.net/documents/iptables-tutorial/">
Oskar Andreasson's tutorial</a>.
</li>
</ul>
<h3 id="kamikaze">8. Using Nodogsplash with Kamikaze</h3>
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.
<p>
An explanation of steps that may be required to successfully
install Nodogsplash on Kamikaze is available here:
<a href="http://forum.openwrt.org/viewtopic.php?id=20282">anarcat post
on forum.opernwrt.org</a>
<p>
Here is a shorter summary of what is required:
<ul>
<li>
The default name for the (wired and wireless) LAN interface in Kamikaze is
<code>br-lan</code>.
Edit <code>/etc/nodogsplash/nodogsplash.conf</code> and set
<code>GatewayInterface</code> appropriately.
</li>
<li>
Kamikaze moves to a different
way of organizing init scripts. Executable
scripts reside in <code>/etc/init.d</code>, but appropriately named symlinks
in <code>/etc/rc.d</code> determine the sequencing of scripts at boot.
After installing Nodogsplash, do the following:
<pre>
cd /etc/init.d
mv S65nodogsplash nodogsplash
cd /etc/rc.d
ln -s /etc/init.d/nodogsplash S65nodogsplash
</pre>
And then use <code>/etc/init.d/nodogsplash</code> to start and stop
Nodogsplash from the command line.
</li>
</ul>
Thanks to Tobias Pal and Jeff Allen and anarcat for testing on Kamikaze.
<hr>
Email contact: nodogsplash (at) kokoro.ucsd.edu
</body>
</html>