# NAME

# 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises):

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](https://nlnetlabs.nl/projects/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)](https://nlnetlabs.nl/documentation/unbound/libunbound/)),
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"](#convenience-functions) below.

Also **NOTE:** libunbound’s facilities for timing out a synchronous query
are rather lackluster. If that’s relevant for you, you probably want
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`, which
subclasses [Promise::ES6](https://metacpan.org/pod/Promise::ES6). You may `cancel()` this promise object.
The promise resolves with either the same hash reference as
`resolve()` returns, or it rejects with a [DNS::Unbound::X](https://metacpan.org/pod/DNS::Unbound::X) instance
that describes the failure.

## _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_.

## $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 after 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](https://metacpan.org/pod/Socket) provides the `inet_ntoa()` and `inet_ntop()`
functions for decoding `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 will normally include a trailing `.` because of the
trailing NUL byte in an encoded DNS name.

## $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](https://github.com/FGasper/p5-DNS-Unbound)

# THANK YOU

Special thanks to [ATOOMIC](https://metacpan.org/author/ATOOMIC) for
making some helpful review notes.