Net::DNS(3pm)

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

NAME

6       Net::DNS - Perl Interface to the Domain Name System
7

SYNOPSIS

9           use Net::DNS;
10

DESCRIPTION

12       Net::DNS is a collection of Perl modules that act as a Domain Name
13       System (DNS) resolver. It allows the programmer to perform DNS queries
14       that are beyond the capabilities of "gethostbyname" and
15       "gethostbyaddr".
16
17       The programmer should be familiar with the structure of a DNS packet.
18       See RFC 1035 or DNS and BIND (Albitz & Liu) for details.
19
20   Resolver Objects
21       A resolver object is an instance of the Net::DNS::Resolver class.  A
22       program may have multiple resolver objects, each maintaining its own
23       state information such as the nameservers to be queried, whether
24       recursion is desired, etc.
25
26   Packet Objects
27       Net::DNS::Resolver queries return Net::DNS::Packet objects.  A packet
28       object has five sections:
29
30       •  header, represented by a Net::DNS::Header object
31
32       •  question, a list of no more than one Net::DNS::Question object
33
34       •  answer, a list of Net::DNS::RR objects
35
36       •  authority, a list of Net::DNS::RR objects
37
38       •  additional, a list of Net::DNS::RR objects
39
40   Update Objects
41       Net::DNS::Update is a subclass of Net::DNS::Packet useful for creating
42       dynamic update requests.
43
44   Header Object
45       The Net::DNS::Header object mediates access to the header data which
46       resides within the corresponding Net::DNS::Packet.
47
48   Question Object
49       The Net::DNS::Question object represents the content of the question
50       section of the DNS packet.
51
52   RR Objects
53       Net::DNS::RR is the base class for DNS resource record (RR) objects in
54       the answer, authority, and additional sections of a DNS packet.
55
56       Do not assume that RR objects will be of the type requested.  The type
57       of an RR object must be checked before calling any methods.
58

METHODS

60       Net::DNS exports methods and auxilliary functions to support DNS
61       updates, zone serial number management, and simple DNS queries.
62
63   version
64           use Net::DNS;
65           print Net::DNS->version, "\n";
66
67       Returns the version of Net::DNS.
68
69   rr
70           # Use a default resolver -- can not get an error string this way.
71           use Net::DNS;
72           my @rr = rr("example.com");
73           my @rr = rr("example.com", "AAAA");
74           my @rr = rr("example.com", "AAAA", "IN");
75
76           # Use your own resolver object.
77           my $res = Net::DNS::Resolver->new;
78           my @rr  = rr($res, "example.com" ... );
79
80           my ($ptr) = rr("2001:DB8::dead:beef");
81
82       The "rr()" method provides simple RR lookup for scenarios where the
83       full flexibility of Net::DNS is not required.
84
85       Returns a list of Net::DNS::RR objects for the specified name or an
86       empty list if the query failed or no record was found.
87
88       See "EXAMPLES" for more complete examples.
89
90   mx
91           # Use a default resolver -- can not get an error string this way.
92           use Net::DNS;
93           my @mx = mx("example.com");
94
95           # Use your own resolver object.
96           my $res = Net::DNS::Resolver->new;
97           my @mx  = mx($res, "example.com");
98
99       Returns a list of Net::DNS::RR::MX objects representing the MX records
100       for the specified name.  The list will be sorted by preference.
101       Returns an empty list if the query failed or no MX record was found.
102
103       This method does not look up address records; it resolves MX only.
104

Dynamic DNS Update Support

