Net::DNSBL::Client(3)

💖 Net::DNSBL::Client — the manual, but make it make sense 💖

okay bestie, so <pink>Net::DNSBL::Client</pink> is a Perl module that lives in the User Contributed Perl Documentation section, and it's literally your little group-chat manager for talking to a whole squad of DNSBLs at once. Multiple blocklists, one query, no drama. Let's get into it 🦋

---

✨ NAME ✨

Net::DNSBL::Client — client code for querying multiple DNSBLs. that's it, that's the whole vibe. 👑

---

🌸 SYNOPSIS 🌸

here's the whole thing in action, no cap:

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' },
        { domain => 'txt.dnsbl.tld', type => 'txt' },
        { domain => 'need-a-key.example.net' }],
    { lookup_keys => { 'need-a-key.example.net' => 'my_secret_key' }});

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

see how it just slays? four DNSBLs, one call, and the keyed one gets its secret handed over separately so the results stay readable. iconic. ✨

---

🎀 METHODS 🎀

💅 Class Methods

new ( $args )

hands you back a brand-new Net::DNSBL::Client object. fresh out the box, ready to go 🫶

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

• resolver — (optional) a Net::DNS::Resolver object. if you don't hand one over, a new resolver gets created for you. no biggie.
• timeout — (optional) an integer number of seconds to use as the upper time limit for the query. if you don't provide it, the default is 10 seconds. and if you do provide it, it must be a positive integer, bestie. no zero, no negatives, no vibes-based timeouts. 😭

---

🌈 Instance Methods

get_resolver ( )

returns the Net::DNS::Resolver object being used for DNS queries. it's giving "who's on aux". 🎧

get_timeout ( )

returns the timeout, in seconds, for queries.

set_timeout ( $secs )

sets the timeout, in seconds, for queries. glow-up for your patience levels. ✨

query_is_in_flight ( )

returns non-zero if query has been called but get_answers hasn't been called yet. returns zero otherwise. it's basically the "are we waiting on someone rn" check. 💀

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

issues a whole set of DNS queries. and here's the thing you need to know: query_ip() returns as soon as the DNS queries have been issued. it does not wait around for the DNS responses to come back. it's not a waiter, it's a sender. 💅

once query_ip() has been called, the Net::DNSBL::Client object is said to have a query in flight. and query_ip() may not be called again while a query is in flight. one at a time, bestie, we're not chaos gremlins (today).

• $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. this one's mandatory, no skipping it. 🚨
  • type — (optional) the type of DNSBL. possible values are:
    • normal — meaning any returned A record indicates a hit,
    • match — meaning one of the returned A records must exactly match a given IP address,
    • mask — meaning one of the returned A records must evaluate to non-zero when bitwise-ANDed against a given IP address,
    • or txt — meaning TXT records should be looked up and returned (rather than A records).

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 that latter case, the integer n must range from 1 to 255 and is equivalent to 0.0.0.n.

for match-type lookups, one or more of the octets can be specified as "x" or "X". for example, specifying a match against 127.0.X.3 will match a return code whose first octet is 127, second is zero, third is anything, and fourth is 3. wildcard energy. 🦋

• userdata — (optional) this element can be any scalar or reference that you like. it is simply returned back to you unchanged in the list of hits. it's the "hold my stuff" pocket of this module. 🎀

$options, if supplied, is a hash of options. currently, three 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.
• lookup_keys — this is a hashref of domain_name => key. some domains require a secret key to be inserted just before the domain name; rather than including the key in the domain, you can separate it out with the lookup_keys hash, making the returned results more readable. keep it cute, keep it clean. 💖

query_domain ( $domain, $dnsbls [, $options])

similar to query_ip, but it considers $domain to be a domain name rather than an IP address, and it does not reverse the domain. same energy, different input. 🌈

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. so like, don't call it when nothing's happening, it will not be cute. 🙈

note that the list of hits is not necessarily returned in the same order as the original list of DNSBLs supplied to query_ip(). do not count on ordering, bestie. seriously.

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_hits — reference to array containing actual A or TXT records 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. it's the module's own little invention 💅)

the hit may contain other elements not documented here; you should count on only the elements documented above. no peeking at undocumented fields and building your whole personality on them. 👑

if no DNSBLs were hit, then a reference to a zero-element list is returned. empty list, zero notes, moving on. ✨

---

🌟 DEPENDENCIES 🌟

• Net::DNS::Resolver
• IO::Select

---

👑 AUTHOR 👑

• Dianne Skoll <dianne@skoll.ca>
• Dave O'Neill <dmo@dmo.ca>

---

💜 COPYRIGHT AND LICENSE 💜

• Copyright (c) 2010 Roaring Penguin Software
• Copyright (c) 2022 Dianne Skoll

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. slay, legally speaking. 🎀

---

and that's the whole manual, bestie!! 🌈✨💖

this iconic little page came from perl v5.42.2 and it's dated 2025-12-14 — Net::DNSBL::Client(3), signing off 💅🦋🌸