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

Zone Serial Number Management

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

Sorting of RR arrays

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

EXAMPLES

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

BUGS

357       Net::DNS is slow.
358
359       For other items to be fixed, or if you discover a bug in this
360       distribution please use the CPAN bug reporting system.
361

COPYRIGHT

363       Copyright (c)1997-2000 Michael Fuhr.
364
365       Portions Copyright (c)2002,2003 Chris Reinhardt.
366
367       Portions Copyright (c)2005 Olaf Kolkman (RIPE NCC)
368
369       Portions Copyright (c)2006 Olaf Kolkman (NLnet Labs)
370
371       Portions Copyright (c)2014 Dick Franks
372
373       All rights reserved.
374

LICENSE

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

AUTHOR INFORMATION

393       Net::DNS is maintained at NLnet Labs (www.nlnetlabs.nl) by Willem
394       Toorop.
395
396       Between 2005 and 2012 Net::DNS was maintained by Olaf Kolkman.
397
398       Between 2002 and 2004 Net::DNS was maintained by Chris Reinhardt.
399
400       Net::DNS was created in 1997 by Michael Fuhr.
401