use AnyEvent::DNS; my $cv = AnyEvent->condvar; AnyEvent::DNS::a "www.google.de", $cv; # ... later my @addrs = $cv->recv;
The stub resolver supports DNS over IPv4 and IPv6, UDP and TCP, optional EDNS0 support for up to 4kiB datagrams and automatically falls back to virtual circuit mode for large responses.
resolver->resolve ($domain => "txt", sub {
for my $record (@_) {
my (undef, undef, undef, @txt) = @$record;
# strings now in @txt
}
});
Each $srv_rr is an array reference with the following contents: "[$priority, $weight, $transport, $target]".
They will be sorted with lowest priority first, then randomly distributed by weight as per RFC 2782.
Example:
AnyEvent::DNS::srv "sip", "udp", "schmorp.de", sub { ...
# @_ = ( [10, 10, 5060, "sip1.schmorp.de" ] )
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.
Example:
AnyEvent::DNS::reverse_verify "2001:500:2f::f", sub { print shift };
# => f.root-servers.net
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
}
Examples:
# an unsuccessful reply
{
'qd' => [
[ 'ruth.plan9.de.mach.uni-karlsruhe.de', '*', 'in' ]
],
'rc' => 'nxdomain',
'ar' => [],
'ns' => [
[
'uni-karlsruhe.de',
'soa',
'in',
600,
'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',
'__' => '<original dns packet>',
}
# a successful reply
{
'qd' => [ [ 'www.google.de', 'a', 'in' ] ],
'rc' => 0,
'ar' => [
[ 'a.l.google.com', 'a', 'in', 3600, '209.85.139.9' ],
[ 'b.l.google.com', 'a', 'in', 3600, '64.233.179.9' ],
[ 'c.l.google.com', 'a', 'in', 3600, '64.233.161.9' ],
],
'ns' => [
[ 'l.google.com', 'ns', 'in', 3600, 'a.l.google.com' ],
[ 'l.google.com', 'ns', 'in', 3600, 'b.l.google.com' ],
],
'tc' => '',
'ra' => 1,
'qr' => 1,
'id' => 64265,
'aa' => '',
'an' => [
[ 'www.google.de', 'cname', 'in', 3600, 'www.google.com' ],
[ 'www.google.com', 'cname', 'in', 3600, 'www.l.google.com' ],
[ 'www.l.google.com', 'a', 'in', 3600, '66.249.93.104' ],
[ 'www.l.google.com', 'a', 'in', 3600, '66.249.93.147' ],
],
'rd' => 1,
'op' => 0,
'__' => '<original dns packet>',
}
Extending DNS Encoder and Decoder
This section describes an experimental method to extend the DNS encoder and decoder with new opcode, rcode, class and type strings, as well as resource record decoders.
Since this is experimental, it can change, as anything can change, but this interface is expe ctedc to be relatively stable and was stable during the whole existance of "AnyEvent::DNS" so far.
Note that, since changing the decoder or encoder might break existing code, you should either be sure to control for this, or only temporarily change these values, e.g. like so:
my $decoded = do {
local $AnyEvent::DNS::opcode_str{7} = "yxrrset";
AnyEvent::DNS::dns_unpack $mypkt
};
$AnyEvent::DNS::opcode_id{notzone} = 10;
$AnyEvent::DNS::opcode_str{10} = 'notzone';
Decode an A record. A records are simply four bytes with one byte per address component, so the decoder simply unpacks them and joins them with dots in between:
$AnyEvent::DNS::dec_rr{1} = sub { join ".", unpack "C4", $_ };
Decode a CNAME record, which contains a potentially compressed domain name.
package AnyEvent::DNS; # for %dec_rr, $ofsd and &_dec_name
$dec_rr{5} = sub { local $ofs = $ofs - length; _dec_name };
It only ever creates one resolver and returns this one on subsequent calls - see $AnyEvent::DNS::RESOLVER, below, for details.
Unless you have special needs, prefer this function over creating your own resolver object.
The resolver is created with the following parameters:
untaint enabled
max_outstanding $ENV{PERL_ANYEVENT_MAX_OUTSTANDING_DNS} (default 10)
"os_config" will be used for OS-specific configuration, unless $ENV{PERL_ANYEVENT_RESOLV_CONF} is specified, in which case that file gets parsed.
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.
The following options are supported:
"#"- and ";"-style comments, "nameserver", "domain", "search", "sortlist", "options" ("timeout", "attempts", "ndots").
Everything else is silently ignored.
This method must be called at most once before trying to resolve anything.
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.
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:
Examples:
# full example, you can paste this into perl:
use Data::Dumper;
use AnyEvent::DNS;
AnyEvent::DNS::resolver->resolve (
"google.com", "*", my $cv = AnyEvent->condvar);
warn Dumper [$cv->recv];
# shortened result:
# [
# [ 'google.com', 'soa', 'in', 3600, 'ns1.google.com', 'dns-admin.google.com',
# 2008052701, 7200, 1800, 1209600, 300 ],
# [
# 'google.com', 'txt', 'in', 3600,
# 'v=spf1 include:_netblocks.google.com ~all'
# ],
# [ 'google.com', 'a', 'in', 3600, '64.233.187.99' ],
# [ 'google.com', 'mx', 'in', 3600, 10, 'smtp2.google.com' ],
# [ 'google.com', 'ns', 'in', 3600, 'ns2.google.com' ],
# ]
# resolve a records:
$res->resolve ("ruth.plan9.de", "a", sub { warn Dumper [@_] });
# result:
# [
# [ 'ruth.schmorp.de', 'a', 'in', 86400, '129.13.162.95' ]
# ]
# resolve any records, but return only a and aaaa records:
$res->resolve ("test1.laendle", "*",
accept => ["a", "aaaa"],
sub {
warn Dumper [@_];
}
);
# result:
# [
# [ 'test1.laendle', 'a', 'in', 86400, '10.0.0.255' ],
# [ 'test1.laendle', 'aaaa', 'in', 60, '3ffe:1900:4545:0002:0240:0000:0000:f7e1' ]
# ]
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.
Marc Lehmann <schmorp@schmorp.de> http://anyevent.schmorp.de