Net::DNS(3pm)

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

NAME

6       Net::DNS - Perl interface to the DNS resolver
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
176   Sorting of RR arrays
177       As of version 0.55 there is functionality to help you sort RR arrays.
178       'rrsort()' is the function that is available to do the sorting. In most
179       cases rrsort will give you the answer that you want but you can specify
180       your own sorting method by using the
181       Net::DNS::RR::FOO->set_rrsort_func() class method. See Net::DNS::RR for
182       details.
183
184       rrsort()
185
186          use Net::DNS qw(rrsort);
187
188          my @prioritysorted=rrsort("SRV","priority",@rr_array);
189
190       rrsort() selects all RRs from the input array that are of the type that
191       are defined in the first argument. Those RRs are sorted based on the
192       attribute that is specified as second argument.
193
194       There are a number of RRs for which the sorting function is
195       specifically defined for certain attributes.  If such sorting function
196       is defined in the code (it can be set or overwritten using the
197       set_rrsort_func() class method) that function is used.
198
199       For instance:
200          my @prioritysorted=rrsort("SRV","priority",@rr_array); returns the
201       SRV records sorted from lowest to heighest priority and for equal
202       priorities from heighes to lowes weight.
203
204       If the function does not exist then a numerical sort on the attribute
205       value is performed.
206          my @portsorted=rrsort("SRV","port",@rr_array);
207
208       If the attribute does not exist for a certain RR than the RRs are
209       sorted on string comparrisson of the rdata.
210
211       If the attribute is not defined than either the default_sort function
212       will be defined or "Canonical sorting" (as defined by DNSSEC) will be
213       used.
214
215       rrsort() returns a sorted array with only elements of the specified RR
216       type or undef.
217
218       rrsort() returns undef when arguments are incorrect.
219

EXAMPLES

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

BUGS

334       "Net::DNS" is slow.
335
336       For other items to be fixed, please see the TODO file included with the
337       source distribution.
338

COPYRIGHT

340       Copyright (c) 1997-2002 Michael Fuhr.  Portions Copyright (c) 2002-2004
341       Chris Reinhardt.  Portions Copyright (c) 2005 Olaf Kolkman (RIPE NCC)
342       Portions Copyright (c) 2006 Olaf Kolkman (NLnet Labs)
343
344       All rights reserved.  This program is free software; you may
345       redistribute it and/or modify it under the same terms as Perl itself.
346

AUTHOR INFORMATION

348       Net::DNS is currently maintained at NLnet Labs (www.nlnetlabs.nl) by:
349               Olaf Kolkman      olaf@net-dns.org
350
351       Between 2002 and 2004 Net::DNS was maintained by:
352              Chris Reinhardt
353
354       Net::DNS was created by:      Michael Fuhr      mike@fuhr.org
355
356       For more information see:
357           http://www.net-dns.org/
358
359       Stay tuned and syncicate:
360           http://www.net-dns.org/blog/
361