Ubuntu Manpage: ipband - IP bandwidth watchdog

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 averaging period divided 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 debugging; 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 hyphen (-), 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