Zonema...server(3pm)

💖 Zonemaster::Nameserver — your fave little DNS nameserver object (3pm) 💖

okay bestie, welcome to the Zonemaster::Nameserver page, straight out of the User Contributed Perl Documentation section of the manual. it's giving ✨ very central object ✨ and honestly? she ate.

---

🌸 SYNOPSIS 🌸

my $ns = Zonemaster::Nameserver->new({ name => 'ns.nic.se', address => '212.247.7.228' });
my $p = $ns->query('www.iis.se', 'AAAA');

like, that's it. that's the whole vibe. make one, query with it. 💅

---

🦋 DESCRIPTION 🦋

okay so this is a super central object in the Zonemaster framework. literally every DNS conversation with the outside world goes through here, which is the whole point — it means we can do cute things like synthesizing and recording traffic. 👑

also? all the objects are unique per name/IP pair. so if you try to make a new one with a pair that already exists, you don't get a new object — you get the existing one handed right back to you. no duplicates, no drama. that's main character energy fr fr.

and the queries plus their responses are cached by IP address, so a specific query only ever gets sent once to each address — even if there are multiple objects for that address with different names. one query, many objects, zero wasted packets. iconic. 🎀

oh and the class methods on this class let you save and load cache contents. handy!

---

🌈 ATTRIBUTES 🌈

• name — a Zonemaster::DNSName object holding the nameserver's name.
• address — a Zonemaster::Net::IP object holding the nameserver's address.
• dns — the Net::LDNS object that actually sends and receives the DNS queries. the muscle. 💪
• cache — a reference to a Zonemaster::Nameserver::Cache object holding the cache of sent queries. > heads up bestie: this is not meant for external use. hands off. 🙈
• times — a reference to a list with elapsed time values for the queries made through this nameserver. yes, she keeps receipts. ⏱️

---

✨ CLASS METHODS ✨

• save($filename) — save the entire object cache to the given filename, using the byte-order-independent Storable format. portable and cute. 💾
• restore($filename) — replace the entire object cache with the contents of the named file. swapperoo. 🔄
• all_known_nameservers() — class method that returns a list of all nameserver objects in the global cache. the whole group chat, assembled. 🫶
• empty_cache() — remove all cached nameserver objects and queries. scorched earth, but make it tidy. 🧹

---

💅 INSTANCE METHODS 💅

• query($name, $type, $flagref) — send a DNS query to the nameserver this object represents. $name and $type are the name and type you're querying for ($type defaults to 'A' if you leave it undefined). $flagref is a reference to a hash — the keys are flags, the values are their corresponding values. the available flags are:
  • class — defaults to 'IN' if not set.
  • usevc — send the query via TCP (only).
  • retrans — the retransmission interval.
  • dnssec — set the DO flag in the query.
  • debug — set the debug flag in the resolver, producing output on STDERR as the query process proceeds. she's narrating her own life. 😭
  • recurse — set the RD flag in the query.
  • udp_timeout — set the UDP timeout for the outgoing UDP socket. > may or may not be observed by the underlying network stack. (translation: she might listen. no promises. 💀)
  • tcp_timeout — set the TCP timeout for the outgoing TCP socket. > may or may not be observed by the underlying network stack. same energy.
  • retry — set the number of times the query is tried.
  • igntc — if set to true, incoming response packets with the TC flag set are not automatically retried over TCP.

real talk: all of these except the first one directly correspond to methods in the Net::LDNS::Resolver object. iykyk.

• string() — returns a string representation of the object. normally that's just the name and the IP address separated by a slash. clean, simple, slay. 🍓
• compare($other) — used for overloading comparison operators.
• sum_time() — returns the total time spent sending queries and waiting for responses.
• min_time() — returns the shortest time spent on a query.
• max_time() — returns the longest time spent on a query.
• average_time() — returns the average time spent on queries.
• median_time() — returns the median query time.
• stddev_time() — returns the standard deviation for the whole set of query times. math girlies rise up 📊
• add_fake_delegation($domain,$data) — adds fake delegation information to this specific nameserver object. takes the same arguments as the similarly named method in Zonemaster. > this is primarily used for internal information, and using it directly will likely give you confusing results — though it may be useful to model certain kinds of misconfigurations. so like, use with intention, bestie. 🙈
• add_fake_ds($domain, $data) — adds fake DS information to this nameserver object. takes the same arguments as the similarly named method in Zonemaster.
• axfr( $domain, $callback, $class ) — does an AXFR for the requested domain from the nameserver. the callback function gets called once for each received RR, with that RR as its only argument. to continue getting more RRs, the callback must return a true value. > and then the page says: if it returns a true value, the AXFR will be aborted. yeah. that's literally what it says. we are simply reporting the lore. 🫠 see Net::LDNS::axfr for more details.

---

and that's the whole page, bestie!! you're now officially fluent in nameserver objects. go forth and query responsibly 💖✨👑

this little tour was brought to you by perl v5.32.0, dated 2021-01-06. vintage but still serving looks. 🎀🦋