Depleting usable bandwidth since April 30, 2000

Cattasaurus

What is Cattasaurus or a captive portal?

A captive portal snags users making HTTP connections and redirects them to a local page using packet mangling. Traditionally, captive portals are either expensive or require a significantly large footprint. Since large footprints dont play particularly well with embedded systems (with barely 8-16 megs worth of flash drive space), I decided to work on a small captive portal for OpenBSD or any other platform that offers the same "pf" (Packet Filter) abilities as OpenBSD. Currently, the total uncompressed size of Cattasaurus is ~420k -- including support executables. Due to its very small interpreter size, the language "REXX" was used. That noted and the fact that this is a spinoff of the whole NoCat project and you have our corny little name.

What is the status of this project?

I put this page up shortly after I had completed this program (11-25-2002), so its rather new at the moment. The first release is very basic and consists of many security issues and yet-to-be-desired fuctions I will list bellow. Currently, it is not intended as an authentication system, but rather a "splash screen" to display a simple message to newcomers.

I keep on hearing the "release early and often" thing by all those open source people, so i guess here it is in the raw.

Also note that although this script does function properly, it should only be ran in controled environments. It is not ready for public primetime (next release it should be).

Current Features:

  • Redirects any inital HTTP traffic to a static splash intro page
  • Removes redirect once user clicks on specific link
  • Pretty small!

    • What it does not yet do but should:

  • Allow usage of images and non-hardcoded splash screens
  • Should not have to be ran as root (use sudo?)
  • Reap expired connections with some sort of reaper service
  • Make use of MAC + IP when filtering (just uses IP for now)
  • Redirect to requested site after clicking out of splash screen (shows debug now)
  • Optional feature to redirect to specific site after clicking out of splash screen
  • Logging, statistics, etc.
  • Installer or at least a README

    Download here: Cattasaurus0.001.tar.gz

    Installation Instructions

    This wont be too much fun, but here we go ...

    First, unzip/tar that archive into /usr/local/cattasaurus/

    You will find the following files:

    auggy-service.rexx - the actual service written in REXX (regina)
    faucet - a mini inetd service, copy this into /usr/local/bin/ or /usr/sbin/
    getpeername - obtain the ip address of the connecting client while as an inetd service, copy this into /usr/local/bin or /usr/sbin
    rexx - Regina rexx compiled for OpenBSD, copy this into /usr/bin/

    Next, make sure you have a working configuration for pf. This would be /etc/pf.conf and /etc/nat.conf

    If you do not have a pf.conf, enter the following into /etc/pf.conf. Note that we really dont touch anything in this file, but it has to exist in order for other pf functions to operate. If you already have stuff going on in pf.conf, skip over this part. 

    # pass all packets in and out (these are the implicit last two rules)
pass in all
pass out all

    /etc/nat.conf has both port forwarding and NAT functions. Cattasaurus' magic is in port forwarding. Cattasaurus won't interfere with your configuration, but you will need to at least add these lines. You must put them at the bottom of your file.

    Cattasaurus uses the "# start big hack" keyword as a starting point. So you should keep this comment intact. I havent quite figured out how Regina rexx handles EOF's, so you *MUST* put "# EOF" at the end. Otherwise you will get a pretty suprise when you run out of diskspace and have to kill the task.

    To keep things short, I have just included 4 entries. But you must create one line per DHCP address you wish to put behind "cattasaurus". I know, a lot of this is stupid and I'll fix this in the next release. I use port 5281 local on the box for my auggy-service.rexx inetd service. You can change this if you want.

    "rl0" is my ethernet interface on my OpenBSD router, you can change this if you have a different interface name.

    "10.22.17.100/32" is the start of my DHCP address space I dish out. You must create one of these for each address ... ugh

    the "10.22.17.1" address is the address of the router. This would be the OpenBSD box you wish to run "Cattasaurus" on. 

    # start big hack

rdr on rl0 proto tcp from 10.22.17.100/32 to any port 80 -> 10.22.17.1 port 5281
rdr on rl0 proto tcp from 10.22.17.101/32 to any port 80 -> 10.22.17.1 port 5281
rdr on rl0 proto tcp from 10.22.17.102/32 to any port 80 -> 10.22.17.1 port 5281
rdr on rl0 proto tcp from 10.22.17.103/32 to any port 80 -> 10.22.17.1 port 5281

# EOF

    After you have set up these pieces, you are ready to go.

    "Cattasaurus" must be ran as root -- oh i know your heart stopped there -- so i suggest only running this software for experimental purposes only. This problem will be fixed in the next release, and will probably make use of something like sudo and require the creation of a new user.

    "Cattasaurus" executes "pfctl" and I can only do that at root. Thats the only reason why.

    Finally, start the service by typing the following command line:

    faucet 5281 --in --out --daemon /usr/local/bin/rexx /usr/local/cattasaurus/auggy-service.rexx

    the --daemon option will then return you to the console and launch faucet as a daemon. --in and --out just pipe I/O to the program executed. Its really simple, really cute. You can find other uses for faucet im sure. Its small :)

    Now after a client passes the flash screen, the address will remain unsplashed forever. This will be fixed once I write a reaper daemon to clean up expired connections....or...you could write one yourself!