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

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

Tries to make a PTR lookup on the given domain. See reverse_lookup and reverse_verify if you want to resolve an IP address to a hostname instead.

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

Tries to reverse-resolve the given IPv4 or IPv6 address (in textual form) into its hostname(s). Handles V4MAPPED and V4COMPAT IPv6 addresses transparently.

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

The same as reverse_lookup, but does forward-lookups to verify that the resolved hostnames indeed point to the address, which makes spoofing harder.

If you want to resolve an address into a hostname, this is the preferred method: The DNS records could still change, but at least this function verified that the hostname, at one point in the past, pointed at the IP address you originally resolved.

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 RFC 1035 is strongly recommended, then everything will be totally clear. Or maybe not.

os_config will be used for OS-specific configuration, unless $ENV{PERL_ANYEVENT_RESOLV_CONF} is specified, in which case that file gets parsed.

$AnyEvent::DNS::RESOLVER

This variable stores the default resolver returned by AnyEvent::DNS::resolver, or undef when the default resolver hasn't been instantiated yet.

One can provide a custom resolver (e.g. one with caching functionality) by storing it in this variable, causing all subsequent resolves done via AnyEvent::DNS::resolver to be done via the custom one.

$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 or ::1) in network format (i.e. as returned by AnyEvent::Socket::parse_address - both IPv4 and IPv6 are 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 $integer (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 was no time-out then query ids can be reused immediately.

untaint => $boolean

When true, then the resolver will automatically untaint results, and might also ignore certain environment variables.

$resolver->parse_resolv_conf ($string)

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

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.

This method must be called at most once before trying to resolve anything.

$resolver->timeout ($timeout, ...)

Sets the timeout values. See the timeout constructor argument (and note that this method expects the timeout values themselves, not an array-reference).

$resolver->max_outstanding ($nrequests)

Sets the maximum number of outstanding requests to $nrequests. See the max_outstanding constructor argument.

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

This is the main low-level workhorse for sending DNS requests.

This function sends a single request (a hash-ref formated as specified for dns_pack) to the configured nameservers in turn until it gets a response. It handles timeouts, retries and automatically falls back to virtual circuit mode (TCP) when it receives a truncated reply. It does not handle anything else, such as the domain searchlist or relative names - use ->resolve for that.

Calls the callback with the decoded response packet if a reply was received, or no arguments in case none of the servers answered.

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

Queries the DNS for the given domain name $qname of type $qtype.

A $qtype is either a numerical query type (e.g. 1 for A records) or a lowercase name (you have to look at the source to see which aliases are supported, but all types from RFC 1035, aaaa, srv, spf and a few more are known to this module). A $qtype of "*" is supported and means "any" record type.

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 10.

The callback will be invoked with arraryefs of the form [$name, $type, $class, $ttl, @data], where $name is the domain name, $type a type string or number, $class a class name, $ttl is the remaining time-to-live and @data is resource-record-dependent data, in seconds. For a records, this will be the textual IPv4 addresses, for ns or cname records this will be a domain name, for txt records these are all the strings and so on.

All types mentioned in RFC 1035, aaaa, srv, naptr and spf are decoded. All resource records not known to this module will have the raw rdata field as fifth array element.

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 values define its value (depending on ndots, the empty suffix will be prepended or appended to that search 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. If this list includes cname, then CNAME-chains will not be followed (because you asked for the CNAME record).

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.

Wait until a free request slot is available and call the callback with the resolver object.

A request slot is used each time a request is actually sent to the nameservers: There are never more than max_outstanding of them.

Although you can submit more requests (they will simply be queued until a request slot becomes available), sometimes, usually for rate-limiting purposes, it is useful to instead wait for a slot before generating the request (or simply to know when the request load is low enough so one can submit requests again).

This is what this method does: The callback will be called when submitting a DNS request will not result in that request being queued. The callback may or may not generate any requests in response.

Note that the callback will only be invoked when the request queue is empty, so this does not play well if somebody else keeps the request queue full at all times.

AUTHOR

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

Module Install Instructions

To install AnyEvent::DNS, simply copy and paste either of the commands in to your terminal