106       The Net::DNS module provides auxilliary functions which support dynamic
107       DNS update requests.
108
109           $update = Net::DNS::Update->new( 'example.com' );
110
111           $update->push( prereq => nxrrset('example.com. AAAA') );
112           $update->push( update => rr_add('example.com. 86400 AAAA 2001::DB8::F00') );
113
114   yxrrset
115       Use this method to add an "RRset exists" prerequisite to a dynamic
116       update packet.  There are two forms, value-independent and value-
117       dependent:
118
119           # RRset exists (value-independent)
120           $update->push( pre => yxrrset("host.example.com AAAA") );
121
122       Meaning:  At least one RR with the specified name and type must exist.
123
124           # RRset exists (value-dependent)
125           $update->push( pre => yxrrset("host.example.com AAAA 2001:DB8::1") );
126
127       Meaning:  At least one RR with the specified name and type must exist
128       and must have matching data.
129
130       Returns a Net::DNS::RR object or "undef" if the object could not be
131       created.
132
133   nxrrset
134       Use this method to add an "RRset does not exist" prerequisite to a
135       dynamic update packet.
136
137           $update->push( pre => nxrrset("host.example.com AAAA") );
138
139       Meaning:  No RRs with the specified name and type can exist.
140
141       Returns a Net::DNS::RR object or "undef" if the object could not be
142       created.
143
144   yxdomain
145       Use this method to add a "name is in use" prerequisite to a dynamic
146       update packet.
147
148           $update->push( pre => yxdomain("host.example.com") );
149
150       Meaning:  At least one RR with the specified name must exist.
151
152       Returns a Net::DNS::RR object or "undef" if the object could not be
153       created.
154
155   nxdomain
156       Use this method to add a "name is not in use" prerequisite to a dynamic
157       update packet.
158
159           $update->push( pre => nxdomain("host.example.com") );
160
161       Meaning:  No RR with the specified name can exist.
162
163       Returns a Net::DNS::RR object or "undef" if the object could not be
164       created.
165
166   rr_add
167       Use this method to add RRs to a zone.
168
169           $update->push( update => rr_add("host.example.com AAAA 2001:DB8::c001:a1e") );
170
171       Meaning:  Add this RR to the zone.
172
173       RR objects created by this method should be added to the "update"
174       section of a dynamic update packet.  The TTL defaults to 86400 seconds
175       (24 hours) if not specified.
176
177       Returns a Net::DNS::RR object or "undef" if the object could not be
178       created.
179
180   rr_del
181       Use this method to delete RRs from a zone.  There are three forms:
182       delete all RRsets, delete an RRset, and delete a specific RR.
183
184           # Delete all RRsets.
185           $update->push( update => rr_del("host.example.com") );
186
187       Meaning:  Delete all RRs having the specified name.
188
189           # Delete an RRset.
190           $update->push( update => rr_del("host.example.com AAAA") );
191
192       Meaning:  Delete all RRs having the specified name and type.
193
194           # Delete a specific RR.
195           $update->push( update => rr_del("host.example.com AAAA 2001:DB8::dead:beef") );
196
197       Meaning:  Delete the RR which matches the specified argument.
198
199       RR objects created by this method should be added to the "update"
200       section of a dynamic update packet.
201
202       Returns a Net::DNS::RR object or "undef" if the object could not be
203       created.
204

Zone Serial Number Management

206       The Net::DNS module provides auxilliary functions which support policy-
207       driven zone serial numbering regimes.
208
209           $soa->serial(SEQUENTIAL);
210           $soa->serial(YYYMMDDxx);
211
212   SEQUENTIAL
213           $successor = $soa->serial( SEQUENTIAL );
214
215       The existing serial number is incremented modulo 2**32.
216
217   UNIXTIME
218           $successor = $soa->serial( UNIXTIME );
219
220       The Unix time scale will be used as the basis for zone serial
221       numbering. The serial number will be incremented if the time elapsed
222       since the previous update is less than one second.
223
224   YYYYMMDDxx
225           $successor = $soa->serial( YYYYMMDDxx );
226
227       The 32 bit value returned by the auxilliary "YYYYMMDDxx()" function
228       will be used as the base for the date-coded zone serial number.  Serial
229       number increments must be limited to 100 per day for the date
230       information to remain useful.
231

Sorting of RR arrays

233       "rrsort()" provides functionality to help you sort RR arrays. In most
234       cases this will give you the result that you expect, but you can
235       specify your own sorting method by using the
236       "Net::DNS::RR::FOO->set_rrsort_func()" class method. See Net::DNS::RR
237       for details.
238
239   rrsort
240           use Net::DNS;
241
242           my @sorted = rrsort( $rrtype, $attribute, @rr_array );
243
244       "rrsort()" selects all RRs from the input array that are of the type
245       defined by the first argument. Those RRs are sorted based on the
246       attribute that is specified as second argument.
247
248       There are a number of RRs for which the sorting function is defined in
249       the code.
250
251       For instance:
252
253           my @prioritysorted = rrsort( "SRV", "priority", @rr_array );
254
255       returns the SRV records sorted from lowest to highest priority and for
256       equal priorities from highest to lowest weight.
257
258       If the function does not exist then a numerical sort on the attribute
259       value is performed.
260
261           my @portsorted = rrsort( "SRV", "port", @rr_array );
262
263       If the attribute is not defined then either the "default_sort()"
264       function or "canonical sorting" (as defined by DNSSEC) will be used.
265
266       "rrsort()" returns a sorted array containing only elements of the
267       specified RR type.  Any other RR types are silently discarded.
268
269       "rrsort()" returns an empty list when arguments are incorrect.
270

