Provided by: ipband_0.7.2-3_i386 bug

NAME

       ipband - IP bandwidth watchdog

SYNOPSIS

       ipband -aAbcCdfFhJlLmMoPrtTv 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.

       -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 -ba". 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.  Default  is
              /etc/ipband.conf.

       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 -ba".

       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.7.2 Mar 23, 2002

SEE ALSO

       tcpdump(1) pcap(3)