Differences between revisions 1 and 2
Revision 1 as of 2005-07-09 23:29:23
Size: 7271
Editor: c-24-21-38-183
Comment: Initial snarf. -jmc
Revision 2 as of 2005-07-11 10:50:28
Size: 7352
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= NoCatAuthInstallationGuide =
Note: this text is from the INSTALL file located in the NoCatAuth software package. The latest version should be in the current tarball.
NoCatAuth installation guide
 Note: this text is from the INSTALL file located in the NoCatAuth software package. The latest version should be in the current tarball.
= NoCatAuth installation guide =
Line 10: Line 9:
Line 11: Line 11:
Line 31: Line 32:
-=-=-=-=-=-=-
Line 36: Line 36:
1. Make sure you have the prerequisites installed:  1. Make sure you have the prerequisites installed:
Line 38: Line 38:
* 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. Support for ipchains is beta, and is currently broken. Patches welcome.   * 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. Support for ipchains is beta, and is currently broken. Patches welcome.
Line 40: Line 40:
* gpgv, a PGP signature verifier. gpgv comes with the gnupg package, which can be downloaded from http://www.gnupg.org/download.html   * gpgv, a PGP signature verifier. gpgv comes with the gnupg package, which can be downloaded from http://www.gnupg.org/download.html
Line 42: Line 42:
* 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.   * 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.
Line 44: Line 44:
* If you want to try the 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/   * If you want to try the 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/
Line 46: Line 46:
* Optionally (and recommended), a local caching DNS server.
2. Unpack the NoCatAuth tarball.
  * Optionally (and recommended), a local caching DNS server.
 2. Unpack the NoCatAuth tarball.
Line 51: Line 51:
3. Edit the Makefile  3. Edit the Makefile
 if necessary. The only real option at present is INST_PATH, which determines where NoCatAuth gets installed to. The default is '/usr/local/nocat', so if that's okay with you, you can skip this step.
Line 53: Line 54:
if necessary. The only real option at present is INST_PATH, which determines where NoCatAuth gets installed to. The default is '/usr/local/nocat', so if that's okay with you, you can skip this step.
4. make gateway
 4. make gateway
 From the NoCatAuth directory, run 'make gateway'. This will install the important pieces of the gateway software.
Line 56: Line 57:
From the NoCatAuth directory, run 'make gateway'. This will install the important pieces of the gateway software.
5. edit Configfile
Edit the /usr/local/nocat/nocat.conf file to suit. These parameters are required:
 5. edit Configfile
 Edit the {{{/usr/local/nocat/nocat.conf}}} file to suit. These parameters are required:
