Programmed by David Hinkle, Commissioned by DerbyTech Routers of Illinois.  
Special thanks goes to Brice Beaman at brice@beamans.org for releasing the 
software and helping with debugging, Blaze at ts@spective.net for his 
excellent logo, and all the guys at havok for distributing clue.

You may use this software under any verson of the GPL that is current as of
your download.  For exact terms and conditions please see www.gnu.org.  

# WHAT IT IS #
Bandwidthd is a unix deamon for graphing the traffic generated by each machine
on several configurable subnets.  It is much easier to configure than mrtg, and
provides significanlty more usefull information.  Mrtg only tells you how much
bandwidthd you are using, bandwidthd tells you that, and who is using it.

Each ip address that has moved any significant volume of traffic has its own
graph.  The graphs are color coded to help you figure out at a glance if your
user is surfing the web, or surfing Kazaa.

Bandwidthd is targeted to run on my routing platforms.  It is very low 
overhead.  Easily graphing a small buisnesses traffic on a 133Mhz Elan 486
every 2.5 minutes. My entire ISP (2000-3000 Ip addresses across 4 states) is 
graphed on a celeron 450 every 10 minutes. 

# PORTABILITY #
Bandwidthd has been made to successfully run on a large number of 
architectures.  However, I don't have access here to anything other than 
linux.  If you would like to provide support for another architecture, 
simply preform the neccisary modifications and post me a patch on sourceforge.
I'll see that it gets in.

# INSTALATION INSTRUCTIONS #

Get and install libpcap from http://www.tcpdump.org/
Get and install libpng from http://www.libpng.org/
Get and install libgd from http://www.boutell.com/gd/
Make sure your system supports System V IPC

make install

edit /usr/local/bandwidthd/etc/bandwidthd.conf

It's a list of the subnets to collect info on, and the device to listen
on.

Bandwidthd will install under /usr/local/bandwidthd.  It will create a
htdocs directory.  When you run bandwidthd, it creates its web tree in
htdocs in the current directory, so cd to /usr/local/bandwidthd and run it
with "./bandwidthd".  If you run it with "/usr/local/bandwidthd" it will not
work.

# GRAPHING INTERVAL #
Bandwidthd defaults to graph up to 4000 local ip's every 2.5 minutes.  If you 
need to track more ip's, change IP_NUM in bandwidthd.h.  More ip addresses 
require more system V shared memory. 3000 ip addresses uses 216k*4.

The weekly graph updates every 10 minutes, monthly every hour, and yearly 
every 12 hours.

A graphing run will automatickly be "skipped" if that last one isn't finished 
before the new one would begin.

# CDF LOGGING #
Bandwidthd can be made to log to CDF by setting "output_cdf" to true. This will 
now log out each intervals traffic, so you can import them into a database and 
use a tool like access to create your own graphs, or implement 95 percentile 
billing, for example.  Sending bandwidthd a HUP will cause it to rotate it's 
logs. It will rotate out 5 times before deleting the oldest log file. 

Only the 2.5 minute interval logs rotate at this time.  These logs are log.cdf,
log.cdf.1, log.cdf.2 etc...  log2.cdf is the same data with a 10 minute 
interval for the weekly graph, log3.cdf is an hourly interval for the monthly
graph, and log4.cdf is a 12 hour interval for the yearly graph.

The log format is best documented in the "StoreIPDataInCDF" function in 
bandwidthd.c.  As of this writing, it consists of one line for each ip address
for each interval.  The line contains only data for the previouse interval.

Fields:
IP Address,Timestamp,Total Sent,Icmp Sent,Udp Sent,Tcp Sent,Ftp Sent,Http Sent, P2P Sent,Total Received,Icmp Received,Udp Received,Tcp Received,Ftp Received,Http Received, P2P Received

# GRAPHING
Also note that bandwidthd does not bother to graph an ip that has trasmited
less than 1Mbit of data.  It does however, include that ip in the table of ip's
at the top of the page, so it's traffic can still be viewed.  This cutoff can
be changed by modifying graph_cutoff in bandwidthd.conf.  "graph_cutoff" is in 
kilobytes.

Graphing can be disabled by setting "graph" to false. This will still log, and
still build the table of ip's, but the graph section will be omited.

# HOW TO KEEP YOUR GRAPHS BETWEEN REBOOTS #
In the bandwidthd.conf file set:
output_cdf true
recover_cdf true

output_cdf will cause bandwidthd to log all of it's data to the log.cdf file 
in it's directory.  recover_cdf will cause bandwidthd to load that file when 
it starts.   You will also want to make a crontab entry like so:

0 0 * * * * /bin/killall -HUP bandwidthd

