
			      DOMTOOLS README FILE
		       HIGH-LEVEL NAME SERVER QUERY TOOLS
				  Version 1.5.0
				   01/02/2000
		    Copyright (c) 1993-2000 by Paul A. Balyoz


The commands in this directory allow you to traverse DNS domain hierarchies,
list all hosts (or subdomains) within a given domain, convert host name to
IP address and vice-versa, convert a normal IP address to the "in-addr.arpa."
format and vice-versa, and more.   These commands can be used manually, or
included as building blocks for higher level DNS tools.  They generate output
that is easily computer parsable.

The goals of this package are:

	1. To provide some high-level tools that do things which most DNS
	   administrators will find valuable such as: sorting by domain names,
	   sorting by IP addresses, generating an /etc/hosts, /etc/networks,
	   or /etc/netmasks files from the DNS database of an entire zone,
	   generating network node lists for network mapping utilities,
	   comparing SOA RRs from each authoritative nameserver for a zone.

	2. To make it easier for people to query Internet domain name servers
	   using single, easy-to-use commands.

	3. To provide computer-parsable output from all commands so that
	   higher level tools are easy to develop.


REQUIREMENTS

	* BIND 4.8.3 or newer (available at http://www.isc.org/bind.html )
	* DiG 2.0 or newer (distributed with BIND package)
	* Perl 5 (available on Internet)
	* Gnu Awk (available on Internet)
	* Any form of awk named "awk"
	* Bourne Shell or equivalent (i.e. sh or bash)

    Also, some of the domain tools in this package require certain special
    resource-records in your DNS database as described in sections 1-4 of
    the RFC1101 document available on the Internet.  Most of the tools will
    still work without those records, but some won't (like networktbl and
    netmasktbl).


DOCUMENTATION

    See the file HOWTOUSE for examples of things you can do with this package.
    See the file MANUAL for complete details on all the tools in this package.
	Sorry, no man-pages yet; everything you need to know is in MANUAL.
    See the file CHANGES for improvements since previous releases.
    See the file WHY for questions and answers.
    See the file BUGS for known bugs and problems.
    See the file TODO for future enhancement plans.

    You can get RFC1101 (and other RFC documents) at:
        ftp://ftp.uu.net/inet/rfc/rfc1101
        ftp://ftp.internic.net/rfc/rfc1101.txt


INSTALLATION

	1. Make sure you already have all the required stuff, see the
	   REQUIREMENTS section, above!  This is important!!
	2. Edit the Makefile and adjust the paths and stuff at the top.
	   Confused by something?  See the section CONFIGURING THE
	   MAKEFILE, below.
	3. Edit the files *.header and *.footer for your site.  You can
	   use the macros TIMEDATE, USER and HOST wherever you want in
	   these files, they will expand to the current time and date,
	   the user's name, and the host they're run on, respectively,
	   when the hosttbl, networktbl, and netmasktbl tools are run.
	4. Type "make -n install" to see what a "make install" would do.
	5. If it looks right, type "make install" to install all the tools
	   and support files.

    If/when you upgrade to BIND 8.x from BIND 4.x, you will also need to
    clear the zone cache (see Makefile for exact location):

		rm /usr/local/lib/domtools/zonecache/*

    Otherwise the axfr command will generate bogus output for any zone
    that it uses from the cache.

    You must install these tools as shown above to use them -- you cannot
    simply run them out of this directory.  Certain macro replacement strings
    are converted to directory paths by the Makefile during installation.
    If you encounter file-not-found errors with words like "DOMBIN", "DOMLIB"
    or "ZONEDIR", you haven't properly installed this package.


CONFIGURING THE MAKEFILE

  Pretty standard Internet style configurations for bin directories, etc.
  There are some things that may confuse you, however:

     PDEST, LDEST
	Physical destination tree vs. Logical destination tree.
	In other words, where do you _really_ install stuff vs. where users
	normally access the files at.  This is useful for AFS installations,
	where users and scripts commonly access a read-only path when running
	programs (LDEST), but the sysadmin has to install the tools using a
	different, writable directory path (PDEST).  If you're confused by
	this, just set them to the same thing, which should be the main tree,
	such as "/usr/local" if you want tools installed in /usr/local/bin,
	supporting files to go in /usr/local/lib, etc.

     NETWORKSDOM
	Domtools has a neat feature -- when you use the networktbl and netmasktbl
	programs to build /etc/networks and /etc/netmasks style files directly
	from DNS data, they can also generate comments in English above each
	network entry, if you have a special branch of your DNS hierarchy that
	contains TXT resource-records that describe each network!  Pretty nifty.
	See Makefile for further details.

     ZONEDIR, ZONECACHEWANTED
	The axfr tool downloads entire zone files at a time.
	Axfr responds much more quickly if you cache the data in a directory
	some place on the local system.  It's a neat idea, but has some
	drawbacks, including (currently) a world-writable directory and the
	fact that no files are ever pruned out of that directory by Domtools.
	If you can live with that, enable ZONECACHEWANTED and specify what
	directory should be created world-writable (ZONEDIR).


TRYING IT OUT

  Read the HOWTOUSE file for examples.  Try them out.  Say the phrase "wow"
  or "interesting" at least once per tool.

  For details on each domain tool, check out the large MANUAL file.  If any
  fail, try other tools at a lower "level" in the MANUAL first.  Higher level
  tools call the lower level ones to get their job done.

  If you want to enable or disable the axfr tool's zone caching feature
  after installation, edit "axfr" in your installed bin directory and
  adjust ZONECACHEEXISTS (see comments there).


BUGS AND PORTING

  This software has been installed and tested in the following configurations:

	Pentium running RedHat Linux 5.0 (kernel 2.0.33)
        Pentium running BSDI 2.0.1
	RS/6000 AIX 3.2.5
        SPARCstations running Solaris 2.5, Sun's BIND
        SPARCstations running Solaris 2.3, BIND 4.9.2
        SPARCstations running Solaris 2.3, Sun's BIND
        SPARCstations running SunOS 4.1.2, BIND 4.8.3
        SPARCstations running SunOS 4.1.1B, BIND 4.8.3
        DEC Alpha running OSF/1 3.2
        NCR X86 running NCR SysV Unix

  If you encounter problems or fix bugs, please let me know!  Also, if you
  port this package to a new platform, let me know what it took.  You should
  send me a general description in English of what you've done, and include
  patches (diff -c oldfile newfile) so that I can include your changes in
  future distributions.

  This software was designed and implemented in my spare time
  (guess that makes it "spareware". :-)


DISTRIBUTION

    The latest version of Domtools can be found at the master site:

	      http://www.domtools.com/dns/domtools.shtml

    Other DNS tools you might be interested in:

	      http://www.domtools.com/dns/

    Free DNS zone "linting" program available on the web:

	      http://www.domtools.com/dlint/


THOUGHT FOR THE DAY

    Why type commands that operate way-down-there,
	When you're thinking on a level way-up-here?


COPYRIGHT NOTICE

  This Domtools software package is Copyright (c) 1993 by Paul A. Balyoz,
  all rights reserved.  You are hereby given permission to use this version
  of this package and to make copies of it, so long as you do not sell it
  or claim that you wrote it.  All copyright messages must be retained as-is.

  For commercial use of this product, contact the author, below.

--
Paul Balyoz,  Unix Sysadmin and Programmer
Domtools Consulting                           pab@domtools.com
Phoenix Arizona, USA                          pbalyoz@jammed.com
