1. OVERVIEW

These two simple bandwidth measurement tools can really help a network
administrator to see what is happening at his linux router at the moment. 'rate'
calculates current bandwidth utilized by packets matching given BPF filter on an
interface and 'bandabusers' shows top n (default: top 10) hosts receiving and
transmitting packets matching given BPF filter. The possibilities are countless,
for instance you can measure current bandwidth utilized by one of the hosts,
by a whole network, by http traffic, by broadcast traffic, by quake traffic,
by packets opening a HTTP connection (with SYN flag set), you can see the top
ten web-surfers, top twelve linuxdoc.org readers, etc. Both programs are
completely command-line and might be used in scripts.

A BPF filter is the same kind of expression that you use to filter packets in
tcpdump.

2. REQUIREMENTS

- 'rate' and 'bandabusers' use libpcap to capture packets.
- additionally, 'bandusers' is currently unable to calculate the datalink
  header size on the given interface, so you need to specify it. Well ...
  it's quite easy to google. For ethernet interfaces it's 14 bytes, which
  is the default.

bmtools haven't been tested in a 64-bit environment, however if they do not
work, not many modifications are needed, I guess...

3. INSTALATION

If libpcap doesn't reside in a standard place on your system, edit Makefile
(add -I/include/path and -L/library path/) to CFLAGS and LDFLAGS.

Type 'make' and copy 'rate' and 'bandabusers' to /usr/local/bin for instance.

4. USAGE

See rate -h and bandabusers -h. 

Examples:

# rate -i eth1
  Shows overall bandwidth on eth1, including ethernet headers

# rate -i eth1 -p 14 -u
  Shows overall bandwidth on eth1, not counting ethernet headers,
  human-readable output (unit prefixes - k, M, G)

# rate -i eth1 -r 3 -f 'dst net 217.98.242.0/24'
  Shows bandwidth utilized by packets on eth1 destined for 217.98.242.0/24
  every 3 seconds

# rate -i eth3 -b -r 10 -q 1 -f 'icmp and src host 213.25.115.11'
  Measures 10-seconds average utilization in bit units for packets on
  eth3 being ICMP packets from 213.25.115.11, and then quits.


# bandabusers -c 213.25.115.0/24
  Shows 10 'bandwidth abusers' (nodes generating the highest traffic)
  from 213.25.115.0/24 on eth0

# bandabusers -t 8 -r 10 -ubz -q 5 -c 10.0.0.0/8 -c 217.98.242.0/24 -f 'icmp'
  Shows 5 (-q 5) current (-z) results of 10-second (-r 10) measurements
  on who from 10.0.0.0/8 and 217.98.242.0/24 is generating the highest icmp
  traffic. The results are printed in human-readable (with prefixes) (-u),
  bit units (-b).

  
5. OUTPUT

pps = packets per second
bps = bits per second
Bps = bytes per second

1 kpps is 1000 pps
1 Mpps is 1000 kpps
1 Gpps is 1000 Mpps
1 kBps is 1024 bps
1 MBps is 1024 kBps
1 GBps is 1024 MBps
1 kbps is 1024 bps
1 Mbps is 1024 kbps
1 Gbps is 1024 Mbps
(of course for bmtools.)

6. AUTHOR

Mateusz 'mteg' Golicz <mtg@elsat.net.pl>. Feel free to send any comments,
patches, bugfixes, suggestions, etc.

7. LICENSE

GNU GPL, see attached 'LICENSE' file.
