Net::DNS::Resolver(3pm)

1Net::DNS::Resolver(3) User Contributed Perl DocumentationNet::DNS::Resolver(3)
2
3
4

NAME

6       Net::DNS::Resolver - DNS resolver class
7

SYNOPSIS

9         use Net::DNS;
10
11         my $res = Net::DNS::Resolver->new;
12
13         # Perform a lookup, using the searchlist if appropriate.
14         my $answer = $res->search('example.com');
15
16         # Perform a lookup, without the searchlist
17         my $answer = $res->query('example.com', 'MX');
18
19         # Perform a lookup, without pre or post-processing
20         my $answer = $res->send('example.com', 'MX', 'CH');
21
22         # Send a prebuilt packet
23         my $packet = Net::DNS::Packet->new(...);
24         my $answer = $res->send($packet);
25

DESCRIPTION

27       Instances of the "Net::DNS::Resolver" class represent resolver objects.
28       A program can have multiple resolver objects, each maintaining its own
29       state information such as the nameservers to be queried, whether recur‐
30       sion is desired, etc.
31

METHODS

33       new
34
35         # Use the system defaults
36         my $res = Net::DNS::Resolver->new;
37
38         # Use my own configuration file
39         my $res = Net::DNS::Resolver->new(config_file => '/my/dns.conf');
40
41         # Set options in the constructor
42         my $res = Net::DNS::Resolver->new(
43               nameservers => [qw(10.1.1.128 10.1.2.128)],
44               recurse     => 0,
45               debug       => 1,
46         );
47
48       Returns a resolver object.  If given no arguments, "new()" returns an
49       object configured to your system's defaults.  On UNIX systems the
50       defaults are read from the following files, in the order indicated:
51
52           /etc/resolv.conf
53           $HOME/.resolv.conf
54           ./.resolv.conf
55
56       The following keywords are recognized in resolver configuration files:
57
58       domain
59           The default domain.
60
61       search
62           A space-separated list of domains to put in the search list.
63
64       nameserver
65           A space-separated list of nameservers to query.
66
67       Files except for /etc/resolv.conf must be owned by the effective userid
68       running the program or they won't be read.  In addition, several envi‐
69       ronment variables can also contain configuration information; see
70       "ENVIRONMENT".
71
72       On Windows systems, an attempt is made to determine the system defaults
73       using the registry.  This is still a work in progress; systems with
74       many dynamically configured network interfaces may confuse Net::DNS.
75
76       You can include a configuration file of your own when creating a
77       resolver object:
78
79        # Use my own configuration file
80        my $res = Net::DNS::Resolver->new(config_file => '/my/dns.conf');
81
82       This is supported on both UNIX and Windows.  Values pulled from a cus‐
83       tom configuration file override the the system's defaults, but can
84       still be overridden by the other arguments to new().
85
86       Explicit arguments to new override both the system's defaults and the
87       values of the custom configuration file, if any.  The following argu‐
88       ments to new() are supported:
89
90       nameservers
91           An array reference of nameservers to query.
92
93       searchlist
94           An array reference of domains.
95
96       recurse
97       debug
98       domain
99       port
100       srcaddr
101       srcport
102       tcp_timeout
103       udp_timeout
104       retrans
105       retry
106       usevc
107       stayopen
108       igntc
109       defnames
110       dnsrch
111       persistent_tcp
112       persistent_udp
113       dnssec
114
115       For more information on any of these options, please consult the method
116       of the same name.
117
118       search
119
120           $packet = $res->search('mailhost');
121           $packet = $res->search('mailhost.example.com');
122           $packet = $res->search('192.168.1.1');
123           $packet = $res->search('example.com', 'MX');
124           $packet = $res->search('user.passwd.example.com', 'TXT', 'HS');
125
126       Performs a DNS query for the given name, applying the searchlist if
127       appropriate.  The search algorithm is as follows:
128
129       1.  If the name contains at least one dot, try it as is.
130
131       2.  If the name doesn't end in a dot then append each item in the
132           search list to the name.  This is only done if dnsrch is true.
133
134       3.  If the name doesn't contain any dots, try it as is.
135
136       The record type and class can be omitted; they default to A and IN.  If
137       the name looks like an IP address (4 dot-separated numbers), then an
138       appropriate PTR query will be performed.
139
140       Returns a "Net::DNS::Packet" object, or "undef" if no answers were
141       found.  If you need to examine the response packet whether it contains
142       any answers or not, use the send() method instead.
143
144       query
145
146           $packet = $res->query('mailhost');
147           $packet = $res->query('mailhost.example.com');
148           $packet = $res->query('192.168.1.1');
149           $packet = $res->query('example.com', 'MX');
150           $packet = $res->query('user.passwd.example.com', 'TXT', 'HS');
151
152       Performs a DNS query for the given name; the search list is not
153       applied.  If the name doesn't contain any dots and defnames is true
154       then the default domain will be appended.
155
156       The record type and class can be omitted; they default to A and IN.  If
157       the name looks like an IP address (IPv4 or IPv6), then an appropriate
158       PTR query will be performed.
159
160       Returns a "Net::DNS::Packet" object, or "undef" if no answers were
161       found.  If you need to examine the response packet whether it contains
162       any answers or not, use the send() method instead.
163
164       send
165
166           $packet = $res->send($packet_object);
167           $packet = $res->send('mailhost.example.com');
168           $packet = $res->send('example.com', 'MX');
169           $packet = $res->send('user.passwd.example.com', 'TXT', 'HS');
170
171       Performs a DNS query for the given name.  Neither the searchlist nor
172       the default domain will be appended.
173
174       The argument list can be either a "Net::DNS::Packet" object or a list
175       of strings.  The record type and class can be omitted; they default to
176       A and IN.  If the name looks like an IP address (Ipv4 or IPv6), then an
177       appropriate PTR query will be performed.
178
179       Returns a "Net::DNS::Packet" object whether there were any answers or
180       not.  Use "$packet->header->ancount" or "$packet->answer" to find out
181       if there were any records in the answer section.  Returns "undef" if
182       there was an error.
183
184       axfr
185
186           @zone = $res->axfr;
187           @zone = $res->axfr('example.com');
188           @zone = $res->axfr('passwd.example.com', 'HS');
189
190       Performs a zone transfer from the first nameserver listed in "name‐
191       servers".  If the zone is omitted, it defaults to the first zone listed
192       in the resolver's search list.  If the class is omitted, it defaults to
193       IN.
194
195       Returns a list of "Net::DNS::RR" objects, or "undef" if the zone trans‐
196       fer failed.
197
198       The redundant SOA record that terminates the zone transfer is not
199       returned to the caller.
200
201       See also "axfr_start" and "axfr_next".
202
203       Here's an example that uses a timeout:
204
205           $res->tcp_timeout(10);
206           my @zone = $res->axfr('example.com');
207
208           if (@zone) {
209               foreach my $rr (@zone) {
210                   $rr->print;
211               }
212           } else {
213               print 'Zone transfer failed: ', $res->errorstring, "\n";
214           }
215
216       axfr_start
217
218           $res->axfr_start;
219           $res->axfr_start('example.com');
220           $res->axfr_start('example.com', 'HS');
221
222       Starts a zone transfer from the first nameserver listed in "name‐
223       servers".  If the zone is omitted, it defaults to the first zone listed
224       in the resolver's search list.  If the class is omitted, it defaults to
225       IN.
226
227       IMPORTANT:
228
229       This method currently returns the "IO::Socket::INET" object that will
230       be used for reading, or "undef" on error.  DO NOT DEPEND ON
231       "axfr_start()" returning a socket object.  THIS MIGHT CHANGE in future
232       releases.
233
234       Use "axfr_next" to read the zone records one at a time.
235
236       axfr_next
237
238           $res->axfr_start('example.com');
239
240           while (my $rr = $res->axfr_next) {
241                   $rr->print;
242           }
243
244       Reads records from a zone transfer one at a time.
245
246       Returns "undef" at the end of the zone transfer.  The redundant SOA
247       record that terminates the zone transfer is not returned.
248
249       See also "axfr".
250
251       nameservers
252
253           @nameservers = $res->nameservers;
254           $res->nameservers('192.168.1.1', '192.168.2.2', '192.168.3.3');
255
256       Gets or sets the nameservers to be queried.
257
258       Also see the IPv6 transport notes below
259
260       print
261
262           $res->print;
263
264       Prints the resolver state on the standard output.
265
266       string
267
268           print $res->string;
269
270       Returns a string representation of the resolver state.
271
272       searchlist
273
274           @searchlist = $res->searchlist;
275           $res->searchlist('example.com', 'a.example.com', 'b.example.com');
276
277       Gets or sets the resolver search list.
278
279       port
280
281           print 'sending queries to port ', $res->port, "\n";
282           $res->port(9732);
283
284       Gets or sets the port to which we send queries.  This can be useful for
285       testing a nameserver running on a non-standard port.  The default is
286       port 53.
287
288       srcport
289
290           print 'sending queries from port ', $res->srcport, "\n";
291           $res->srcport(5353);
292
293       Gets or sets the port from which we send queries.  The default is 0,
294       meaning any port.
295
296       srcaddr
297
298           print 'sending queries from address ', $res->srcaddr, "\n";
299           $res->srcaddr('192.168.1.1');
300
301       Gets or sets the source address from which we send queries.  Convenient
302       for forcing queries out a specific interfaces on a multi-homed host.
303       The default is 0.0.0.0, meaning any local address.
304
305       bgsend
306
307           $socket = $res->bgsend($packet_object) ⎪⎪ die " $res->errorstring";
308
309           $socket = $res->bgsend('mailhost.example.com');
310           $socket = $res->bgsend('example.com', 'MX');
311           $socket = $res->bgsend('user.passwd.example.com', 'TXT', 'HS');
312
313       Performs a background DNS query for the given name, i.e., sends a query
314       packet to the first nameserver listed in "$res->nameservers" and
315       returns immediately without waiting for a response.  The program can
316       then perform other tasks while waiting for a response from the name‐
317       server.
318
319       The argument list can be either a "Net::DNS::Packet" object or a list
320       of strings.  The record type and class can be omitted; they default to
321       A and IN.  If the name looks like an IP address (4 dot-separated num‐
322       bers), then an appropriate PTR query will be performed.
323
324       Returns an "IO::Socket::INET" object or "undef" on error in which case
325       the reason for failure can be found through a call to the errorstring
326       method.
327
328       The program must determine when the socket is ready for reading and
329       call "$res->bgread" to get the response packet.  You can use
330       "$res->bgisready" or "IO::Select" to find out if the socket is ready
331       before reading it.
332
333       bgread
334
335           $packet = $res->bgread($socket);
336           undef $socket;
337
338       Reads the answer from a background query (see "bgsend").  The argument
339       is an "IO::Socket" object returned by "bgsend".
340
341       Returns a "Net::DNS::Packet" object or "undef" on error.
342
343       The programmer should close or destroy the socket object after reading
344       it.
345
346       bgisready
347
348           $socket = $res->bgsend('foo.example.com');
349           until ($res->bgisready($socket)) {
350               # do some other processing
351           }
352           $packet = $res->bgread($socket);
353           $socket = undef;
354
355       Determines whether a socket is ready for reading.  The argument is an
356       "IO::Socket" object returned by "$res->bgsend".
357
358       Returns true if the socket is ready, false if not.
359
360       tsig
361
362           my $tsig = $res->tsig;
363
364           $res->tsig(Net::DNS::RR->new("$key_name TSIG $key"));
365
366           $tsig = Net::DNS::RR->new("$key_name TSIG $key");
367           $tsig->fudge(60);
368           $res->tsig($tsig);
369
370           $res->tsig($key_name, $key);
371
372           $res->tsig(0);
373
374       Get or set the TSIG record used to automatically sign outgoing queries
375       and updates.  Call with an argument of 0 or '' to turn off automatic
376       signing.
377
378       The default resolver behavior is not to sign any packets.  You must
379       call this method to set the key if you'd like the resolver to sign
380       packets automatically.
381
382       You can also sign packets manually -- see the "Net::DNS::Packet" and
383       "Net::DNS::Update" manual pages for examples.  TSIG records in manu‐
384       ally-signed packets take precedence over those that the resolver would
385       add automatically.
386
387       retrans
388
389           print 'retrans interval: ', $res->retrans, "\n";
390           $res->retrans(3);
391
392       Get or set the retransmission interval.  The default is 5.
393
394       retry
395
396           print 'number of tries: ', $res->retry, "\n";
397           $res->retry(2);
398
399       Get or set the number of times to try the query.  The default is 4.
400
401       recurse
402
403           print 'recursion flag: ', $res->recurse, "\n";
404           $res->recurse(0);
405
406       Get or set the recursion flag.  If this is true, nameservers will be
407       requested to perform a recursive query.  The default is true.
408
409       defnames
410
411           print 'defnames flag: ', $res->defnames, "\n";
412           $res->defnames(0);
413
414       Get or set the defnames flag.  If this is true, calls to query will
415       append the default domain to names that contain no dots.  The default
416       is true.
417
418       dnsrch
419
420           print 'dnsrch flag: ', $res->dnsrch, "\n";
421           $res->dnsrch(0);
422
423       Get or set the dnsrch flag.  If this is true, calls to search will
424       apply the search list.  The default is true.
425
426       debug
427
428           print 'debug flag: ', $res->debug, "\n";
429           $res->debug(1);
430
431       Get or set the debug flag.  If set, calls to search, query, and send
432       will print debugging information on the standard output.  The default
433       is false.
434
435       usevc
436
437           print 'usevc flag: ', $res->usevc, "\n";
438           $res->usevc(1);
439
440       Get or set the usevc flag.  If true, then queries will be performed
441       using virtual circuits (TCP) instead of datagrams (UDP).  The default
442       is false.
443
444       tcp_timeout
445
446           print 'TCP timeout: ', $res->tcp_timeout, "\n";
447           $res->tcp_timeout(10);
448
449       Get or set the TCP timeout in seconds.  A timeout of "undef" means
450       indefinite.  The default is 120 seconds (2 minutes).
451
452       udp_timeout
453
454           print 'UDP timeout: ', $res->udp_timeout, "\n";
455           $res->udp_timeout(10);
456
457       Get or set the UDP timeout in seconds.  A timeout of "undef" means the
458       retry and retrans settings will be just utilized to perform the retries
459       until they are exhausted.  The default is "undef".
460
461       persistent_tcp
462
463           print 'Persistent TCP flag: ', $res->persistent_tcp, "\n";
464           $res->persistent_tcp(1);
465
466       Get or set the persistent TCP setting.  If set to true, Net::DNS will
467       keep a TCP socket open for each host:port to which it connects.  This
468       is useful if you're using TCP and need to make a lot of queries or
469       updates to the same nameserver.
470
471       This option defaults to false unless you're running under a SOCKSified
472       Perl, in which case it defaults to true.
473
474       persistent_udp
475
476           print 'Persistent UDP flag: ', $res->persistent_udp, "\n";
477           $res->persistent_udp(1);
478
479       Get or set the persistent UDP setting.  If set to true, Net::DNS will
480       keep a single UDP socket open for all queries.  This is useful if
481       you're using UDP and need to make a lot of queries or updates.
482
483       igntc
484
485           print 'igntc flag: ', $res->igntc, "\n";
486           $res->igntc(1);
487
488       Get or set the igntc flag.  If true, truncated packets will be ignored.
489       If false, truncated packets will cause the query to be retried using
490       TCP.  The default is false.
491
492       errorstring
493
494           print 'query status: ', $res->errorstring, "\n";
495
496       Returns a string containing the status of the most recent query.
497
498       answerfrom
499
500           print 'last answer was from: ', $res->answerfrom, "\n";
501
502       Returns the IP address from which we received the last answer in
503       response to a query.
504
505       answersize
506
507           print 'size of last answer: ', $res->answersize, "\n";
508
509       Returns the size in bytes of the last answer we received in response to
510       a query.
511
512       dnssec
513
514           print "dnssec flag: ", $res->dnssec, "\n";
515           $res->dnssec(0);
516
517       Enabled DNSSEC this will set the checking disabled flag in the query
518       header and add EDNS0 data as in RFC2671 and RFC3225
519
520       When set to true the answer and additional section of queries from
521       secured zones will contain DNSKEY, NSEC and RRSIG records.
522
523       Setting calling the dnssec method with a non-zero value will set the
524       UDP packet size to the default value of 2048. If that is to small or to
525       big for your environement you should call the udppacketsize() method
526       immeditatly after.
527
528          $res->dnssec(1);    # turns on DNSSEC and sets udp packetsize to 2048
529          $res->udppacketsize(1028);   # lowers the UDP pakcet size
530
531       The method will Croak::croak with the message "You called the
532       Net::DNS::Resolver::dnssec() method but do not have Net::DNS::SEC
533       installed at ..." if you call it without Net::DNS::SEC being in your
534       @INC path.
535
536       cdflag
537
538           print "checking disabled flag: ", $res->dnssec, "\n";
539           $res->dnssec(1);
540           $res->cdflag(1);
541
542       Sets or gets the CD bit for a dnssec query.  This bit is always zero
543       for non dnssec queries. When the dnssec is enabled the flag can be set
544       to 1.
545
546       udppacketsize
547
548           print "udppacketsize: ", $res->udppacketsize, "\n";
549           $res->udppacketsize(2048);
550
551       udppacketsize will set or get the packet size. If set to a value
552       greater than Net::DNS::PACKETSZ() an EDNS extension will be added indi‐
553       cating suppport for MTU path recovery.
554
555       Default udppacketsize is Net::DNS::PACKETSZ()[24m (512)
556

CUSTOMIZING

558       Net::DNS::Resolver is actually an empty subclass.  At compile time a
559       super class is chosen based on the current platform.  A side benefit of
560       this allows for easy modification of the methods in Net::DNS::Resolver.
561       You simply add a method to the namespace!
562
563       For example, if we wanted to cache lookups:
564
565        package Net::DNS::Resolver;
566
567        my %cache;
568
569        sub search {
570               my ($self, @args) = @_;
571
572               return $cache{@args} ⎪⎪= $self->SUPER::search(@args);
573        }
574

IPv6 transport

576       The Net::DNS::Resolver library will use IPv6 transport if the appropri‐
577       ate libraries (Socket6 and IO::Socket::INET6) are available and the
578       address the server tries to connect to is an IPv6 address.
579
580       The print() will method will report if IPv6 transport is available.
581
582       You can use the force_v4() method with a non-zero argument to force
583       IPv4 transport.
584
585       The nameserver() method has IPv6 dependend behavior. If IPv6 is not
586       available or IPv4 transport has been forced the nameserver() method
587       will only return IPv4 addresses.
588
589       For example
590
591           $res->nameservers('192.168.1.1', '192.168.2.2', '2001:610:240:0:53:0:0:3');
592           $res->force_v4(1);
593           print join (" ",$res->nameserver());
594
595       Will print: 192.168.1.1 192.168.2.2
596

ENVIRONMENT

598       The following environment variables can also be used to configure the
599       resolver:
600
601       RES_NAMESERVERS
602
603           # Bourne Shell
604           RES_NAMESERVERS="192.168.1.1 192.168.2.2 192.168.3.3"
605           export RES_NAMESERVERS
606
607           # C Shell
608           setenv RES_NAMESERVERS "192.168.1.1 192.168.2.2 192.168.3.3"
609
610       A space-separated list of nameservers to query.
611
612       RES_SEARCHLIST
613
614           # Bourne Shell
615           RES_SEARCHLIST="example.com sub1.example.com sub2.example.com"
616           export RES_SEARCHLIST
617
618           # C Shell
619           setenv RES_SEARCHLIST "example.com sub1.example.com sub2.example.com"
620
621       A space-separated list of domains to put in the search list.
622
623       LOCALDOMAIN
624
625           # Bourne Shell
626           LOCALDOMAIN=example.com
627           export LOCALDOMAIN
628
629           # C Shell
630           setenv LOCALDOMAIN example.com
631
632       The default domain.
633
634       RES_OPTIONS
635
636           # Bourne Shell
637           RES_OPTIONS="retrans:3 retry:2 debug"
638           export RES_OPTIONS
639
640           # C Shell
641           setenv RES_OPTIONS "retrans:3 retry:2 debug"
642
643       A space-separated list of resolver options to set.  Options that take
644       values are specified as option:value.
645

BUGS

647       Error reporting and handling needs to be improved.
648
649       The current implementation supports TSIG only on outgoing packets.  No
650       validation of server replies is performed.
651
652       bgsend does not honor the usevc flag and only uses UDP for transport.
653

COPYRIGHT

655       Copyright (c) 1997-2002 Michael Fuhr.
656
657       Portions Copyright (c) 2002-2004 Chris Reinhardt.  Portions Copyright
658       (c) 2005 Olaf M. Kolkman, NLnet Labs.
659
660       All rights reserved.  This program is free software; you may redis‐
661       tribute it and/or modify it under the same terms as Perl itself.
662