NAME
DNS::Unbound - libunbound in Perl
SYNOPSIS
my $dns = DNS::Unbound->new()->set_option( verbosity => 2 );
# This appears to be safe:
$dns->enable_threads();
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();See examples/ in the distribution for demonstrations of making this module interface with AnyEvent or IO::Async.
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 DNS::Unbound::Result instance.
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: Despite Perl’s iffy relationship with threads, this appears to work without issue.
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
Unless otherwise noted, the following methods correspond to their equivalents in libunbound.
OBJ->poll()
OBJ->fd()
OBJ->wait()
OBJ->process()
OBJ->count_pending_queries()
Returns the number of outstanding asynchronous queries.
METHODS FOR DEALING WITH DNSSEC
The following correspond to their equivalents in libunbound.
OBJ->add_ta()
OBJ->add_ta_autr()
OBJ->add_ta_file()
OBJ->trustedkeys()
CONVENIENCE FUNCTIONS
The following may be called either as object methods or as static functions (but not as class methods). In addition to these, Socket provides the inet_ntoa() and inet_ntop() functions for decoding the values of A and AAAA records.
NOTE: Consider parsing DNS::Unbound::Result’s answer_packet() with Net::DNS::Packet as a more robust, albeit heavier, way to parse query result data.
$decoded = decode_name($encoded)
Decodes a DNS name. Useful for, e.g., NS, CNAME, and PTR 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.
LICENSE & COPYRIGHT
Copyright 2019 Gasper Software Consulting.
This library is licensed under the same terms as Perl itself.
REPOSITORY
https://github.com/FGasper/p5-DNS-Unbound
THANK YOU
Special thanks to ATOOMIC for making some helpful review notes.