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 somewhat familiar with the format of a DNS
18       packet and its various sections.  See RFC 1035 or DNS and BIND (Albitz
19       & Liu) for details.
20
21   Resolver Objects
22       A resolver object is an instance of the Net::DNS::Resolver class. A
23       program can have multiple resolver objects, each maintaining its own
24       state information such as the nameservers to be queried, whether
25       recursion is desired, etc.
26
27   Packet Objects
28       Net::DNS::Resolver queries return Net::DNS::Packet objects.  Packet
29       objects have five sections:
30
31       ·  The header section, a Net::DNS::Header object.
32
33       ·  The question section, a list of Net::DNS::Question objects.
34
35       ·  The answer section, a list of Net::DNS::RR objects.
36
37       ·  The authority section, a list of Net::DNS::RR objects.
38
39       ·  The additional section, a list of Net::DNS::RR objects.
40
41   Update Objects
42       The Net::DNS::Update package is a subclass of Net::DNS::Packet for
43       creating packet objects to be used in dynamic updates.
44
45   Header Objects
46       Net::DNS::Header objects represent the header section of a DNS packet.
47
48   Question Objects
49       Net::DNS::Question objects represent the question section of a DNS
50       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       Don't assume that RR objects will be of the type you requested --
57       always check an RR object's type before calling any of its methods.
58

METHODS

60       See the manual pages listed above for other class-specific methods.
61
62   version
63           print Net::DNS->version, "\n";
64
65       Returns the version of Net::DNS.
66
67   mx
68           # Use a default resolver -- can't get an error string this way.
69           use Net::DNS;
70           my @mx = mx("example.com");
71
72           # Use your own resolver object.
73           use Net::DNS;
74           my $res = Net::DNS::Resolver->new;
75           my  @mx = mx($res, "example.com");
76
77       Returns a list of Net::DNS::RR::MX objects representing the MX records
78       for the specified name; the list will be sorted by preference. Returns
79       an empty list if the query failed or no MX records were found.
80
81       This method does not look up A records -- it only performs MX queries.
82
83       See "EXAMPLES" for a more complete example.
84
85   yxrrset
86       Use this method to add an "RRset exists" prerequisite to a dynamic
87       update packet.  There are two forms, value-independent and value-
88       dependent:
89
90           # RRset exists (value-independent)
91           $update->push(pre => yxrrset("host.example.com A"));
92
93       Meaning:  At least one RR with the specified name and type must exist.
94
95           # RRset exists (value-dependent)
96           $packet->push(pre => yxrrset("host.example.com A 10.1.2.3"));
97
98       Meaning:  At least one RR with the specified name and type must exist
99       and must have matching data.
100
101       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
102       created.
103
104   nxrrset
105       Use this method to add an "RRset does not exist" prerequisite to a
106       dynamic update packet.
107
108           $packet->push(pre => nxrrset("host.example.com A"));
109
110       Meaning:  No RRs with the specified name and type can exist.
111
112       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
113       created.
114
115   yxdomain
116       Use this method to add a "name is in use" prerequisite to a dynamic
117       update packet.
118
119           $packet->push(pre => yxdomain("host.example.com"));
120
121       Meaning:  At least one RR with the specified name must exist.
122
123       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
124       created.
125
126   nxdomain
127       Use this method to add a "name is not in use" prerequisite to a dynamic
128       update packet.
129
130           $packet->push(pre => nxdomain("host.example.com"));
131
132       Meaning:  No RR with the specified name can exist.
133
134       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
135       created.
136
137   rr_add
138       Use this method to add RRs to a zone.
139
140           $packet->push(update => rr_add("host.example.com A 10.1.2.3"));
141
142       Meaning:  Add this RR to the zone.
143
144       RR objects created by this method should be added to the "update"
145       section of a dynamic update packet.  The TTL defaults to 86400 seconds
146       (24 hours) if not specified.
147
148       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
149       created.
150
151   rr_del
152       Use this method to delete RRs from a zone.  There are three forms:
153       delete an RRset, delete all RRsets, and delete an RR.
154
155           # Delete an RRset.
156           $packet->push(update => rr_del("host.example.com A"));
157
158       Meaning:  Delete all RRs having the specified name and type.
159
160           # Delete all RRsets.
161           $packet->push(update => rr_del("host.example.com"));
162
163       Meaning:  Delete all RRs having the specified name.
164
165           # Delete an RR.
166           $packet->push(update => rr_del("host.example.com A 10.1.2.3"));
167
168       Meaning:  Delete all RRs having the specified name, type, and data.
169
170       RR objects created by this method should be added to the "update"
171       section of a dynamic update packet.
172
173       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
174       created.
175

