NAME
DNS::Unbound - libunbound in Perl
SYNOPSIS
my $dns = DNS::Unbound->new()->set_option( verbosity => 2 );
my $verbosity = $dns->get_option( 'verbosity' );
$dns->set_option( verbosity => 1 + $verbosity );Synchronous queries:
my $res_hr = $dns->resolve( 'cpan.org', 'NS' );
# See below about encodings in “data”.
my @ns = map { $dns->decode_name($_) } @{ $res_hr->{'data'} };Asynchronous queries use the “Promise” pattern:
my $query1 = $dns->resolve_async( 'usa.gov', 'A' )->then(
sub { my $data = shift()->{'data'}; ... }, # success handler
sub { ... }, # failure handler
);
my $query2 = $dns->resolve_async( 'in-addr.arpa', 'NS' )->then(
sub { ... },
sub { ... },
);
# As an alternative to wait(), see below for documentation on
# the fd(), poll(), and process() methods.
$dns->wait();DESCRIPTION
This library is a Perl interface to NLNetLabs’s widely-used Unbound recursive DNS resolver.
METHODS
CLASS->new()
Instantiates this class.
$result_hr = OBJ->resolve( $NAME, $TYPE [, $CLASS ] )
Runs a synchronous query for a given $NAME and $TYPE. $TYPE may be expressed numerically or, for convenience, as a string. $CLASS is optional and defaults to 1 (IN), which is probably what you want.
Returns a reference to a hash that corresponds to a libunbound struct ub_result (cf. libunbound(3)), excluding len, answer_packet, and answer_len.
NOTE: Members of data are in their DNS-native RDATA encodings. (libunbound doesn’t track which record type uses which encoding, so neither does DNS::Unbound.) To decode some common record types, see "CONVENIENCE FUNCTIONS" below.
Also NOTE: libunbound doesn’t seem to offer effective controls for timing out a synchronous query. If timeouts are relevant for you, you probably need to use resolve_async() instead.
$query = OBJ->resolve_async( $NAME, $TYPE [, $CLASS ] );
Like resolve() but starts an asynchronous query rather than a synchronous one.
This returns an instance of DNS::Unbound::AsyncQuery.
See below for the methods you’ll need to use in tandem with this one.
OBJ->enable_threads()
Sets OBJ’s asynchronous queries to use threads rather than forking. Off by default. Throws an exception if called after an asynchronous query has already been sent.
Returns OBJ.
NOTE: Perl’s relationship with threads is … complicated. This option is not well-tested. If in doubt, just skip it.
OBJ->set_option( $NAME => $VALUE )
Sets a configuration option. Returns OBJ.
Note that this is basically just a passthrough to the underlying ub_ctx_set_option() function and is thus subject to the same limitations as that function; for example, you can’t set verbosity after the configuration has been “finalized”. (So use debuglevel() for that instead.)
$value = OBJ->get_option( $NAME )
Gets a configuration option’s value.
OBJ->debuglevel( $LEVEL )
Sets the debug level (an integer). Returns OBJ.
As of libunbound v1.9.2, this is just a way to set the verbosity option regardless of whether the configuration is finalized.
OBJ->debugout( $FD_OR_FH )
Accepts a file descriptor or Perl filehandle and designates that as the destination for libunbound diagnostic information.
Returns OBJ.
$str = CLASS->unbound_version()
Gives the libunbound version string.
METHODS FOR DEALING WITH ASYNCHRONOUS QUERIES
The following methods correspond to their equivalents in libunbound.
OBJ->poll()
OBJ->fd()
OBJ->wait()
OBJ->process()
CONVENIENCE FUNCTIONS
Note that Socket provides the inet_ntoa() and inet_ntop() functions for decoding the values of A and AAAA records.
The following may be called either as object methods or as static functions (but not as class methods):
$decoded = decode_name($encoded)
Decodes a DNS name. Useful for, e.g., NS query results.
Note that this function’s return will normally include a trailing . because of the trailing NUL byte in an encoded DNS name. This is normal and expected.
$strings_ar = decode_character_strings($encoded)
Decodes a list of character-strings into component strings, returned as an array reference. Useful for TXT query results.
REPOSITORY
https://github.com/FGasper/p5-DNS-Unbound
THANK YOU
Special thanks to ATOOMIC for making some helpful review notes.