###
## NoCatAuth installation guide
##
ver 1.2 -- 8/15/01 


###
## 6 Easy Steps to Installing Your Very Own Captive Portal.
##

Running a captive portal requires root permissions on the gateway machine.

1. Make sure you have the prerequisites installed:
    
    * Linux 2.4.x with iptables. You'll find a sample kernel configuration
	in etc/linux-2.4.config. Support for other OSes is planned, 
	especially FreeBSD. Patches welcome.

    * gpgv, a PGP signature verifier. gpgv comes with the gnupg package, 
	which can be had from http://www.gnupg.org/download.html.

    * You'll probably also want to run dhcpd on this machine, but DHCP
	can in some cases be served from your access point or elsewhere on 
	your local network. Make sure that, if you're using external DNS,
	that your dhcpd hands out the same DNS address listed in nocat.conf.

    * If you want to try the (experimental) bandwidth throttling rules,
        you'll also need a copy of the 'tc' tool from the iproute2 package.
        Get it at ftp://ftp.inr.ac.ru/ip-routing/.

2. Unpack the NoCatAuth tarball. You probably already did this if you're
reading this file.

    $ tar xvfz NoCatAuth-x.xx.tar.gz

3. Read the README.

4. Edit the Makefile, if necessary. The only real option at present is
INST_PATH, which determines where NoCatAuth gets installed to. Defaults 
to '/usr/local/nocat', so if that's okay with you, you can skip this step.

5. From the NoCatAuth directory, run 'make gateway'. This will install the
important pieces of the captive portal software.

6. Edit the /usr/local/nocat/nocat.conf file to suit.
    
    * InternalDevice must be set to the interface name of your wireless card,
	or the ethernet card that talks to your AP.

    * ExternalDevice must be set to the name of the network interface
	that talks to the Internet, e.g. the ethernet card connected to your
	DSL or cable modem.

    * LocalNetwork needs to be set to the network address and mask of your
	internal (e.g. wireless) network. This typically takes the form 
	111.222.333.444/255.255.255.0, or 11.22.33.44/24, etc.

    * DNSAddr needs to be set to the same domain name server address that your 
	DHCP server hands out, if and only if you're using a DNS outside your
	local network (as specified above). Otherwise, if you have an internal
	DNS, leave this option commented out.

    * AuthServiceAddr, AuthServiceURL, and LogoutURL depend on your chosen
	auth service. Check with them for these values.

    * IncludePorts and ExcludePorts can be set to restrict ports that public
        users can access (i.e., to disallow email traffic.)  If you use
        IncludePorts, only the ports listed will be allowed.  Using
        ExcludePorts makes all ports available *except* the ports listed. 
        Currently, only TCP ports are supported.


###
## Starting the NoCatAuth captive portal.
##

You should now be able to start the portal by running
/usr/local/nocat/bin/gateway as root.  If it doesn't start cleanly, read on.

The portal needs to know where to find (a) its perl libraries, and (b) its
nocat.conf configuration file. NoCatAuth tries to figure out these values
on its own. If you installed to /usr/local/nocat, you should have no
problems.

Otherwise, you may need to add the following variables to the
shell environment before running the gateway script:

    $ export PERL5LIB=/path/to/nocat/lib:$PERL5LIB
    $ export NOCAT=/path/to/nocat/nocat.conf

Utilities like iptables, modprobe, and gpgv need to be in your $PATH somewhere
(if they aren't already). For example:

    $ export PATH=$PATH:/sbin:/usr/sbin

Starting the gateway is then as simple as: (from a root prompt)

    # /path/to/nocat/bin/gateway

NOTE: You MUST run the gateway program as root, in order for it to be able to
update the firewall rules as needed. Arguably, this is a bug. Patches welcome.

To start the gateway service automatically at boot time, check out the
etc/nocat.rc script.  Install it by copying it to /etc/rc.d/init.d, and
either add a call to it in your rc.local, or symlink it to your runlevel,
like this:

    # ln -s /etc/rc.d/init.d/nocat.rc /etc/rc.d/rc3.d/S99nocat

Congratulations.  You're now running a gateway.


###
## Running Your Own Auth Service.
##

If you're just running a wireless node, you can skip this section.

NoCatAuth needs gpg from gnupg.org, and the Digest::MD5 and DBI modules from
CPAN. You'll also need to install the appropriate DBD modules for your
database. We use mysql, but the SQL isn't complex, and PostgreSQL, or indeed
almost any other relational database should work.  You'll need a database to 
store your user accounts -- you can find table schemas in etc/nocat.schema. 
You'll need an Apache installation with SSL working. The nocat.conf options
should be fairly self-explanatory. You can find NoCat-specific Apache 
configuration in etc/authserv.conf. You'll need to make the cgi-bin scripts
accessible from somewhere.

Work is actively in progress to integrate a single shared membership database
for the various wireless groups that have expressed an interest in
participating. If you're starting a community wireless network of your own,
and might be interested in roaming agreements with other groups, drop us a
line at authservice@nocat.net.

### Thanks for using NoCatAuth. GOOD LUCK! PATCHES WELCOME!
