NAME

       Net::RBLClient - Queries multiple Realtime Blackhole Lists in parallel

SYNOPSIS

           use Net::RBLClient;
           my $rbl = Net::RBLClient->new;
           $rbl->lookup('211.101.236.160');
           my @listed_by = $rbl->listed_by;

DESCRIPTION

       This module is used to discover what RBL's are listing a particular IP address.  It
       parallelizes requests for fast response.

       An RBL, or Realtime Blackhole List, is a list of IP addresses meeting some criteria such
       as involvement in Unsolicited Bulk Email.  Each RBL has its own criteria for addition and
       removal of addresses.  If you want to block email or other traffic to/from your network
       based on one or more RBL's, you should carefully study the behavior of those RBL's before
       and during such blocking.

CONSTRUCTOR

       new( [ARGS] )
           Takes an optional hash of arguments:

           lists
               An arraref of (sub)domains representing RBLs.  In other words, each element in the
               array is a string similar to 'relays.somerbl.org'.  Use this if you want to query
               a specific list of RBL's - if this argument is omitted, a large list of RBL's is
               queried.

           query_txt
               Set this to true if you want Net::RBLClient to also query for TXT records, in
               which many RBL's store additional information about the reason for including an IP
               address or links to pages that contain such information.  You can then retrieve
               these information using the "txt_hash()" method.

           max_time
               The maximum time in seconds that the lookup function should take.  In fact, the
               function can take up to "max_time + timeout" seconds.  Max_time need not be
               integer.  Of course, if the lookup returns due to max_time, some DNS replies will
               be missed.

               Default: 8 seconds.

           timeout
               The maximum time in seconds spent awaiting each DNS reply packet.  The only reason
               to change this is if "max_time" is decreased to a small value.

               Default: 1 second.

           max_hits
               A hit is an affirmative response, stating that the IP address is on a certain
               list.  If "max_hits" hits are received, "lookup()" returns immediately.  This lets
               the calling program save time.

               Default: 1000 (effectively out of the picture).

           max_replies
               A reply from an RBL could be affirmative or negative.  Either way, it counts
               towards "max_replies".  "Lookup()" returns when "max_replies" replies have been
               received.

           udp_maxlen
               The maximum number of bytes read from a DNS reply packet.  There's probably no
               reason to change this.

               Default: 4000

           server
               The local nameserver to use for all queries.  Should be either a resolvable
               hostname or a dotted quad IP address.

               By default, the first nameserver in /etc/resolv.conf will be used.

METHODS

       lookup( IPADDR )
           Lookup one IP address on all RBL's previously defined.  The IP address must be
           expressed in dotted quad notation, like '1.2.3.4'.  "Lookup()" returns 1.

       listed_by()
           Return an array of RBL's which block the specified IP.  The RBL's are indicated via
           the (sub)domain used for DNS query.  The calling program must first call "lookup()".

       listed_hash()
           Return a hash whose keys are the RBL's which block the specified IP, represented as in
           "listed_by()".  If the RBL returned an A record, the value for that key will be the IP
           address in the A record - typically 127.0.0.1 - 127.0.0.4.  If the RBL returned a
           CNAME, the value will be the hostname, typically used for a comment on why the IP
           address is listed.

       txt_hash()
           Return a hash (or a reference to that hash if called in a scalar context) whose keys
           are the RBL's which block the specified IP, represented as in "listed_by()".  If the
           RBL returned TXT records containing additional information, the value will contain
           this information (several TXT records from one RBL will be joined by semicolons, but
           this should not happen), if not, it will be undef.

AUTHOR

       Asher Blum <asher@wildspark.com>

CREDITS

       Martin H. Sluka <martin@sluka.de>

COPYRIGHT

       Copyright (C) 2002 Asher Blum.  All rights reserved.  This code is free software; you can
       redistribute it and/or modify it under the same terms as Perl itself.