1AnyEvent::DNS(3)      User Contributed Perl Documentation     AnyEvent::DNS(3)
2
3
4

NAME

6       AnyEvent::DNS - fully asynchronous DNS resolution
7

SYNOPSIS

9          use AnyEvent::DNS;
10
11          my $cv = AnyEvent->condvar;
12          AnyEvent::DNS::a "www.google.de", $cv;
13          # ... later
14          my @addrs = $cv->recv;
15

DESCRIPTION

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
20       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
24   CONVENIENCE FUNCTIONS
25       AnyEvent::DNS::a $domain, $cb->(@addrs)
26           Tries to resolve the given domain to IPv4 address(es).
27
28       AnyEvent::DNS::aaaa $domain, $cb->(@addrs)
29           Tries to resolve the given domain to IPv6 address(es).
30
31       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
35       AnyEvent::DNS::ns $domain, $cb->(@hostnames)
36           Tries to resolve the given domain name into a list of name servers.
37
38       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
43              resolver->resolve ($domain => "txt", sub {
44                 for my $record (@_) {
45                    my (undef, undef, undef, @txt) = @$record;
46                    # strings now in @txt
47                 }
48              });
49
50       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
54           Each $srv_rr is an array reference with the following contents:
55           "[$priority, $weight, $transport, $target]".
56
57           They will be sorted with lowest priority first, then randomly
58           distributed by weight as per RFC 2782.
59
60           Example:
61
62              AnyEvent::DNS::srv "sip", "udp", "schmorp.de", sub { ...
63              # @_ = ( [10, 10, 5060, "sip1.schmorp.de" ] )
64
65       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
70       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
75       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
80       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
85           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
90           Example:
91
92              AnyEvent::DNS::reverse_verify "2001:500:2f::f", sub { print shift };
93              # => f.root-servers.net
94
95   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
102       $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
107           Resource records are not yet encodable.
108
109           Examples:
110
111              # very simple request, using lots of default values:
112              { rd => 1, qd => [ [ "host.domain", "a"] ] }
113
114              # more complex example, showing how flags etc. are named:
115
116              {
117                 id => 10000,
118                 op => "query",
119                 rc => "nxdomain",
120
121                 # flags
122                 qr => 1,
123                 aa => 0,
124                 tc => 0,
125                 rd => 0,
126                 ra => 0,
127                 ad => 0,
128                 cd => 0,
129
130                 qd => [@rr], # query section
131                 an => [@rr], # answer section
132                 ns => [@rr], # authority section
133                 ar => [@rr], # additional records section
134              }
135
136       $dns = AnyEvent::DNS::dns_unpack $pkt
137           Unpacks a DNS packet into a perl data structure.
138
139           Examples:
140
141              # 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
170              # a successful reply
171
172              {
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
200       Extending DNS Encoder and Decoder
201
202       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
206       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
210       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
214          my $decoded = do {
215             local $AnyEvent::DNS::opcode_str{7} = "yxrrset";
216             AnyEvent::DNS::dns_unpack $mypkt
217          };
218
219       %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
224              $AnyEvent::DNS::opcode_id{notzone} = 10;
225              $AnyEvent::DNS::opcode_str{10} = 'notzone';
226
227       %AnyEvent::DNS::rcode_id, %AnyEvent::DNS::rcode_str
228           Same as above, for for rcode values.
229
230       %AnyEvent::DNS::class_id, %AnyEvent::DNS::class_str
231           Same as above, but for resource record class names/values.
232
233       %AnyEvent::DNS::type_id, %AnyEvent::DNS::type_str
234           Same as above, but for resource record type names/values.
235
236       %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
243           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
247              $AnyEvent::DNS::dec_rr{1} = sub { join ".", unpack "C4", $_ };
248
249           Decode a CNAME record, which contains a potentially compressed
250           domain name.
251
252              package AnyEvent::DNS; # for %dec_rr, $ofsd and &_dec_name
253              $dec_rr{5} = sub { local $ofs = $ofs - length; _dec_name };
254
255   THE AnyEvent::DNS RESOLVER CLASS
256       This is the class which does the actual protocol work.
257
258       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
263           It only ever creates one resolver and returns this one on
264           subsequent calls - see $AnyEvent::DNS::RESOLVER, below, for
265           details.
266
267           Unless you have special needs, prefer this function over creating
268           your own resolver object.
269
270           The resolver is created with the following parameters:
271
272              untaint          enabled
273              max_outstanding  $ENV{PERL_ANYEVENT_MAX_OUTSTANDING_DNS} (default 10)
274
275           "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
279       $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
284           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
289       $resolver = new AnyEvent::DNS key => value...
290           Creates and returns a new resolver.
291
292           The following options are supported:
293
294           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
300           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
305           search => [...]
306               The default search list of suffixes to append to a domain name
307               (default: none).
308
309           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
314           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
321           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
326           untaint => $boolean
327               When true, then the resolver will automatically untaint
328               results, and might also ignore certain environment variables.
329
330       $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
335           "#"- and ";"-style comments, "nameserver", "domain", "search",
336           "sortlist", "options" ("timeout", "attempts", "ndots").
337
338           Everything else is silently ignored.
339
340       $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
345           This method must be called at most once before trying to resolve
346           anything.
347
348       $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
353       $resolver->max_outstanding ($nrequests)
354           Sets the maximum number of outstanding requests to $nrequests. See
355           the "max_outstanding" constructor argument.
356
357       $resolver->request ($req, $cb->($res))
358           This is the main low-level workhorse for sending DNS requests.
359
360           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
368           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
371       $resolver->resolve ($qname, $qtype, %options, $cb->(@rr))
372           Queries the DNS for the given domain name $qname of type $qtype.
373
374           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
380           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
383           CNAME chains (although illegal) are followed up to a length of 10.
384
385           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
393           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
397           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
402           The following options are supported:
403
404           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
412           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
419           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
424           Examples:
425
426              # 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
433              # 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
446              # resolve a records:
447              $res->resolve ("ruth.plan9.de", "a", sub { warn Dumper [@_] });
448
449              # result:
450              # [
451              #   [ 'ruth.schmorp.de', 'a', 'in', 86400, '129.13.162.95' ]
452              # ]
453
454              # 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
462              # 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
468       $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
472           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
475           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
481           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
486           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

AUTHOR

491          Marc Lehmann <schmorp@schmorp.de>
492          http://anyevent.schmorp.de
493
494
495
496perl v5.32.0                      2020-07-28                  AnyEvent::DNS(3)
Impressum