NAME

Net::DNSBL::Client - Client code for querying multiple DNSBLs

SYNOPSIS

use Net::DNSBL::Client;
my $c = Net::DNSBL::Client->new({ timeout => 3 });

$c->query_ip('127.0.0.2', [
    { domain => 'simple.dnsbl.tld' },
    { domain => 'masked.dnsbl.tld', type => 'mask', data => '0.0.0.255' }
]);

# And later...
my $answers = $c->get_answers();

METHODS

Class Methods

new ( $args )

Returns a new Net::DNSBL::Client object.

$args is a hash reference and may contain the following key-value pairs:

resolver

(optional) A Net::DNS::Resolver object. If not provided, a new resolver will be created.

timeout

(optional) An integer number of seconds to use as the upper time limit for the query. If not provided, the default is 10 seconds. If provided, timeout must be a positive integer.

Instance Methods

get_resolver ( )

Returns the Net::DNS::Resolver object used for DNS queries.

get_timeout ( )

Returns the timeout in seconds for queries.

set_timeout ( $secs )

Sets the timeout in seconds for queries.

query_is_in_flight ( )

Returns non-zero if "query" has been called, but "get_answers" has not yet been called. Returns zero otherwise.

query_ip ( $ipaddr, $dnsbls [, $options])

Issues a set of DNS queries. Note that the query_ip() method returns as soon as the DNS queries have been issued. It does not wait for DNS responses to come in. Once query_ip() has been called, the Net::DNSBL::Client object is said to have a query in flight. query_ip() may not be called again while a query is in flight.

$ipaddr is the text representation of an IPv4 or IPv6 address.

$dnsbls is a reference to a list of DNSBL entries; each DNSBL entry is a hash with the following members:

domain

(required) The domain to query. For example, zen.spamhaus.org.

type

(optional) The type of DNSBL. Possible values are normal, meaning that any returned A record indicates a hit, match, meaning that one of the returned A records must exactly match a given IP address, or mask, meaning that one of the returned A records must evaluate to non-zero when bitwise-ANDed against a given IP address. If omitted, type defaults to normal

data

(optional) For the match and mask types, this data specifies the required match or the bitwise-AND mask. In the case of a mask type, the data can be something like "0.0.0.4", or an integer like "8". In the latter case, the integer n must range from 1 to 255 and is equivalent to 0.0.0.n.

userdata

(optional) This element can be any scalar or reference that you like. It is simply returned back unchanged in the list of hits.

$options, if supplied, is a hash of options. Currently, two options are defined:

early_exit

If set to 1, querying will stop after the first positive result is received, even if other DNSBLs are being queried. Default is 0.

return_all

If set to 1, then the return value from get_answers() will contain all DNSBLs that were supplied to query_ip(), even if the DNSBL did not hit. If set to 0 (the default), then the return value from get_answers() only returns entries for those DNSBLs that actually hit.

get_answers ( )

This method may only be called while a query is in flight. It waits for DNS replies to come back and returns a reference to a list of hits. Once get_answers() returns, a query is no longer in flight.

Note that the list of hits is not necessarily returned in the same order as the original list of DNSBLs supplied to query_ip().

Each hit in the returned list is a hash reference containing the following elements:

domain

The domain of the DNSBL.

hit

Set to 1 if the DNSBL was hit or 0 if it was not. (You will only get entries with hit set to 0 if you used the return_all option to query_ip().)

type

The type of the DNSBL (normal, match or mask).

data

The data supplied (for normal and mask types)

userdata

The userdata as supplied in the query_ip() call

actual_hit

The actual A record returned by the lookup that caused a hit.

replycode

The reply code from the DNS server (as a string). Likely to be one of NOERROR, NXDOMAIN, SERVFAIL or TIMEOUT. (TIMEOUT is not a real DNS reply code; it is synthesized by this Perl module if the lookup times out.)

The hit may contain other elements not documented here; you should count on only the elements documented above.

If no DNSBLs were hit, then a reference to a zero-element list is returned.

DEPENDENCIES

Net::DNS::Resolver, IO::Select

AUTHOR

David Skoll <dfs@roaringpenguin.com>, Dave O'Neill <dmo@roaringpenguin.com>

COPYRIGHT AND LICENSE

Copyright (c) 2010 Roaring Penguin Software

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.