NAME

AnyEvent::DNS - fully asynchronous DNS resolution

SYNOPSIS

 use AnyEvent::DNS;

DESCRIPTION

This module offers both a number of DNS convenience functions as well as a fully asynchronous and high-performance pure-perl stub resolver.

The stub resolver supports DNS over UDP, optional EDNS0 support for up to 4kiB datagrams and automatically falls back to virtual circuit mode for large responses.

CONVENIENCE FUNCTIONS

AnyEvent::DNS::addr $node, $service, $proto, $family, $type, $cb->([$family, $type, $proto, $sockaddr], ...)

Tries to resolve the given nodename and service name into protocol families and sockaddr structures usable to connect to this node and service in a protocol-independent way. It works remotely similar to the getaddrinfo posix function.

$node is either an IPv4 or IPv6 address or a hostname, $service is either a service name (port name from /etc/services) or a numerical port number. If both $node and $service are names, then SRV records will be consulted to find the real service, otherwise they will be used as-is. If you know that the service name is not in your services database, then you can specify the service in the format name=port (e.g. http=80).

$proto must be a protocol name, currently tcp, udp or sctp. The default is tcp.

$family must be either 0 (meaning any protocol is OK), 4 (use only IPv4) or 6 (use only IPv6). This setting might be influenced by $ENV{PERL_ANYEVENT_PROTOCOLS}.

$type must be SOCK_STREAM, SOCK_DGRAM or SOCK_SEQPACKET (or undef in which case it gets automatically chosen).

The callback will receive zero or more array references that contain $family, $type, $proto for use in socket and a binary $sockaddr for use in connect (or bind).

The application should try these in the order given.

Example:

   AnyEvent::DNS::addr "google.com", "http", 0, undef, undef, sub { ... };

AnyEvent::DNS::a $domain, $cb->(@addrs)

Tries to resolve the given domain to IPv4 address(es).

AnyEvent::DNS::aaaa $domain, $cb->(@addrs)

Tries to resolve the given domain to IPv6 address(es).

AnyEvent::DNS::mx $domain, $cb->(@hostnames)

Tries to resolve the given domain into a sorted (lower preference value first) list of domain names.

AnyEvent::DNS::ns $domain, $cb->(@hostnames)

Tries to resolve the given domain name into a list of name servers.

AnyEvent::DNS::txt $domain, $cb->(@hostnames)

Tries to resolve the given domain name into a list of text records.

AnyEvent::DNS::srv $service, $proto, $domain, $cb->(@srv_rr)

Tries to resolve the given service, protocol and domain name into a list of service records.

Each srv_rr is an array reference with the following contents: [$priority, $weight, $transport, $target].

They will be sorted with lowest priority, highest weight first (TODO: should use the RFC algorithm to reorder same-priority records for weight).

