jammy (8) ipband.8.gz

Provided by: ipband_0.8.1-5.1_amd64 bug

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

SEE ALSO

       tcpdump(1) pcap(3)