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   print
253           $res->print;
254
255       Prints the resolver state on the standard output.
256
257   string
258           print $res->string;
259
260       Returns a string representation of the resolver state.
261
262   searchlist
263           @searchlist = $res->searchlist;
264           $res->searchlist('example.com', 'a.example.com', 'b.example.com');
265
266       Gets or sets the resolver search list.
267
268   port
269           print 'sending queries to port ', $res->port, "\n";
270           $res->port(9732);
271
272       Gets or sets the port to which we send queries.  This can be useful for
273       testing a nameserver running on a non-standard port.  The default is
274       port 53.
275
276   srcport
277           print 'sending queries from port ', $res->srcport, "\n";
278           $res->srcport(5353);
279
280       Gets or sets the port from which we send queries.  The default is 0,
281       meaning any port.
282
283   srcaddr
284           print 'sending queries from address ', $res->srcaddr, "\n";
285           $res->srcaddr('192.168.1.1');
286
287       Gets or sets the source address from which we send queries.  Convenient
288       for forcing queries out a specific interfaces on a multi-homed host.
289       The default is 0.0.0.0, meaning any local address.
290
291   bgsend
292           $socket = $res->bgsend($packet_object) || die " $res->errorstring";
293
294           $socket = $res->bgsend('mailhost.example.com');
295           $socket = $res->bgsend('example.com', 'MX');
296           $socket = $res->bgsend('user.passwd.example.com', 'TXT', 'HS');
297
298       Performs a background DNS query for the given name, i.e., sends a query
299       packet to the first nameserver listed in "$res->nameservers" and
300       returns immediately without waiting for a response.  The program can
301       then perform other tasks while waiting for a response from the
302       nameserver.
303
304       The argument list can be either a "Net::DNS::Packet" object or a list
305       of strings.  The record type and class can be omitted; they default to
306       A and IN.  If the name looks like an IP address (4 dot-separated
307       numbers), then an appropriate PTR query will be performed.
308
309       Returns an "IO::Socket::INET" object or "undef" on error in which case
310       the reason for failure can be found through a call to the errorstring
311       method.
312
313       The program must determine when the socket is ready for reading and
314       call "$res->bgread" to get the response packet.  You can use
315       "$res->bgisready" or "IO::Select" to find out if the socket is ready
316       before reading it.
317
318   bgread
319           $packet = $res->bgread($socket);
320           undef $socket;
321
322       Reads the answer from a background query (see "bgsend").  The argument
323       is an "IO::Socket" object returned by "bgsend".
324
325       Returns a "Net::DNS::Packet" object or "undef" on error.
326
327       The programmer should close or destroy the socket object after reading
328       it.
329
330   bgisready
331           $socket = $res->bgsend('foo.example.com');
332           until ($res->bgisready($socket)) {
333               # do some other processing
334           }
335           $packet = $res->bgread($socket);
336           $socket = undef;
337
338       Determines whether a socket is ready for reading.  The argument is an
339       "IO::Socket" object returned by "$res->bgsend".
340
341       Returns true if the socket is ready, false if not.
342
343   tsig
344           my $tsig = $res->tsig;
345
346           $res->tsig(Net::DNS::RR->new("$key_name TSIG $key"));
347
348           $tsig = Net::DNS::RR->new("$key_name TSIG $key");
349           $tsig->fudge(60);
350           $res->tsig($tsig);
351
352           $res->tsig($key_name, $key);
353
354           $res->tsig(0);
355
356       Get or set the TSIG record used to automatically sign outgoing queries
357       and updates.  Call with an argument of 0 or '' to turn off automatic
358       signing.
359
360       The default resolver behavior is not to sign any packets.  You must
361       call this method to set the key if you'd like the resolver to sign
362       packets automatically.
363
364       You can also sign packets manually -- see the "Net::DNS::Packet" and
365       "Net::DNS::Update" manual pages for examples.  TSIG records in
366       manually-signed packets take precedence over those that the resolver
367       would add automatically.
368
369   retrans
370           print 'retrans interval: ', $res->retrans, "\n";
371           $res->retrans(3);
372
373       Get or set the retransmission interval.  The default is 5.
374
375   retry
376           print 'number of tries: ', $res->retry, "\n";
377           $res->retry(2);
378
379       Get or set the number of times to try the query.  The default is 4.
380
381   recurse
382           print 'recursion flag: ', $res->recurse, "\n";
383           $res->recurse(0);
384
385       Get or set the recursion flag.  If this is true, nameservers will be
386       requested to perform a recursive query.  The default is true.
387
388   defnames
389           print 'defnames flag: ', $res->defnames, "\n";
390           $res->defnames(0);
391
392       Get or set the defnames flag.  If this is true, calls to query will
393       append the default domain to names that contain no dots.  The default
394       is true.
395
396   dnsrch
397           print 'dnsrch flag: ', $res->dnsrch, "\n";
398           $res->dnsrch(0);
399
400       Get or set the dnsrch flag.  If this is true, calls to search will
401       apply the search list.  The default is true.
402
403   debug
404           print 'debug flag: ', $res->debug, "\n";
405           $res->debug(1);
406
407       Get or set the debug flag.  If set, calls to search, query, and send
408       will print debugging information on the standard output.  The default
409       is false.
410
411   usevc
412           print 'usevc flag: ', $res->usevc, "\n";
413           $res->usevc(1);
414
415       Get or set the usevc flag.  If true, then queries will be performed
416       using virtual circuits (TCP) instead of datagrams (UDP).  The default
417       is false.
418
419   tcp_timeout
420           print 'TCP timeout: ', $res->tcp_timeout, "\n";
421           $res->tcp_timeout(10);
422
423       Get or set the TCP timeout in seconds.  A timeout of "undef" means
424       indefinite.  The default is 120 seconds (2 minutes).
425
426   udp_timeout
427           print 'UDP timeout: ', $res->udp_timeout, "\n";
428           $res->udp_timeout(10);
429
430       Get or set the UDP timeout in seconds.  A timeout of "undef" means the
431       retry and retrans settings will be just utilized to perform the retries
432       until they are exhausted.  The default is "undef".
433
434   persistent_tcp
435           print 'Persistent TCP flag: ', $res->persistent_tcp, "\n";
436           $res->persistent_tcp(1);
437
438       Get or set the persistent TCP setting.  If set to true, Net::DNS will
439       keep a TCP socket open for each host:port to which it connects.  This
440       is useful if you're using TCP and need to make a lot of queries or
441       updates to the same nameserver.
442
443       This option defaults to false unless you're running under a SOCKSified
444       Perl, in which case it defaults to true.
445
446   persistent_udp
447           print 'Persistent UDP flag: ', $res->persistent_udp, "\n";
448           $res->persistent_udp(1);
449
450       Get or set the persistent UDP setting.  If set to true, Net::DNS will
451       keep a single UDP socket open for all queries.  This is useful if
452       you're using UDP and need to make a lot of queries or updates.
453
454   igntc
455           print 'igntc flag: ', $res->igntc, "\n";
456           $res->igntc(1);
457
458       Get or set the igntc flag.  If true, truncated packets will be ignored.
459       If false, truncated packets will cause the query to be retried using
460       TCP.  The default is false.
461
462   errorstring
463           print 'query status: ', $res->errorstring, "\n";
464
465       Returns a string containing the status of the most recent query.
466
467   answerfrom
468           print 'last answer was from: ', $res->answerfrom, "\n";
469
470       Returns the IP address from which we received the last answer in
471       response to a query.
472
473   answersize
474           print 'size of last answer: ', $res->answersize, "\n";
475
476       Returns the size in bytes of the last answer we received in response to
477       a query.
478
479   dnssec
480           print "dnssec flag: ", $res->dnssec, "\n";
481           $res->dnssec(0);
482
483       Enabled DNSSEC this will set the checking disabled flag in the query
484       header and add EDNS0 data as in RFC2671 and RFC3225
485
486       When set to true the answer and additional section of queries from
487       secured zones will contain DNSKEY, NSEC and RRSIG records.
488
489       Setting calling the dnssec method with a non-zero value will set the
490       UDP packet size to the default value of 2048. If that is to small or to
491       big for your environement you should call the udppacketsize() method
492       immeditatly after.
493
494          $res->dnssec(1);    # turns on DNSSEC and sets udp packetsize to 2048
495          $res->udppacketsize(1028);   # lowers the UDP pakcet size
496
497       The method will Croak::croak with the message "You called the
498       Net::DNS::Resolver::dnssec() method but do not have Net::DNS::SEC
499       installed at ..." if you call it without Net::DNS::SEC being in your
500       @INC path.
501
502   cdflag
503           print "checking disabled flag: ", $res->dnssec, "\n";
504           $res->dnssec(1);
505           $res->cdflag(1);
506
507       Sets or gets the CD bit for a dnssec query.  This bit is always zero
508       for non dnssec queries. When the dnssec is enabled the flag defaults to
509       0 can be set to 1.
510
511   adflag
512           print "checking disabled flag: ", $res->dnssec, "\n";
513           $res->dnssec(1);
514           $res->adflag(1);
515
516       Sets or gets the AD bit for a dnssec query.  This bit is always zero
517       for non dnssec queries. When the dnssec is enabled the flag defaults to
518       1.
519
520   udppacketsize
521           print "udppacketsize: ", $res->udppacketsize, "\n";
522           $res->udppacketsize(2048);
523
524       udppacketsize will set or get the packet size. If set to a value
525       greater than Net::DNS::PACKETSZ() an EDNS extension will be added
526       indicating suppport for MTU path recovery.
527
528       Default udppacketsize is Net::DNS::PACKETSZ()[24m (512)
529

CUSTOMIZING

531       Net::DNS::Resolver is actually an empty subclass.  At compile time a
532       super class is chosen based on the current platform.  A side benefit of
533       this allows for easy modification of the methods in Net::DNS::Resolver.
534       You simply add a method to the namespace!
535
536       For example, if we wanted to cache lookups:
537
538        package Net::DNS::Resolver;
539
540        my %cache;
541
542        sub search {
543               my ($self, @args) = @_;
544
545               return $cache{@args} ||= $self->SUPER::search(@args);
546        }
547

IPv6 transport

549       The Net::DNS::Resolver library will use IPv6 transport if the
550       appropriate libraries (Socket6 and IO::Socket::INET6) are available and
551       the address the server tries to connect to is an IPv6 address.
552
553       The print() will method will report if IPv6 transport is available.
554
555       You can use the force_v4() method with a non-zero argument to force
556       IPv4 transport.
557
558       The nameserver() method has IPv6 dependend behavior. If IPv6 is not
559       available or IPv4 transport has been forced the nameserver() method
560       will only return IPv4 addresses.
561
562       For example
563
564           $res->nameservers('192.168.1.1', '192.168.2.2', '2001:610:240:0:53:0:0:3');
565           $res->force_v4(1);
566           print join (" ",$res->nameserver());
567
568       Will print: 192.168.1.1 192.168.2.2
569

ENVIRONMENT

571       The following environment variables can also be used to configure the
572       resolver:
573
574   RES_NAMESERVERS
575           # Bourne Shell
576           RES_NAMESERVERS="192.168.1.1 192.168.2.2 192.168.3.3"
577           export RES_NAMESERVERS
578
579           # C Shell
580           setenv RES_NAMESERVERS "192.168.1.1 192.168.2.2 192.168.3.3"
581
582       A space-separated list of nameservers to query.
583
584   RES_SEARCHLIST
585           # Bourne Shell
586           RES_SEARCHLIST="example.com sub1.example.com sub2.example.com"
587           export RES_SEARCHLIST
588
589           # C Shell
590           setenv RES_SEARCHLIST "example.com sub1.example.com sub2.example.com"
591
592       A space-separated list of domains to put in the search list.
593
594   LOCALDOMAIN
595           # Bourne Shell
596           LOCALDOMAIN=example.com
597           export LOCALDOMAIN
598
599           # C Shell
600           setenv LOCALDOMAIN example.com
601
602       The default domain.
603
604   RES_OPTIONS
605           # Bourne Shell
606           RES_OPTIONS="retrans:3 retry:2 debug"
607           export RES_OPTIONS
608
609           # C Shell
610           setenv RES_OPTIONS "retrans:3 retry:2 debug"
611
612       A space-separated list of resolver options to set.  Options that take
613       values are specified as option:value.
614

BUGS

616       Error reporting and handling needs to be improved.
617
618       The current implementation supports TSIG only on outgoing packets.  No
619       validation of server replies is performed.
620
621       bgsend does not honor the usevc flag and only uses UDP for transport.
622

COPYRIGHT

624       Copyright (c) 1997-2002 Michael Fuhr.
625
626       Portions Copyright (c) 2002-2004 Chris Reinhardt.  Portions Copyright
627       (c) 2005 Olaf M. Kolkman, NLnet Labs.
628
629       All rights reserved.  This program is free software; you may
630       redistribute it and/or modify it under the same terms as Perl itself.
631