mirror of
https://github.com/openNDS/openNDS.git
synced 2026-05-04 03:01:32 -04:00
343 lines
12 KiB
HTML
343 lines
12 KiB
HTML
<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 how Nodogsplash works, how to get it and run it,
|
|
and how to customize its behavior for your application.
|
|
|
|
<h3>1. Overview</h3>
|
|
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
<p>
|
|
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.
|
|
<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 different 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>
|
|
</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 see the current status of your nodogsplash process:
|
|
<pre>
|
|
/usr/bin/ndsctl status
|
|
</pre>
|
|
</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 is typically named <code>eth1</code>
|
|
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:
|
|
<ol>
|
|
<li>
|
|
<em>Blocked</em>, 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.)
|
|
</li>
|
|
<li>
|
|
<em>Trusted</em>, 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.)
|
|
</li>
|
|
<li>
|
|
<em>Authenticated</em>, 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 <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 only to the DNS port
|
|
on addresses forwarded through the router, and to ports
|
|
and protocols opened in
|
|
<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-based</a>
|
|
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 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.
|
|
<p>
|
|
Of course, there is the usual tradeoff between security and usability.
|
|
For example, not opening ports 25 and 80 in the
|
|
<code>FirewallRuleSet users-to-router</code>
|
|
helps to prevent unauthorized administrative access to your router,
|
|
but (if you have an empty TrustedMACList) does this by blocking
|
|
<em>all</em> ssh and http access to the router from the managed
|
|
interface.
|
|
<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>
|
|
</li>
|
|
<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.
|
|
</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>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>5. Debugging nodogsplash</h3>
|
|
<ul>
|
|
<li>
|
|
To see 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 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.
|
|
<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://iptables-tutorial.frozentux.net/iptables-tutorial.html">
|
|
Oskar Andreasson's tutorial</a>.
|
|
</li>
|
|
</ul>
|
|
<h3 id="kamikaze">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, if these changes are made:
|
|
<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
|
|
(more standard) 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 /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 for testing on Kamikaze.
|
|
<hr>
|
|
Email contact: nodogsplash (at) kokoro.ucsd.edu
|
|
|
|
</body>
|
|
</html>
|