README added

web-splash/README

@@ -0,0 +1,118 @@
+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