IPA_IPFW(8)                                                        IPA_IPFW(8)



NAME
       ipa_ipfw -- IPA accounting module for FreeBSD IP Firewall

DESCRIPTION
       ipa_ipfw is an IPA accounting module with the following features:

       -      The  module  is  designed for traffic accounting from FreeBSD IP
              Firewall (including IPFW2) rules byte counters;

       -      The module understands IP Firewall rules byte counters overflow;

       -      It  is possible to summarize and subtract statistics of IP Fire-
              wall rules byte counters;

       -      It is possible to distinguish IP Firewall rules  with  the  same
              numbers;

       -      IP  Firewall  rules can be dynamically added to and deleted from
              the system, the module correctly works in such situations.

       Before reading the next paragraph you should read documentation for  IP
       Firewall  for  information  how  to setup IP Firewall rules for traffic
       accounting.

       The name of the accounting system is ipfw.

CONFIGURATION FILE FORMAT
       Configuration for the module is integrated into ipa.conf(5).  The  con-
       figuration prefix of this module is ``ipfw''.

       To  get  traffic statistics of some IP Firewall rule use the ipfw:rules
       parameter:

           ipfw:rules = [-]number[.subnumber];

       This parameter should be placed in the rule section.

       There is only one rule number in the original  format  of  IP  Firewall
       rule.   Extra subnumber can be added to distinguish rules with the same
       number, first rule with some number has a subnumber equal to 0,  second
       rule  with  the same number has a subnumber equal to 1 and so on.  If a
       subnumber is omitted, then it is treated as 0.  A subnumber in IP Fire-
       wall  rule  is something new and is not mentioned in the ipfw(8) manual
       page.

       The `-' sign can be placed before IP Firewall rule number, in this case
       the module will subtract statistics of this rule.

       Several  IP  Firewall  rules,  separated  by spaces, can be used in the
       ipfw:rules parameter and their statistics will be added  or  subtracted
       according to signs before rules' numbers.

       The ipfw:maxchunk parameter allows to safely flush IP Firewall rules or
       delete and add the same rules when ipa(8) is running:

           ipfw:maxchunk = <bytes>;

       This parameter should be used in global and rule sections.

       If the old value of a byte counter is greater than the current value of
       some  IP  Firewall  rule  and  if  the  difference (including overflow)
       between them is greater than the ipfw:maxchunk parameter's value,  then
       the  module  takes  absolute  value  of the byte counter as the current
       chunk of statistics for this rule.

       Too small value of  the  ipfw:maxchunk  parameter  can  lead  to  wrong
       results.   Its value should be greater than difference of byte counters
       of any IP Firewall rule used in a ipa.conf(5)'s rule during update time
       interval.

       It  will be better to check some variables of IP Firewall kernel struc-
       tures and determine whether some IP Firewall  rule  has  been  changed.
       But  there  are  no such variables in IP Firewall kernel structures (at
       the moment when this manual page was being written), so it is necessary
       to use the ipfw:maxchunk parameter.

       The  module  always sends log messages when some IP Firewall rule over-
       flowed or probably was changed (this is checked with the  help  of  the
       ipfw:maxchunk  parameter) and when some IP Firewall rule is added to or
       deleted from the IP Firewall kernel table.  It is possible to  suppress
       these warning messages using the ipfw:quiet parameter:

           ipfw:quiet = <value>;

       This parameter can be placed in global and rule sections.

       The  default  value of this parameter is equal to zero, this means that
       all warning messages are sent to the log.  If its value has 0x1 bit on,
       then  no  log  message  is sent when a byte counter of some IP Firewall
       rule overflows.  If its value has 0x2 bit on, then no  log  message  is
       sent when some IP Firewall rule is added or deleted.

       The ipfw:debug parameter helps to debug the module:

           ipfw:debug = <level>;

       This parameter should not be placed in any section.

       Only  two values are allowed for the debug level: 0 and 1.  The default
       value of this parameter is 0, and debugging is disabled.

       Example:

           ac_mod "ipa_ipfw.so";

           global {
               /* ... */
               ac_list = ipfw;
               ipfw:quiet = 3;
               ipfw:maxchunk = 1G;
           }

           rule 1 {
               /* ... */
               ipfw:rules = 100 200.1 300;
           }

           rule 2 {
               /* ... */
               ipfw:rules = 100 -200 300.0 300.1;
               ipfw:maxchunk = 500M;
           }

       The first rule inherits the ipfw:maxchunk  parameter  from  the  global
       section,  both  rules  inherit the ipfw:quiet parameter from the global
       section.

SEE ALSO
       ipfw(8)

COMPATIBILITY
       IP Firewall first appeared in FreeBSD 2.0.  FreeBSD  IPFW2  was  intro-
       duced  in  Summer  2002.   This module is expected to work with FreeBSD
       starting from 3.0-RELEASE.

AUTHOR
       Andrey Simonenko <simon@comsys.ntu-kpi.kiev.ua>

BUGS
       If you install new FreeBSD kernel with new IP Firewall API, then it  is
       necessary to rebuild this module.

       If you find any bug, please send email me.



                                January 4, 2008                    IPA_IPFW(8)