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. Author Information
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'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 against a C-module (library) that is supplied 
with the code.  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.

See http://www.net-dns.org/blog/ for announcments 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:

    http://search.cpan.org/dist/Net-DNS/

or through

    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 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.

     Test::More       
     IO::Socket      
     MIME::Base64     
     Digest::MD5  
     Digest::HMAC_MD5


For IPv6 support you will need Socket6 and IO::Socket::INET6.  The availability
of these is tested at runtime.


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.


Net::DNS is mostly developed on MacOS X.  I have access to Linux,
FreeBSD and if need be to cygwin.


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 with a included C module.  This speeds
up parts of the packet parsing process.  The Makefile.PL script will
attempt to determine if the C module can be used.  To override 
Makefile.PL's guess, use the '--xs' option to force linking the library:

	perl Makefile.PL --xs
	
Use the '--noxs' option to use the pure perl version:

	perl Makefile.PL --noxs


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.  Online tests will be run by default, but the result
will not negatively affect the outcome of test suite.

Also, if you wish to not 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.

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.3.1 (with 9.3.2 at the
horizon).

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. DNSSEC
---------

The extensions to make Net::DNS DNSSEC-aware are distributed separately
as Net::DNS::SEC.  The package is available from CPAN.  Because of its
dependency on Crypt::OpenSSL and other not-so-standard libraries, it
is distributed as a separate package. 


10. BUGS
--------

Net::DNS, while over fourteen 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.

Please use the following form to submit bug reports:

     https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-DNS

If you find a bug, please report it in "rt.cpan.org" 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.


11. COPYRIGHT
-------------

Copyright (c) 1997-2002 Michael Fuhr. 

Portions Copyright (c) 2002-2004 Chris Reinhardt.

Portions Copyright (c) 2005 Olaf Kolkman (RIPE NCC)

Portions Copyright (c) 2005 Olaf Kolkman (NLnet Labs)

All rights reserved.  This program is free software; you may redistribute
it and/or modify it under the same terms as Perl itself.


12. AUTHOR INFORMATION
----------------------

Net::DNS is currently maintained at NLnet Labs (www.nlnetlabs.nl) by:
        Olaf Kolkman and his team.
	olaf at net-dns.org

Between 2002 and 2004 Net::DNS was maintained by:
       Chris Reinhardt


Net::DNS was created by:
	Michael Fuhr
	mike at fuhr.org 


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 maintaing Net::DNS for a couple of 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
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 [OK: that's
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've always developed Net::DNS using open-source systems and I'm
proud to make Net::DNS freely available to the world.

----
$Id: README 935 2011-10-27 12:41:31Z willem $