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. Bugs 10. Copyright 11. Author Information 12. 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's planned for future versions, see the TODO file. Net::DNS does not depend on any C libraries. However, if possible Net::DNS tries to link to the libresolv library. This provides a notable speed increase. The author invites feedback on Net::DNS. If there's something you'd like to have added, please let me know. If you find a bug, please send me the information described in the BUGS section below. 2. AVAILABILITY --------------- You can get the latest version of Net::DNS from the Comprehensive Perl Archive Network (CPAN) or from the module's homepage: http://www.perl.org/CPAN/modules/by-module/Net/ http://www.net-dns.org/ The following link will always be the current released version: http://www.net-dns.org/download/Net-DNS-release.tar.gz Additionally, nightly cvs snapshots of the current developement version are at: http://www.net-dns.org/snaps/ Please note that the CVS version at any given moment may be broken. 3. PREREQUISITES ---------------- Net::DNS has been tested with the following: Perl 5.8.2 Version of Socket distributed with Perl 5.8.2 Version of IO::Socket distributed with Perl 5.8.2 Version of IO::Select distributed with Perl 5.8.2 Version of FileHandle distributed with Perl 5.8.2 Perl 5.6.1 Version of Socket distributed with Perl 5.6.1 Version of IO::Socket distributed with Perl 5.6.1 Version of IO::Select distributed with Perl 5.6.1 Version of FileHandle distributed with Perl 5.6.1 You can obtain the latest version of Perl from: http://www.cpan.org/src/ 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 don't, Net::DNS won't work. When you run "perl Makefile.PL", Perl should complain if any of the required modules are missing. To build this module, run the following commands: perl Makefile.PL make make test make install Net::DNS can optionally link to the libresolv library. This speeds up parts of the packet parsing process. The Makefile.PL script will attempt to determine if the library can be used. To override Makefile.PL's guess, use the '--xs' option to force linking the library: perl Makefile.PL --xs Use the '--no-xs' option to use the pure perl version: perl Makefile.PL --no-xs If you wish to not run the online tests, the '--no-online-tests' option can be used. Similarly, '--online-tests' will enable the online 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. Please note that there are some bugs in the BIND 8.1-REL nameserver that can cause it to dump core when receiving certain dynamic updates, so if you have problems using Net::DNS that might be the cause. If you're running BIND 9, you should be using the latest version available from the Internet Software Consortium (ISC, www.isc.org) or from your OS vendor. As of this writing, the latest production version of BIND 9 available from the ISC is 9.2.3. Here's 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 --------------------------- As of version 0.15, Net::DNS supports the TSIG resource record to perform signed queries and updates (see 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. BUGS ------- Net::DNS, while nearly four years old, is still under development and is sure to contain a few bugs. Please see the TODO and Changes files for more information. I 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 author accepts no blame if you corrupt your zone. That warning in place, I am aware of at least one large company that has used Net::DNS to make thousands of dynamic updates per day for nearly three years without any problems. If you find a bug, please report it to the author along with the following information: * 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're making, if the data is available to Internet nameservers If I don't have access to a system similar to yours, I may ask you to insert some debugging lines and report back on the results. The more help and information you can provide, the better. The hope is to do all of Net::DNS's bug tracking using rt.cpan.org. Please use the following form to submit bug reports: https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-DNS 10. COPYRIGHT ------------- Copyright (c) 1997-2002 Michael Fuhr. Portions Copyright (c) 2002-2003 Chris Reinhardt. All rights reserved. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. 11. AUTHOR INFORMATION ---------------------- Net::DNS is currently maintained by a group, led by: Chris Reinhardt ctriv@net-dns.org Net::DNS was created by: Michael Fuhr mike@fuhr.org If you have any questions about Net::DNS or wish to help in development, please join the Net::DNS mailing list by sending an email to devel-request@lists.net-dns.org with "subscribe" in the subject. 12. ACKNOWLEDGMENTS ------------------- Thanks to Mike for letting me take care of his baby. Thanks to Olaf Kolkman and Rob Brown 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 and TODO files; 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 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. Thanks to the thousands who participate in the open-source community. I've always developed Net::DNS using open-source systems and I'm proud to make Net::DNS freely available to the world. ---- $Id: README,v 2.101 2003/12/13 10:37:47 ctriv Exp $