SYNOPSIS

       ipband -aAbcCdfFhJlLmMowPrtTv INTERFACE




DESCRIPTION

       ipband is a pcap based IP traffic monitor.  It tallies per-subnet traf-
       fic 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  band-
              width 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 ("sub-
              net"  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
              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 calcula-
              tion.  The number can be a positive or a negative integer. Nega-
              tive 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, speci-
              fies  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 some-
              one 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 indi-
              cates 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
              Set  number of subnet mask bits (1-32) for subnet traffic aggre-
              gation. 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 lis-
              tening 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:


       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.



       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  indi-
              vidual  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,calcu-
              late 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



Man(1) output converted with man2html