EXAMPLES

272       The following brief examples illustrate some of the features of
273       Net::DNS.  The documentation for individual modules and the demo
274       scripts included with the distribution provide more extensive examples.
275
276       See Net::DNS::Update for an example of performing dynamic updates.
277
278   Look up host addresses.
279           use Net::DNS;
280           my $res   = Net::DNS::Resolver->new;
281           my $reply = $res->search("www.example.com", "AAAA");
282
283           if ($reply) {
284               foreach my $rr ($reply->answer) {
285                   print $rr->address, "\n" if $rr->can("address");
286               }
287           } else {
288               warn "query failed: ", $res->errorstring, "\n";
289           }
290
291   Find the nameservers for a domain.
292           use Net::DNS;
293           my $res   = Net::DNS::Resolver->new;
294           my $reply = $res->query("example.com", "NS");
295
296           if ($reply) {
297               foreach $rr (grep { $_->type eq "NS" } $reply->answer) {
298                   print $rr->nsdname, "\n";
299               }
300           } else {
301               warn "query failed: ", $res->errorstring, "\n";
302           }
303
304   Find the MX records for a domain.
305           use Net::DNS;
306           my $name = "example.com";
307           my $res  = Net::DNS::Resolver->new;
308           my @mx   = mx($res, $name);
309
310           if (@mx) {
311               foreach $rr (@mx) {
312                   print $rr->preference, "\t", $rr->exchange, "\n";
313               }
314           } else {
315               warn "Can not find MX records for $name: ", $res->errorstring, "\n";
316           }
317
318   Print domain SOA record in zone file format.
319           use Net::DNS;
320           my $res   = Net::DNS::Resolver->new;
321           my $reply = $res->query("example.com", "SOA");
322
323           if ($reply) {
324               foreach my $rr ($reply->answer) {
325                   $rr->print;
326               }
327           } else {
328               warn "query failed: ", $res->errorstring, "\n";
329           }
330
331   Perform a zone transfer and print all the records.
332           use Net::DNS;
333           my $res  = Net::DNS::Resolver->new;
334           $res->tcp_timeout(20);
335           $res->nameservers("ns.example.com");
336
337           my @zone = $res->axfr("example.com");
338
339           foreach $rr (@zone) {
340               $rr->print;
341           }
342
343           warn $res->errorstring if $res->errorstring;
344
345   Perform a background query and print the reply.
346           use Net::DNS;
347           my $res    = Net::DNS::Resolver->new;
348           $res->udp_timeout(10);
349           $res->tcp_timeout(20);
350           my $socket = $res->bgsend("host.example.com", "AAAA");
351
352           while ( $res->bgbusy($socket) ) {
353               # do some work here while waiting for the response
354               # ...and some more here
355           }
356
357           my $packet = $res->bgread($socket);
358           if ($packet) {
359               $packet->print;
360           } else {
361               warn "query failed: ", $res->errorstring, "\n";
362           }
363

BUGS

365       Net::DNS is slow.
366
367       For other items to be fixed, or if you discover a bug in this
368       distribution please use the CPAN bug reporting system.
369

COPYRIGHT

371       Copyright (c)1997-2000 Michael Fuhr.
372
373       Portions Copyright (c)2002,2003 Chris Reinhardt.
374
375       Portions Copyright (c)2005 Olaf Kolkman (RIPE NCC)
376
377       Portions Copyright (c)2006 Olaf Kolkman (NLnet Labs)
378
379       Portions Copyright (c)2014 Dick Franks
380
381       All rights reserved.
382

LICENSE

384       Permission to use, copy, modify, and distribute this software and its
385       documentation for any purpose and without fee is hereby granted,
386       provided that the original copyright notices appear in all copies and
387       that both copyright notice and this permission notice appear in
388       supporting documentation, and that the name of the author not be used
389       in advertising or publicity pertaining to distribution of the software
390       without specific prior written permission.
391
392       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
393       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
394       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
395       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
396       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
397       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
398       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
399

AUTHOR INFORMATION

401       Net::DNS is maintained at NLnet Labs (www.nlnetlabs.nl) by Willem
402       Toorop.
403
404       Between 2005 and 2012 Net::DNS was maintained by Olaf Kolkman.
405
406       Between 2002 and 2004 Net::DNS was maintained by Chris Reinhardt.
407
408       Net::DNS was created in 1997 by Michael Fuhr.
409