.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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::Nameserver 3pm"
.TH Zonemaster::Nameserver 3pm "2021-01-06" "perl v5.32.0" "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::Nameserver \- object representing a DNS nameserver
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    my $ns = Zonemaster::Nameserver\->new({ name => \*(Aqns.nic.se\*(Aq, address => \*(Aq212.247.7.228\*(Aq });
\&    my $p = $ns\->query(\*(Aqwww.iis.se\*(Aq, \*(AqAAAA\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a very central object in the Zonemaster framework. All \s-1DNS\s0
communications with the outside world pass through here, so we can do
things like synthezising and recording traffic. All the objects are
also unique per name/IP pair, and creating a new one with an already
existing pair will return the existing object instead of creating a
new one. Queries and their responses are cached by \s-1IP\s0 address, so that
a specific query will only be sent once to each address (even if there
are multiple objects for that address with different names).
.PP
Class methods on this class allows saving and loading cache contents.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.IP "name" 4
.IX Item "name"
A Zonemaster::DNSName object holding the nameserver's name.
.IP "address" 4
.IX Item "address"
A Zonemaster::Net::IP object holding the nameserver's address.
.IP "dns" 4
.IX Item "dns"
The Net::LDNS object used to actually send and receive \s-1DNS\s0 queries.
.IP "cache" 4
.IX Item "cache"
A reference to a Zonemaster::Nameserver::Cache object holding the cache of sent queries. Not meant for external use.
.IP "times" 4
.IX Item "times"
A reference to a list with elapsed time values for the queries made through this nameserver.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP "save($filename)" 4
.IX Item "save($filename)"
Save the entire object cache to the given filename, using the
byte-order-independent Storable format.
.IP "restore($filename)" 4
.IX Item "restore($filename)"
Replace the entire object cache with the contents of the named file.
.IP "\fBall_known_nameservers()\fR" 4
.IX Item "all_known_nameservers()"
Class method that returns a list of all nameserver objects in the global cache.
.IP "\fBempty_cache()\fR" 4
.IX Item "empty_cache()"
Remove all cached nameserver objects and queries.
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.ie n .IP "query($name, $type, $flagref)" 4
.el .IP "query($name, \f(CW$type\fR, \f(CW$flagref\fR)" 4
.IX Item "query($name, $type, $flagref)"
Send a \s-1DNS\s0 query to the nameserver the object represents. \f(CW$name\fR and \f(CW$type\fR are the name and type that will be queried for (\f(CW$type\fR defaults
to 'A' if it's left undefined). \f(CW$flagref\fR is a reference to a hash, the keys of which are flags and the values are their corresponding values.
The available flags are as follows. All but the first directly correspond to methods in the Net::LDNS::Resolver object.
.RS 4
.IP "class" 4
.IX Item "class"
Defaults to '\s-1IN\s0' if not set.
.IP "usevc" 4
.IX Item "usevc"
Send the query via \s-1TCP\s0 (only).
.IP "retrans" 4
.IX Item "retrans"
The retransmission interval
.IP "dnssec" 4
.IX Item "dnssec"
Set the \s-1DO\s0 flag in the query.
.IP "debug" 4
.IX Item "debug"
Set the debug flag in the resolver, producing output on \s-1STDERR\s0 as the query process proceeds.
.IP "recurse" 4
.IX Item "recurse"
Set the \s-1RD\s0 flag in the query.
.IP "udp_timeout" 4
.IX Item "udp_timeout"
Set the \s-1UDP\s0 timeout for the outgoing \s-1UDP\s0 socket. May or may not be observed by the underlying network stack.
.IP "tcp_timeout" 4
.IX Item "tcp_timeout"
Set the \s-1TCP\s0 timeout for the outgoing \s-1TCP\s0 socket. May or may not be observed by the underlying network stack.
.IP "retry" 4
.IX Item "retry"
Set the number of times the query is tried.
.IP "igntc" 4
.IX Item "igntc"
If set to true, incoming response packets with the \s-1TC\s0 flag set are not automatically retried over \s-1TCP.\s0
.RE
.RS 4
.RE
.IP "\fBstring()\fR" 4
.IX Item "string()"
Returns a string representation of the object. Normally this is just the name and \s-1IP\s0 address separated by a slash.
.IP "compare($other)" 4
.IX Item "compare($other)"
Used for overloading comparison operators.
.IP "\fBsum_time()\fR" 4
.IX Item "sum_time()"
Returns the total time spent sending queries and waiting for responses.
.IP "\fBmin_time()\fR" 4
.IX Item "min_time()"
Returns the shortest time spent on a query.
.IP "\fBmax_time()\fR" 4
.IX Item "max_time()"
Returns the longest time spent on a query.
.IP "\fBaverage_time()\fR" 4
.IX Item "average_time()"
Returns the average time spent on queries.
.IP "\fBmedian_time()\fR" 4
.IX Item "median_time()"
Returns the median query time.
.IP "\fBstddev_time()\fR" 4
.IX Item "stddev_time()"
Returns the standard deviation for the whole set of query times.
.IP "add_fake_delegation($domain,$data)" 4
.IX Item "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
confusing results (but may be useful to model certain kinds of
misconfigurations).
.ie n .IP "add_fake_ds($domain, $data)" 4
.el .IP "add_fake_ds($domain, \f(CW$data\fR)" 4
.IX Item "add_fake_ds($domain, $data)"
Adds fake \s-1DS\s0 information to this nameserver object. Takes the same arguments as
the similarly named method in Zonemaster.
.ie n .IP "axfr( $domain, $callback, $class )" 4
.el .IP "axfr( \f(CW$domain\fR, \f(CW$callback\fR, \f(CW$class\fR )" 4
.IX Item "axfr( $domain, $callback, $class )"
Does an \s-1AXFR\s0 for the requested domain from the nameserver. The callback
function will be called once for each received \s-1RR,\s0 with that \s-1RR\s0 as its only
argument. To continue getting more RRs, the callback must return a true value.
If it returns a true value, the \s-1AXFR\s0 will be aborted. See Net::LDNS::axfr
for more details.