NAME

SYNOPSIS

  use Net::DNSBL::MultiDaemon qw(
        :debug
        run
        bl_lookup  
        set_extension
  );

  run($BLzone,$L,$R,$DNSBL,$STATs,$Run,$Sfile,$StatStamp,$DEBUG)
  bl_lookup($put,$mp,$rtp,$sinaddr,$alarm,$rid,$id,$rip,$type,$zone,@blist);

DESCRIPTION

multi_dnsbl is a DNS emulator daemon that increases the efficacy of DNSBL look-ups in a mail system. multi_dnsbl may be used as a stand-alone DNSBL or as a plug-in for a standard BIND 9 installation. multi_dnsbl shares a common configuration file format with the Mail::SpamCannibal sc_BLcheck.pl script so that DNSBL's can be maintained in a common configuration file for an entire mail installation.

Because DNSBL usefulness is dependent on the nature and source of spam sent to a specific site and because sometimes DNSBL's may provide intermittant service, multi_dnsbl interrogates them sorted in the order of greatest successful hits. DNSBL's that do not respond within the configured timeout period are not interrogated at all after 6 consecutive failures, and thereafter will be retried not more often than once every hour until they come back online. This eliminates the need to place DNSBL's in a particular order in your MTA's config file or periodically monitor the DNSBL statistics and/or update the MTA config file.

In addition to optimizing DNSBL interrogation, multi_dnsbl may be configured to locally accept or reject specified IP's, IP ranges and to reject specified countries by 2 character country code. By adding a DNSBL entry of in-addr.arpa, IP's will be rejected that do not return some kind of valid reverse DNS lookup. In addition, IP's can be rejected that have a PTR record that matchs a configurable GENERIC 'regexp' set.

Reject codes are as follows:

  query 2.0.0.127.{zonename}    127.0.0.2
  blocked by configured DNSBL   127.0.0.2
  no reverse DNS                127.0.0.4
  BLOCKED (local blacklist)     127.0.0.5
  Blocked by Country            127.0.0.6
  Blocked GENERIC               127.0.0.7

OPERATION

Let us say for example that blackholes.easynet.nl (below) will return an A record and list.dsbl.org, bl.spamcop.net, dynablock.easynet.nl, will not.

                LIST
        9451    list.dsbl.org
        6516    bl.spamcop.net
        2350    dynablock.easynet.nl
        575     blackholes.easynet.nl
        327     cbl.abuseat.org
        309     dnsbl.sorbs.net
        195     dnsbl.njabl.org
        167     sbl.spamhaus.org
        22      spews.dnsbl.net.au
        6       relays.ordb.org
        1       proxies.blackholes.easynet.nl
        0       dsbl.org

A query to multi_dnsbl (pseudo.dnsbl in this example) looks like this

        QUERY
  1.2.3.4.pseudo.dnsbl
          |
          V
  ####################
  #    multi_dnsbl   #
  ####################
   |                                  RESPONSE
   +--> 1.2.3.4.list.dsbl.org         NXDOMAIN
   |
   +--> 1.2.3.4.bl.spamcop.net        NXDOMAIN
   |
   +--> 1.2.3.4.dynablock.easynet.nl  NXDOMAIN
   |
   +--> 1.2.3.4.blackholes.easynet.nl A-127.0.0.2

The A record is returned to originator of the Query and the statistics count on blackholes.easynet.nl is incremented by one.