Zone Serial Number Management

177       The Net::DNS module provides auxiliary functions which support policy-
178       driven zone serial numbering regimes.
179
180   Strictly Sequential
181           $successor = $soa->serial( SEQUENTIAL );
182
183       The existing serial number is incremented modulo 2**32.
184
185   Time Encoded
186           $successor = $soa->serial( UNIXTIME );
187
188       The Unix time scale will be used as the basis for zone serial
189       numbering. The serial number will be incremented if the time elapsed
190       since the previous update is less than one second.
191
192   Date Encoded
193           $successor = $soa->serial( YYYYMMDDxx );
194
195       The 32 bit value returned by the auxiliary YYYYMMDDxx() function will
196       be used as the base for the date-coded zone serial number.  Serial
197       number increments must be limited to 100 per day for the date
198       information to remain useful.
199
200   Sorting of RR arrays
201       As of version 0.55 there is functionality to help you sort RR arrays.
202       'rrsort()' is the function that is available to do the sorting. In most
203       cases rrsort will give you the answer that you want but you can specify
204       your own sorting method by using the
205       Net::DNS::RR::FOO->set_rrsort_func() class method. See Net::DNS::RR for
206       details.
207
208       rrsort()
209
210          use Net::DNS qw(rrsort);
211
212          my @prioritysorted=rrsort("SRV","priority",@rr_array);
213
214       rrsort() selects all RRs from the input array that are of the type that
215       are defined in the first argument. Those RRs are sorted based on the
216       attribute that is specified as second argument.
217
218       There are a number of RRs for which the sorting function is
219       specifically defined for certain attributes.  If such sorting function
220       is defined in the code (it can be set or overwritten using the
221       set_rrsort_func() class method) that function is used.
222
223       For instance:
224          my @prioritysorted=rrsort("SRV","priority",@rr_array); returns the
225       SRV records sorted from lowest to heighest priority and for equal
226       priorities from heighes to lowes weight.
227
228       If the function does not exist then a numerical sort on the attribute
229       value is performed.
230          my @portsorted=rrsort("SRV","port",@rr_array);
231
232       If the attribute does not exist for a certain RR than the RRs are
233       sorted on string comparrisson of the rdata.
234
235       If the attribute is not defined than either the default_sort function
236       will be defined or "Canonical sorting" (as defined by DNSSEC) will be
237       used.
238
239       rrsort() returns a sorted array with only elements of the specified RR
240       type or undef.
241
242       rrsort() returns undef when arguments are incorrect.
243

EXAMPLES

