-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
334 lines (229 loc) · 10.6 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
Net::DNS - Perl DNS Resolver Module
===================================
TABLE OF CONTENTS
-----------------
1. Description
2. Availability
3. Prerequisites
4. Installation
5. Running Tests
6. Demonstration Scripts
7. Dynamic Updates
8. Signed Queries & Updates
9. DNSSEC
10. Bugs
11. Copyright
12. License
13. Staying Tuned
14. Acknowledgments
1. DESCRIPTION
-----------
Net::DNS is a DNS resolver implemented in Perl. It allows the programmer
to perform nearly any type of DNS query from a Perl script. For details
and examples, please read the Net::DNS manual page.
To read about the latest features, see the Changes file. To find out about
known bugs and to see what is planned for future versions, see the CPAN RT
ticket list.
The author invites feedback on Net::DNS. If there is something you would
like to have added, please let me know. If you find a bug, please send me
the information described in the BUGS section below.
See http://www.net-dns.org/blog/ for announcements about Net::DNS.
2. AVAILABILITY
------------
You can get the latest version of Net::DNS from the Comprehensive Perl
Archive Network (CPAN) or from the module's homepage:
https://metacpan.org/release/Net-DNS
or through
http://www.net-dns.org/
Additionally a subversion repository is made available through
http://www.net-dns.org/svn/net-dns/
The version on the "trunk" (http://www.net-dns.org/svn/net-dns/trunk) is
the version that is targeted for next release.
Please note that the SVN version at any given moment may be broken.
3. PREREQUISITES
-------------
The availability of prerequisites for Net::DNS is tested at installation
time. These are the core packages that need to be available:
Digest::HMAC
Digest::MD5
Digest::SHA
File::Spec
IO::Socket
IO::Socket::IP
MIME::Base64
Time::Local
Test::More
The availability of these optional packages is tested at runtime:
Digest::BubbleBabble
Net::DNS::SEC
Net::LibIDN2
You can obtain the latest version of Perl from:
http://www.cpan.org
Some of the demonstration and contributed scripts may require additional
modules -- see demo/README and contrib/README for details.
Note that the Test::More module is actually part of the Test-Simple
distribution. See the FAQ (lib/Net/DNS/FAQ.pod) for more information.
4. INSTALLATION
------------
Please install any modules mentioned in the PREREQUISITES section above.
If you do not, some features of Net::DNS will not work. When you run "perl
Makefile.PL", Perl should complain if any of the required modules is
missing.
To build this module, run the following commands:
tar xvzf Net-DNS-?.??.tar.gz
cd Net-DNS-?.??
perl Makefile.PL
make
make test
make install
If you do not wish to run the online tests, the '--no-online-tests' option
can be used. Similarly, '--online-tests' will enable the online tests.
Online tests will be run by default, but the result will not adversely
affect the outcome of test suite.
Also, if you do not wish to run the IPv6 tests, the '--no-IPv6-tests'
option can be used. Similarly, '--IPv6-tests' will enable the IPv6 tests.
5. RUNNING TESTS
-------------
If any of the tests fail, please contact the author with the output from
the following command:
make test TEST_VERBOSE=1
6. DEMONSTRATION SCRIPTS
---------------------
There are a few demonstration scripts in the demo/ directory -- see
demo/README for more information. Contributed scripts are in the contrib/
directory -- see contrib/README.
The author would be happy to include any contributed scripts in future
versions of this module. All I ask is that they be documented (preferably
using POD) and that the contributor's name and contact information be
mentioned somewhere.
7. DYNAMIC UPDATES
---------------
Net::DNS supports DNS dynamic updates as documented in RFC 2136; for more
information and examples, please see the Net::DNS::Update manual page.
Here is a summary of the update semantics for those interested (see RFC
2136 for details):
PREREQUISITE SECTION
# RRs NAME TTL CLASS TYPE RDLENGTH RDATA
----- ---- --- ----- ---- -------- -----
yxrrset 1 name 0 ANY type 0 empty
yxrrset 1+ name 0 class type rdlength rdata
nxrrset 1 name 0 NONE type 0 empty
yxdomain 1 name 0 ANY ANY 0 empty
nxdomain 1 name 0 NONE ANY 0 empty
UPDATE SECTION
# RRs NAME TTL CLASS TYPE RDLENGTH RDATA
----- ---- --- ----- ---- -------- -----
add RRs 1+ name ttl class type rdlength rdata
del RRset 1 name 0 ANY type 0 empty
del all RRsets 1 name 0 ANY ANY 0 empty
del RRs 1+ name 0 NONE type rdlength rdata
8. SIGNED QUERIES & UPDATES
------------------------
Net::DNS supports the TSIG resource record to perform signed queries and
updates (RFC 2845). See the Net::DNS::Packet and Net::DNS::Update manual
pages for examples.
If you're using the BIND nameserver, the BIND FAQ shows how to generate
keys and configure the nameserver to use them:
http://www.nominum.com/resources/faqs/bind-faq.html
TSIG support is new and isn't yet complete. Please use with caution on
production systems. Feedback on TSIG functionality would be most welcome.
9. DNSSEC
------
The extensions to enable the DNSSEC signature generation and verification
functions are distributed separately as Net::DNS::SEC. The package is
available from CPAN.
10. BUGS
----
Net::DNS, although begun in 1997, is still under development and may still
contain a few bugs. Please see CPAN RT and Changes file for more
information.
We recommend that you exercise caution when using Net::DNS to maintain a
production nameserver via dynamic updates. Always test your code
*thoroughly*. The Net::DNS authors accept no blame if you corrupt your
zone. That warning in place, We are aware of one large company that has
used Net::DNS to make thousands of dynamic updates per day for at least
three years without any problems.
Please use the following form to submit bug reports:
https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-DNS
If you find any bugs, please report each in a separate "rt.cpan.org"
report along with the following information:
* subject field containing a concise descriptive summary
* version of Perl (output of 'perl -V' is best)
* version of Net::DNS
* operating system type and version
* version of nameserver (if known)
* exact text of error message or description of problem
* the shortest possible program that exhibits the problem
* the specific queries you are making, if the fault can be
demonstrated using Internet nameservers
If we do not have access to a system similar to yours, you may be asked
to insert some debugging lines and report back on the results. The more
focussed the help and information you provide, the better.
Net::DNS is currently maintained at NLnet Labs (www.nlnetlabs.nl) by:
Willem Toorop.
Between 2005 and 2012 Net::DNS was maintained by:
Olaf Kolkman and his team.
Between 2002 and 2004 Net::DNS was maintained by Chris Reinhardt.
Net::DNS was created in 1997 by Michael Fuhr.
11. COPYRIGHT
---------
Authorship of individual components and significant contributions is shown
in the copyright notice attached to the relevant documentation. Copyright
in all components is retained by their respective authors.
12. LICENSE
-------
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the original copyright notices appear in all copies and that both
copyright notice and this permission notice appear in supporting
documentation, and that the name of the author not be used in advertising
or publicity pertaining to distribution of the software without specific
prior written permission.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
13. STAYING TUNED
-------------
http://www.net-dns.org is a web site dedicated to the development of
Net::DNS. Announcements about Net::DNS and Net::DNS::SEC will be done
through the Net::DNS weblog at http://www.net-dns.org/blog/. An RSS feed
for the weblog is available.
If you want to have access to the latest and greatest code a subversion
repository is made available through
http://www.net-dns.org/svn/net-dns/
The version on the "trunk" (http://www.net-dns.org/svn/net-dns/trunk) is
the version that is targeted for next release.
Please note that code from the SVN repositories trunk and development
branches may be broken at any time.
14. ACKNOWLEDGMENTS
---------------
Thanks to Mike for letting me take care of his baby.
Thanks to Chris for maintaining Net::DNS for a couple of years.
Thanks to Olaf for maintaining Net::DNS for over eight years.
Thanks to Rob Brown and Dick Franks for all their patches and input.
Thanks to all who have used Net::DNS and reported bugs, made suggestions,
contributed code, and encouraged me to add certain features. Many of these
people are mentioned by name in the Changes file; lack of mention should
be considered an oversight and not a conscious act of omission.
Thanks to Larry Wall and all who have made Perl possible.
Thanks to Paul Albitz and Cricket Liu for allowing me [OK: that is Mike]
to write the Net::DNS section in the programming chapter of DNS and BIND,
3rd Edition. This chapter in earlier editions was very helpful while I
was developing Net::DNS, and I was proud to contribute to it.
Thanks to Paul Vixie and all who have worked on the BIND nameserver, which
I've used exclusively while developing Net::DNS.
Thanks to Andreas Gustafsson for DNAME support, and for all the work he
has done on BIND 9.
Olaf acknowledges the RIPE NCC for allowing Net::DNS maintenance to take
place as part of 'the job'.
Thanks to the team that maintains wireshark. Without its marvelous
interface, debugging of bugs in wireformat would be so much more
difficult.
Thanks to the thousands who participate in the open-source community. I
have always developed Net::DNS using open-source systems and I am proud
to make Net::DNS freely available to the world.
---- $Id$