++ed by:

1 non-PAUSE user.

Felipe Gasper
and 1 contributors


DNS::Unbound - libunbound in Perl


    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.



This library is a Perl interface to NLNetLabs’s widely-used Unbound recursive DNS resolver.



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 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. 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 instance that describes the failure.


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.


The following methods correspond to their equivalents in libunbound:






Note that 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.




Special thanks to ATOOMIC for making some helpful review notes.