NAME

Net::DNSBL::Client - Client code for querying multible 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 => '127.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, only one option is 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.

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.

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

domain

The domain of the DNSBL.

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.

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.