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 Sys‐
13       tem (DNS) resolver.  It allows the programmer to perform DNS queries
14       that are beyond the capabilities of "gethostbyname" and "gethost‐
15       byaddr".
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
23       A resolver object is an instance of the Net::DNS::Resolver class. A
24       program can have multiple resolver objects, each maintaining its own
25       state information such as the nameservers to be queried, whether recur‐
26       sion is desired, etc.
27
28       Packet Objects
29
30       Net::DNS::Resolver queries return Net::DNS::Packet objects.  Packet
31       objects have five sections:
32
33       ·  The header section, a Net::DNS::Header object.
34
35       ·  The question section, a list of Net::DNS::Question objects.
36
37       ·  The answer section, a list of Net::DNS::RR objects.
38
39       ·  The authority section, a list of Net::DNS::RR objects.
40
41       ·  The additional section, a list of Net::DNS::RR objects.
42
43       Update Objects
44
45       The Net::DNS::Update package is a subclass of Net::DNS::Packet for cre‐
46       ating packet objects to be used in dynamic updates.
47
48       Header Objects
49
50       Net::DNS::Header objects represent the header section of a DNS packet.
51
52       Question Objects
53
54       Net::DNS::Question objects represent the question section of a DNS
55       packet.
56
57       RR Objects
58
59       Net::DNS::RR is the base class for DNS resource record (RR) objects in
60       the answer, authority, and additional sections of a DNS packet.
61
62       Don't assume that RR objects will be of the type you requested --
63       always check an RR object's type before calling any of its methods.
64

METHODS

66       See the manual pages listed above for other class-specific methods.
67
68       version
69
70           print Net::DNS->version, "\n";
71
72       Returns the version of Net::DNS.
73
74       mx
75
76           # Use a default resolver -- can't get an error string this way.
77           use Net::DNS;
78           my @mx = mx("example.com");
79
80           # Use your own resolver object.
81           use Net::DNS;
82           my $res = Net::DNS::Resolver->new;
83           my  @mx = mx($res, "example.com");
84
85       Returns a list of Net::DNS::RR::MX objects representing the MX records
86       for the specified name; the list will be sorted by preference. Returns
87       an empty list if the query failed or no MX records were found.
88
89       This method does not look up A records -- it only performs MX queries.
90
91       See "EXAMPLES" for a more complete example.
92
93       yxrrset
94
95       Use this method to add an "RRset exists" prerequisite to a dynamic
96       update packet.  There are two forms, value-independent and value-depen‐
97       dent:
98
99           # RRset exists (value-independent)
100           $update->push(pre => yxrrset("host.example.com A"));
101
102       Meaning:  At least one RR with the specified name and type must exist.
103
104           # RRset exists (value-dependent)
105           $packet->push(pre => yxrrset("host.example.com A 10.1.2.3"));
106
107       Meaning:  At least one RR with the specified name and type must exist
108       and must have matching data.
109
110       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
111       created.
112
113       nxrrset
114
115       Use this method to add an "RRset does not exist" prerequisite to a
116       dynamic update packet.
117
118           $packet->push(pre => nxrrset("host.example.com A"));
119
120       Meaning:  No RRs with the specified name and type can exist.
121
122       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
123       created.
124
125       yxdomain
126
127       Use this method to add a "name is in use" prerequisite to a dynamic
128       update packet.
129
130           $packet->push(pre => yxdomain("host.example.com"));
131
132       Meaning:  At least one RR with the specified name must exist.
133
134       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
135       created.
136
137       nxdomain
138
139       Use this method to add a "name is not in use" prerequisite to a dynamic
140       update packet.
141
142           $packet->push(pre => nxdomain("host.example.com"));
143
144       Meaning:  No RR with the specified name can exist.
145
146       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
147       created.
148
149       rr_add
150
151       Use this method to add RRs to a zone.
152
153           $packet->push(update => rr_add("host.example.com A 10.1.2.3"));
154
155       Meaning:  Add this RR to the zone.
156
157       RR objects created by this method should be added to the "update" sec‐
158       tion of a dynamic update packet.  The TTL defaults to 86400 seconds (24
159       hours) if not specified.
160
161       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
162       created.
163
164       rr_del
165
166       Use this method to delete RRs from a zone.  There are three forms:
167       delete an RRset, delete all RRsets, and delete an RR.
168
169           # Delete an RRset.
170           $packet->push(update => rr_del("host.example.com A"));
171
172       Meaning:  Delete all RRs having the specified name and type.
173
174           # Delete all RRsets.
175           $packet->push(update => rr_del("host.example.com"));
176
177       Meaning:  Delete all RRs having the specified name.
178
179           # Delete an RR.
180           $packet->push(update => rr_del("host.example.com A 10.1.2.3"));
181
182       Meaning:  Delete all RRs having the specified name, type, and data.
183
184       RR objects created by this method should be added to the "update" sec‐
185       tion of a dynamic update packet.
186
187       Returns a "Net::DNS::RR" object or "undef" if the object couldn't be
188       created.
189
190       Sorting of RR arrays
191
192       As of version 0.55 there is functionality to help you sort RR arrays.
193       'rrsort()' is the function that is available to do the sorting. In most
194       cases rrsort will give you the answer that you want but you can specify
195       your own sorting method by using the
196       Net::DNS::RR::FOO->set_rrsort_func() class method. See Net::DNS::RR for
197       details.
198
199       rrsort()
200
201          use Net::DNS qw(rrsort);
202
203          my @prioritysorted=rrsort("SRV","priority",@rr_array);
204
205       rrsort() selects all RRs from the input array that are of the type that
206       are defined in the first argument. Those RRs are sorted based on the
207       attribute that is specified as second argument.
208
209       There are a number of RRs for which the sorting function is specifi‐
210       cally defined for certain attributes.  If such sorting function is
211       defined in the code (it can be set or overwritten using the
212       set_rrsort_func() class method) that function is used.
213
214       For instance:
215          my @prioritysorted=rrsort("SRV","priority",@rr_array); returns the
216       SRV records sorted from lowest to heighest priority and for equal pri‐
217       orities from heighes to lowes weight.
218
219       If the function does not exist then a numerical sort on the attribute
220       value is performed.
221          my @portsorted=rrsort("SRV","port",@rr_array);
222
223       If the attribute does not exist for a certain RR than the RRs are
224       sorted on string comparrisson of the rdata.
225
226       If the attribute is not defined than either the default_sort function
227       will be defined or "Canonical sorting" (as defined by DNSSEC) will be
228       used.
229
230       rrsort() returns a sorted array with only elements of the specified RR
231       type or undef.
232
233       rrsort() returns undef when arguments are incorrect.
234

EXAMPLES

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

BUGS

356       "Net::DNS" is slow.
357
358       For other items to be fixed, please see the TODO file included with the
359       source distribution.
360

COPYRIGHT

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

AUTHOR INFORMATION

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