1AnyEvent::DNS(3) User Contributed Perl Documentation AnyEvent::DNS(3)
2
6 AnyEvent::DNS - fully asynchronous DNS resolution
7
9 use AnyEvent::DNS;
10 my $cv = AnyEvent->condvar;
12 AnyEvent::DNS::a "www.google.de", $cv;
13 # ... later
14 my @addrs = $cv->recv;
15
17 This module offers both a number of DNS convenience functions as well
18 as a fully asynchronous and high-performance pure-perl stub resolver.
19 The stub resolver supports DNS over IPv4 and IPv6, UDP and TCP,
21 optional EDNS0 support for up to 4kiB datagrams and automatically falls
22 back to virtual circuit mode for large responses.
23 CONVENIENCE FUNCTIONS
25 AnyEvent::DNS::a $domain, $cb->(@addrs)
26 Tries to resolve the given domain to IPv4 address(es).
27 AnyEvent::DNS::aaaa $domain, $cb->(@addrs)
29 Tries to resolve the given domain to IPv6 address(es).
30 AnyEvent::DNS::mx $domain, $cb->(@hostnames)
32 Tries to resolve the given domain into a sorted (lower preference
33 value first) list of domain names.
34 AnyEvent::DNS::ns $domain, $cb->(@hostnames)
36 Tries to resolve the given domain name into a list of name servers.
37 AnyEvent::DNS::txt $domain, $cb->(@hostnames)
39 Tries to resolve the given domain name into a list of text records.
40 Only the first text string per record will be returned. If you want
41 all strings, you need to call the resolver manually:
42 resolver->resolve ($domain => "txt", sub {
44 for my $record (@_) {
45 my (undef, undef, undef, @txt) = @$record;
46 # strings now in @txt
47 }
48 });
49 AnyEvent::DNS::srv $service, $proto, $domain, $cb->(@srv_rr)
51 Tries to resolve the given service, protocol and domain name into a
52 list of service records.
53 Each $srv_rr is an array reference with the following contents:
55 "[$priority, $weight, $transport, $target]".
56 They will be sorted with lowest priority first, then randomly
58 distributed by weight as per RFC 2782.
59 Example:
61 AnyEvent::DNS::srv "sip", "udp", "schmorp.de", sub { ...
63 # @_ = ( [10, 10, 5060, "sip1.schmorp.de" ] )
64 AnyEvent::DNS::any $domain, $cb->(@rrs)
66 Tries to resolve the given domain and passes all resource records
67 found to the callback. Note that this uses a DNS "ANY" query,
68 which, as of RFC 8482, are officially deprecated.
69 AnyEvent::DNS::ptr $domain, $cb->(@hostnames)
71 Tries to make a PTR lookup on the given domain. See
72 "reverse_lookup" and "reverse_verify" if you want to resolve an IP
73 address to a hostname instead.
74 AnyEvent::DNS::reverse_lookup $ipv4_or_6, $cb->(@hostnames)
76 Tries to reverse-resolve the given IPv4 or IPv6 address (in textual
77 form) into its hostname(s). Handles V4MAPPED and V4COMPAT IPv6
78 addresses transparently.
79 AnyEvent::DNS::reverse_verify $ipv4_or_6, $cb->(@hostnames)
81 The same as "reverse_lookup", but does forward-lookups to verify
82 that the resolved hostnames indeed point to the address, which
83 makes spoofing harder.
84 If you want to resolve an address into a hostname, this is the
86 preferred method: The DNS records could still change, but at least
87 this function verified that the hostname, at one point in the past,
88 pointed at the IP address you originally resolved.
89 Example:
91 AnyEvent::DNS::reverse_verify "2001:500:2f::f", sub { print shift };
93 # => f.root-servers.net
94 LOW-LEVEL DNS EN-/DECODING FUNCTIONS
96 $AnyEvent::DNS::EDNS0
97 This variable decides whether dns_pack automatically enables EDNS0
98 support. By default, this is disabled (0), unless overridden by
99 $ENV{PERL_ANYEVENT_EDNS0}, but when set to 1, AnyEvent::DNS will
100 use EDNS0 in all requests.
101 $pkt = AnyEvent::DNS::dns_pack $dns
103 Packs a perl data structure into a DNS packet. Reading RFC 1035 is
104 strongly recommended, then everything will be totally clear. Or
105 maybe not.
106 Resource records are not yet encodable.
108 Examples:
110 # very simple request, using lots of default values:
112 { rd => 1, qd => [ [ "host.domain", "a"] ] }
113 # more complex example, showing how flags etc. are named:
115 {
117 id => 10000,
118 op => "query",
119 rc => "nxdomain",
120 # flags
122 qr => 1,
123 aa => 0,
124 tc => 0,
125 rd => 0,
126 ra => 0,
127 ad => 0,
128 cd => 0,
129 qd => [@rr], # query section
131 an => [@rr], # answer section
132 ns => [@rr], # authority section
133 ar => [@rr], # additional records section
134 }
135 $dns = AnyEvent::DNS::dns_unpack $pkt
137 Unpacks a DNS packet into a perl data structure.
138 Examples:
140 # an unsuccessful reply
142 {
143 'qd' => [
144 [ 'ruth.plan9.de.mach.uni-karlsruhe.de', '*', 'in' ]
145 ],
146 'rc' => 'nxdomain',
147 'ar' => [],
148 'ns' => [
149 [
150 'uni-karlsruhe.de',
151 'soa',
152 'in',
153 600,
154 'netserv.rz.uni-karlsruhe.de',
155 'hostmaster.rz.uni-karlsruhe.de',
156 2008052201, 10800, 1800, 2592000, 86400
157 ]
158 ],
159 'tc' => '',
160 'ra' => 1,
161 'qr' => 1,
162 'id' => 45915,
163 'aa' => '',
164 'an' => [],
165 'rd' => 1,
166 'op' => 'query',
167 '__' => '<original dns packet>',
168 }
169 # a successful reply
171 {
173 'qd' => [ [ 'www.google.de', 'a', 'in' ] ],
174 'rc' => 0,
175 'ar' => [
176 [ 'a.l.google.com', 'a', 'in', 3600, '209.85.139.9' ],
177 [ 'b.l.google.com', 'a', 'in', 3600, '64.233.179.9' ],
178 [ 'c.l.google.com', 'a', 'in', 3600, '64.233.161.9' ],
179 ],
180 'ns' => [
181 [ 'l.google.com', 'ns', 'in', 3600, 'a.l.google.com' ],
182 [ 'l.google.com', 'ns', 'in', 3600, 'b.l.google.com' ],
183 ],
184 'tc' => '',
185 'ra' => 1,
186 'qr' => 1,
187 'id' => 64265,
188 'aa' => '',
189 'an' => [
190 [ 'www.google.de', 'cname', 'in', 3600, 'www.google.com' ],
191 [ 'www.google.com', 'cname', 'in', 3600, 'www.l.google.com' ],
192 [ 'www.l.google.com', 'a', 'in', 3600, '66.249.93.104' ],
193 [ 'www.l.google.com', 'a', 'in', 3600, '66.249.93.147' ],
194 ],
195 'rd' => 1,
196 'op' => 0,
197 '__' => '<original dns packet>',
198 }
199 Extending DNS Encoder and Decoder
201 This section describes an experimental method to extend the DNS encoder
203 and decoder with new opcode, rcode, class and type strings, as well as
204 resource record decoders.
205 Since this is experimental, it can change, as anything can change, but
207 this interface is expe ctedc to be relatively stable and was stable
208 during the whole existance of "AnyEvent::DNS" so far.
209 Note that, since changing the decoder or encoder might break existing
211 code, you should either be sure to control for this, or only
212 temporarily change these values, e.g. like so:
213 my $decoded = do {
215 local $AnyEvent::DNS::opcode_str{7} = "yxrrset";
216 AnyEvent::DNS::dns_unpack $mypkt
217 };
218 %AnyEvent::DNS::opcode_id, %AnyEvent::DNS::opcode_str
220 Two hashes that map lowercase opcode strings to numerical id's (For
221 the encoder), or vice versa (for the decoder). Example: add a new
222 opcode string "notzone".
223 $AnyEvent::DNS::opcode_id{notzone} = 10;
225 $AnyEvent::DNS::opcode_str{10} = 'notzone';
226 %AnyEvent::DNS::rcode_id, %AnyEvent::DNS::rcode_str
228 Same as above, for for rcode values.
229 %AnyEvent::DNS::class_id, %AnyEvent::DNS::class_str
231 Same as above, but for resource record class names/values.
232 %AnyEvent::DNS::type_id, %AnyEvent::DNS::type_str
234 Same as above, but for resource record type names/values.
235 %AnyEvent::DNS::dec_rr
237 This hash maps resource record type values to code references. When
238 decoding, they are called with $_ set to the undecoded data portion
239 and $ofs being the current byte offset. of the record. You should
240 have a look at the existing implementations to understand how it
241 works in detail, but here are two examples:
242 Decode an A record. A records are simply four bytes with one byte
244 per address component, so the decoder simply unpacks them and joins
245 them with dots in between:
246 $AnyEvent::DNS::dec_rr{1} = sub { join ".", unpack "C4", $_ };
248 Decode a CNAME record, which contains a potentially compressed
250 domain name.
251 package AnyEvent::DNS; # for %dec_rr, $ofsd and &_dec_name
253 $dec_rr{5} = sub { local $ofs = $ofs - length; _dec_name };
254 THE AnyEvent::DNS RESOLVER CLASS
256 This is the class which does the actual protocol work.
257 AnyEvent::DNS::resolver
259 This function creates and returns a resolver that is ready to use
260 and should mimic the default resolver for your system as good as
261 possible. It is used by AnyEvent itself as well.
262 It only ever creates one resolver and returns this one on
264 subsequent calls - see $AnyEvent::DNS::RESOLVER, below, for
265 details.
266 Unless you have special needs, prefer this function over creating
268 your own resolver object.
269 The resolver is created with the following parameters:
271 untaint enabled
273 max_outstanding $ENV{PERL_ANYEVENT_MAX_OUTSTANDING_DNS} (default 10)
274 "os_config" will be used for OS-specific configuration, unless
276 $ENV{PERL_ANYEVENT_RESOLV_CONF} is specified, in which case that
277 file gets parsed.
278 $AnyEvent::DNS::RESOLVER
280 This variable stores the default resolver returned by
281 "AnyEvent::DNS::resolver", or "undef" when the default resolver
282 hasn't been instantiated yet.
283 One can provide a custom resolver (e.g. one with caching
285 functionality) by storing it in this variable, causing all
286 subsequent resolves done via "AnyEvent::DNS::resolver" to be done
287 via the custom one.
288 $resolver = new AnyEvent::DNS key => value...
290 Creates and returns a new resolver.
291 The following options are supported:
293 server => [...]
295 A list of server addresses (default: "v127.0.0.1" or "::1") in
296 network format (i.e. as returned by
297 "AnyEvent::Socket::parse_address" - both IPv4 and IPv6 are
298 supported).
299 timeout => [...]
301 A list of timeouts to use (also determines the number of
302 retries). To make three retries with individual time-outs of 2,
303 5 and 5 seconds, use "[2, 5, 5]", which is also the default.
304 search => [...]
306 The default search list of suffixes to append to a domain name
307 (default: none).
308 ndots => $integer
310 The number of dots (default: 1) that a name must have so that
311 the resolver tries to resolve the name without any suffixes
312 first.
313 max_outstanding => $integer
315 Most name servers do not handle many parallel requests very
316 well. This option limits the number of outstanding requests to
317 $integer (default: 10), that means if you request more than
318 this many requests, then the additional requests will be queued
319 until some other requests have been resolved.
320 reuse => $seconds
322 The number of seconds (default: 300) that a query id cannot be
323 re-used after a timeout. If there was no time-out then query
324 ids can be reused immediately.
325 untaint => $boolean
327 When true, then the resolver will automatically untaint
328 results, and might also ignore certain environment variables.
329 $resolver->parse_resolv_conf ($string)
331 Parses the given string as if it were a resolv.conf file. The
332 following directives are supported (but not necessarily
333 implemented).
334 "#"- and ";"-style comments, "nameserver", "domain", "search",
336 "sortlist", "options" ("timeout", "attempts", "ndots").
337 Everything else is silently ignored.
339 $resolver->os_config
341 Tries so load and parse /etc/resolv.conf on portable operating
342 systems. Tries various egregious hacks on windows to force the DNS
343 servers and searchlist out of the system.
344 This method must be called at most once before trying to resolve
346 anything.
347 $resolver->timeout ($timeout, ...)
349 Sets the timeout values. See the "timeout" constructor argument
350 (and note that this method expects the timeout values themselves,
351 not an array-reference).
352 $resolver->max_outstanding ($nrequests)
354 Sets the maximum number of outstanding requests to $nrequests. See
355 the "max_outstanding" constructor argument.
356 $resolver->request ($req, $cb->($res))
358 This is the main low-level workhorse for sending DNS requests.
359 This function sends a single request (a hash-ref formated as
361 specified for "dns_pack") to the configured nameservers in turn
362 until it gets a response. It handles timeouts, retries and
363 automatically falls back to virtual circuit mode (TCP) when it
364 receives a truncated reply. It does not handle anything else, such
365 as the domain searchlist or relative names - use "->resolve" for
366 that.
367 Calls the callback with the decoded response packet if a reply was
369 received, or no arguments in case none of the servers answered.
370 $resolver->resolve ($qname, $qtype, %options, $cb->(@rr))
372 Queries the DNS for the given domain name $qname of type $qtype.
373 A $qtype is either a numerical query type (e.g. 1 for A records) or
375 a lowercase name (you have to look at the source to see which
376 aliases are supported, but all types from RFC 1035, "aaaa", "srv",
377 "spf" and a few more are known to this module). A $qtype of "*" is
378 supported and means "any" record type.
379 The callback will be invoked with a list of matching result records
381 or none on any error or if the name could not be found.
382 CNAME chains (although illegal) are followed up to a length of 10.
384 The callback will be invoked with arraryefs of the form "[$name,
386 $type, $class, $ttl, @data"], where $name is the domain name, $type
387 a type string or number, $class a class name, $ttl is the remaining
388 time-to-live and @data is resource-record-dependent data, in
389 seconds. For "a" records, this will be the textual IPv4 addresses,
390 for "ns" or "cname" records this will be a domain name, for "txt"
391 records these are all the strings and so on.
392 All types mentioned in RFC 1035, "aaaa", "srv", "naptr" and "spf"
394 are decoded. All resource records not known to this module will
395 have the raw "rdata" field as fifth array element.
396 Note that this resolver is just a stub resolver: it requires a name
398 server supporting recursive queries, will not do any recursive
399 queries itself and is not secure when used against an untrusted
400 name server.
401 The following options are supported:
403 search => [$suffix...]
405 Use the given search list (which might be empty), by appending
406 each one in turn to the $qname. If this option is missing then
407 the configured "ndots" and "search" values define its value
408 (depending on "ndots", the empty suffix will be prepended or
409 appended to that "search" value). If the $qname ends in a dot,
410 then the searchlist will be ignored.
411 accept => [$type...]
413 Lists the acceptable result types: only result types in this
414 set will be accepted and returned. The default includes the
415 $qtype and nothing else. If this list includes "cname", then
416 CNAME-chains will not be followed (because you asked for the
417 CNAME record).
418 class => "class"
420 Specify the query class ("in" for internet, "ch" for chaosnet
421 and "hs" for hesiod are the only ones making sense). The
422 default is "in", of course.
423 Examples:
425 # full example, you can paste this into perl:
427 use Data::Dumper;
428 use AnyEvent::DNS;
429 AnyEvent::DNS::resolver->resolve (
430 "google.com", "*", my $cv = AnyEvent->condvar);
431 warn Dumper [$cv->recv];
432 # shortened result:
434 # [
435 # [ 'google.com', 'soa', 'in', 3600, 'ns1.google.com', 'dns-admin.google.com',
436 # 2008052701, 7200, 1800, 1209600, 300 ],
437 # [
438 # 'google.com', 'txt', 'in', 3600,
439 # 'v=spf1 include:_netblocks.google.com ~all'
440 # ],
441 # [ 'google.com', 'a', 'in', 3600, '64.233.187.99' ],
442 # [ 'google.com', 'mx', 'in', 3600, 10, 'smtp2.google.com' ],
443 # [ 'google.com', 'ns', 'in', 3600, 'ns2.google.com' ],
444 # ]
445 # resolve a records:
447 $res->resolve ("ruth.plan9.de", "a", sub { warn Dumper [@_] });
448 # result:
450 # [
451 # [ 'ruth.schmorp.de', 'a', 'in', 86400, '129.13.162.95' ]
452 # ]
453 # resolve any records, but return only a and aaaa records:
455 $res->resolve ("test1.laendle", "*",
456 accept => ["a", "aaaa"],
457 sub {
458 warn Dumper [@_];
459 }
460 );
461 # result:
463 # [
464 # [ 'test1.laendle', 'a', 'in', 86400, '10.0.0.255' ],
465 # [ 'test1.laendle', 'aaaa', 'in', 60, '3ffe:1900:4545:0002:0240:0000:0000:f7e1' ]
466 # ]
467 $resolver->wait_for_slot ($cb->($resolver))
469 Wait until a free request slot is available and call the callback
470 with the resolver object.
471 A request slot is used each time a request is actually sent to the
473 nameservers: There are never more than "max_outstanding" of them.
474 Although you can submit more requests (they will simply be queued
476 until a request slot becomes available), sometimes, usually for
477 rate-limiting purposes, it is useful to instead wait for a slot
478 before generating the request (or simply to know when the request
479 load is low enough so one can submit requests again).
480 This is what this method does: The callback will be called when
482 submitting a DNS request will not result in that request being
483 queued. The callback may or may not generate any requests in
484 response.
485 Note that the callback will only be invoked when the request queue
487 is empty, so this does not play well if somebody else keeps the
488 request queue full at all times.
489
491 Marc Lehmann <schmorp@schmorp.de>
492 http://anyevent.schmorp.de
493perl v5.34.0 2021-07-22 AnyEvent::DNS(3)