Line 60: Line 60:
* InternalDevice must be set to the interface name of your wireless card, or the ethernet card that talks to your AP (e.g., eth0. See docs/Introduction.txt for more details.)   * !InternalDevice must be set to the interface name of your wireless card, or the ethernet card that talks to your AP (e.g., eth0. See docs/Introduction.txt for more details.)
Line 62: Line 62:
* ExternalDevice must be set to the name of the network interface that talks to the Internet. (probably the ethernet card connected to your DSL or cable modem, or your dialup device: eth1, ppp0, etc.)   * !ExternalDevice must be set to the name of the network interface that talks to the Internet. (probably the ethernet card connected to your DSL or cable modem, or your dialup device: eth1, ppp0, etc.)
Line 64: Line 64:
* LocalNetwork needs to be set to the network address and mask of your internal (wireless) network. This typically takes the form 111.222.333.444/255.255.255.0, or 11.22.33.44/24, etc.   * !LocalNetwork needs to be set to the network address and mask of your internal (wireless) network. This typically takes the form 111.222.333.444/255.255.255.0, or 11.22.33.44/24, etc.
Line 66: Line 66:
* !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 LocalNetwork (as specified above). Otherwise, if you're using a caching DNS server on the gateway or anywhere else on your wireless network, leave this option commented out.   * !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 LocalNetwork (as specified above). Otherwise, if you're using a caching DNS server on the gateway or anywhere else on your wireless network, leave this option commented out.
Line 68: Line 68:
* GatewayMode toggles between Open and Captive mode. An Open gateway just displays the html file specified in SplashForm for acceptance. Captive mode implements the whole authentication process. If you want people to have to login, use Captive mode.   * !GatewayMode toggles between Open and Captive mode. An Open gateway just displays the html file specified in SplashForm for acceptance. Captive mode implements the whole authentication process. If you want people to have to login, use Captive mode.
Line 70: Line 70:
* AuthServiceAddr, !AuthServiceURL, and !LogoutURL depend on your chosen auth service (assuming you're using Captive as your GatewayMode.) Check with your local auth service admins for these values (or leave the defaults to use our auth service.)   * !AuthServiceAddr, !AuthServiceURL, and !LogoutURL depend on your chosen auth service (assuming you're using Captive as your !GatewayMode.) Check with your local auth service admins for these values (or leave the defaults to use our auth service.)
Line 72: Line 72:
* IncludePorts and ExcludePorts can be set to restrict ports that public users can access (say, 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 gateway
  * !IncludePorts and ExcludePorts can be set to restrict ports that public users can access (say, 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 gateway ==
Line 89: Line 89:
Line 93: Line 94:
Line 99: Line 101:
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: 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:
Line 106: Line 108:
* Make sure that your dhcp server hands out the same DNS address listed in nocat.conf (if you're using external DNS). Otherwise, your wireless clients won't be able to resolve hostnames.  * Make sure that your dhcp server hands out the same DNS address listed in nocat.conf (if you're using external DNS). Otherwise, your wireless clients won't be able to resolve hostnames.
Line 108: Line 110:
* We have designed this software to be run on very modest hardware (a 486/50 with 32MB ram should be plenty.) Please consider running the gateway on a dedicated machine before simply installing it on your existing firewall.  * We have designed this software to be run on very modest hardware (a 486/50 with 32MB ram should be plenty.) Please consider running the gateway on a dedicated machine before simply installing it on your existing firewall.
Line 115: Line 117:

----
[CategoryNoCat] [CategorySoftware]
  • Note: this text is from the INSTALL file located in the NoCatAuth software package. The latest version should be in the current tarball.

NoCatAuth installation guide

This is the quick-and-dirty guide to getting a wireless gateway running with the NoCatAuth system. If you simply want to "run a NoCat node", this should get you going.

For detailed instructions on how to set up your own Authentication Service (and a good overall view of how this whole thing works), check out Introduction.txt and AuthService.txt in the doc/ directory.

We don't recommend running the gateway and the authservice on the same machine, but if you're dead-set on doing it, be sure to read doc/SameMachine.txt *first*.

Installing a Gateway

For the terminally impatient

Check your prerequisites as below. Then, try the following:

      $ su -
      # tar zvxf NoCatAuth-x.xx.tar.gz
      # cd NoCatAuth-x.xx
      # make gateway
      # cd /usr/local/nocat
      # vi nocat.conf
      # bin/gateway 

If you see something to the effect of:

      [2001-12-28 20:38:27] Resetting firewall.
      [2001-12-28 20:38:27] Binding listener socket to 0.0.0.0 

...then you're up! Watch the progress in 'nocat.log', and give it a try.

Step by step

Currently, the gateway is designed to run on a standalone box. If you have other firewall rules defined, THEY WILL BE OVERWRITTEN by the gateway process when it starts. See the end of this file for how to get around this, but please first consider running the gateway on its own machine.

Also, remember that running a gateway requires root permissions.

  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. Support for ipchains is beta, and is currently broken. Patches welcome.

    • gpgv, a PGP signature verifier. gpgv comes with the gnupg package, which can be downloaded 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.
    • If you want to try the 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/

    • Optionally (and recommended), a local caching DNS server.
  2. Unpack the NoCatAuth tarball.

      $ tar zvxf NoCatAuth-x.xx.tar.gz 
  1. Edit the Makefile

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

  2. make gateway

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

  3. edit Configfile

    Edit the /usr/local/nocat/nocat.conf file to suit. These parameters are required:

    • InternalDevice must be set to the interface name of your wireless card, or the ethernet card that talks to your AP (e.g., eth0. See docs/Introduction.txt for more details.)

    • ExternalDevice must be set to the name of the network interface that talks to the Internet. (probably the ethernet card connected to your DSL or cable modem, or your dialup device: eth1, ppp0, etc.)

    • LocalNetwork needs to be set to the network address and mask of your internal (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 LocalNetwork (as specified above). Otherwise, if you're using a caching DNS server on the gateway or anywhere else on your wireless network, leave this option commented out.

    • GatewayMode toggles between Open and Captive mode. An Open gateway just displays the html file specified in SplashForm for acceptance. Captive mode implements the whole authentication process. If you want people to have to login, use Captive mode.

    • AuthServiceAddr, !AuthServiceURL, and !LogoutURL depend on your chosen auth service (assuming you're using Captive as your GatewayMode.) Check with your local auth service admins for these values (or leave the defaults to use our auth service.)

    • IncludePorts and ExcludePorts can be set to restrict ports that public users can access (say, 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 gateway

You should now be able to start the portal by running bin/gateway as root. You'll see a message to the effect of:

      [2001-12-28 20:38:27] Resetting firewall.
      [2001-12-28 20:38:27] Binding listener socket to 0.0.0.0 

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 very hard 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 should be in your $PATH somewhere (if they aren't already). For example:

      $ export PATH=$[PATH]/sbin:/usr/sbin:/usr/local/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.

Important Notes for the Gateway

  • Make sure that your dhcp server hands out the same DNS address listed in nocat.conf (if you're using external DNS). Otherwise, your wireless clients won't be able to resolve hostnames.
  • We have designed this software to be run on very modest hardware (a 486/50 with 32MB ram should be plenty.) Please consider running the gateway on a dedicated machine before simply installing it on your existing firewall.
    • IP security is a complicated enough already... NoCat adds to the complexity by introducing dynamic firewall rules that are triggered by completely anonymous users (via the wireless.) While no security system is foolproof, risk can be minimized by isolating your wireless node from the rest of your network. Please read docs/Introduction.txt (and a good book on firewalls) for more details.

Thanks for using NoCatAuth. GOOD LUCK! PATCHES WELCOME!


[CategoryNoCat] [CategorySoftware]

NoCatAuthInstallationGuide (last edited 2007-11-23 18:01:56 by localhost)