.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Zonemaster::Engine::Recursor 3pm"
.TH Zonemaster::Engine::Recursor 3pm 2024-04-22 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Zonemaster::Engine::Recursor \- recursive resolver for Zonemaster
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    my $packet = Zonemaster::Engine::Recursor\->recurse( $name, $type, $dns_class );
\&    my $pname  = Zonemaster::Engine::Recursor\->parent( \*(Aqexample.org\*(Aq );
.Ve
.SH "CLASS VARIABLES"
.IX Header "CLASS VARIABLES"
.ie n .SS %recurse_cache
.el .SS \f(CW%recurse_cache\fP
.IX Subsection "%recurse_cache"
Will cache result of previous queries.
.ie n .SS %_fake_addresses_cache
.el .SS \f(CW%_fake_addresses_cache\fP
.IX Subsection "%_fake_addresses_cache"
A hash of hashrefs of arrayrefs.
The keys of the top level hash are domain names.
The keys of the second level hashes are name server names (normalized to lower
case).
The elements of the third level arrayrefs are IP addresses.
.PP
The IP addresses are those of the nameservers which are used in case of fake
delegations (pre-publication tests).
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.SS \fBinit_recursor()\fP
.IX Subsection "init_recursor()"
Initialize the recursor by loading the root hints.
.ie n .SS "recurse($name, $type, $class)"
.el .SS "recurse($name, \f(CW$type\fP, \f(CW$class\fP)"
.IX Subsection "recurse($name, $type, $class)"
Does a recursive resolution from the root servers down for the given triplet.
.SS parent($name)
.IX Subsection "parent($name)"
Does a recursive resolution from the root down for the given name (using type \f(CW\*(C`SOA\*(C'\fR and class \f(CW\*(C`IN\*(C'\fR). If the resolution is successful, it returns
the domain name of the second-to-last step. If the resolution is unsuccessful, it returns the domain name of the last step.
.ie n .SS "get_ns_from($packet, $state)"
.el .SS "get_ns_from($packet, \f(CW$state\fP)"
.IX Subsection "get_ns_from($packet, $state)"
Internal method. Takes a packet and a recursion state and returns a list of ns objects. Used to follow redirections.
.ie n .SS "get_addresses_for($name[, $state])"
.el .SS "get_addresses_for($name[, \f(CW$state\fP])"
.IX Subsection "get_addresses_for($name[, $state])"
Takes a name and returns a (possibly empty) list of IP addresses for
that name (in the form of Net::IP::XS objects). When used
internally by the recursor it's passed a recursion state as its second
argument.
.ie n .SS "add_fake_addresses($domain, $data)"
.el .SS "add_fake_addresses($domain, \f(CW$data\fP)"
.IX Subsection "add_fake_addresses($domain, $data)"
Class method to create fake addresses for fake delegations for a specified domain from data provided.
.SS has_fake_addresses($domain)
.IX Subsection "has_fake_addresses($domain)"
Check if there is at least one fake nameserver specified for the given domain.
.ie n .SS "get_fake_addresses($domain, $nsname)"
.el .SS "get_fake_addresses($domain, \f(CW$nsname\fP)"
.IX Subsection "get_fake_addresses($domain, $nsname)"
Returns a list of all cached fake addresses for the given domain and name server name.
Returns an empty list if no data is cached for the given arguments.
.SS get_fake_names($domain)
.IX Subsection "get_fake_names($domain)"
Returns a list of all cached fake name server names for the given domain.
Returns an empty list if no data is cached for the given argument.
.SS remove_fake_addresses($domain)
.IX Subsection "remove_fake_addresses($domain)"
Remove fake delegation data for a specified domain.
.SS \fBclear_cache()\fP
.IX Subsection "clear_cache()"
Class method to empty the cache of responses to recursive queries (but not the ones for fake delegations).
.PP
N.B. This method does not affect fake delegation data.
.SS \fBroot_servers()\fP
.IX Subsection "root_servers()"
Returns a list of ns objects representing the root servers.
.PP
.Vb 1
\&    my @name_servers = Zonemaster::Engine::Recursor\->root_servers();
.Ve
.PP
The default list of root servers is read from a file installed in the shared data directory.
This list can be replaced like so:
.PP
.Vb 8
\&    Zonemaster::Engine::Recursor\->remove_fake_addresses( \*(Aq.\*(Aq );
\&    Zonemaster::Engine::Recursor\->add_fake_addresses(
\&        \*(Aq.\*(Aq,
\&        {
\&            \*(Aqns1.example\*(Aq => [\*(Aq192.0.2.1\*(Aq],
\&            \*(Aqns2.example\*(Aq => [\*(Aq192.0.2.2\*(Aq],
\&        }
\&    );
.Ve