NAME
ipband - IP bandwidth watchdog
SYNOPSIS
ipband -aAbcCdfFhJlLmMowPrtTv INTERFACE
DESCRIPTION
ipband is a pcap based IP traffic monitor. It tallies per-subnet
traffic and bandwidth usage and starts detailed logging if specified
threshold for the specific subnet is exceeded. If traffic has been high
for a certain period of time, the report for that subnet is generated
which can be appended to a file or e-mailed. When bandwidth usage drops
below the threshold, detailed logging for the subnet is stopped and
memory is freed.
This utility could be handy in a limited bandwidth WAN environment
(frame relay, ISDN etc. circuits) to pinpoint offending traffic source
if certain links become saturated to the point where legitimate packets
start getting dropped.
It also can be used to monitor internet connection when specifying the
range of local ip addresses (to avoid firing reports about non-local
networks).
Bandwidth is defined as total size in kBytes of the layer 2 frames with
IP packets passing the specified interface during the avaraging period
devided by the number of seconds in that period.
COMMAND LINE OPTIONS
interface
Network interface to read data from.
-a secs
Averaging period in seconds. How often total traffic and
bandwidth should be calculated. Default is 60 secs.
-A Include threshold exceeded accumulated time and percentage in
the report. This option works only with preloaded subnets
("subnet" directive) because otherwise subnet data is deleted
when bandwidth usage drops below threshold to clear memory and
reduce processing time.
-b kBps
Bandwidth threshold in kBytes per sec. Default is 7 kBps i.e. 56
kbps.
-c filename
Use filename as configuration file. Default is /etc/ipband.conf.
Specifying different bandwidth threshold per subnet is only
available through the configuration file. See subnet directive
in the CONFIGURATION FILE section below.
-C Ignore configuration file.
-d level
Debug level. 0 - no debuging; 1 - summary; 2 - subnet
statistics; 3 - all packets captured. Default is 0.
-f filterstr
Use filterstr as pcap filter. See manual page for tcpdump. Also
see EXAMPLES section below.
-F Fork and run in background. Default is run in foreground.
-h Print help and exit.
-J number
Packet length adjustment in bytes. This option can be used when
layer 2 frame sizes for the interface ipband is listening on and
the interface we are measuring the bandwidth for are different.
For example, if you are concerned about bandwidth usage on a
router’s frame relay interface with 6 bytes overhead (frame
header + RFC1490 encapsulation) while ipband is running on an
ethernet interface with 14 bytes MAC frame, then you could use
value -8 for this option to get more accurate bandwidth
calculation. The number can be a positive or a negative integer.
Negative values should not exceed leyer 2 frame size for the
ipband’s interface (i.e. we can’t use -15 in the above example).
The default is 0.
-l filename
If -M (or mailto directive in config file) option is set,
specifies name of the file to be appended to the end of e-mail
reports.
-L ip-range[:ip-range[:ip-range[..]]]
This option specifies which network numbers should be considered
local when collecting data and generating reports (actually
non-local networks are not logged at all). It can be used
instead of config file’s multiple "subnet" directives (unlike
that directive, there would be a single bandwidth threshold
specified by -b option). This option can be used for monitoring
internet connections when you don’t want to get reports on
someone else’s networks.
There can be many ip-ranges separate by colons. No spaces may
appear in the argument. Each ip-range can be either a single ip
address such as 192.168.1.1 which indicates a range of one, a
partial ip address such as 192.168.1.0 which indicates a range
from 192.168.1.0 to 192.168.1.255, a low and high ip address
separated by a hypen (-), and a single ip address, a slash (/)
and an integer between 0 and 32 (a "net address") which
indicates a network. If you run ipband with the debug option
(-d) the program will print the entire list of ip ranges, so you
can check their values.
Here is a list of arguments to -L along with the corresponding
range.
COMMAND: ipband eth0 -l 137.99.11
RANGE: 137.99.11.0-137.99.11.255
COMMAND: ipband eth0 -L 137.99.11:127.0.5/23
RANGE: 137.99.11.0-137.99.11.255,127.0.4.0-127.0.5.255
COMMAND: ipband eth0 -L 127.1.5.17-127.1.7.131
RANGE: 127.1.5.17-127.1.7.131
-m maskbits
Set number of subnet mask bits (1-32) for subnet traffic
aggregation. Default is 24 (255.255.255.0).
-M email address(es)
Send detailed subnet report to specified e-mail address(es).
Multiple addresses must be separated by comma.
-o filename
Filename to output detailed subnet report. Default is ipband.txt
in current directory.
-w filename
HTML report output file. Default is ipband.html in current
directory. The styles.css file can be used in the same directory
to customize its look and feel.
-P Do not use promiscuous mode on the network interface we are
listening on.
-r secs
Reporting period - number of seconds bandwidth threshold may be
exceeded before it should be reported. Default is 300 seconds.
-t number
Limit subnet report to a given number of per-host connections
with highest byte count (top connections). Default is no limit.
-T string
MTA command string for mailing reports. Default is
"/usr/sbin/sendmail -t -oi". The string is tokenized and passed
directly to exec(), so that shell’s metacharacters are not
interpreted.
-v Print version and exit.
CONFIGURATION FILE
In addition to command line options you can use a configuration file.
When ipband starts it first looks for /etc/ipband.conf. You can also
give the ’-c’ (see OPTIONS above) to specify a configuration file.
The options in the config file are specified by keyword/value pairs.
Lines starting with # are ignored.
Below is a list of config file options:
interface interface
Interface to read packets from.
promisc {yes/no}
Like -P option, specifies whether or not to use promiscious mode
on the listening network interface. Promiscuous mode is the
default.
debug {0-3}
Like -d option, specifies debug level.
fork {yes/no}
Like -F option, specifies whether or not to run in background.
Default is no.
filter filterstr
Like -f option, specifies pcap filter.
outfile filename
Like -o option, specifies report file name. efault is ipband.txt
in current directory.
htmlfile filename
Like -w option, HTML report output file. Default is ipband.html
in current directory. The styles.css file can be used in the
same directory to customize its look and feel.
htmltitle title
HTML title of the report output file.
bandwidth kBps
Like -b option, bandwidth threshold in kBytes per second.
Default is 7.0 kBps.
average secs
Like -a option, tells ipband nomber of seconds to average
per-subnet traffic and calculate bandwidth usage. Default is 60
seconds.
lenadj number
Like -J option, specifies packet length adjustment in bytes.
report secs
Like -r option, number of seconds specified threshold(s) may be
exceeded before report is fired off. Default is 300 secs.
top number
Like -t option, limits subnet report to a given number of
per-host connections with highest byte count (top connections).
Default is 0 - no limit.
accumulate {yes/no}
Like -A option, whether or not to include threshold exceeded
accumulated time and percentage in the report. Default is no.
mailto email address(es)
Like -M option, e-mail address(es) detailed subnet report should
be sent to. Multiple addresses must be separated by comma.
mailfoot filename
Like -l option, name of the file to be appended to the end of
e-mail reports.
mtastring string
Like -T option, specifies MTA command string for mailing
reports. Default is "/usr/sbin/sendmail -t -oi".
maskbits {1-32}
Like -m option, sets the number of network mask bits. Default is
24 (corresponding to subnet mask 255.255.255.0).
localrange ip_range
Like -L option, determines which range(s) of ip addresses are
considered local.
subnet subnet-ip bandwidth kBps
Specifies which subnets ipband should work with and sets
individual bandwidth thresholds for them - one subnet option per
line (subnet mask is set by maskbits option). This option is
only available through a configuration file. Setting it limits
data collection and reporting to the specified subnets.
EXAMPLES
ipband eth0 -f net 10.10.0.0/16 -m 24 -a 300 -r 900
Will capture packets from/to ip addresses matching
10.10.0.0/255.255.0.0, tally traffic by the third
octet,calculate bandwidth utilization every 5 minutes and report
per host traffic every 15 minutes.
ipband -c ipband.conf
Read configuration from file ipband.conf.
BUGS
Report mailing blocks until pipe to sendmail returns.
Report any bugs to anevynni@russelmetals.com.
Thanks.
AUTHOR
Andrew Nevynniy anevynni@russelmetals.com
ipband is based on ipaudit-0.95 by J Rifkin jon.rifkin@uconn.edu
(http://www.sp.uconn.edu/~jrifkin).
VERSION
0.8.1 Jun 13, 2008
SEE ALSO
tcpdump(1) pcap(3)