INSTALLATION / CONFIGURATION / OPERATION

  Syntax: ./rc.multi_dnsbl start    /path/to/config.file
          ./rc.multi_dnsbl start -v /path/to/config.file
          ./rc.multi_dnsbl stop     /path/to/config.file
          ./rc.multi_dnsbl restart  /path/to/config.file

  The -v switch will print the scripts 
  actions verbosely to the STDERR.

  MDstatfile     => '/path/to/statistics/file.txt',
  MDpidpath      => '/path/to/pidfiles', # /var/run
  MDzone         => 'pseudo.dnsbl',

  # OPTIONAL
  MDstatrefresh => 300,       # seconds
  MDipaddr      => '0.0.0.0', # PROBABLY NOT WHAT YOU WANT
  MDport        => 9953,
  MDcache       => 10000,     # an entry takes ~400 bytes
                              # default 10000 (to small)

  i.e.  dig 2.0.0.127.pseudo.dnsbl

        .... results

  //zone pseudo.dnsbl
  zone "pseudo.dnsbl" in {
        type forward;
        forward only;
        forwarders { 
            127.0.0.1 port 9953;
        };
  };

        allow-notify {};
        allow-query { address_match_list };
        allow-recursion { address_match_list };
        allow-transfer {};

  FEATURE(`dnsbl',`pseudo.dnsbl',
  `554 Rejected $&{client_addr} found in http://www.my.blacklist.org')dnl

SYSTEM SIGNALS

• TERM

  Operations the statistics file is updated with the internal counts and the daemon then exits.

• HUP

  Operations are stopped including an update of the optional statistics file, the configuration file is re-read and operations are restarted.

• USR1

  The statistics file is updated on the next second tick.

• USR2

  The statistics file is deleted, internal statistics then a new (empty) statistics file is written on the next second tick.

PERL MODULE DESCRIPTION

The following describes the workings of individual functions used to implement multi_dnsbl.

•

run($BLzone,$L,$R,$DNSBL,$STATs,$Run,$Sfile,$StatStamp,$DEBUG);

This function is the 'run' portion for the DNSBL multidaemon

  input:
        $BLzone zone name,
        $L      local listen socket object pointer,
        $R      remote socket object pointer,
        $DNSBL  config hash pointer,
        $STATs  statistics hash pointer
        $Run    pointer to stats refresh time,  # must be non-zero
        $Sfile  statistics file path,
        $StatStamp      stat file initial time stamp

  returns:      nothing
    

• bl_lookup($put,$mp,$rtp,$sinaddr,$alarm,$rid,$id,$rip,$type,$zone,@blist);

  Generates a query message for the first DNSBL in the @blist array. Creates a thread entry for the response and subsequent queries should the first one fail.

    input:        put,
                  message pointer,
                  remote thread pointer,
                  sockinaddr,
                  connection timeout,
                  remote id or undef to create
                  id of question,
                  reverse IP address in text
                  type of query received, (used in response)
                  ORIGINAL zone (case preserved),
                  array of remaining DNSBL's in sorted order
    returns:      nothing, puts stuff in thread queue
  
    extra:        if URBL processing is required,
                  $remoteThreads{$rid}->{urbl}
                  is set to the domain to look up
      

• set_extension($pointer);

  This function sets a pointer to user defined extensions to Net::DNSBL::MultiDaemon.

  Pointer is of the form:

          $Extension ->{
                  OPCODE   => value,
                  CLASS    => subref->($Extension,internal args),
                  NAME     => subref->($Extension,internal args),
                  TYPE     => subref->($Extension,internal args),
                  LOOKUP   => subref->($Extension,internal args),
                  ANSWER   => subref->($Extension,internal args),
                  NOTFOUND => subref->($Extension,internal args)
          };
      

  The pointer should be blessed into the package of the caller if the calling package needs to store persistant variables for its own instance. The subref will be called with the first argument of $Extension.

  Care should be taken to NOT instantiate a %remoteThreads in the CLASS, NAME, TYPE section unless it is know that it will be found and expired/deleted.

  Read the code if you wish to add an extension

DEPENDENCIES

  Unix::Syslog
  Geo::IP::PurePerl [conditional for country codes]
  NetAddr::IP
  Net::DNS::Codes
  Net::DNS::ToolKit

EXPORT_OK

        run
        bl_lookup

EXPORT_TAGS :debug

  DEBUG is a set of semaphores for the 'run' function

  $D_CLRRUN    = 0x1;  # clear run flag and force unconditional return
  $D_SHRTHD    = 0x2;  # return short header message
  $D_TIMONLY   = 0x4;  # exit at end of timer section
  $D_QRESP     = 0x8;  # return query response message
  $D_NOTME     = 0x10; # return received response not for me
  $D_ANSTOP    = 0x20; # clear run OK flag if ANSWER present
  $D_VERBOSE   = 0x40; # verbose debug statements to STDERR

AUTHOR

COPYRIGHT

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