Nodogsplash Project Introduction

0. The Nodogsplash project

Nodogsplash offers a simple-to-provide restricted access to an Internet
Connection. It is derived from the codebase of the Wifi Guard Dog project.
Nodogsplash is released under, the GNU general public License.

• Mailing List:http://ml.ninux.org/mailman/listinfo/nodogsplash
• Original Homepage:http://kokoro.ucsd.edu/nodogsplash
• wifidog:http://dev.wifidog.org/
• GNU gpl:http://www.gnu.org/copyleft/gpl.html

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

1. Overview

Nodogsplash offers a solution to the 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 is
Providing, you don ' t need or want the complexity of the 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
The ' 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 is configurable, by editing the configuration
File and the splash page. The default installed configuration May is all
Need, though.

2. Installing and Running Nodogsplash

• There is a router working with OPENWRT. Nodogsplash has been compiled against a
  OpenWrt Attitude Adjustment BuildRoot; It may or may not be on the 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 are basically working before try to install
  Nodogsplash. In particular, make sure your DHCP daemon is serving addresses
  On the interface that Nodogsplash would manage (typically Br-lan or eth1), and
  For the following with SSH or telnet access to your router over a different
  Interface.

• To install Nodogsplash, obtain the NODOGSPLASH*.IPK package for 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

  (note:to prevent installation of an older package
  References to remote package repositories in your ipkg.conf file)

• If the interface-want Nodogsplash to manage are not Br-lan,
  Edit/etc/nodogsplash/nodogsplash.conf and set Gatewayinterface.

• To start Nodogsplash, run the following, or just reboot the router:

  /etc/init.d/nodogsplash start

• To test the installation, connect a client machine to the interface on your
  Router that's managed by Nodogsplash (for example, connect to the router ' s
  Wireless LAN) and in a browser on this 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 stop Nodogsplash:

  /etc/init.d/nodogsplash stop

• To uninstall Nodogsplash:

  ipkg remove nodogsplash

3. How Nodogsplash Works

A Wireless router running OpenWrt has both or more interfaces; Nodogsplash
Manages one of them. This would typically is Br-lan, the bridge to both the
Wireless and Wired LAN; Or the Wireless LAN interface may be named something
else if you had broken the Br-lan bridge to separate the wired and wireless
LAN ' s.

3.1 Packet Filtering

Nodogsplash considers four kinds of packets coming to the router over the
Managed interface. Each packet is one of the these kinds:

2. 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 is dropped.
4. Trusted, if the source MAC address of the packet matches one listed in the
   Trustedmaclist. By default, these packets is 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.
6. Authenticated, if the packet ' s IP and MAC source addresses have gone
   Through the Nodogsplash authentication process and have not yet expired.
   These packets is 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).
8. preauthenticated. Any other packet. These packets is accepted and routed
   to a limited set of addresses and ports (see Firewallruleset
   PreAuthenticate D-users and Firewallruleset Users-to-router in the
   nodogsplash.conf configuration file). Any other packet are dropped, except
   that a packet for destination port in any address was redirected to Port
   205 0 on the router, where Nodogsplash ' s builtin libhttpd-based Web server
   is listening. This begins the ' authentication ' process. The server would
   serve a splash page back to the source IP address of the packet. The user
   clicking the appropriate link on the splash page would complete the
   process and causing future packets from T His ip/mac address to being 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 it rules at the beginning of existing chains,