245       The following examples show how to use the "Net::DNS" modules.  See the
246       other manual pages and the demo scripts included with the source code
247       for additional examples.
248
249       See the "Net::DNS::Update" manual page for an example of performing
250       dynamic updates.
251
252   Look up a host's addresses.
253         use Net::DNS;
254         my $res   = Net::DNS::Resolver->new;
255         my $query = $res->search("host.example.com");
256
257         if ($query) {
258             foreach my $rr ($query->answer) {
259                 next unless $rr->type eq "A";
260                 print $rr->address, "\n";
261             }
262         } else {
263             warn "query failed: ", $res->errorstring, "\n";
264         }
265
266   Find the nameservers for a domain.
267         use Net::DNS;
268         my $res   = Net::DNS::Resolver->new;
269         my $query = $res->query("example.com", "NS");
270
271         if ($query) {
272             foreach $rr (grep { $_->type eq 'NS' } $query->answer) {
273                 print $rr->nsdname, "\n";
274             }
275         }
276         else {
277             warn "query failed: ", $res->errorstring, "\n";
278         }
279
280   Find the MX records for a domain.
281         use Net::DNS;
282         my $name = "example.com";
283         my $res  = Net::DNS::Resolver->new;
284         my @mx   = mx($res, $name);
285
286         if (@mx) {
287             foreach $rr (@mx) {
288                 print $rr->preference, " ", $rr->exchange, "\n";
289             }
290         } else {
291             warn "Can't find MX records for $name: ", $res->errorstring, "\n";
292         }
293
294   Print a domain's SOA record in zone file format.
295         use Net::DNS;
296         my $res   = Net::DNS::Resolver->new;
297         my $query = $res->query("example.com", "SOA");
298
299         if ($query) {
300             ($query->answer)[0]->print;
301         } else {
302             print "query failed: ", $res->errorstring, "\n";
303         }
304
305   Perform a zone transfer and print all the records.
306         use Net::DNS;
307         my $res  = Net::DNS::Resolver->new;
308         $res->nameservers("ns.example.com");
309
310         my @zone = $res->axfr("example.com");
311
312         foreach $rr (@zone) {
313             $rr->print;
314         }
315
316   Perform a background query and do some other work while waiting for the
317       answer.
318         use Net::DNS;
319         my $res    = Net::DNS::Resolver->new;
320         my $socket = $res->bgsend("host.example.com");
321
322         until ($res->bgisready($socket)) {
323             # do some work here while waiting for the answer
324             # ...and some more here
325         }
326
327         my $packet = $res->bgread($socket);
328         $packet->print;
329
330   Send a background query and use select to determine when the answer has
331       arrived.
332         use Net::DNS;
333         use IO::Select;
334
335         my $timeout = 5;
336         my $res     = Net::DNS::Resolver->new;
337         my $bgsock  = $res->bgsend("host.example.com");
338         my $sel     = IO::Select->new($bgsock);
339
340         # Add more sockets to $sel if desired.
341         my @ready = $sel->can_read($timeout);
342         if (@ready) {
343             foreach my $sock (@ready) {
344                 if ($sock == $bgsock) {
345                     my $packet = $res->bgread($bgsock);
346                     $packet->print;
347                     $bgsock = undef;
348                 }
349                 # Check for the other sockets.
350                 $sel->remove($sock);
351                 $sock = undef;
352             }
353         } else {
354             warn "timed out after $timeout seconds\n";
355         }
356

BUGS

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

COPYRIGHT

364       Copyright (c)1997-2002 Michael Fuhr.  Portions Copyright(c)2002-2004
365       Chris Reinhardt.  Portions Copyright(c)2005 Olaf Kolkman (RIPE NCC)
366       Portions Copyright(c)2006 Olaf Kolkman (NLnet Labs)
367
368       All rights reserved.
369
370       This program is free software; you may redistribute it and/or modify it
371       under the same terms as Perl itself.
372

AUTHOR INFORMATION

374       Net::DNS is currently maintained at NLnet Labs (www.nlnetlabs.nl) by:
375               Olaf Kolkman      olaf@net-dns.org
376
377       Between 2002 and 2004 Net::DNS was maintained by:
378              Chris Reinhardt
379
380       Net::DNS was created by:      Michael Fuhr      mike@fuhr.org
381
382       For more information see:
383           http://www.net-dns.org/
384
385       Stay tuned and syndicate:
386           http://www.net-dns.org/blog/
387