todo:	1. Insert the 'captive' chain someplace such that the Full Firewall
	   Control rules are enacted before the captive rules

	2. Get the SmoothWall GUI header/footer inserted in the GUI page



Captive Portal v1.2


----------
Changelog

v1.2 (10 Aug 2005)
- user now has option to logoff
- squid logs sorted by account
- allow list (/var/smoothwall/mods/captive/allow.sh) for clients you do not
  want to be captured
v1.1 (30 Jul 2005) - bug fixes and feature creep
- information button added to GUI
- event log added
- nmap integrated into GUI

v1.0 (02 Feb 2005) - initial release


----------
Introduction

This mod allows SmoothWall Express 2.0 to function as a captive portal.  All
clients must authenticate by username & password before being granted access
to the internet (red network in SmoothWall terms).

By default, all traffic from all clients connecting through the SmoothWall is
blocked.  Web requests (port 80) are redirected to a web page that prompts
the client for a username and password.  After login, the client has normal
access to the red network.  Each client must obtain its IP address by DHCP
from the SmoothWall.

A short list of this mod's key features
- force clients to authenticate before accessing the internet
- account management via the SmoothWall web GUI
- account management via a command line (ssh session)
- ability to force re-login after an arbitrary period of time
- "one-time use" accounts which disable themselves after a specified time
- each web page a client sees is fully customizable
- force clients to obtain an IP address by DHCP from the SmoothWall

After bug fixes, the future enhancements at the top of the list are
- closer integration with the Squid web proxy to enable the filtering of
  http log data by user rather than IP

Suggestions, criticisms, and bug reports are desired.  Please feel free to
private-message me through the community.smoothwall.org forums.

	- pgg

----------
System Requirements

To install this mod, you need to have ...
- A functioning SmoothWall.  Fixes 1-7 are highly recommended, but not required.
- Squid (the web proxy) enabled in transparent node.
- SmoothWall's DHCP server running.  Clients on static IPs can not authenticate.


----------
List Of Files:

/usr/local/bin/captive_adduser			add/change an authorized user
/usr/local/bin/captive_deluser			delete an authorized user
/usr/local/bin/captive_print			print user info & login status
/usr/local/bin/captive_printuser		print status of a specific user
/home/httpd/cgi-bin/captive_login.cgi		handles logins
/home/httpd/cgi-bin/captive_gui.cgi		admin GUI
/var/smoothwall/mods/captive/captive_cleanup	logoff users with expired login
/var/smoothwall/mods/captive/captive_flush	logoff all users
/var/smoothwall/mods/captive/captive_httpd	mini-httpd server for login form
/var/smoothwall/mods/captive/captivedb
/var/smoothwall/mods/captive/startup.sh
/var/smoothwall/mods/captive/loginpage.html
/var/smoothwall/mods/captive/successful_login.html
/var/smoothwall/mods/captive/error_acct_disabled.html
/var/smoothwall/mods/captive/error_bad_user_or_pass.html
/var/smoothwall/mods/captive/error_system.html
/var/smoothwall/mods/captive/nmap/cron.sh
/var/smoothwall/mods/captive/nmap/nmap-html-beautify
/var/smoothwall/mods/captive/nmap/nmap.sh
/var/smoothwall/mods/captive/nmap/todo.sh
/var/smoothwall/mods/captive/nmap/todo.sh.base*
/home/httpd/html/ui/assets/3.6/img/pagetitles/black.gif
/home/httpd/html/ui/assets/3.6/img/pagetitles/clear.gif

And some nmap stuff courtesy of AwPhuch:
/usr/share/nmap/
/usr/share/nmap/nmap-rpc
/usr/share/nmap/nmap-protocols
/usr/share/nmap/nmap-os-fingerprints
/usr/share/nmap/nmap-mac-prefixes
/usr/share/nmap/nmap-service-probes
/usr/share/nmap/nmap-services
/usr/bin/nmap

The first four files are command line utilities.  Everything they do can be
done through the GUI and they are only included for the sake of convenience.

The C source and Makefile is in /var/smoothwall/mods/captive/src


----------
Installation Instructions


