== Intro ==
Due to our strict constrains with regards to captive portals (low-memory, no-login needed, auto-update of content) we decided to make our own. The software we build WLPortal is based around 5 components: 
 1. {{{pf}}} or {{{ipfw}}} firewall rules in the FreeBSD kernel.
 1. {{{thttpd}}} instance serving the captive portal CGI.
 1. The CGI script itself.
 1. The template files for making the entrance pretty.
 1. {{{crontab}}} entry to cleanup stale entries.

== Work flow ==
 1. The user gets deflected to the Captive Portal by the {{{firewall}}} if he/she tries to reach an external website.
 1. The user reads the welcome pages and clicks OK.
 1. The MAC/IP of the user's device gets whitelisted in the {{{firewalll}}}.
 1. The user gets redirected to the specified website (http://wirelessleiden.nl by default).
 1. The {{{crontab}}} entry deletes the user if he/she has been idle too long.

== Template configurations ==
Important: this only holds true for nodes build in the {{{iris-releng-9.0-ileiden}}} branch, build after {{{r10249 | rick | 2012-03-19 19:06:36 +0100 (Mon, 19 Mar 2012)}}}

Warning: Make sure to only alter the cosmetics of the file and not the technical structure of the forms or submit url.

You can edit the config file with:
node# vim /usr/local/etc/wlportal/login.tmpl

Please do mind that this file gets lost after a reboot. If you like to store the edited file in a persistent place, make sure to place it at the configuration store:
node# mount -uwo noatime /cfg
node# cp /usr/local/etc/wlportal/login.tmpl /cfg/local/wlportal/login.tmpl
node# umount /cfg

== Configuration File ==
You can use the configuration file file:/usr/local/etc/wlportal/config.yaml to provide overwrites for the base configuration entries defined in the script. This allows you to alter the default redirect page and white-listing of specific hosts.


== File Hierarchy ==
 * file:/usr/local/www/wlportal/index.cgi - The Main worker.
 * file:/etc/ipfw.sh or file:/etc/pf.conf - The Base Firewall Redirect Rules.
 * file:/usr/local/etc/wlportal/login.tmpl - Active Template.
 * file:/usr/local/etc/wlportal/config.yaml - Active Configuration.
 * file:/usr/local/etc/thttpd.conf - Active {{{thttpd}}} Configuration.
 * file:/etc/crontab - crontab(4) '''recycle''' calls.
 * file:/etc/rc.conf.local - Startup configuration for the local daemons.