SFSU Penalty Box
(c) 2004 San Francisco State University, All Rights Reserved
Licensed under the GNU Public License
This software comes with ABSOLUTELY NO WARRANTY; This is free software, and you are welcome to redistribute it under certain conditions; listed in the file LICENSE
Written for SFSU Housing by benjamin wilder <mrcawfee@users.sourceforge.net>
Includes Telnet.pm Copyright 1997, 2000, Jay Rogers. All rights reserved.
General Description
The penaltybox is a solution to certain users clogging the network. We give them a quota, the user can do a max set amount of traffic for a period of time. If they exceed that amount their connection will be limited. This is a way of 'encouraging' the users to keep their traffic down and at the same time not affecting the 90% of the users who do not consume most of the bandwidth. On our network 10% of the users use 50-60% of all the traffic, and when bandwidth is expensive this is alot. Limit the users who attempt to download every film ever made.
The users will be blocked immediatly when they exceed their limit, and they will be blocked from that point on for how ever long you set your time period. (eg we have a 10 gb/week limit, so if they go over on day 3, they will be limited to 64kbps until day 10, they will be blocked for an entire week after they have exceed their limit).
Required
libpcap
Download from http://www.tcpdump.org
Perl 5+
Packeteer Appliance http://www.packeteer.com/
PHP 4+
Optional Libraries
For Email Notification
libsmtp
This program is used to send email warnings to users when they
approach their limit, it is not needed for normal operation
Download from http://libsmtp.berlios.de/
glib
libsmtp requires GLIB
http://www.gtk.org
Installation
The penaltybox requires it's own working directory /usr/local/penaltybox will be fine, untar the entire package into the directory that you choose.
WITHOUT LibSMTP
$ make noemail
With LibSMTP
$ make
Errors related to hash_map or any error in trbree.h try this first:
$ make usemap
or
$ make noemail_usemap
If you get compilation errors about 'pcap' or 'smtp' then you don't have all the libraries installed, 'pcap' is required, 'smtp' is not, installing without smtp support is detailed above
Configuration
Main PB Configuration:
A sample configuration file is provided in [PB Home]/conf/pb.conf, the
variables are pretty self explainatory, the sample file is also commented
to help guide you along, most are path names and other simple configurations.
File permissions:
**This is extremely important, without correct permissions the penaltybox
may not work and it may not tell you that it isn't working correctly.
In the base directory there is a file permissions.sh, i highly suggest
you set this file to run as a cron job (using cron.txt has the configuration)
in case something happens to change the permissions, it allows access to certain
files that the web interface needs to interact, and some files need write access
from the webpage as well, this program will correct this, change the group
"www-data" to which ever user group apache runs under, you also are going
to need to change the directory structure.
Configuring your packeteer:
Telnet or ssh into your packeteer, you need to create the following classes and host lists
% class new inbound students folder
% class new outbound students folder
% hl new penaltybox
% class new inbound/students redirect inside list:penaltybox outside service:http
% policy apply never-admit inbound/students/redirect
% policy admit inbound/students/redirect [URL to penalty box's student page]
% class new inbound/students allowed outside host:[URL to penalty box's student page] inside list:penaltybox
% class set inbound/students/allowed exception
Allowing users to check their bandwidth usage
- Viewing the webpage The pbhome/student directory contains all of the functions that are needed for the student to check their bandwidth usage. It will automatically get their ip address and show them their statistics. I suggest making this directory the DocumentRoot directory of your apache server.
- Embedding the graph in another PHP Document
there is a way to embed the graph of their bandwidth usage into
another php document. All this will print is the graph.
Here is some example code:
<? readfile ("http://student.check.url/index.php?noHeaders=true"); ?>
How will they be notified when they are blocked?
The PB will configure the packeteer to redirect the users to the web page to
view their statistics, it will have a section saying that they have exceeded
their bandwidth quota and to be removed from the redirect they have to click
okay and the redirect will be removed and they can continue surfing at their
limited speed. This is where the permission problem affects the users the most,
if the pb program cannot write to the file they will never be removed from
the redirect! so it is extremely important that the apache server can modify
certain files (permissions.sh)
Administration Web Page
This is located in [pbhome]/public_html directory, this contains all of the
functions to view the users that are currently stuck in the penaltybox, as
well as the statistics of all users on the network. Combined with the Directory
Lookup (see below) you can use it to track down people who are using static
ip addresses as they will show up on the list as "Unknown". The penaltybox
allows you to restrict access to this page to specific subnets if needed.
The Directory Lookup
The penaltybox has the ability to retrieve the user's name, email and room
number from a server. Because your systems are different than anyone else's
i have made this an extremely general function that you probally are going
to have to create an interface yourself to make work.. But i have an example
for you. When the pb detects a user that it does not know, it will send their
mac address to the directory server and request that information. It sends
the information to a WEB PAGE. The macs will be sent in the GET field in the
form of a PHP array called "macs", and it will expect the directory to return
the formatted data, if the data is not in the correct format it will just
ignore the error and continue.
Data format:
BEGIN\n
[Mac Address]\n
[Name]\n
[Email Address]\n
[Room]\n
END\n
Example PHP Code:
<?php
$macs = $_GET['macs'];
foreach($macs as $mac) {
$userInfo = GetUserInfo($mac);
print "BEGIN\n$mac\n{$userInfo['name']}\n{$userInfo['email']}\n{$userInfo['room']}\nEND\n";
}
?>
It is fairly simple, it is your job to write the function to get that data from wherever you have it.
Configuring Your Server
I recommend that you have atleast 2 NICs in your server.
NIC 1 - Web interface
NIC 2 - Traffic Mirror
The reason i suggest this is when traffic starts to increase the time it takes to view the interface becomes frustratingly slow. The second nic doesn't even need to have a real IP address, acually i suggest you don't, that way all it will do is recieve traffic and it can not send any out of that nic.
Configuring Your Network
The penaltybox server needs to be in an area that it can view all traffic from the network.
Hubbed network
All Traffic goes to all ports so as long as you can view the entire
network's traffic you can pretty much put it anywhere.
Switched Network
This gets alittle more tricky because the switch doesn't broadcast
to all ports. Put the penaltybox on the core of your network, some
switches, probally most, have a mirror port or the ability to turn
one port into a mirror port. For the penalty box to work it needs
to be in a mirror port. The PB is essential a packet sniffer which
just counts the size of the packets it recieves, so it needs to
recieve everything to get an accurate count of the traffic.
Issues with VLANs.
The penalty box is NOT vlan aware, it cannot differentiate between
2 vlans. The issue arises when you have multiple packeteers for
each VLAN. The penaltybox won't know which one to talk too. If that
doesn't matter, and the entire network is just on one packeteer then
the pb MAY* work.
* I have not tested this, and i am saying this with a fairly limited
knowlege of how the vlan works, so i am leaning towards it may work.
Work around this problem:
multiple NICS. each plugged into a specific vlan. But you need
a different configuration file for each vlan and a seporate copies
of pb running. This works for my network. and it also requires some
hacking php files so it knows which set of data to use when viewing the admin page
or viewing statistics.
Yes i know this readme is incomplete, but i hate writining documentation, if you have any other questions you can always email me at mrcawfee@users.sourceforge.net