From d9086bca2f4f2632dafb504da89a167f7c1af369 Mon Sep 17 00:00:00 2001 From: lars Date: Fri, 20 May 2005 21:20:31 +0000 Subject: [PATCH] README added --- web-splash/README | 118 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 web-splash/README diff --git a/web-splash/README b/web-splash/README new file mode 100644 index 0000000..2402f6c --- /dev/null +++ b/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