These instructions assume
- you know how to copy files from your PC to the SmoothWall
- you know how to use ssh (putty, securecrt, etc) to open a terminal
- you know how to edit text files on your SmoothWall
- you have the Squid web proxy enabled and running in transparent mode
- you have the DHCP server running on your SmoothWall 
If you have questions or problems with any of the above, go to the support
forums at http://community.smoothwall.org/forum/ for help.

1. Obtain the current tarball from http://www.geocities.com/p_g_g_2004/captive.html

2. Get the tarball to your SmoothWall via scp or WinSCP or some other method

3. Unpack it:  tar zxvf captive-portal-1.1.tgz -C /

4. Add the following to the end of /etc/rc.d/rc.firewall.up
	/sbin/iptables -t nat -N captive
	/sbin/iptables -t nat -I PREROUTING -j captive

5. Add the following to /etc/rc.d/rc.sysinit just before the line that says
       'echo "Silencing kernel, syslog output on tty12"':

       /var/smoothwall/mods/captive/startup.sh

       Edit that file and replace 192.168.0.1 with the IP address of your green NIC!
       
6. Add the following to the end of /etc/crontab
       # Captive Portal - check for expired sessions
       */5 * * * * root /var/smoothwall/mods/captive/captive_cleanup
       */5 * * * * root /var/smoothwall/mods/captive/nmap/cron.sh
       0 2 * * * root /var/smoothwall/mods/captive/captive_squid_logs


7. Change the permissions for the two CGI programs:
       # chmod 6755 /home/httpd/cgi-bin/captive_*.cgi

8. Edit the following page:
       /var/smoothwall/mods/captive/loginpage.html

       Edit the line that begins with

       <FORM ACTION="https://192.168.0.1:441/cgi-bin/captive_login.cgi"
       Change the 192.168.0.1 to the address of your SW's green NIC.

       This is the page that an unauthenticated user will see first.  At
       a minimum, it prompts for a username and password.  This is also a
       good place to put a "terms of service" notice or any other kind of
       announcement.

9. (Optional) Edit these files to customize the web pages your users see.
       /var/smoothwall/mods/captive/successful_login.html
       This is the page that a newly-authenticated user will see.

       /var/smoothwall/mods/captive/error_acct_disabled.html
       If a user enters a valid username and password, but has had his
       account disabled, this is the page he will see.

       /var/smoothwall/mods/captive/error_bad_user_or_pass.html
       If a user enters an invalid username or password, this is the page
       he will see.

       /var/smoothwall/mods/captive/error_system.html
       Hopefully a user will never see this page, since it means that something
       is configured incorrectly, and a login failed.  Typically it means that
       the database that is corrupted, absent, or set with improper permissions.

10. Edit /home/httpd/cgi-bin/.htaccess and add the following lines to the end:
       <Files captive_gui.cgi>
       require user admin
       </Files>

11. Open the web GUI and add some users:
       https://smoothwall:441/cgi-bin/captive_gui.cgi


----------
Command Line Utilities

Everything that can be done through the GUI can also be done through the
command line.  There are no extra "command line only" features.  Each of
these programs is located in /usr/local/bin and is in your default path.

1. captive_adduser [username] [password] [hours until re-login] {"disabled" | "one-time"}
   Creates a new account, or modifies an existing one.  If you select a
   username that already exists, the old information will be overwritten.  If
   "disabled" or "one-time" isn't specified then the account is created in
   the enabled state.  Examples:
      captive_adduser billy BillyPass1 3.0
      captive_adduser joe JoesPassword75 1.0 disabled
      captive_adduser jimbob 123JIMbob 2.0 one-time

2. captive_deluser [username]
   Deletes an existing account.

3. captive_print
   Prints a list of all users, their passwords, login durations, account
   status, and (if logged in) their IP address, MAC address, and session
   time remaining.

4. captive_printuser [username]
   Same as captive_print, but will only print information for specified user.



----------
Credits & Acknowledgements

- NetWhiz for his iptables help and patience
- AwPhuch for his convenient nmap package
- the GNU gdbm hashed database library
- captive_httpd source derived from code in Stevens' Unix Network Programming


