1package Net::DNS::Resolver; 2# 3# $Id: Resolver.pm 614 2006-09-25 08:12:29Z olaf $ 4# 5 6use strict; 7use vars qw($VERSION @ISA); 8 9$VERSION = (qw$LastChangedRevision: 614 $)[1]; 10 11BEGIN { 12 if ($^O eq 'MSWin32') { 13 require Net::DNS::Resolver::Win32; 14 @ISA = qw(Net::DNS::Resolver::Win32); 15 } elsif ($^O eq 'cygwin') { 16 require Net::DNS::Resolver::Cygwin; 17 @ISA = qw(Net::DNS::Resolver::Cygwin); 18 } else { 19 require Net::DNS::Resolver::UNIX; 20 @ISA = qw(Net::DNS::Resolver::UNIX); 21 } 22} 23 24__PACKAGE__->init(); 25 261; 27 28__END__ 29 30=head1 NAME 31 32Net::DNS::Resolver - DNS resolver class 33 34=head1 SYNOPSIS 35 36 use Net::DNS; 37 38 my $res = Net::DNS::Resolver->new; 39 40 # Perform a lookup, using the searchlist if appropriate. 41 my $answer = $res->search('example.com'); 42 43 # Perform a lookup, without the searchlist 44 my $answer = $res->query('example.com', 'MX'); 45 46 # Perform a lookup, without pre or post-processing 47 my $answer = $res->send('example.com', 'MX', 'CH'); 48 49 # Send a prebuilt packet 50 my $packet = Net::DNS::Packet->new(...); 51 my $answer = $res->send($packet); 52 53=head1 DESCRIPTION 54 55Instances of the C<Net::DNS::Resolver> class represent resolver objects. 56A program can have multiple resolver objects, each maintaining its 57own state information such as the nameservers to be queried, whether 58recursion is desired, etc. 59 60=head1 METHODS 61 62=head2 new 63 64 # Use the system defaults 65 my $res = Net::DNS::Resolver->new; 66 67 # Use my own configuration file 68 my $res = Net::DNS::Resolver->new(config_file => '/my/dns.conf'); 69 70 # Set options in the constructor 71 my $res = Net::DNS::Resolver->new( 72 nameservers => [qw(10.1.1.128 10.1.2.128)], 73 recurse => 0, 74 debug => 1, 75 ); 76 77Returns a resolver object. If given no arguments, C<new()> returns an 78object configured to your system's defaults. On UNIX systems the 79defaults are read from the following files, in the order indicated: 80 81 /etc/resolv.conf 82 $HOME/.resolv.conf 83 ./.resolv.conf 84 85The following keywords are recognized in resolver configuration files: 86 87=over 4 88 89=item domain 90 91The default domain. 92 93=item search 94 95A space-separated list of domains to put in the search list. 96 97=item nameserver 98 99A space-separated list of nameservers to query. 100 101=back 102 103Files except for F</etc/resolv.conf> must be owned by the effective 104userid running the program or they won't be read. In addition, several 105environment variables can also contain configuration information; see 106L</ENVIRONMENT>. 107 108On Windows systems, an attempt is made to determine the system defaults 109using the registry. This is still a work in progress; systems with many 110dynamically configured network interfaces may confuse Net::DNS. 111 112You can include a configuration file of your own when creating a 113resolver object: 114 115 # Use my own configuration file 116 my $res = Net::DNS::Resolver->new(config_file => '/my/dns.conf'); 117 118This is supported on both UNIX and Windows. Values pulled from a custom 119configuration file override the the system's defaults, but can still be 120overridden by the other arguments to new(). 121 122Explicit arguments to new override both the system's defaults and the 123values of the custom configuration file, if any. The following 124arguments to new() are supported: 125 126=over 4 127 128=item nameservers 129 130An array reference of nameservers to query. 131 132=item searchlist 133 134An array reference of domains. 135 136=item recurse 137 138=item debug 139 140=item domain 141 142=item port 143 144=item srcaddr 145 146=item srcport 147 148=item tcp_timeout 149 150=item udp_timeout 151 152=item retrans 153 154=item retry 155 156=item usevc 157 158=item stayopen 159 160=item igntc 161 162=item defnames 163 164=item dnsrch 165 166=item persistent_tcp 167 168=item persistent_udp 169 170=item dnssec 171 172=back 173 174For more information on any of these options, please consult the method 175of the same name. 176 177=head2 search 178 179 $packet = $res->search('mailhost'); 180 $packet = $res->search('mailhost.example.com'); 181 $packet = $res->search('192.168.1.1'); 182 $packet = $res->search('example.com', 'MX'); 183 $packet = $res->search('user.passwd.example.com', 'TXT', 'HS'); 184 185Performs a DNS query for the given name, applying the searchlist 186if appropriate. The search algorithm is as follows: 187 188=over 4 189 190=item 1. 191 192If the name contains at least one dot, try it as is. 193 194=item 2. 195 196If the name doesn't end in a dot then append each item in 197the search list to the name. This is only done if B<dnsrch> 198is true. 199 200=item 3. 201 202If the name doesn't contain any dots, try it as is. 203 204=back 205 206The record type and class can be omitted; they default to A and 207IN. If the name looks like an IP address (4 dot-separated numbers), 208then an appropriate PTR query will be performed. 209 210Returns a "Net::DNS::Packet" object, or "undef" if no answers were 211found. If you need to examine the response packet whether it contains 212any answers or not, use the send() method instead. 213 214=head2 query 215 216 $packet = $res->query('mailhost'); 217 $packet = $res->query('mailhost.example.com'); 218 $packet = $res->query('192.168.1.1'); 219 $packet = $res->query('example.com', 'MX'); 220 $packet = $res->query('user.passwd.example.com', 'TXT', 'HS'); 221 222Performs a DNS query for the given name; the search list is not 223applied. If the name doesn't contain any dots and B<defnames> 224is true then the default domain will be appended. 225 226The record type and class can be omitted; they default to A and 227IN. If the name looks like an IP address (IPv4 or IPv6), 228then an appropriate PTR query will be performed. 229 230Returns a "Net::DNS::Packet" object, or "undef" if no answers were 231found. If you need to examine the response packet whether it contains 232any answers or not, use the send() method instead. 233 234=head2 send 235 236 $packet = $res->send($packet_object); 237 $packet = $res->send('mailhost.example.com'); 238 $packet = $res->send('example.com', 'MX'); 239 $packet = $res->send('user.passwd.example.com', 'TXT', 'HS'); 240 241Performs a DNS query for the given name. Neither the searchlist 242nor the default domain will be appended. 243 244The argument list can be either a C<Net::DNS::Packet> object or a list 245of strings. The record type and class can be omitted; they default to 246A and IN. If the name looks like an IP address (Ipv4 or IPv6), 247then an appropriate PTR query will be performed. 248 249Returns a C<Net::DNS::Packet> object whether there were any answers or not. 250Use C<< $packet->header->ancount >> or C<< $packet->answer >> to find out 251if there were any records in the answer section. Returns C<undef> if there 252was an error. 253 254=head2 axfr 255 256 @zone = $res->axfr; 257 @zone = $res->axfr('example.com'); 258 @zone = $res->axfr('passwd.example.com', 'HS'); 259 260Performs a zone transfer from the first nameserver listed in C<nameservers>. 261If the zone is omitted, it defaults to the first zone listed in the resolver's 262search list. If the class is omitted, it defaults to IN. 263 264Returns a list of C<Net::DNS::RR> objects, or C<undef> if the zone 265transfer failed. 266 267The redundant SOA record that terminates the zone transfer is not 268returned to the caller. 269 270See also L</axfr_start> and L</axfr_next>. 271 272Here's an example that uses a timeout: 273 274 $res->tcp_timeout(10); 275 my @zone = $res->axfr('example.com'); 276 277 if (@zone) { 278 foreach my $rr (@zone) { 279 $rr->print; 280 } 281 } else { 282 print 'Zone transfer failed: ', $res->errorstring, "\n"; 283 } 284 285=head2 axfr_start 286 287 $res->axfr_start; 288 $res->axfr_start('example.com'); 289 $res->axfr_start('example.com', 'HS'); 290 291Starts a zone transfer from the first nameserver listed in C<nameservers>. 292If the zone is omitted, it defaults to the first zone listed in the resolver's 293search list. If the class is omitted, it defaults to IN. 294 295B<IMPORTANT>: 296 297This method currently returns the C<IO::Socket::INET> object that will 298be used for reading, or C<undef> on error. DO NOT DEPEND ON C<axfr_start()> 299returning a socket object. THIS MIGHT CHANGE in future releases. 300 301Use C<axfr_next> to read the zone records one at a time. 302 303=head2 axfr_next 304 305 $res->axfr_start('example.com'); 306 307 while (my $rr = $res->axfr_next) { 308 $rr->print; 309 } 310 311Reads records from a zone transfer one at a time. 312 313Returns C<undef> at the end of the zone transfer. The redundant 314SOA record that terminates the zone transfer is not returned. 315 316See also L</axfr>. 317 318=head2 nameservers 319 320 @nameservers = $res->nameservers; 321 $res->nameservers('192.168.1.1', '192.168.2.2', '192.168.3.3'); 322 323Gets or sets the nameservers to be queried. 324 325Also see the IPv6 transport notes below 326 327=head2 print 328 329 $res->print; 330 331Prints the resolver state on the standard output. 332 333=head2 string 334 335 print $res->string; 336 337Returns a string representation of the resolver state. 338 339=head2 searchlist 340 341 @searchlist = $res->searchlist; 342 $res->searchlist('example.com', 'a.example.com', 'b.example.com'); 343 344Gets or sets the resolver search list. 345 346=head2 port 347 348 print 'sending queries to port ', $res->port, "\n"; 349 $res->port(9732); 350 351Gets or sets the port to which we send queries. This can be useful 352for testing a nameserver running on a non-standard port. The 353default is port 53. 354 355=head2 srcport 356 357 print 'sending queries from port ', $res->srcport, "\n"; 358 $res->srcport(5353); 359 360Gets or sets the port from which we send queries. The default is 0, 361meaning any port. 362 363=head2 srcaddr 364 365 print 'sending queries from address ', $res->srcaddr, "\n"; 366 $res->srcaddr('192.168.1.1'); 367 368Gets or sets the source address from which we send queries. Convenient 369for forcing queries out a specific interfaces on a multi-homed host. 370The default is 0.0.0.0, meaning any local address. 371 372=head2 bgsend 373 374 $socket = $res->bgsend($packet_object) || die " $res->errorstring"; 375 376 $socket = $res->bgsend('mailhost.example.com'); 377 $socket = $res->bgsend('example.com', 'MX'); 378 $socket = $res->bgsend('user.passwd.example.com', 'TXT', 'HS'); 379 380 381 382Performs a background DNS query for the given name, i.e., sends a 383query packet to the first nameserver listed in C<< $res->nameservers >> 384and returns immediately without waiting for a response. The program 385can then perform other tasks while waiting for a response from the 386nameserver. 387 388The argument list can be either a C<Net::DNS::Packet> object or a list 389of strings. The record type and class can be omitted; they default to 390A and IN. If the name looks like an IP address (4 dot-separated numbers), 391then an appropriate PTR query will be performed. 392 393Returns an C<IO::Socket::INET> object or C<undef> on error in which 394case the reason for failure can be found through a call to the 395errorstring method. 396 397The program must determine when the socket is ready for reading and 398call C<< $res->bgread >> to get the response packet. You can use C<< 399$res->bgisready >> or C<IO::Select> to find out if the socket is ready 400before reading it. 401 402=head2 bgread 403 404 $packet = $res->bgread($socket); 405 undef $socket; 406 407Reads the answer from a background query (see L</bgsend>). The argument 408is an C<IO::Socket> object returned by C<bgsend>. 409 410Returns a C<Net::DNS::Packet> object or C<undef> on error. 411 412The programmer should close or destroy the socket object after reading it. 413 414=head2 bgisready 415 416 $socket = $res->bgsend('foo.example.com'); 417 until ($res->bgisready($socket)) { 418 # do some other processing 419 } 420 $packet = $res->bgread($socket); 421 $socket = undef; 422 423Determines whether a socket is ready for reading. The argument is 424an C<IO::Socket> object returned by C<< $res->bgsend >>. 425 426Returns true if the socket is ready, false if not. 427 428=head2 tsig 429 430 my $tsig = $res->tsig; 431 432 $res->tsig(Net::DNS::RR->new("$key_name TSIG $key")); 433 434 $tsig = Net::DNS::RR->new("$key_name TSIG $key"); 435 $tsig->fudge(60); 436 $res->tsig($tsig); 437 438 $res->tsig($key_name, $key); 439 440 $res->tsig(0); 441 442Get or set the TSIG record used to automatically sign outgoing 443queries and updates. Call with an argument of 0 or '' to turn off 444automatic signing. 445 446The default resolver behavior is not to sign any packets. You must 447call this method to set the key if you'd like the resolver to sign 448packets automatically. 449 450You can also sign packets manually -- see the C<Net::DNS::Packet> 451and C<Net::DNS::Update> manual pages for examples. TSIG records 452in manually-signed packets take precedence over those that the 453resolver would add automatically. 454 455=head2 retrans 456 457 print 'retrans interval: ', $res->retrans, "\n"; 458 $res->retrans(3); 459 460Get or set the retransmission interval. The default is 5. 461 462=head2 retry 463 464 print 'number of tries: ', $res->retry, "\n"; 465 $res->retry(2); 466 467Get or set the number of times to try the query. The default is 4. 468 469=head2 recurse 470 471 print 'recursion flag: ', $res->recurse, "\n"; 472 $res->recurse(0); 473 474Get or set the recursion flag. If this is true, nameservers will 475be requested to perform a recursive query. The default is true. 476 477=head2 defnames 478 479 print 'defnames flag: ', $res->defnames, "\n"; 480 $res->defnames(0); 481 482Get or set the defnames flag. If this is true, calls to B<query> will 483append the default domain to names that contain no dots. The default 484is true. 485 486=head2 dnsrch 487 488 print 'dnsrch flag: ', $res->dnsrch, "\n"; 489 $res->dnsrch(0); 490 491Get or set the dnsrch flag. If this is true, calls to B<search> will 492apply the search list. The default is true. 493 494=head2 debug 495 496 print 'debug flag: ', $res->debug, "\n"; 497 $res->debug(1); 498 499Get or set the debug flag. If set, calls to B<search>, B<query>, 500and B<send> will print debugging information on the standard output. 501The default is false. 502 503=head2 usevc 504 505 print 'usevc flag: ', $res->usevc, "\n"; 506 $res->usevc(1); 507 508Get or set the usevc flag. If true, then queries will be performed 509using virtual circuits (TCP) instead of datagrams (UDP). The default 510is false. 511 512=head2 tcp_timeout 513 514 print 'TCP timeout: ', $res->tcp_timeout, "\n"; 515 $res->tcp_timeout(10); 516 517Get or set the TCP timeout in seconds. A timeout of C<undef> means 518indefinite. The default is 120 seconds (2 minutes). 519 520=head2 udp_timeout 521 522 print 'UDP timeout: ', $res->udp_timeout, "\n"; 523 $res->udp_timeout(10); 524 525Get or set the UDP timeout in seconds. A timeout of C<undef> means 526the retry and retrans settings will be just utilized to perform the 527retries until they are exhausted. The default is C<undef>. 528 529=head2 persistent_tcp 530 531 print 'Persistent TCP flag: ', $res->persistent_tcp, "\n"; 532 $res->persistent_tcp(1); 533 534Get or set the persistent TCP setting. If set to true, Net::DNS 535will keep a TCP socket open for each host:port to which it connects. 536This is useful if you're using TCP and need to make a lot of queries 537or updates to the same nameserver. 538 539This option defaults to false unless you're running under a 540SOCKSified Perl, in which case it defaults to true. 541 542=head2 persistent_udp 543 544 print 'Persistent UDP flag: ', $res->persistent_udp, "\n"; 545 $res->persistent_udp(1); 546 547Get or set the persistent UDP setting. If set to true, Net::DNS 548will keep a single UDP socket open for all queries. 549This is useful if you're using UDP and need to make a lot of queries 550or updates. 551 552=head2 igntc 553 554 print 'igntc flag: ', $res->igntc, "\n"; 555 $res->igntc(1); 556 557Get or set the igntc flag. If true, truncated packets will be 558ignored. If false, truncated packets will cause the query to 559be retried using TCP. The default is false. 560 561=head2 errorstring 562 563 print 'query status: ', $res->errorstring, "\n"; 564 565Returns a string containing the status of the most recent query. 566 567=head2 answerfrom 568 569 print 'last answer was from: ', $res->answerfrom, "\n"; 570 571Returns the IP address from which we received the last answer in 572response to a query. 573 574=head2 answersize 575 576 print 'size of last answer: ', $res->answersize, "\n"; 577 578Returns the size in bytes of the last answer we received in 579response to a query. 580 581 582=head2 dnssec 583 584 print "dnssec flag: ", $res->dnssec, "\n"; 585 $res->dnssec(0); 586 587Enabled DNSSEC this will set the checking disabled flag in the query header 588and add EDNS0 data as in RFC2671 and RFC3225 589 590When set to true the answer and additional section of queries from 591secured zones will contain DNSKEY, NSEC and RRSIG records. 592 593Setting calling the dnssec method with a non-zero value will set the 594UDP packet size to the default value of 2048. If that is to small or 595to big for your environement you should call the udppacketsize() 596method immeditatly after. 597 598 $res->dnssec(1); # turns on DNSSEC and sets udp packetsize to 2048 599 $res->udppacketsize(1028); # lowers the UDP pakcet size 600 601The method will Croak::croak with the message "You called the 602Net::DNS::Resolver::dnssec() method but do not have Net::DNS::SEC 603installed at ..." if you call it without Net::DNS::SEC being in your 604@INC path. 605 606 607 608=head2 cdflag 609 610 print "checking disabled flag: ", $res->dnssec, "\n"; 611 $res->dnssec(1); 612 $res->cdflag(1); 613 614Sets or gets the CD bit for a dnssec query. This bit is always zero 615for non dnssec queries. When the dnssec is enabled the flag can be set 616to 1. 617 618=head2 udppacketsize 619 620 print "udppacketsize: ", $res->udppacketsize, "\n"; 621 $res->udppacketsize(2048); 622 623udppacketsize will set or get the packet size. If set to a value greater than 624Net::DNS::PACKETSZ() an EDNS extension will be added indicating suppport for MTU path 625recovery. 626 627Default udppacketsize is Net::DNS::PACKETSZ() (512) 628 629=head1 CUSTOMIZING 630 631Net::DNS::Resolver is actually an empty subclass. At compile time a 632super class is chosen based on the current platform. A side benefit of 633this allows for easy modification of the methods in Net::DNS::Resolver. 634You simply add a method to the namespace! 635 636For example, if we wanted to cache lookups: 637 638 package Net::DNS::Resolver; 639 640 my %cache; 641 642 sub search { 643 my ($self, @args) = @_; 644 645 return $cache{@args} ||= $self->SUPER::search(@args); 646 } 647 648 649=head1 IPv6 transport 650 651The Net::DNS::Resolver library will use IPv6 transport if the 652appropriate libraries (Socket6 and IO::Socket::INET6) are available 653and the address the server tries to connect to is an IPv6 address. 654 655The print() will method will report if IPv6 transport is available. 656 657You can use the force_v4() method with a non-zero argument 658to force IPv4 transport. 659 660The nameserver() method has IPv6 dependend behavior. If IPv6 is not 661available or IPv4 transport has been forced the nameserver() method 662will only return IPv4 addresses. 663 664For example 665 666 $res->nameservers('192.168.1.1', '192.168.2.2', '2001:610:240:0:53:0:0:3'); 667 $res->force_v4(1); 668 print join (" ",$res->nameserver()); 669 670Will print: 192.168.1.1 192.168.2.2 671 672 673 674 675=head1 ENVIRONMENT 676 677The following environment variables can also be used to configure 678the resolver: 679 680=head2 RES_NAMESERVERS 681 682 # Bourne Shell 683 RES_NAMESERVERS="192.168.1.1 192.168.2.2 192.168.3.3" 684 export RES_NAMESERVERS 685 686 # C Shell 687 setenv RES_NAMESERVERS "192.168.1.1 192.168.2.2 192.168.3.3" 688 689A space-separated list of nameservers to query. 690 691=head2 RES_SEARCHLIST 692 693 # Bourne Shell 694 RES_SEARCHLIST="example.com sub1.example.com sub2.example.com" 695 export RES_SEARCHLIST 696 697 # C Shell 698 setenv RES_SEARCHLIST "example.com sub1.example.com sub2.example.com" 699 700A space-separated list of domains to put in the search list. 701 702=head2 LOCALDOMAIN 703 704 # Bourne Shell 705 LOCALDOMAIN=example.com 706 export LOCALDOMAIN 707 708 # C Shell 709 setenv LOCALDOMAIN example.com 710 711The default domain. 712 713=head2 RES_OPTIONS 714 715 # Bourne Shell 716 RES_OPTIONS="retrans:3 retry:2 debug" 717 export RES_OPTIONS 718 719 # C Shell 720 setenv RES_OPTIONS "retrans:3 retry:2 debug" 721 722A space-separated list of resolver options to set. Options that 723take values are specified as I<option>:I<value>. 724 725=head1 BUGS 726 727Error reporting and handling needs to be improved. 728 729The current implementation supports TSIG only on outgoing packets. 730No validation of server replies is performed. 731 732bgsend does not honor the usevc flag and only uses UDP for transport. 733 734=head1 COPYRIGHT 735 736Copyright (c) 1997-2002 Michael Fuhr. 737 738Portions Copyright (c) 2002-2004 Chris Reinhardt. 739Portions Copyright (c) 2005 Olaf M. Kolkman, NLnet Labs. 740 741All rights reserved. This program is free software; you may redistribute 742it and/or modify it under the same terms as Perl itself. 743 744=head1 SEE ALSO 745 746L<perl(1)>, L<Net::DNS>, L<Net::DNS::Packet>, L<Net::DNS::Update>, 747L<Net::DNS::Header>, L<Net::DNS::Question>, L<Net::DNS::RR>, 748L<resolver(5)>, RFC 1035, RFC 1034 Section 4.3.5 749 750=cut 751