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 AnyEvent::DNS::srv $service, $proto, $domain, $cb->(@srv_rr)
42 Tries to resolve the given service, protocol and domain name into a
43 list of service records.
44 Each $srv_rr is an array reference with the following contents:
46 "[$priority, $weight, $transport, $target]".
47 They will be sorted with lowest priority first, then randomly
49 distributed by weight as per RFC 2782.
50 Example:
52 AnyEvent::DNS::srv "sip", "udp", "schmorp.de", sub { ...
54 # @_ = ( [10, 10, 5060, "sip1.schmorp.de" ] )
55 AnyEvent::DNS::ptr $domain, $cb->(@hostnames)
57 Tries to make a PTR lookup on the given domain. See
58 "reverse_lookup" and "reverse_verify" if you want to resolve an IP
59 address to a hostname instead.
60 AnyEvent::DNS::any $domain, $cb->(@rrs)
62 Tries to resolve the given domain and passes all resource records
63 found to the callback.
64 AnyEvent::DNS::reverse_lookup $ipv4_or_6, $cb->(@hostnames)
66 Tries to reverse-resolve the given IPv4 or IPv6 address (in textual
67 form) into it's hostname(s). Handles V4MAPPED and V4COMPAT IPv6
68 addresses transparently.
69 AnyEvent::DNS::reverse_verify $ipv4_or_6, $cb->(@hostnames)
71 The same as "reverse_lookup", but does forward-lookups to verify
72 that the resolved hostnames indeed point to the address, which
73 makes spoofing harder.
74 If you want to resolve an address into a hostname, this is the
76 preferred method: The DNS records could still change, but at least
77 this function verified that the hostname, at one point in the past,
78 pointed at the IP address you originally resolved.
79 Example:
81 AnyEvent::DNS::ptr "2001:500:2f::f", sub { print shift };
83 # => f.root-servers.net
84 LOW-LEVEL DNS EN-/DECODING FUNCTIONS
86 $AnyEvent::DNS::EDNS0
87 This variable decides whether dns_pack automatically enables EDNS0
88 support. By default, this is disabled (0), unless overridden by
89 $ENV{PERL_ANYEVENT_EDNS0}, but when set to 1, AnyEvent::DNS will
90 use EDNS0 in all requests.
91 $pkt = AnyEvent::DNS::dns_pack $dns
93 Packs a perl data structure into a DNS packet. Reading RFC 1035 is
94 strongly recommended, then everything will be totally clear. Or
95 maybe not.
96 Resource records are not yet encodable.
98 Examples:
100 # very simple request, using lots of default values:
102 { rd => 1, qd => [ [ "host.domain", "a"] ] }
103 # more complex example, showing how flags etc. are named:
105 {
107 id => 10000,
108 op => "query",
109 rc => "nxdomain",
110 # flags
112 qr => 1,
113 aa => 0,
114 tc => 0,
115 rd => 0,
116 ra => 0,
117 ad => 0,
118 cd => 0,
119 qd => [@rr], # query section
121 an => [@rr], # answer section
122 ns => [@rr], # authority section
123 ar => [@rr], # additional records section
124 }
125 $dns = AnyEvent::DNS::dns_unpack $pkt
127 Unpacks a DNS packet into a perl data structure.
128 Examples:
130 # an unsuccessful reply
132 {
133 'qd' => [
134 [ 'ruth.plan9.de.mach.uni-karlsruhe.de', '*', 'in' ]
135 ],
136 'rc' => 'nxdomain',
137 'ar' => [],
138 'ns' => [
139 [
140 'uni-karlsruhe.de',
141 'soa',
142 'in',
143 'netserv.rz.uni-karlsruhe.de',
144 'hostmaster.rz.uni-karlsruhe.de',
145 2008052201, 10800, 1800, 2592000, 86400
146 ]
147 ],
148 'tc' => '',
149 'ra' => 1,
150 'qr' => 1,
151 'id' => 45915,
152 'aa' => '',
153 'an' => [],
154 'rd' => 1,
155 'op' => 'query'
156 }
157 # a successful reply
159 {
161 'qd' => [ [ 'www.google.de', 'a', 'in' ] ],
162 'rc' => 0,
163 'ar' => [
164 [ 'a.l.google.com', 'a', 'in', '209.85.139.9' ],
165 [ 'b.l.google.com', 'a', 'in', '64.233.179.9' ],
166 [ 'c.l.google.com', 'a', 'in', '64.233.161.9' ],
167 ],
168 'ns' => [
169 [ 'l.google.com', 'ns', 'in', 'a.l.google.com' ],
170 [ 'l.google.com', 'ns', 'in', 'b.l.google.com' ],
171 ],
172 'tc' => '',
173 'ra' => 1,
174 'qr' => 1,
175 'id' => 64265,
176 'aa' => '',
177 'an' => [
178 [ 'www.google.de', 'cname', 'in', 'www.google.com' ],
179 [ 'www.google.com', 'cname', 'in', 'www.l.google.com' ],
180 [ 'www.l.google.com', 'a', 'in', '66.249.93.104' ],
181 [ 'www.l.google.com', 'a', 'in', '66.249.93.147' ],
182 ],
183 'rd' => 1,
184 'op' => 0
185 }
186 THE AnyEvent::DNS RESOLVER CLASS
188 This is the class which does the actual protocol work.
189 AnyEvent::DNS::resolver
191 This function creates and returns a resolver that is ready to use
192 and should mimic the default resolver for your system as good as
193 possible.
194 It only ever creates one resolver and returns this one on
196 subsequent calls.
197 Unless you have special needs, prefer this function over creating
199 your own resolver object.
200 The resolver is created with the following parameters:
202 untaint enabled
204 max_outstanding $ENV{PERL_ANYEVENT_MAX_OUTSTANDING_DNS}
205 "os_config" will be used for OS-specific configuration, unless
207 $ENV{PERL_ANYEVENT_RESOLV_CONF} is specified, in which case that
208 file gets parsed.
209 $resolver = new AnyEvent::DNS key => value...
211 Creates and returns a new resolver.
212 The following options are supported:
214 server => [...]
216 A list of server addresses (default: "v127.0.0.1") in network
217 format (i.e. as returned by "AnyEvent::Socket::parse_address" -
218 both IPv4 and IPv6 are supported).
219 timeout => [...]
221 A list of timeouts to use (also determines the number of
222 retries). To make three retries with individual time-outs of 2,
223 5 and 5 seconds, use "[2, 5, 5]", which is also the default.
224 search => [...]
226 The default search list of suffixes to append to a domain name
227 (default: none).
228 ndots => $integer
230 The number of dots (default: 1) that a name must have so that
231 the resolver tries to resolve the name without any suffixes
232 first.
233 max_outstanding => $integer
235 Most name servers do not handle many parallel requests very
236 well. This option limits the number of outstanding requests to
237 $integer (default: 10), that means if you request more than
238 this many requests, then the additional requests will be queued
239 until some other requests have been resolved.
240 reuse => $seconds
242 The number of seconds (default: 300) that a query id cannot be
243 re-used after a timeout. If there was no time-out then query
244 ids can be reused immediately.
245 untaint => $boolean
247 When true, then the resolver will automatically untaint
248 results, and might also ignore certain environment variables.
249 $resolver->parse_resolv_conf ($string)
251 Parses the given string as if it were a resolv.conf file. The
252 following directives are supported (but not necessarily
253 implemented).
254 "#"-style comments, "nameserver", "domain", "search", "sortlist",
256 "options" ("timeout", "attempts", "ndots").
257 Everything else is silently ignored.
259 $resolver->os_config
261 Tries so load and parse /etc/resolv.conf on portable operating
262 systems. Tries various egregious hacks on windows to force the DNS
263 servers and searchlist out of the system.
264 $resolver->timeout ($timeout, ...)
266 Sets the timeout values. See the "timeout" constructor argument
267 (and note that this method uses the values itself, not an array-
268 reference).
269 $resolver->max_outstanding ($nrequests)
271 Sets the maximum number of outstanding requests to $nrequests. See
272 the "max_outstanding" constructor argument.
273 $resolver->request ($req, $cb->($res))
275 This is the main low-level workhorse for sending DNS requests.
276 This function sends a single request (a hash-ref formated as
278 specified for "dns_pack") to the configured nameservers in turn
279 until it gets a response. It handles timeouts, retries and
280 automatically falls back to virtual circuit mode (TCP) when it
281 receives a truncated reply.
282 Calls the callback with the decoded response packet if a reply was
284 received, or no arguments in case none of the servers answered.
285 $resolver->resolve ($qname, $qtype, %options, $cb->(@rr))
287 Queries the DNS for the given domain name $qname of type $qtype.
288 A $qtype is either a numerical query type (e.g. 1 for A records) or
290 a lowercase name (you have to look at the source to see which
291 aliases are supported, but all types from RFC 1035, "aaaa", "srv",
292 "spf" and a few more are known to this module). A $qtype of "*" is
293 supported and means "any" record type.
294 The callback will be invoked with a list of matching result records
296 or none on any error or if the name could not be found.
297 CNAME chains (although illegal) are followed up to a length of 10.
299 The callback will be invoked with arraryefs of the form "[$name,
301 $type, $class, @data"], where $name is the domain name, $type a
302 type string or number, $class a class name and @data is resource-
303 record-dependent data. For "a" records, this will be the textual
304 IPv4 addresses, for "ns" or "cname" records this will be a domain
305 name, for "txt" records these are all the strings and so on.
306 All types mentioned in RFC 1035, "aaaa", "srv", "naptr" and "spf"
308 are decoded. All resource records not known to this module will
309 have the raw "rdata" field as fourth entry.
310 Note that this resolver is just a stub resolver: it requires a name
312 server supporting recursive queries, will not do any recursive
313 queries itself and is not secure when used against an untrusted
314 name server.
315 The following options are supported:
317 search => [$suffix...]
319 Use the given search list (which might be empty), by appending
320 each one in turn to the $qname. If this option is missing then
321 the configured "ndots" and "search" values define its value
322 (depending on "ndots", the empty suffix will be prepended or
323 appended to that "search" value). If the $qname ends in a dot,
324 then the searchlist will be ignored.
325 accept => [$type...]
327 Lists the acceptable result types: only result types in this
328 set will be accepted and returned. The default includes the
329 $qtype and nothing else. If this list includes "cname", then
330 CNAME-chains will not be followed (because you asked for the
331 CNAME record).
332 class => "class"
334 Specify the query class ("in" for internet, "ch" for chaosnet
335 and "hs" for hesiod are the only ones making sense). The
336 default is "in", of course.
337 Examples:
339 # full example, you can paste this into perl:
341 use Data::Dumper;
342 use AnyEvent::DNS;
343 AnyEvent::DNS::resolver->resolve (
344 "google.com", "*", my $cv = AnyEvent->condvar);
345 warn Dumper [$cv->recv];
346 # shortened result:
348 # [
349 # [ 'google.com', 'soa', 'in', 'ns1.google.com', 'dns-admin.google.com',
350 # 2008052701, 7200, 1800, 1209600, 300 ],
351 # [
352 # 'google.com', 'txt', 'in',
353 # 'v=spf1 include:_netblocks.google.com ~all'
354 # ],
355 # [ 'google.com', 'a', 'in', '64.233.187.99' ],
356 # [ 'google.com', 'mx', 'in', 10, 'smtp2.google.com' ],
357 # [ 'google.com', 'ns', 'in', 'ns2.google.com' ],
358 # ]
359 # resolve a records:
361 $res->resolve ("ruth.plan9.de", "a", sub { warn Dumper [@_] });
362 # result:
364 # [
365 # [ 'ruth.schmorp.de', 'a', 'in', '129.13.162.95' ]
366 # ]
367 # resolve any records, but return only a and aaaa records:
369 $res->resolve ("test1.laendle", "*",
370 accept => ["a", "aaaa"],
371 sub {
372 warn Dumper [@_];
373 }
374 );
375 # result:
377 # [
378 # [ 'test1.laendle', 'a', 'in', '10.0.0.255' ],
379 # [ 'test1.laendle', 'aaaa', 'in', '3ffe:1900:4545:0002:0240:0000:0000:f7e1' ]
380 # ]
381 $resolver->wait_for_slot ($cb->($resolver))
383 Wait until a free request slot is available and call the callback
384 with the resolver object.
385 A request slot is used each time a request is actually sent to the
387 nameservers: There are never more than "max_outstanding" of them.
388 Although you can submit more requests (they will simply be queued
390 until a request slot becomes available), sometimes, usually for
391 rate-limiting purposes, it is useful to instead wait for a slot
392 before generating the request (or simply to know when the request
393 load is low enough so one can submit requests again).
394 This is what this method does: The callback will be called when
396 submitting a DNS request will not result in that request being
397 queued. The callback may or may not generate any requests in
398 response.
399 Note that the callback will only be invoked when the request queue
401 is empty, so this does not play well if somebody else keeps the
402 request queue full at all times.
403
405 Marc Lehmann <schmorp@schmorp.de>
406 http://home.schmorp.de/
407perl v5.12.1 2009-12-08 AnyEvent::DNS(3)