1. Licence
These shell scripts are licenced under the GPL Version 2.0
(or higher at your option). Details can be found in the file
COPYING or at http://www.fsf.org/licensing/licenses/gpl.html.


2. Overview
web-splash manipulates some iptables rules to redirect the
first web access of a client to a page you choose. This can
be used for open wireless networks that want to inform
anonymous users about the policy of the net.
Further http (and other) requests will be forwarded. You may
also restrict access to some services, if you want.

web-splash does also give you information about the traffic
consumption of every user. This can be used to limit the
traffic volume or speed with packages like "fairspeed"
(https://systemausfall.org/toolforge/fairspeed).


3. How does it work?
 - clients retrieve an IP by your dhcp server
 - of course, your router should be their default gateway
 - the clients are allowed to use nameservice
 - only DNS requests get forwarded while the client is not
   registered
 - the first request on port 80 (http) will get redirected
   to the router itself
 - each the index.html of the webserver's root and the
   error-404-document should contain an http-refresh tag
   leading to /www/cgi-bin/web-splash.cgi
 - this cgi will register the client (that means: add a
   iptable rule to allow forwarding for this client) and
   show the page, that is set by the "SPLASH_DOCUMENT"
   variable in /etc/web-splash.conf
 - FUTURE: there will be a script that unregisters clients
   after a specified idle time (so they will get redirected
   to the login page again)


4. Installation
You may install web-splash with the ipkg package manager or
manually.

4.1 with ipkg
The package can be installed with the ipkg package management
(it was developd for embeded devices).
With ipkg you may just type:
  ipkg install web-splash_???.ipk

Now you should take a look at /etc/web-splash.conf.
If you use thttpd as your webserver, then you should restart
it. Otherwise it will not see the new default page for a
404-error. This will be explained later in this document ...

4.2 manuallly
If you do use a distribution that does not include ipkg, then
you may install it manually.

  1.) unpack the sources
	tar xzf web-splash_???.tar.gz

  2.) config file
	cp web-splash.conf /etc

  3.) functions "library"
 	cp web-splash-function.sh /usr/lib

  4.) main script
 	cp web-splash.sh /usr/bin

  5.) cgi script
	cp web-splash.cgi /www/cgi-bin

  6.) default web site
	cp -r splash-site /www/web-splash

If you used different locations for these files, then
you need to change the settings in /etc/web-splash.conf too.


5. webserver configuration
It is necessary, that your webserver redirects all request to
the cgi of web-splash. This can be done by using an alias
directive (if your webserver supports this) or defining a
custom error-404-document in your webserver (thttpd can do this).

For thttpd your configuration is already complete if you
installed web-splash as described before.


6. splash page
Surely you want to replace the default page that was installed
with your own text (or change the SPLASH_DOCUMENT setting in
/etc/web-splash.conf).
This page could show some information that your users should
get before using the internet.


7. support open networks!
web-splash was designed for open (wireless) networks. 
I hope that this software ease the work of their administrator's
to spread the word ...
(see http://freenetworks.org)


8. contact
Send me an email if you have questions or suggestions:
devel@sumpfralle.de

the project's homepage:
https://systemausfall.org/toolforge/web-splash

the subversion repository:
https://svn.systemausfall.org/svn/openwrt-packages

the bug tracker:
https://systemausfall.org/trac/openwrt-packages