NAME

Net::Blacklist::Client - Queries multiple RBLs or URIBLs in parallel.

SYNOPSIS

        use Net::Blacklist::Client;
        my $rbl = Net::Blacklist::Client->new;
        my $result = $rbl->lookup_ip('127.0.0.2');
        foreach my $list (keys %$result){
                printf "%s: %s (%s)\n", $list, $result->{$list}->{a}, $result->{$list}->{txt};
        }

DESCRIPTION

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

This module is heavily based on Net::RBLClient by Asher Blum. It adds an updated list of RBLs and removes many dead ones, the ability to look up domains in domain-specific RBLs, and changes the output format. Although it is very similar and does the same job, due to the changes in the output formats, it is not suitable as a drop-in replacement.

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 RBLs, you should carefully study the behavior of those RBLs before and during such blocking.

CONSTRUCTOR

new( [ARGS] )

Takes an optional hash of arguments:

lists_ip

An arraref of domains representing IP address RBL root domains. Each element in the array should be a string representing the root domain for the RBL you wish to use, for example 'bl.spamcop.net' is the root domain of Spamcop's blacklist. Use this if you want to query a specific list of RBLs - if this argument is omitted, a large list of default RBLs is used.

lists_domain

Similar to lists_ip, but these are used when querying domains with lookup_domain. Note that IP and domain RBLs are usually separate, so using a list of IP RBLs to check domains is a bad plan. Currently, the URIBL and SURBL services are used by default.

query_txt

This option controls whether Net::Blacklist::Client looks up corresponding TXT records. The TXT record is used by many RBL's store additional information about the reason for including an IP address or links to pages that contain such information.

Default: True

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_ip( 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_ip returns a reference to a hash with each list the IP appears on as keys. The values depend on the status of the query_txt constructor option, if it is enabled, than a the value of the hash returned by lookup_ip will by a hashref with the keys a and txt, containing the A and TXT records returned by the RBL. If it is disabled then the value is simply set to the IP address returned by the A record request.

lookup_domain( DOMAIN )

Exactly the same as lookup_ip, except it accepts a domain, and uses a different list of domain-specific RBLs. The hash reference returned is in exactly the same format.

AUTHOR

Dan Thomas <dan@cpan.org>

Based on Net::RBLClient by Asher Blum <asher@wildspark.com>

COPYRIGHT

Copyright (C) 2007 Dan Thomas. The original Net::RBLClient is 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.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 398:

You forgot a '=back' before '=head1'

Around line 400:

'=item' outside of any '=over'