NAME
Zonemaster::Engine::Recursor - recursive resolver for Zonemaster
SYNOPSIS
my $packet = Zonemaster::Engine::Recursor->recurse( $name, $type, $dns_class );
my $pname = Zonemaster::Engine::Recursor->parent( 'example.org' );CLASS VARIABLES
%_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.
The IP addresses are those of the nameservers which are used in case of fake delegations (pre-publication tests).
CLASS METHODS
init_recursor()
Initialize the recursor by loading the root hints.
recurse($name[, $type, $class, $ns])
Does a recursive resolution for the given name down from the root servers (or for the given name server(s), if any). Only the first argument is mandatory. The rest are optional and default to, respectively: 'A', 'IN', and "root_servers()".
Takes a string or a Zonemaster::Engine::DNSName object (name); and optionally a string (query type), a string (query class), and an arrayref of Zonemaster::Engine::Nameserver objects.
Returns a Zonemaster::Engine::Packet object (which can be undef).
parent($name)
Does a recursive resolution from the root down for the given name (using type SOA and class IN). 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.
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.
add_fake_addresses($domain, $data)
Class method to create fake addresses for fake delegations for a specified domain from data provided.
has_fake_addresses($domain)
Check if there is at least one fake nameserver specified for the given domain.
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.
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.
remove_fake_addresses($domain)
Remove fake delegation data for a specified domain.
clear_cache()
Class method to empty the cache of responses to recursive queries (but not the ones for fake delegations).
N.B. This method does not affect fake delegation data.
root_servers()
Returns a list of Zonemaster::Engine::Nameserver objects representing the root servers.
my @name_servers = Zonemaster::Engine::Recursor->root_servers();The default list of root servers is read from a file installed in the shared data directory. This list can be replaced like so:
Zonemaster::Engine::Recursor->remove_fake_addresses( '.' );
Zonemaster::Engine::Recursor->add_fake_addresses(
'.',
{
'ns1.example' => ['192.0.2.1'],
'ns2.example' => ['192.0.2.2'],
}
);INTERNAL METHODS
_recurse()
my ( $p, $state_hash ) = _recurse( $name, $type_string, $dns_class_string, $p, $state_hash );Performs a recursive lookup resolution for the given arguments. Used by the recursive lookup method in this module.
Takes a Zonemaster::Engine::DNSName object, a string (query type), a string (DNS class), a Zonemaster::Engine::Packet object, and a reference to a hash. The mandatory keys for that hash are 'ns' (arrayref), 'count' (integer), 'common' (integer), 'seen' (hash), 'glue' (hash) and optional keys are 'in_progress' (hash), 'candidate' (Zonemaster::Engine::Packet object or undef), 'trace' (array), 'tseen' (hash), 'tcount' (integer).
Returns a Zonemaster::Engine::Packet (or undef) and a hash.
_get_ns_from()
my @ns = _get_ns_from( $packet, $state );Used to follow redirections by the recursive lookup helper method in this module.
Takes a Zonemaster::Engine::Packet object and a reference to a hash.
Returns a list of Zonemaster::Engine::Nameserver objects.
_resolve_cname()
my ( $p, $state_hash ) = _resolve_cname( $name, $type_string, $dns_class_string, $p, $state_hash );Performs a CNAME resolution for the given arguments. Used by the recursive lookup helper method in this module. If the CNAME resolution is successful, the first return value will be a packet (which could be undef) and at least one of the following message tags is logged:
- CNAME_FOLLOWED_IN_ZONE
-
This message tag indicates that the CNAME target was found in the current response and has the requested record type, so no additional recursion is needed.
- CNAME_FOLLOWED_OUT_OF_ZONE
-
This message tag indicates that the CNAME target is outside the queried name's zone and is resolved through a new recursive lookup.
- CNAME_TO_NODATA
-
This message tag indicates that the CNAME target was resolved authoritatively. The name exists but not with the requested record type.
Note that the resolution has multiple validation steps and, in case of an error, the first return value will be undef and at least one of the following message tags is logged:
- CNAME_CHAIN_TOO_LONG
-
This message tag indicates that the number of distinct lookups made to resolve a CNAME chain is longer than the maximum allowed length with respect to $CNAME_MAX_CHAIN_LENGTH.
- CNAME_LOOP_INNER
-
This message tag indicates that there is a loop in the CNAME chain within the same zone.
- CNAME_LOOP_OUTER
-
This message tag indicates that there is a loop in the CNAME chain across different zones.
- CNAME_RECORDS_CHAIN_BROKEN
-
This message tag indicates that the CNAME chain in the current response is broken, i.e. that with multiple CNAME records in a response there is at least one CNAME record with a target that does not point to a corresponding CNAME record in the same response.
- CNAME_RECORDS_MULTIPLE_FOR_NAME
-
This message tag indicates that there are more than one CNAME record with the same owner name in the current response.
- CNAME_RECORDS_TOO_MANY
-
This message tag indicates that there are too many, with respect to $CNAME_MAX_RECORDS, non-duplicate CNAME records in the current response.
- CNAME_UNRESOLVABLE
-
This message tag indicates that the CNAME resolution could not be completed and is there as a catch-all to handle unforeseen problems in the CNAME resolution process.
Finally the following message tags can be also be logged alongside all of the above message tags:
- CNAME_RECORDS_DUPLICATES
-
This message tag indicates that there are duplicate CNAME records in the current response.
- CNAME_NO_MATCH
-
This message tag indicates that there is a record of the requested type in the answer section of the response but with a different owner name than the CNAME target within that same response.
Takes a Zonemaster::Engine::DNSName object, a string (query type), a string (DNS class), a Zonemaster::Engine::Packet, and a reference to a hash.
Returns a Zonemaster::Engine::Packet (or undef) and a reference to a hash.