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:

	http://search.cpan.org/dist/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      

	MIME::Base64     

	Time::Local

	Test::More       

The availability of these optional packages is tested at runtime:

	Digest::BubbleBabble

	Digest::GOST

	IO::Socket::INET6

	IO::Socket::IP

	Net::DNS::SEC

	Net::LibIDN

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 above copyright notice appear in all copies and that both that

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: README 1550 2017-03-08 13:14:14Z willem $