-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.html
495 lines (481 loc) · 17.2 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
<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>
<a href="$authtarget">Enter</a>
</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>
<form method='GET' action='$authaction'>
<input type='hidden' name='tok' value='$tok'>
<input type='hidden' name='redir' value='$redir'>
<input type='submit' value='Click Here to Enter'>
</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>
<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'>
</form>
</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>