Ubuntu Manpage: Net::DNS::Resolver::Unbound - Net::DNS resolver based on libunbound

Provided by: libnet-dns-resolver-unbound-perl_1.32-1_amd64

NAME

       Net::DNS::Resolver::Unbound - Net::DNS resolver based on libunbound

SYNOPSIS

               use Net::DNS;
               use Net::DNS::Resolver::Unbound;
               my $resolver = Net::DNS::Resolver::Unbound->new(...);
               my $response = $resolver->send(...);

DESCRIPTION

Net::DNS::Resolver::Unbound is designed as an extension to an existing Net::DNS installation which
facilitates DNS(SEC) name resolution using the libunbound library developed by NLnet Labs.

Net::DNS::Resolver::Unbound replaces the resolver send() and bgsend() functionality in the
Net::DNS::Resolver::Base implementation.

As of this writing, the implementation has some significant limitations:

• Selection of transport protocol and associated parameters is almost entirely at the discretion of
Unbound.

• There is no provision for specifying DNS header flags or EDNS options in outbound packets.

• It is not possible to send a pre-constructed packet to a nameserver. A best-effort attempt is made
instead using (qname,qtype,qclass) extracted from the presented packet.

• Result packet is synthesised in libunbound and not the "real thing". In particular, the queryID
returned by Unbound is always zero.

Replacing Net::DNS::Resolver Base Class
Placing "-register" in the Net::DNS::Resolver::Unbound import list, will cause it to register itself with
Net::DNS as the resolver base class.

use Net::DNS;
use Net::DNS::Resolver::Unbound -register;
my $resolver = Net::DNS::Resolver->new(...);
my $response = $resolver->send(...);

Note that "-register" is a global setting that applies to the entire program; it cannot be applied only
for certain callers, removed, or limited by lexical scope.

METHODS

   new
               # Use the default configuration
               my $resolver = Net::DNS::Resolver::Unbound->new();

               # Set options in the constructor
               my $resolver = Net::DNS::Resolver::Unbound->new(
                       debug_level => 2,
                       defnames    => 1,
                       dnsrch,     => 1,
                       domain      => 'domain',
                       nameservers => [ '2001:DB8::1', ... ],
                       ndots       => 1,
                       searchlist  => ['domain' ... ]
                       );

       Returns  a  new Net::DNS::Resolver::Unbound resolver object.  If no arguments are supplied, new() returns
       an object having the default configuration.

       On Unix and Linux systems, the default values are read from the following files, in the order indicated:

           /etc/resolv.conf, $HOME/.resolv.conf, ./.resolv.conf

       The following keywords are recognised in resolver configuration files:

       nameserver
           IP address of a name server that the resolver should query.

       domain
           The domain suffix to be appended to a short non-absolute name.

       search
           A space-separated list of domains in the desired search path.

       Except for /etc/resolv.conf, files will only be read  if  owned  by  the  effective  userid  running  the
       program.

       Note  that the domain and searchlist keywords are mutually exclusive.  If both are present, the resulting
       behaviour is unspecified.  If neither is present, the domain is determined from the local hostname.

   nameservers
               my $dnssec_resolver = Net::DNS::Resolver::Unbound->new(
                       nameservers => [],      # override /etc/resolv.conf
                       add_ta_file => '/var/lib/unbound/root.key'
                       );

               my $DoT_resolver = Net::DNS::Resolver::Unbound->new(
                       nameserver => '2606:4700:4700::1111@853#cloudflare-dns.com',
                       nameserver => '1.1.1.1@853#cloudflare-dns.com',
                       nameserver => '2001:4860:4860::8888@853#dns.google',
                       nameserver => '8.8.8.8@853#dns.google',
                       option  => ['tls-cert-bundle' => '/etc/ssl/cert.pem'],
                       set_tls => 1
                       );

               $resolver->nameservers( '::1', '127.0.0.1', ... );
               @nameservers = $resolver->nameservers;

       By default, DNS queries are sent to the IP addresses listed  in  /etc/resolv.conf  or  similar  platform-
       specific sources.

   search, query, send, bgsend, bgbusy, bgread
       See Net::DNS::Resolver.

   option
               $resolver->option( 'tls-cert-bundle' => '/etc/ssl/cert.pem' );

       Set Unbound resolver (name,value) context option.

   config
               $resolver->config( 'Unbound.cfg' );

       This is a power-users interface that lets you specify all sorts of Unbound configuration options.

   set_fwd
               $resolver->set_fwd( 'IP address' );

       Set IPv4 or IPv6 address to which DNS queries are to be directed.  The destination machine is expected to
       run  a  recursive  resolver.   If  the  proxy  is not DNSSEC-capable, validation may fail.  Can be called
       several times, in that case the addresses are used as backup servers.

   set_tls
               $resolver->set_tls( 0 );
               $resolver->set_tls( 1 );

       Use DNS over TLS for queries to nameservers specified using set_fwd().

   set_stub
               $resolver->set_stub( 'zone', '10.1.2.3', 0 );

       Add a stub zone, with given address to send to. This is for custom root hints  or  pointing  to  a  local
       authoritative DNS server. For DNS resolvers and the 'DHCP DNS' IP address, use set_fwd().

   resolv_conf
               $resolver->resolv_conf( 'filename' );

       Extract  nameserver list from resolv.conf(5) format configuration file.  Any domain, searchlist, ndots or
       other settings are ignored.

       Note that Net::DNS builds its own nameserver  list  using  /etc/resolv.conf  or  other  platform-specific
       sources.

   hosts
               $resolver->hosts( 'filename' );

       Read  list  of  hosts  from  the  filename given, usually /etc/hosts.  These addresses are not flagged as
       DNSSEC secure when queried.

   add_ta
               $resolver->add_ta( 'trust anchor' );

       Add a trust anchor which is a string that holds a valid DNSKEY or DS RR in RFC1035 zonefile format.

   add_ta_file
               $resolver->add_ta_file( '/var/lib/unbound/root.key' );

       Pass the name of a file containing DS and DNSKEY records (as from dig or drill).

   add_ta_autr
               $resolver->add_ta_autr( 'filename' );

       Add trust anchor to the given context that is tracked with RFC5011 automated  trust  anchor  maintenance.
       The file is written when the trust anchor is changed.

   trusted_keys
               $resolver->trusted_keys( 'filename' );

       Pass the name of a BIND-style config file containing trusted-keys{}.

   debug_out
               $resolver->debug_out( out );

       Send  debug  output  (and  error  output)  to the specified stream.  Pass a null argument to disable. The
       default is stderr.

   debug_level
               $resolver->debug_level(0);

       Set verbosity of the debug output directed to stderr.  The default level 0 is off, 1 minimal, 2 detailed,
       3 lots, and 4 lots more.

   async_thread
               $resolver->async_thread(1);

       Set the context behaviour for asynchronous actions.  Enable a call to resolve_async() to create a  thread
       to handle work in the background.  If false (by default), a process is forked to perform the work.

   print, string
               $resolver->print;
               print $resolver->string;

       Prints the resolver state on the standard output.

COPYRIGHT

       Copyright (c)2022,2024 Dick Franks

       All Rights Reserved

LICENSE