Example:

   AnyEvent::DNS::srv "sip", "udp", "schmorp.de", sub { ...
   # @_ = ( [10, 10, 5060, "sip1.schmorp.de" ] )

AnyEvent::DNS::ptr $ipv4_or_6, $cb->(@hostnames)

Tries to reverse-resolve the given IPv4 or IPv6 address (in textual form) into it's hostname(s).

Example:

   AnyEvent::DNS::ptr "2001:500:2f::f", sub { print shift };
   # => f.root-servers.net

AnyEvent::DNS::any $domain, $cb->(@rrs)

Tries to resolve the given domain and passes all resource records found to the callback.

LOW-LEVEL DNS EN-/DECODING FUNCTIONS

$AnyEvent::DNS::EDNS0

This variable decides whether dns_pack automatically enables EDNS0 support. By default, this is disabled (0), unless overridden by $ENV{PERL_ANYEVENT_EDNS0), but when set to 1, AnyEvent::DNS will use EDNS0 in all requests.

$pkt = AnyEvent::DNS::dns_pack $dns

Packs a perl data structure into a DNS packet. Reading RFC1034 is strongly recommended, then everything will be totally clear. Or maybe not.

Resource records are not yet encodable.

Examples:

  # very simple request, using lots of default values:
  { rd => 1, qd => [ [ "host.domain", "a"] ] }

  # more complex example, showing how flags etc. are named:

  {
     id => 10000,
     op => "query",
     rc => "nxdomain",

     # flags
     qr => 1,
     aa => 0,
     tc => 0,
     rd => 0,
     ra => 0,
     ad => 0,
     cd => 0,

     qd => [@rr], # query section
     an => [@rr], # answer section
     ns => [@rr], # authority section
     ar => [@rr], # additional records section
  }

$dns = AnyEvent::DNS::dns_unpack $pkt

Unpacks a DNS packet into a perl data structure.

Examples:

  # an unsuccessful reply
  {
    'qd' => [
              [ 'ruth.plan9.de.mach.uni-karlsruhe.de', '*', 'in' ]
            ],
    'rc' => 'nxdomain',
    'ar' => [],
    'ns' => [
              [
                'uni-karlsruhe.de',
                'soa',
                'in',
                'netserv.rz.uni-karlsruhe.de',
                'hostmaster.rz.uni-karlsruhe.de',
                2008052201, 10800, 1800, 2592000, 86400
              ]
            ],
    'tc' => '',
    'ra' => 1,
    'qr' => 1,
    'id' => 45915,
    'aa' => '',
    'an' => [],
    'rd' => 1,
    'op' => 'query'
  }

  # a successful reply

  {
    'qd' => [ [ 'www.google.de', 'a', 'in' ] ],
    'rc' => 0,
    'ar' => [
              [ 'a.l.google.com', 'a', 'in', '209.85.139.9' ],
              [ 'b.l.google.com', 'a', 'in', '64.233.179.9' ],
              [ 'c.l.google.com', 'a', 'in', '64.233.161.9' ],
            ],
    'ns' => [
              [ 'l.google.com', 'ns', 'in', 'a.l.google.com' ],
              [ 'l.google.com', 'ns', 'in', 'b.l.google.com' ],
            ],
    'tc' => '',
    'ra' => 1,
    'qr' => 1,
    'id' => 64265,
    'aa' => '',
    'an' => [
              [ 'www.google.de', 'cname', 'in', 'www.google.com' ],
              [ 'www.google.com', 'cname', 'in', 'www.l.google.com' ],
              [ 'www.l.google.com', 'a', 'in', '66.249.93.104' ],
              [ 'www.l.google.com', 'a', 'in', '66.249.93.147' ],
            ],
    'rd' => 1,
    'op' => 0
  }

THE AnyEvent::DNS RESOLVER CLASS

This is the class which does the actual protocol work.

AnyEvent::DNS::resolver

This function creates and returns a resolver that is ready to use and should mimic the default resolver for your system as good as possible.

It only ever creates one resolver and returns this one on subsequent calls.

Unless you have special needs, prefer this function over creating your own resolver object.

$resolver = new AnyEvent::DNS key => value...

Creates and returns a new resolver.

The following options are supported:

server => [...]

A list of server addresses (default: v127.0.0.1) in network format (4 octets for IPv4, 16 octets for IPv6 - not yet supported).

timeout => [...]

A list of timeouts to use (also determines the number of retries). To make three retries with individual time-outs of 2, 5 and 5 seconds, use [2, 5, 5], which is also the default.

search => [...]

The default search list of suffixes to append to a domain name (default: none).

ndots => $integer

The number of dots (default: 1) that a name must have so that the resolver tries to resolve the name without any suffixes first.

max_outstanding => $integer

Most name servers do not handle many parallel requests very well. This option limits the number of outstanding requests to $n (default: 10), that means if you request more than this many requests, then the additional requests will be queued until some other requests have been resolved.

reuse => $seconds

The number of seconds (default: 300) that a query id cannot be re-used after a timeout. If there as no time-out then query id's can be reused immediately.

$resolver->parse_resolv_conv ($string)

Parses the given string as if it were a resolv.conf file. The following directives are supported (but not necessarily implemented).

#-style comments, nameserver, domain, search, sortlist, options (timeout, attempts, ndots).

Everything else is silently ignored.

$resolver->os_config

Tries so load and parse /etc/resolv.conf on portable operating systems. Tries various egregious hacks on windows to force the DNS servers and searchlist out of the system.

$resolver->request ($req, $cb->($res))

Sends a single request (a hash-ref formated as specified for dns_pack) to the configured nameservers including retries. Calls the callback with the decoded response packet if a reply was received, or no arguments on timeout.

$resolver->resolve ($qname, $qtype, %options, $cb->($rcode, @rr))

Queries the DNS for the given domain name $qname of type $qtype (a qtype of "*" is supported and means "any").

The callback will be invoked with a list of matching result records or none on any error or if the name could not be found.

CNAME chains (although illegal) are followed up to a length of 8.

Note that this resolver is just a stub resolver: it requires a name server supporting recursive queries, will not do any recursive queries itself and is not secure when used against an untrusted name server.

The following options are supported:

search => [$suffix...]

Use the given search list (which might be empty), by appending each one in turn to the $qname. If this option is missing then the configured ndots and search define its value. If the $qname ends in a dot, then the searchlist will be ignored.

accept => [$type...]

Lists the acceptable result types: only result types in this set will be accepted and returned. The default includes the $qtype and nothing else.

class => "class"

Specify the query class ("in" for internet, "ch" for chaosnet and "hs" for hesiod are the only ones making sense). The default is "in", of course.

Examples:

   $res->resolve ("ruth.plan9.de", "a", sub {
      warn Dumper [@_];
   });

   [
     [
       'ruth.schmorp.de',
       'a',
       'in',
       '129.13.162.95'
     ]
   ]

   $res->resolve ("test1.laendle", "*",
      accept => ["a", "aaaa"],
      sub {
         warn Dumper [@_];
      }
   );

   [
     [
       'test1.laendle',
       'a',
       'in',
       '10.0.0.255'
     ],
     [
       'test1.laendle',
       'aaaa',
       'in',
       '3ffe:1900:4545:0002:0240:0000:0000:f7e1'
     ]
   ]

AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/