Nodogsplash should is 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 is taken by clients connected on that interface.
Nodogsplash implements this functionality by enabling the intermediate queue
Devices (IMQ ' s), one for upload and one for download, and attaching simple
rate-limited HTB Qdiscs to them. Rules is inserted in the router ' s iptables
Mangle prerouting and Postrouting tables to jump to these IMQ ' s. The result is
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

In the configuration file, a firewallrule have the form:

FirewallRule permission [protocol [port portrange] [to ip]

where

• permission is required and must are allow, block, drop, log, or Ulog.
• protocol is optional. If present, it must is TCP, UDP, ICMP, or all.
  Defaults to all.
• Port portrange is optional. If present, protocol must be TCP or UDP.
  Portrange can is a single integer port number, or a colon-separated port
  range, e.g. 1024:1028. Defaults to all ports.

• To IP is optional. If present, IP must be a decimal dotted-quad IP address
  With optional mask. Defaults to 0.0.0.0/0, i.e. all addresses.

• To the contents of the splash page, edit the splash page file:

  /etc/nodogsplash/htdocs/splash.html

When the splash page was served, the following variables in the page was
Replaced by their values:

• $gatewayname The value of Gatewayname as set in nodogsplash.conf.

• $authtarget A URL which encodes a unique token and the URL of the user ' s
  Original Web request. If Nodogsplash receives a request at the this URL, it
  Completes the authentication process for the client and replies to the
  Request with a "302 Found" to the encoded originally requested
  Url. (Alternatively, can use a Get-method HTML form to send this
  Information to the Nodogsplash server; See below.) As a simple example:

  <a href="$authtarget">Enter</a>

• $imagesdir The directory in Nodogsplash's web hierarchy where images to IS
  Displayed in the splash page must is located.

• $tok,$redir,$authaction, and $denyaction is also available and can be
  Useful if want to write the splash page to use a Get-method HTML form
  Instead of using $authtarget as the value of an HREF attribute to
  Communicate with the Nodogsplash server. As a simple example:

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

• $clientip, $clientmac and $gatewaymac the respective addresses
  Of the client or gateway. This might is usefull in cases where the data
  Needs to is forwarded to some and other place by the Plash page itself.

• $nclients and $maxclients User stats. Usefull when do need to
  Display something like "N of M users online" on the splash site.

• $uptime The time Nodogsplash is running.

• To change the appearance of informational and error pages which
  Occasionally be served by Nodogsplash, edit the Infoskel file:

  /etc/nodogsplash/htdocs/infoskel.html

In this file, variables $gatewayname, $version, $title, and $content would be
replaced by their values. $title is a summary of the information or kind of
Error $content is the content of the information or error message.

5. Authentication5.1 site-wide username and password

Nodogsplash can 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 is site-wide (not per user), and they is sent in the
The clear using HTTP GET, which is a secure mechanism.
To enable the This, the edit nodogsplash.conf to set parameters passwordauthentication,
usernameauthentication, Password, Username, and passwordattempts as desired.
Then the splash page must with 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 and 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‘>  </form>

5.2 Forwarding Authentication

Nodogsplash allows to call a external program for authentication using
The options binvoucher/enablepreauth/forcevoucher in nodogsplash.conf.
The given program for Binvoucher would be called using the clients MAC address as argument.
The output is expected to being the number of seconds the client is authenticated.
It may also contain the clients download and upload speed limit in kbits/s.
See the example configuration file for further details.

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 sockets. Some Command line options:

• To print to stdout some information about your Nodogsplash process:

  /usr/bin/ndsctl status

• To block a MAC address, when the MAC mechanism is block:

  /usr/bin/ndsctl block MAC

• To unblock a MAC address, when the MAC mechanism is block:

  /usr/bin/ndsctl unblock MAC p>

• To allow a MAC address, when the MAC mechanism are allow:

  /usr/bin/ndsctl allow MAC

  /li>

• To unallow a MAC address, when the MAC mechanism was allow:

  /usr/bin/ndsctl unallow MAC

• To deauthenticate a currently authenticated user given their IP or MAC
  Address:

  /USR/BIN/NDSC TL Deauth ip| MAC

• To set the verbosity of logged messages to N:

  /usr/bin/ndsctl loglevel n

For more options, run ndsctl-h. (Note So if you want the effect of NDSCTL
Commands to persist across Nodogsplash restarts.
Configuration file.)

7. Debugging Nodogsplash

• to see maximally verbose debugging output from Nodogsplash, edit the
  /etc/init.d/nodogsplash file to set the OPTION S variable to the flags "-s-d 7",
  Restart or reboot, and view messages with Logread. The-s flag logs to
  Syslog, the-d 7 flags sets level 7, Log_debug, for debugging messages
  (see SYSLOG.H). You don't want to run with these flags routinely, as it'll
  quickly fill the syslog circular buffer, unless you enable Remote logging. A
  Lower level of logging, for example Level 5, Log_notice, was more appropriate
  for routine use (this is the default) . Logging level can also is set using
  Ndsctl as shown above.
  Alternatively, you can set the flag-f instead of-s, and restart.
  This would run Nodogsplash in the foreground, logging to stdout.
• When stopped, Nodogsplash deletes it 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
  would also mark packets and use IMQ ' s. Therefore one or both of Nodogsplash and
  A QOS package may malfunction if used together. Potential conflicts may
  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 in debugging iptables, see for example Oskar
  Andreasson ' s_tutorial.

This article by http://www.wifidog.pro/2015/05/11/nodogsplash%E9%A1%B9%E7%9B%AE%E4%BB%8B%E7%BB%8D.html compilation, reprint please indicate the source

Nodogsplash Project Introduction