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$