NAME
    Net::DNSBL::Statistics - gather DNSBL Statistics

SYNOPSIS
      use Net::DNSBL::Statistics qw(
            run
            plaintxt
            htmltxt
      );

      %dnsblcounts=run(\%config,$NonBlockSock,$sockaddr_in);
      $text = plaintxt(\%config,\%dnsblscounts);
      $html = htmltxt(\%config,\%dnsblcounts);

DESCRIPTION
    Net::DNSBL::Statistics is the Perl module that collects statistics on
    the interrogation success for a list of IP addresses against a list of
    DNSBL's. The module is used to implement the reproting script dnsblstat.

CONFIGURATION FILE
    With the addition of a few elements, the configuration file for
    dnsblstat shares a common format with the Mail::SpamCannibal
    sc_BLcheck.pl script, facilitating common maintenance of DNSBL's for
    your MTA installation.

    The sample configuration file statistics.conf.sample is heavily
    commented with the details for each configuration element.

SYSTEM SIGNALS
    dnsblstat responds to the following system signals:

    * TERM
      Script is terminated.

PERL MODULE DESCRIPTION - Script Implementation
    Net::DNSBL::Statistics provides most of the functions that implement
    dnsblstat which is a script that collects statistics from a list of IP
    address interrogations against a list of DNSBL's

dnsblstat usage
    How to use dnsblstat

      Syntax: dnsblstat path/to/config.file
        or
            dnsblstat -t path/to/config.file
            dnsblstat -w path/to/config.file

    Normally dnsblstat prints a sorted list (by count) of the DNSBL's
    interrogated with their reply count, percentage of the total count, and
    any comments from the DNSBL's 'comment' key field in the config file.
    The 'comment' field may contain html markup text.

      i.e.
      44 100.0%  TOTAL IP's interrogated
      41  93.2%  UNION of all results   
      34  77.3%  dnsbl.sorbs.net comment
      ........

    The -t switch will print a start and stop time.

      i.e.
      # start: Fri Jan  4 17:46:44 2008
      # stop : Fri Jan  4 17:58:21 2008

    The -w switch will put the output into an HTML table without the <table>
    statement </table>>., a commment as above and with an <a
    href="...">dnsbl name</a> statement replacing the dnsbl name if the
    'url' key is present in the config file.

      i.e.
      A one line example corresponding to the text line above:

      34  77.3% dnsbl.sorbs.net

      with a 'comment' key of: 127.0.0.2,5,7,8,9,10,12
      and a 'url' key of:      http://www.au.sorbs.net/using.shtml

      <tr class=dnsbl><td align=right>34</td>
        <td align=right>77.3%</td>
        <td align=left><a
         href="http://www.au.sorbs.net/using.shtml">dnsbl.sorbs.net</a></td>
        <td align=left>127.0.0.2,5,7,8,9,10,12</td>
      </tr>

Net::DNSBL::Statistics FUNCTIONS
    * %dnsblscounts=run(\%config,$NonBlockSock,$sockaddr_in);
        Returns the total number of IP's interrogated (IP list less white
        listed items) and a hash of DNSBL names and their respective SPAM
        reply counts or equivalent for 'in-addr.arpa' and GENERIC.

          input:   config pointer,
                   non-blocking socket descriptor,
                   sockaddr_in for local DNS host

          returns: dnsbl count hash

        The dnsbl count hash will have two added keys:

                TOTAL   the total number of interrogations less whitelist
                UNION   the total number of spam 'hits'

          HINTs:   use Net::NBsocket qw( open_udbNB sockaddr_in );
                   use Net::DNS::ToolKit qw( get_ns );

                   my $sock = open_udpNB();
                   my $sockaddr_in = sockaddr_in(53, scalar get_ns());

    * $text = plaintxt($config,\%dnsbls);
        Generate a plain text report of the form:

          44 100.0%  TOTAL IP's interrogated
          41  93.2%  UNION of all results
          34  77.3%  dnsbl.sorbs.net comment
          22  50.0%  GENERIC comment
          13  29.5%  in-addr.arpa comment
          11  25.0%  cbl.abuseat.org comment
          9   20.5%  list.dsbl.org comment
          2    4.5%  dnsbl.njabl.org comment
          1    2.3%  bl.spamcannibal.org comment
          0    0.0%  dynablock.njabl.org comment

          input:        configuration pointer,
                        dnsbl count hash pointer
          returns:      text buffer

        The 'comment' comes from the config file 'comment' key field for
        each specified DNSBL or is blank if there is no 'comment' key.

    * $html = htmltxt($config,\%dnsbls);
        Generate a report as above but with <tr><td></td></tr> table markup.
        The <table></table> tags are not generated. If there is a 'url' key
        field in the respective DNSBL config entry, the DNSBL name is
        provide with <a href="url">DNSBL</a> tags with the specified 'url'
        as the 'href' value.

          input:        configuration pointer,
                        dnsbl count hash pointer
          returns:      html text buffer

        A one line example corresponding to the text line above:

          34  77.3% dnsbl.sorbs.net 

          with a 'comment' key of: 127.0.0.2,5,7,8,9,10,12
          and a 'url' key of:      http://www.au.sorbs.net/using.shtml

          <tr class=dnsbl><td align=right>34</td>
            <td align=right>77.3%</td>
            <td align=left><a 
             href="http://www.au.sorbs.net/using.shtml">dnsbl.sorbs.net</a></td>
            <td align=left>127.0.0.2,5,7,8,9,10,12</td>
          </tr>

Statistics Web Page HOWTO
    Read the "contrib/HOWTO" document that describes the scripts used with
    'cron' to auto generate web pages for the statistics reports

EXPORT_OK
            run
            plaintxt
            htmltxt

AUTHOR
    Michael Robinton, michael@bizsystems.com

COPYRIGHT
    Copyright 2008-2014, Michael Robinton. This program is free software;
    you can redistribute it and/or modify it under the terms of the GNU
    General Public License as published by the Free Software Foundation;
    either version 2 of the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

SEE ALSO
    the Mail::SpamCannibal manpage, the Net::DNS::Codes manpage, the
    Net::DNS::ToolKit manpage, the Net::DNSBL::MultiDaemon manpage