| … | |
… | |
| 14 | =head1 DESCRIPTION |
14 | =head1 DESCRIPTION |
| 15 | |
15 | |
| 16 | This module offers both a number of DNS convenience functions as well |
16 | This module offers both a number of DNS convenience functions as well |
| 17 | as a fully asynchronous and high-performance pure-perl stub resolver. |
17 | as a fully asynchronous and high-performance pure-perl stub resolver. |
| 18 | |
18 | |
| 19 | The stub resolver supports DNS over UDP, optional EDNS0 support for up to |
19 | The stub resolver supports DNS over IPv4 and IPv6, UDP and TCP, optional |
| 20 | 4kiB datagrams and automatically falls back to virtual circuit mode for |
20 | EDNS0 support for up to 4kiB datagrams and automatically falls back to |
| 21 | large responses. |
21 | virtual circuit mode for large responses. |
| 22 | |
22 | |
| 23 | =head2 CONVENIENCE FUNCTIONS |
23 | =head2 CONVENIENCE FUNCTIONS |
| 24 | |
24 | |
| 25 | =over 4 |
25 | =over 4 |
| 26 | |
26 | |
| … | |
… | |
| 187 | |
187 | |
| 188 | =item $AnyEvent::DNS::EDNS0 |
188 | =item $AnyEvent::DNS::EDNS0 |
| 189 | |
189 | |
| 190 | This variable decides whether dns_pack automatically enables EDNS0 |
190 | This variable decides whether dns_pack automatically enables EDNS0 |
| 191 | support. By default, this is disabled (C<0>), unless overridden by |
191 | support. By default, this is disabled (C<0>), unless overridden by |
| 192 | C<$ENV{PERL_ANYEVENT_EDNS0>), but when set to C<1>, AnyEvent::DNS will use |
192 | C<$ENV{PERL_ANYEVENT_EDNS0}>, but when set to C<1>, AnyEvent::DNS will use |
| 193 | EDNS0 in all requests. |
193 | EDNS0 in all requests. |
| 194 | |
194 | |
| 195 | =cut |
195 | =cut |
| 196 | |
196 | |
| 197 | our $EDNS0 = $ENV{PERL_ANYEVENT_EDNS0} * 1; # set to 1 to enable (partial) edns0 |
197 | our $EDNS0 = $ENV{PERL_ANYEVENT_EDNS0} * 1; # set to 1 to enable (partial) edns0 |
| … | |
… | |
| 270 | "*" => 255, |
270 | "*" => 255, |
| 271 | ); |
271 | ); |
| 272 | |
272 | |
| 273 | our %class_str = reverse %class_id; |
273 | our %class_str = reverse %class_id; |
| 274 | |
274 | |
| 275 | # names MUST have a trailing dot |
|
|
| 276 | sub _enc_name($) { |
275 | sub _enc_name($) { |
| 277 | pack "(C/a*)*", (split /\./, shift), "" |
276 | pack "(C/a*)*", (split /\./, shift), "" |
| 278 | } |
277 | } |
| 279 | |
278 | |
| 280 | sub _enc_qd() { |
279 | sub _enc_qd() { |
| … | |
… | |
| 340 | + $rcode_id{$req->{rc}} * 0x0001, |
339 | + $rcode_id{$req->{rc}} * 0x0001, |
| 341 | |
340 | |
| 342 | scalar @{ $req->{qd} || [] }, |
341 | scalar @{ $req->{qd} || [] }, |
| 343 | scalar @{ $req->{an} || [] }, |
342 | scalar @{ $req->{an} || [] }, |
| 344 | scalar @{ $req->{ns} || [] }, |
343 | scalar @{ $req->{ns} || [] }, |
| 345 | $EDNS0 + scalar @{ $req->{ar} || [] }, # include EDNS0 option here |
344 | $EDNS0 + scalar @{ $req->{ar} || [] }, # EDNS0 option included here |
| 346 | |
345 | |
| 347 | (join "", map _enc_qd, @{ $req->{qd} || [] }), |
346 | (join "", map _enc_qd, @{ $req->{qd} || [] }), |
| 348 | (join "", map _enc_rr, @{ $req->{an} || [] }), |
347 | (join "", map _enc_rr, @{ $req->{an} || [] }), |
| 349 | (join "", map _enc_rr, @{ $req->{ns} || [] }), |
348 | (join "", map _enc_rr, @{ $req->{ns} || [] }), |
| 350 | (join "", map _enc_rr, @{ $req->{ar} || [] }), |
349 | (join "", map _enc_rr, @{ $req->{ar} || [] }), |
| 351 | |
350 | |
| 352 | ($EDNS0 ? pack "C nnNn", 0, 41, MAX_PKT, 0, 0 : "") # EDNS0, 4kiB udp payload size |
351 | ($EDNS0 ? pack "C nnNn", 0, 41, MAX_PKT, 0, 0 : "") # EDNS0 option |
| 353 | } |
352 | } |
| 354 | |
353 | |
| 355 | our $ofs; |
354 | our $ofs; |
| 356 | our $pkt; |
355 | our $pkt; |
| 357 | |
356 | |
| … | |
… | |
| 560 | |
559 | |
| 561 | =over 4 |
560 | =over 4 |
| 562 | |
561 | |
| 563 | =item server => [...] |
562 | =item server => [...] |
| 564 | |
563 | |
| 565 | A list of server addresses (default: C<v127.0.0.1>) in network format (4 |
564 | A list of server addresses (default: C<v127.0.0.1>) in network format |
| 566 | octets for IPv4, 16 octets for IPv6 - not yet supported). |
565 | (i.e. as returned by C<AnyEvent::Socket::parse_address> - both IPv4 and |
|
|
566 | IPv6 are supported). |
| 567 | |
567 | |
| 568 | =item timeout => [...] |
568 | =item timeout => [...] |
| 569 | |
569 | |
| 570 | A list of timeouts to use (also determines the number of retries). To make |
570 | A list of timeouts to use (also determines the number of retries). To make |
| 571 | three retries with individual time-outs of 2, 5 and 5 seconds, use C<[2, |
571 | three retries with individual time-outs of 2, 5 and 5 seconds, use C<[2, |
| … | |
… | |
| 580 | The number of dots (default: C<1>) that a name must have so that the resolver |
580 | The number of dots (default: C<1>) that a name must have so that the resolver |
| 581 | tries to resolve the name without any suffixes first. |
581 | tries to resolve the name without any suffixes first. |
| 582 | |
582 | |
| 583 | =item max_outstanding => $integer |
583 | =item max_outstanding => $integer |
| 584 | |
584 | |
| 585 | Most name servers do not handle many parallel requests very well. This option |
585 | Most name servers do not handle many parallel requests very well. This |
| 586 | limits the number of outstanding requests to C<$n> (default: C<10>), that means |
586 | option limits the number of outstanding requests to C<$integer> |
| 587 | if you request more than this many requests, then the additional requests will be queued |
587 | (default: C<10>), that means if you request more than this many requests, |
| 588 | until some other requests have been resolved. |
588 | then the additional requests will be queued until some other requests have |
|
|
589 | been resolved. |
| 589 | |
590 | |
| 590 | =item reuse => $seconds |
591 | =item reuse => $seconds |
| 591 | |
592 | |
| 592 | The number of seconds (default: C<300>) that a query id cannot be re-used |
593 | The number of seconds (default: C<300>) that a query id cannot be re-used |
| 593 | after a timeout. If there as no time-out then query id's can be reused |
594 | after a timeout. If there as no time-out then query id's can be reused |
| … | |
… | |
| 957 | $self->_scheduler; |
958 | $self->_scheduler; |
| 958 | } |
959 | } |
| 959 | |
960 | |
| 960 | =item $resolver->resolve ($qname, $qtype, %options, $cb->($rcode, @rr)) |
961 | =item $resolver->resolve ($qname, $qtype, %options, $cb->($rcode, @rr)) |
| 961 | |
962 | |
| 962 | Queries the DNS for the given domain name C<$qname> of type C<$qtype> (a |
963 | Queries the DNS for the given domain name C<$qname> of type C<$qtype>. |
| 963 | qtype of "*" is supported and means "any"). |
964 | |
|
|
965 | A C<$qtype> is either a numerical query type (e.g. C<1> for A recods) or |
|
|
966 | a lowercase name (you have to look at the source to see which aliases are |
|
|
967 | supported, but all types from RFC 1034, C<aaaa>, C<srv>, C<spf> and a few |
|
|
968 | more are known to this module). A qtype of "*" is supported and means |
|
|
969 | "any" record type. |
| 964 | |
970 | |
| 965 | The callback will be invoked with a list of matching result records or |
971 | The callback will be invoked with a list of matching result records or |
| 966 | none on any error or if the name could not be found. |
972 | none on any error or if the name could not be found. |
| 967 | |
973 | |
| 968 | CNAME chains (although illegal) are followed up to a length of 8. |
974 | CNAME chains (although illegal) are followed up to a length of 8. |
|
|
975 | |
|
|
976 | The callback will be invoked with an result code in string form (noerror, |
|
|
977 | formerr, servfail, nxdomain, notimp, refused and so on), or numerical |
|
|
978 | form if the result code is not supported. The remaining arguments are |
|
|
979 | arraryefs of the form C<[$name, $type, $class, @data>], where C<$name> is |
|
|
980 | the domain name, C<$type> a type string or number, C<$class> a class name |
|
|
981 | and @data is resource-record-dependent data. For C<a> records, this will |
|
|
982 | be the textual IPv4 addresses, for C<ns> or C<cname> records this will be |
|
|
983 | a domain name, for C<txt> records these are all the strings and so on. |
|
|
984 | |
|
|
985 | All types mentioned in RFC 1034, C<aaaa>, C<srv> and C<spf> are |
|
|
986 | decoded. All resource records not known to this module will just return |
|
|
987 | the raw C<rdata> field as fourth entry. |
| 969 | |
988 | |
| 970 | Note that this resolver is just a stub resolver: it requires a name server |
989 | Note that this resolver is just a stub resolver: it requires a name server |
| 971 | supporting recursive queries, will not do any recursive queries itself and |
990 | supporting recursive queries, will not do any recursive queries itself and |
| 972 | is not secure when used against an untrusted name server. |
991 | is not secure when used against an untrusted name server. |
| 973 | |
992 | |
| … | |
… | |
| 984 | |
1003 | |
| 985 | =item accept => [$type...] |
1004 | =item accept => [$type...] |
| 986 | |
1005 | |
| 987 | Lists the acceptable result types: only result types in this set will be |
1006 | Lists the acceptable result types: only result types in this set will be |
| 988 | accepted and returned. The default includes the C<$qtype> and nothing |
1007 | accepted and returned. The default includes the C<$qtype> and nothing |
| 989 | else. |
1008 | else. If this list includes C<cname>, then CNAME-chains will not be |
|
|
1009 | followed (because you asked for the CNAME record). |
| 990 | |
1010 | |
| 991 | =item class => "class" |
1011 | =item class => "class" |
| 992 | |
1012 | |
| 993 | Specify the query class ("in" for internet, "ch" for chaosnet and "hs" for |
1013 | Specify the query class ("in" for internet, "ch" for chaosnet and "hs" for |
| 994 | hesiod are the only ones making sense). The default is "in", of course. |
1014 | hesiod are the only ones making sense). The default is "in", of course. |
| 995 | |
1015 | |
| 996 | =back |
1016 | =back |
| 997 | |
1017 | |
| 998 | Examples: |
1018 | Examples: |
| 999 | |
1019 | |
| 1000 | $res->resolve ("ruth.plan9.de", "a", sub { |
1020 | # full example, you can paste this into perl: |
| 1001 | warn Dumper [@_]; |
1021 | use Data::Dumper; |
| 1002 | }); |
1022 | use AnyEvent::DNS; |
|
|
1023 | AnyEvent::DNS::resolver->resolve ( |
|
|
1024 | "google.com", "*", my $cv = AnyEvent->condvar); |
|
|
1025 | warn Dumper [$cv->recv]; |
| 1003 | |
1026 | |
|
|
1027 | # shortened result: |
| 1004 | [ |
1028 | # [ |
|
|
1029 | # [ 'google.com', 'soa', 'in', 'ns1.google.com', 'dns-admin.google.com', |
|
|
1030 | # 2008052701, 7200, 1800, 1209600, 300 ], |
| 1005 | [ |
1031 | # [ |
| 1006 | 'ruth.schmorp.de', |
1032 | # 'google.com', 'txt', 'in', |
| 1007 | 'a', |
1033 | # 'v=spf1 include:_netblocks.google.com ~all' |
| 1008 | 'in', |
1034 | # ], |
| 1009 | '129.13.162.95' |
1035 | # [ 'google.com', 'a', 'in', '64.233.187.99' ], |
|
|
1036 | # [ 'google.com', 'mx', 'in', 10, 'smtp2.google.com' ], |
|
|
1037 | # [ 'google.com', 'ns', 'in', 'ns2.google.com' ], |
| 1010 | ] |
1038 | # ] |
|
|
1039 | |
|
|
1040 | # resolve a records: |
|
|
1041 | $res->resolve ("ruth.plan9.de", "a", sub { warn Dumper [@_] }); |
|
|
1042 | |
|
|
1043 | # result: |
|
|
1044 | # [ |
|
|
1045 | # [ 'ruth.schmorp.de', 'a', 'in', '129.13.162.95' ] |
| 1011 | ] |
1046 | # ] |
| 1012 | |
1047 | |
|
|
1048 | # resolve any records, but return only a and aaaa records: |
| 1013 | $res->resolve ("test1.laendle", "*", |
1049 | $res->resolve ("test1.laendle", "*", |
| 1014 | accept => ["a", "aaaa"], |
1050 | accept => ["a", "aaaa"], |
| 1015 | sub { |
1051 | sub { |
| 1016 | warn Dumper [@_]; |
1052 | warn Dumper [@_]; |
| 1017 | } |
1053 | } |
| 1018 | ); |
1054 | ); |
| 1019 | |
1055 | |
| 1020 | [ |
1056 | # result: |
| 1021 | [ |
1057 | # [ |
| 1022 | 'test1.laendle', |
1058 | # [ 'test1.laendle', 'a', 'in', '10.0.0.255' ], |
| 1023 | 'a', |
1059 | # [ 'test1.laendle', 'aaaa', 'in', '3ffe:1900:4545:0002:0240:0000:0000:f7e1' ] |
| 1024 | 'in', |
|
|
| 1025 | '10.0.0.255' |
|
|
| 1026 | ], |
|
|
| 1027 | [ |
|
|
| 1028 | 'test1.laendle', |
|
|
| 1029 | 'aaaa', |
|
|
| 1030 | 'in', |
|
|
| 1031 | '3ffe:1900:4545:0002:0240:0000:0000:f7e1' |
|
|
| 1032 | ] |
1060 | # ] |
| 1033 | ] |
|
|
| 1034 | |
1061 | |
| 1035 | =cut |
1062 | =cut |
| 1036 | |
1063 | |
| 1037 | sub resolve($%) { |
1064 | sub resolve($%) { |
| 1038 | my $cb = pop; |
1065 | my $cb = pop; |
