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
30       recursion is desired, etc.
31

METHODS

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

CUSTOMIZING

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

IPv6 transport

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

ENVIRONMENT

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

BUGS

639       Error reporting and handling needs to be improved.
640
641       The current implementation supports TSIG only on outgoing packets.  No
642       validation of server replies is performed.
643
644       bgsend does not honor the usevc flag and only uses UDP for transport.
645

COPYRIGHT

647       Copyright (c) 1997-2002 Michael Fuhr.
648
649       Portions Copyright (c) 2002-2004 Chris Reinhardt.  Portions Copyright
650       (c) 2005 Olaf M. Kolkman, NLnet Labs.
651
652       All rights reserved.  This program is free software; you may
653       redistribute it and/or modify it under the same terms as Perl itself.
654