RBLClient(3pm)

💖 Net::RBLClient 💖

okay bestie, so this is a User Contributed Perl Documentation page for Net::RBLClient — that's the module, and the manpage itself is filed under RBLClient(3pm) in section 3pm. pull up a chair, we're doing DNS detective work together 🕵️♀️✨

---

🌈 NAME 🌈

Net::RBLClient — it queries a whole bunch of Realtime Blackhole Lists at the same time, in parallel, because waiting is not the vibe.

---

🎀 SYNOPSIS 🎀

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

literally four lines and you're done, slay 💅

---

🦋 DESCRIPTION 🦋

This module exists to figure out which RBLs are listing a particular IP address. It parallelizes the requests so you get a fast response — no cap, speed is the whole point.

so like, an RBL (Realtime Blackhole List) is a list of IP addresses that meet some criteria, e.g. being involved in Unsolicited Bulk Email. every RBL has its own criteria for adding and removing addresses — they're all different, they're all doing their own thing 🙈

⚠️ real talk: if you wanna 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. like, do your research first, bestie. this is not a vibes-only situation.

---

✨ CONSTRUCTOR ✨

new( [ARGS] )

takes an optional hash of arguments — here's the whole menu, no secrets:

• lists — an arraref (yes, arraref, that's what it says 😭) of (sub)domains representing RBLs. each element in the array is a string similar to 'relays.somerbl.org'. use this when you want to query a specific list of RBLs — if you omit this argument, a large list of RBLs gets queried instead.
• query_txt — set this to true if you want Net::RBLClient to also query for TXT records, which is where a lot of RBLs stash extra info about why an IP address got included, or links to pages that have that info. then you can grab all of that with the "txt_hash()" method. 🎁
• max_time — the maximum time in seconds that the lookup function should take. heads up though: the function can actually take up to max_time + timeout seconds. max_time need not be integer. and yeah, if the lookup returns because of 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, i.e. "yes this IP address is on this list." if max_hits hits are received, lookup() returns immediately, which lets the calling program save time. ⏱️
  • Default: 1000 (which is 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 tbh.
  • 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 ) — look up one IP address on all RBLs 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 RBLs which block the specified IP. the RBLs are indicated via the (sub)domain used for DNS query. the calling program must first call "lookup()". don't skip that step, fr fr 🙏
• listed_hash() — return a hash whose keys are the RBLs 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 RBLs 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), and 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.

---

and that's the whole page, bestie!! 🎉 this one's running on perl v5.34.0, dated 2022-06-30 — go forth and query those RBLs, you absolute icon 👑💅✨