README
1Net::DNS - Perl DNS Resolver Module
2===================================
3
4
5TABLE OF CONTENTS
6-----------------
7
81. Description
92. Availability
103. Prerequisites
114. Installation
125. Running Tests
136. Demonstration Scripts
147. Dynamic Updates
158. Signed Queries & Updates
169. DNSSEC
1710. Bugs
1811. Copyright
1912. Author Information
2013. Staying Tuned
2114. Acknowledgments
22
23
241. DESCRIPTION
25--------------
26
27Net::DNS is a DNS resolver implemented in Perl. It allows the
28programmer to perform nearly any type of DNS query from a Perl
29script. For details and examples, please read the Net::DNS manual
30page.
31
32To read about the latest features, see the Changes file. To find
33out about known bugs and to see what's planned for future versions,
34see the TODO file.
35
36Net::DNS does not depend on any C libraries. However, if possible
37Net::DNS tries to link against a C-library that is supplied with the
38code. This provides a notable speed increase.
39
40The author invites feedback on Net::DNS. If there's something you'd
41like to have added, please let me know. If you find a bug, please
42send me the information described in the BUGS section below.
43
44See http://www.net-dns.org/blog/ for announcments about Net::DNS
45
46
472. AVAILABILITY
48---------------
49
50You can get the latest version of Net::DNS from the Comprehensive
51Perl Archive Network (CPAN) or from the module's homepage:
52
53 http://search.cpan.org/dist/Net-DNS/
54or through
55 http://www.net-dns.org/
56
57The following link will always be the current released version:
58
59 http://www.net-dns.org/download/Net-DNS-release.tar.gz
60
61
62Additionally a subversion repository is made available through
63 http://www.net-dns.org/svn/net-dns/
64
65
66The version on the "trunk" (http://www.net-dns.org/svn/net-dns/trunk) is
67the version that is targeted for next release.
68
69Please note that the SVN version at any given moment may be broken.
70
71
723. PREREQUISITES
73----------------
74
75
76The availability of prerequisites for Net::DNS is tested at
77installation time. These are the core packages that need to be
78available.
79
80 Test::More
81 IO::Socket
82 MIME::Base64
83 Digest::MD5
84 Digest::HMAC_MD5
85 Net::IP
86
87
88For IPv6 support you will need Socket6 and IO::Socket::INET6. The availability
89of these is tested at runtime.
90
91
92You can obtain the latest version of Perl from:
93
94 http://www.cpan.org/src/
95
96Some of the demonstration and contributed scripts may require
97additional modules -- see demo/README and contrib/README for details.
98
99Note that the Test::More module is actually part of the Test-Simple
100distribution. See the FAQ (lib/Net/DNS/FAQ.pod) for more information.
101
102
103Net::DNS is mostly developed on MacOS X. I have access to Linux,
104FreeBSD and if need be to cygwin.
105
106
1074. INSTALLATION
108---------------
109
110Please install any modules mentioned in the PREREQUISITES section
111above. If you don't, Net::DNS won't work. When you run "perl
112Makefile.PL", Perl should complain if any of the required modules
113are missing.
114
115To build this module, run the following commands:
116
117 perl Makefile.PL
118 make
119 make test
120 make install
121
122Net::DNS can optionally link to the libresolv library. This speeds
123up parts of the packet parsing process. The Makefile.PL script will
124attempt to determine if the library can be used. To override
125Makefile.PL's guess, use the '--xs' option to force linking the library:
126
127 perl Makefile.PL --xs
128
129Use the '--noxs' option to use the pure perl version:
130
131 perl Makefile.PL --noxs
132
133
134If you wish to not run the online tests, the '--no-online-tests'
135option can be used. Similarly, '--online-tests' will enable the
136online tests.
137
138
1395. RUNNING TESTS
140----------------
141
142If any of the tests fail, please contact the author with the output
143from the following command:
144
145 make test TEST_VERBOSE=1
146
147
1486. DEMONSTRATION SCRIPTS
149------------------------
150
151There are a few demonstration scripts in the demo/ directory -- see
152demo/README for more information. Contributed scripts are in the
153contrib/ directory -- see contrib/README.
154
155The author would be happy to include any contributed scripts in
156future versions of this module. All I ask is that they be documented
157(preferably using POD) and that the contributor's name and contact
158information be mentioned somewhere.
159
160
1617. DYNAMIC UPDATES
162------------------
163
164Net::DNS supports DNS dynamic updates as documented in RFC 2136;
165for more information and examples, please see the Net::DNS::Update
166manual page.
167
168Please note that there are some bugs in the BIND 8.1-REL nameserver
169that can cause it to dump core when receiving certain dynamic updates,
170so if you have problems using Net::DNS that might be the cause. If
171you're running BIND 9, you should be using the latest version
172available from the Internet Software Consortium (ISC, www.isc.org) or
173from your OS vendor. As of this writing, the latest production
174version of BIND 9 available from the ISC is 9.3.1. (with 9.3.2 at the
175horizon)
176
177Here's a summary of the update semantics for those interested (see
178RFC 2136 for details):
179
180 PREREQUISITE SECTION
181 # RRs NAME TTL CLASS TYPE RDLENGTH RDATA
182 ----- ---- --- ----- ---- -------- -----
183 yxrrset 1 name 0 ANY type 0 empty
184 yxrrset 1+ name 0 class type rdlength rdata
185 nxrrset 1 name 0 NONE type 0 empty
186 yxdomain 1 name 0 ANY ANY 0 empty
187 nxdomain 1 name 0 NONE ANY 0 empty
188
189
190 UPDATE SECTION
191 # RRs NAME TTL CLASS TYPE RDLENGTH RDATA
192 ----- ---- --- ----- ---- -------- -----
193 add RRs 1+ name ttl class type rdlength rdata
194 del RRset 1 name 0 ANY type 0 empty
195 del all RRsets 1 name 0 ANY ANY 0 empty
196 del RRs 1+ name 0 NONE type rdlength rdata
197
198
1998. SIGNED QUERIES & UPDATES
200---------------------------
201
202As of version 0.15, Net::DNS supports the TSIG resource record to
203perform signed queries and updates (see RFC 2845). See the
204Net::DNS::Packet and Net::DNS::Update manual pages for examples.
205
206If you're using the BIND nameserver, the BIND FAQ shows how to
207generate keys and configure the nameserver to use them:
208
209http://www.nominum.com/resources/faqs/bind-faq.html
210
211TSIG support is new and isn't yet complete. Please use with caution
212on production systems. Feedback on TSIG functionality would be most
213welcome.
214
215
2169. DNSSEC
217---------
218
219The extensions to make Net::DNS DNSSEC aware are distributed seperatly
220as Net::DNS::SEC. The package is available from CPAN. Because of its
221dependency on Crypt::OpenSSL and other not so standard libraries, it
222is distributed as a seperate package.
223
224
22510. BUGS
226--------
227
228Net::DNS, while over four years old, is still under development and is
229sure to contain a few bugs. Please see the TODO and Changes files for
230more information.
231
232I recommend that you exercise caution when using Net::DNS to maintain a
233production nameserver via dynamic updates. Always test your code
234*thoroughly*. The Net::DNS author accepts no blame if you corrupt your
235zone. That warning in place, I am aware of at least one large company
236that has used Net::DNS to make thousands of dynamic updates per day for
237nearly three years without any problems.
238
239Please use the following form to submit bug reports:
240
241 https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-DNS
242
243If you find a bug, please report it in "rt.cpan.org" along with the
244following information:
245
246 * version of Perl (output of 'perl -V' is best)
247 * version of Net::DNS
248 * operating system type and version
249 * version of nameserver (if known)
250 * exact text of error message or description of problem
251 * the shortest possible program that exhibits the problem
252 * the specific queries you're making, if the data is available
253 to Internet nameservers
254
255If I don't have access to a system similar to yours, I may ask you
256to insert some debugging lines and report back on the results.
257The more help and information you can provide, the better.
258
259
26011. COPYRIGHT
261-------------
262
263Copyright (c) 1997-2002 Michael Fuhr.
264
265Portions Copyright (c) 2002-2004 Chris Reinhardt.
266
267Portions Copyright (c) 2005 Olaf Kolkman (RIPE NCC)
268
269Portions Copyright (c) 2005 Olaf Kolkman (NLnet Labs)
270
271All rights reserved. This program is free software; you may redistribute
272it and/or modify it under the same terms as Perl itself.
273
274
27512. AUTHOR INFORMATION
276----------------------
277
278Net::DNS is currently maintained at NLnet Labs (www.nlnetlabs.nl) by:
279 Olaf Kolkman and his team.
280 olaf at net-dns.org
281
282Between 2002 and 2004 Net::DNS was maintained by:
283 Chris Reinhardt
284
285
286Net::DNS was created by:
287 Michael Fuhr
288 mike at fuhr.org
289
290
29113. STAYING TUNED
292--------------------
293
294http://www.net-dns.org is a web site dedicated to the development of
295Net::DNS. Announcements about Net::DNS and Net::DNS::SEC will be done
296through the Net::DNS weblog at http://www.net-dns.org/blog/. An RSS
297feed for the weblog is available.
298
299If you want to have access to the latest and greatest code a
300subversion repository is made available through
301
302 http://www.net-dns.org/svn/net-dns/
303
304The version on the "trunk" (http://www.net-dns.org/svn/net-dns/trunk) is
305the version that is targeted for next release.
306
307Please note that code from the SVN repositories trunk and development
308branches may be broken at any time.
309
310
31113. ACKNOWLEDGMENTS
312-------------------
313
314
315Thanks to Mike for letting me take care of his baby.
316
317Thanks to Chris for maintaing Net::DNS for a couple of years.
318
319Thanks to Rob Brown and Dick Franks for all their patches and input.
320
321Thanks to all who have used Net::DNS and reported bugs, made
322suggestions, contributed code, and encouraged me to add certain
323features. Many of these people are mentioned by name in the Changes
324and TODO files; lack of mention should be considered an oversight
325and not a conscious act of omission.
326
327Thanks to Larry Wall and all who have made Perl possible.
328
329Thanks to Paul Albitz and Cricket Liu for allowing me [OK: that's
330Mike] to write the Net::DNS section in the programming chapter of _DNS
331and BIND_, 3rd Edition. This chapter in earlier editions was very
332helpful while I was developing Net::DNS, and I was proud to contribute
333to it.
334
335Thanks to Paul Vixie and all who have worked on the BIND nameserver,
336which I've used exclusively while developing Net::DNS.
337
338Thanks to Andreas Gustafsson for DNAME support, and for all the work
339he has done on BIND 9.
340
341Olaf acknowledges the RIPE NCC for allowing Net::DNS maintenance to
342take place as part of 'the job'.
343
344Thanks to the team that maintains wireshark, without its marvelous
345interface debuging of bugs in wireformat would be so much more
346difficult.
347
348Thanks to the thousands who participate in the open-source community.
349I've always developed Net::DNS using open-source systems and I'm
350proud to make Net::DNS freely available to the world
351
352----
353$Id: README 654 2007-06-20 15:02:50Z olaf $
354