This will send bandwidthd a HUP every night at midnight.  When bandwidthd 
recieves a HUP it rotates it's log files.  Bandwidthd will also recover data
from the rotated log files when it starts.  It will rotate each log file out
5 times, then delete it.  Bandwidthd creates pretty big logs if it's tracking
alot of ip addresses, so you will want to do this.

# COLOR CODES #
RED 	ICMP
BROWN	UDP
YELLOW	IP ENCAPSULATED (Ip over Ip, IPSEC, most VPN's)
BLUE 	HTTP (Port 80 TCP, actually)
PURPLE	Peer2Peer (Lots of TCP ports generally used by P2P software)
GREEN	TCP

# SPECIFYING THE LIBPCAP FILTER #
if you'd like more control over what traffic is counted, you can specify a
manuel filter to be passed to libpcap.  You can use this to remove certain 
ip's or only graph certain ip's, or limit the graphs to certain kinds of 
traffic.  You should always specify "ip" in the filter.  For example:

filter "ip and host 64.215.40.1"

# HOW TO IMPROVE PERFORANCE #
Bandwidthd's primary bottleneck is the drawing of graphs for ip addresses.  To
improve bandwidthd's performance, therefore, the only thing you can really do 
is reduce the number of graphs it has to draw in any given run.  Adjust 
graph_cutoff in the bandwidthd.conf file in order to tune out the ip addresses
that don't use so much bandwidth.  These ip addresses will still have their 
data displayed in the table at the top of the page, so you can still see
what's going on with them.

Alternativly, you can choose to graph less often.  Bandwidthd automatickly 
skips a graphing run if the last one is still going when the new one is 
scheduled to start.  If you'd like to graph less often than your server is 
capeable of, you can edit skip_intervals in bandwidthd.conf.  A value of 1
means to skip every other interval, 3 would mean to skip three intervals 
between each run.  This doesn't disable bandwidthd's automatic skipping.

# KNOWN BUGS AND TROUBLESHOOTING #

Bandwidthd doesn't do a very good job of tracking ftp.  This is because only
some ftp server software follows the rfc standard of sourceing all ftp 
transfers from port 20.  Surprisingly, Microsofts ftp deamon is compliant in
this regard, whereas most open source deamons are not.

If you try to compile bandwidthd with sun make, you'll get this error:
make: Fatal error in reader: Makefile, line 13: Unexpected end of line seen
Compile with gnu make, or overwrite Makefile with Makefile.solaris.

Some versions of make shipping with OpenBsd complain about missing dependancy 
operators.  Use gnu make if you can, if you can't, figure out how to fix the 
make file and supply me with a Makefile.OpenBsd.

Sometimes bandwidthd won't make, canning out with an error like:
bandwidthd.c:251: Structure has no member named `source'
bandwidthd.c:252: Stucture has no member names `dest'

This is because there are two versions of the tcphdr structure.  Some unixes
use `source' and `dest', others use `th_sport' and `th_dport'.  If you get the
error, change the "#ifdef SOLARIS" line to "#ifdef TRUE".  If someone can shed
some light on this situation for me, that would be great.

Bandwidthd always runs out of the current directory, it doesn't go looking in 
/usr/local/bandwidthd for it's stuff.  Always cd to /usr/local/bandwidthd (or,
for that matter, wherever you want to put it) before you run it.

Bandwidthd forks to perform it's graphing functions.  After this fork finishes 
it remains as a zombie until the next interval, at which time it is reaped by 
the main process.  This zombie is nothing to worry about, it's just an entry 
in the process table waiting to be deleted.  With the new weekly, monthly, 
yearly graphs you'll have up to 4 zombies now.  

By default, bandwidthd now runs in promiscuous mode.  This means it can be used
to monitor traffic not routing through it's host.  Just make sure that the host
and the actual router are on the same hub (Not switch) and everything will be 
ok. Under some circumstances, traffic may get counted twice.  If traffic routes
to the other router, then routes back out along the same wire, it may get counted 
twice by bandwidthd.  This is much less of a problem than you might think, due
to a little known packet called an "icmp redirect" that causes all packets after
the first to go directly to it's target.  If you find that traffic looks like it's 
getting counted twice, make sure you're not firewalling off the icmp redirects.  
If you find that you actually see none of this traffic, it may be because the icmp
redirects cause it to ultimatly end up going from one port on a switch to another, 
never touching your hub. If you want bandwidthd to only see traffic actually going 
into and out of the host set "promiscuous" to false in bandwidthd.conf.

Bandwidthd supports ethernet, linux cooked sockets, raw, and token ring, and 
most ppp packet encapsulation.  If you get an "Unknown Datalink Type" error, 
bandwidthd has not been programed to handle the physical encapsulation of the 
ip packets on that interface.  If you send me a sample capture and a copy past 
of the error message I'll see if I can make bandwidthd work for you.