Back to files

SFSU Penaltybox
(c) 2004-2006 San Francisco State University Licensed under the GNU General Public License v2 See file COPYING for details

Written by: Benjamin Wilder
mrcawfee@cawfee.org

Needed Hardware

This is designed to work with a PacketShaper network appliance (http://www.packeteer.com) to do all of the complex limiting.

Needed Packages

libcurl3 Development packages
libpcap Development packages

php5
-with sockets enabled (see http://www.php.net/manual/en/ref.sockets.php)

Command Line Options

  --help          show the help messsage
  --verison       print version information
  -d              run as daemon
  -c [file]       select configuration file
  -i [iface]      interface to listen on
  -v              verbose output (doesn't work with -d)
  -nocheck        bypass permissions checking
  -p [file]       custom pid file
  -show           output current hosts and quit
  -t              output the traffic
  -dump           just output the traffic, don't do any logging or limiting (requires -i)
  -u [min]        minutes between file updates

Tested On

Unfortunately I have only tested this verison on: Debian Sarge
Ubuntu 6.06

ToDo

Better Admin Page
Ability to remove users from the limit
(can't think of a good way to do it from the webpage becides reading a text file everytime it updates... i hate that idea)

Compiling

# ./confiugure
# make
# make install
# sh install_finish.sh

Configuration

Network Placement:

You need to place the server, with a mirrored port at the core end of your network. If you aren't at the core, then the server won't be able to count all of the traffic that going around your network.

Server Configuration:

You are going to need a computer with 2 NIC cards, one configured with a real ip address and another configured with a fake one, this is where the mirror port from your switch will be connected.

Sample Debian Configuration:

# fake network
iface eth2 inet static

        address 172.10.10.2
        netmask 255.255.255.0

# real ip address
iface eth1 inet static

        address 10.10.10.10 
        netmask 255.255.255.0
        network 10.10.10.0
        gateway 10.10.10.254
        broadcast 10.10.10.255

Connect the mirrored port in your switch to the second interface.

Testing to see if the mirror port works

run the penaltybox program:

./penaltybox -dump -i eth2

if you see lots and lots and lots of traffic being outputed, it's a good bet that you are getting the traffic from this switch.

The Configuration File

Default location for the configuration file is /usr/local/etc/pb.conf

-----pb.conf----
verbose false

section network

        # the ethernet adapter for the mirrored port
        adapter "eth1"  
        #list all of your subnets
        range "10.0.0.1-10.0.0.230"
        range "10.0.1.1-10.0.1.230"
        #hosts to ignore
        ignore "10.0.0.53"

end

section filesystem

        hostdirectory   "/usr/local/lib/pb/hosts/"
        summary_xml     "/usr/local/lib/pb/pb.xml"
        file_update_min 3       # refreshes every 3 minutes

end

section limit

        enable  true
        threshold 10240         # how much bandwidth they are allocated in MB
        limit_length    7       # how long their limiting period is in days
        limit_bandwidth 64      # the speed they get after they are limited     

        # this is the configuration of your packet shaper
        section limiter
                type "packeteer"
                range   "10.0.0.1-10.0.0.255"
                address "10.0.0.253"
                password "password"
                # serial # of the packeteer
                serial "056-1151515"
        end
        
        # .. you can specify more limiters with
        # different ranges if you have multiple 
        # packetshapers

end

Configuring the Webpage

Move the subdirectory penaltybox_web into the web directory of your server, and make sure you have php5 installed.

Edit the configuration file "config.php" in the web directory

----config.php------
<?php

$packeteers = new PacketeerList;

$mary       = new Packeteer;
$mary->setAddress('10.0.0.1');          // IP Address of your packeteer
$mary->setSerial('045-0000000');        // Serial # of your packeteer
$mary->setPassword('password');         // Password of your packetere

$mary->addRange('10.0.0.1', '10.0.0.254'); $packeteers->addPacketeer($mary);

// Repeat above step for more packet shapers // $tcs = new Packeteer
// $tcs->setAddress('12.0.0.2');
// $tcs->setSerial('065-00000000');
// $tcs->setPassword('wooo password');
// $tcs->addRange('12.0.0.1', '12.254.254.254'); // $packeteers->addPacketeer($tcs);

// Configuration
// These values need to match the ones you entered in // pb.conf

$threshold                      = 10 * pow (2,30);      // 10 GB
$update_sec                     = 3 * 60                // 3 minutes
$limit_length           = 7;                    // days
$limit_speed            = 64;                   // in kbps

$admin_user             = "user";
$admin_pass             = "pass";

// HostDirectories list

$host_directories       = array (
        "/usr/local/lib/pb/hosts",
);
$summary_xml            = array (
        "/usr/local/lib/pb/pb.xml"

);

Files to edit for custom data (not sure if you want our contact info on all your pages ;)

penaltybox_web/page_foot.php
penaltybox_web/tail_text.php

Running the penaltybox

# /usr/local/bin/penaltybox

Running in daemon mode

# /usr/local/bin/penaltybox -d

Running when your server starts

Because this is very server specific i created a few scripts but they won't install automatically

penaltybox.debian       -- init.d startup script that works with debian and ubuntu
penaltybox.initd        -- Generic startup script that should work with other distros

Configuring Your PacketShaper

First SSH into your packeteers that you are using and enter these commands:

Packeteer class new Inbound students folder Packeteer class new Outboud students folder Packeteer hl new penaltybox
Packeteer class new Inbound/students redirect inside list:penaltybox Packeteer policy apply never-admit Inbound/students/redirect Packeteer policy admit Inbound/students/redirect "http://<<<Penaltybox Webiste>>>" web Packeteer class new Inbound/students pbserver inside list:penaltybox outside host:<<<Penaltybox Website>> Packeteer class set Inbound/students/pbserver exception

The only thing REQUIRED of those are the first 3 lines, the rest create a webredirect to notify the user when they get limited

BUGS With the Web-Redirect:
I suggest that you test the web-redirect, which is the only part of the penaltybox that is problematic. If your packeteer is being overloaded the web redirect has been known on our network to function improperly, that includes students being unable to view web pages where they recieve a "Document Contains No Data" message.

Test the web redirect by manually inserting a known host into the host list as follows: Packeteer# hl add penaltybox <ip address> and see if it works, usually it does but it has been known to fail (we have 3, on one of our 4500s i had to disable the web redirect because of this problem). to disable the web redirect just delete the 'redirect' class.