NAME Captive::Portal - Perl based solution for controlled network access ABSTRACT A so called *Captive Portal* written in perl for Linux Gateways. For a longer explanation see: DESCRIPTION Captive::Portal a.k.a. CaPo is a Hotspot solution for Linux Gateways. CaPo is developed and in service at Ulm University for thousands of concurrent users. The main focus is scalability, performance, simple administration and user-friendliness. The goals were achieved by using scalable technologies like ipset(8) instead of native iptables(8), FastCGI instead of CGI and a fine tuned concurrent session handling based on the filesystem locking mechanism without any need for an additional RDBMS. CaPo is compatible with any FastCGI enabled HTTP(S)-server. ALGORITHM IN SHORT 1. Internal NAT redirect HTTP-traffic on the gateways inside interface - from unknown clients - is redirected by an iptables(8) NAT-rule to a port the HTTP-server is listen, e.g. iptables -t nat -A PREROUTING -i eth1 -p tcp --dport 80 -j REDIRECT --to-port 5281 2. HTTP to HTTPS redirect The HTTP-server redirects the HTTP-request by a rewrite rule to an HTTPS-request for the CaPo script *capo.fcgi* , e.g. RewriteEngine On RewriteRule .* https://gateway.acme.org/capo/? [R,L] 3. SESSION LOGIN The *capo.fcgi* script offers a login/splash page. After successful login the firewall is dynamically changed to allow this clients IP/MAC tuple for internet access. 4. SESSION LOGOUT The capo.fcgi script offers a status/logut page. After successful logout the firewall is dynamically changed to disallow this IP/MAC tuple for internet access. 5. SESSION IDLE A cronjob fires periodically the capo-ctl.pl script checking for idle sessions. Idle means, the client didn't send any packet for a period of time (cfg param: IDLE_TIME = 10min). Before a session is put into idle state the client is once pinged. It is a design goal not requiring JavaScript on clients! 6. SESSION REACTIVATION For a short period of time (cfg param: KEEP_OLD_STATE_PERIOD = 1h) the session is still on disc, but in idle state. If a client request matches the sessions IP/MAC/COOKIE data, the session is reactivated without a login page. INSTALLATION Please see the INSTALL file in this distribution. As a minimum please be aware of the following access restrictions: Captive::Portal needs access to iptables(8) and ipset(8) to change the firewall-rules on request. You must add the following rule (or similar) to the sudoers file, depending on the username of your http daemon: WWW_USER ALL=NOPASSWD: /PATH/TO/iptables, /PATH/TO/ipset If you use fping(8) (see USE_FPING config parameter) to trigger idle sessions before going idle you must add fping to the sudoers file like ipset and iptables, regardless of the suid bit on fping, since we need special timing flags available only for root: WWW_USER ALL=NOPASSWD: /PATH/TO/iptables, /PATH/TO/ipset, /PATH/TO/fping The default $SESSIONS_DIR is set to '/var/cache/capo'. WWW_USER must be the owner of this dir with write permissions! CONFIGURATION The configuration file is searched in the following default places: $ENV{CAPTIVE_PORTAL_CONFIG} || $Bin/../etc/local/config.pl || $Bin/../etc/config.pl LOGGING Logging is handled by the Log::Log4perl module. The logging configuration is searched in the following default places: $ENV{CAPTIVE_PORTAL_LOG4PERL} || $Bin/../etc/local/log4perl.conf || $Bin/../etc/log4perl.conf LOCAL ADAPTATION The HTML files are generated from templates (Template-Toolkit syntax). You should use the original template files as stanzas and put the locally changed versions into the local template tree. See template search order prefers the local templates. The firewall rules and commands are also generated from template files. Normally there should no need to change the firewall rules but it would be possible without changing the perl code. I18N There exists a template tree for each supported language. Some system/error messages used by the program must also be translated for the message catalog in the config file. SEE ALSO Captive::Portal::Role::Config, capo.fcgi and capo-ctl.pl BUGS AND LIMITATIONS There are no known problems with this module. Please report any bugs or feature requests to "bug-captive-portal at rt.cpan.org", or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. AUTHOR Karl Gaissmaier, "" LICENSE AND COPYRIGHT Copyright 2010-2011 Karl Gaissmaier, all rights reserved. This distribution is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or b) the Artistic License version 2.0. The full text of the license can be found in the LICENSE file included with this distribution.