release/src/router/nocat/README

   1 NoCatSplash is a Open Public Network Gateway Daemon.  It performs as a
   2 [captive/open/active] portal.  When run on a gateway/router on a network,
   3 all web requests are redirected until the client either logs in or clicks
   4 "I Accept" to an AUP. The gateway daemon then changes the firewall rules
   5 on the gateway to pass traffic for that client (based on IP address and
   6 MAC address).
   7
   8 NoCatSplash is the successor to NoCatAuth, which was written in Perl.
   9 NoCatSplash is written in ANSI C in order to be smaller and work better on
  10 embedded style devices. NoCatSplash uses the portable GLib library from the
  11 GNOME Project for its event loop, memory management, and high-level data
  12 structures.
  13
  14 NoCatSplash is copyrighted (c) 2004 - 2005 by Schuyler Erle
  15 <schuyler@nocat.net> and Rob Flickenger <rob@nocat.net>, and is distributed
  16 under the GNU Public License v2 or better.
  17
  18 *** Quickstart
  19
  20 ./configure
  21 make
  22 make install
  23 vi /usr/local/etc/nocat.conf
  24 /usr/local/sbin/splashd
  25
  26 *** Requirements - Current
  27
  28 - Linux
  29  * glib 1.2
  30  * iptables
  31  * netfilter kernel modules for NAT, redirection, etc.
  32  * GnuPG (passive mode only)
  33  * libghttp (remote splash only)
  34
  35 *** Requirements - Future Version
  36
  37 - FreeBSD
  38  * ipfw - no MAC address filtering
  39  * ipfwv2 - includes MAC address filtering
  40  * gmake
  41
  42 - OpenBSD
  43  * pfctl
  44
  45 - NetBSD
  46
  47 - Mac OS X
  48
  49 *** Building NoCatSplash for normal operation
  50
  51 To build and configure the NoCatSplash gateway, run:
  52
  53 $ cd NoCatSplash-nightly
  54 $ ./configure
  55 $ make
  56
  57 iptables must be in your path when you run ./configure! Next, as root:
  58
  59 # make install
  60 # vi /usr/local/etc/nocat.conf [or use your editor of choice]
  61
  62 In addition to the usual GNU ./configure options, NoCatSplash also supports:
  63
  64   --prefix=<path to install>
  65         defaults to /usr/local
  66
  67   --with-remote-splash
  68         If enabled, splashd will attempt to fetch its splash page
  69         from the URL specified by SplashURL, rather than using the
  70         local one specified by SplashForm. SplashForm is retained
  71         as a fallback in the event that SplashURL can't be loaded.
  72
  73   --with-mode=passive
  74         Compile for *experimental* authenticating passive mode. Passive mode
  75         basically doesn't really work yet. Patches welcome.
  76
  77   --with-firewall=loopback
  78         Compiles with "loopback" firewall scripts for testing.
  79
  80   --with-ghttpd
  81         Also compiles ghttpd for local web server testing.
  82
  83
  84 *** Running the NoCatSplash gateway
  85
  86 To run the NoCatSplash gateway, you must be root. Run:
  87
  88 # export PATH=$PATH:/sbin
  89 # ./splashd
  90
  91 In particular, you need to make sure that iptables can be found via the
  92 PATH environment variable before executing splashd.
  93
  94 *** Building NoCatSplash for testing purposes
  95
  96 You can build NoCatSplash with the "loopback" firewall scripts in order
  97 to test it on a machine without any network connection:
  98
  99 $ cd splash
 100 $ ./configure --prefix=/tmp/nocat --with-firewall=loopback \
 101      --with-ghttpd
 102 $ make
 103 $ make install
 104 $ vi /tmp/nocat/etc/nocat.conf
 105
 106 Set "LoginTimeout" to a low value, say, 120 seconds. As root, run:
 107
 108 # /tmp/nocat/sbin/ghttpd &
 109 # /tmp/nocat/sbin/splashd
 110
 111 If you're not currently running a web server,  this will start ghttpd, a
 112 lightweight web server, running on port 80, serving data out of the
 113 DocumentRoot specified in nocat.conf.  Then run /tmp/nocat/sbin/splashd. Open a
 114 browser, and go to http://localhost/test.html or some other page on your local
 115 web server. You should be captured and allowed to log in, at which point you
 116 should be directed to the web page you attempted to visit. You should be able
 117 to browse your local web server until your login expires.
 118
 119 *** Notes
 120
 121 NoCatSplash only runs on Linux at present. Contact me if you are
 122 interested in porting it to other operating systems, particularly *BSD,
 123 and I will give you pointers on how to do so.
 124
 125 People who have been paying attention will note that I've temporarily
 126 thrown out my original design for NoCatSplash, and concentrated on
 127 building a simplified rendition of the NoCatAuth Open mode in C. This
 128 is deliberate. The original design was nice, but too baroque for getting
 129 this project off the ground.
 130
 131 Anyway, this code is going to change very rapidly. It might
 132 not be fancy, but it should work. Comments and questions welcome.
 133
 134 SDE <schuyler@nocat.net>