README file for the University of Utah DNS Tools.

Author: Kirk Eide <Kirk.Eide@cc.utah.edu>
		  http://www.utah.edu/~keide/Kirk_Eide.html
Version: 1.3
Date: 5/28/96

Special thanks to: LeRoy N. Eide, Robert Roll, and Dylan Pocock

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

WARNING: I and the University of Utah make no warranties that this software
is bug free or even does anything at all.  Use at your own risk.  Really...

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

What you'll need to know to use this set of tools:

 - You'll need some knowledge of Perl (5.0 or higher)
 - You'll need perl installed and working with all of it's std libs.
 - You'll need knowlede of DNS and BIND (these tools are to help
   maintain data which you understand.  The will still allow you to do
   bad things to your data...)
 - You'll need to be familiar with some http server that has CGI hooks
   (if you want to use the WWW interface)

If you fail any of these tests, please throw this package away now...

Unfortunately, I do not really have time to support this software as much as
I would like to.  But, I am always happy to recieve bug reports and user
modifications via email.  Bugs should get fixed pretty quickly, features
come slower.

--------------------

What is all this?

These tools were developed for my own personal use and sanity at the University
of Utah Computer Center.  When I took on the job of doing DNS management at the
Computer Center, I found the organization (or lack there of) of the DNS files
to be a great time sink.  It took me for ever to locate the data I was
looking for.  Then I had to check the file out (RCS), make the changes, then
check it back in.  Of course I fogot to bump the serial number, so I would
have to check the file out again, bump the serial number, and then back in.
God forbid that I had to edit the named.boot file...

What I wanted was an easy way to manage the data (possibly even ways to verify
the data).  Finally one day while I was looking for insparation (OK I was down
the hall in the restroom), I had an idea which turned into these tools.  The
next day at work I grabbed all the people who would be affected by what I was
about to do and described the idea to them.  From that came the real
structure of that which now exists.  Cool.

-------------------------

How does this help me?

What these tools do is replicate DNS space using the file system of the
machine you run them on.  Basically, the tools build a directory tree in 
which the data is kept.  For example: data for cc.utah.edu will be kept in
a directory called ./edu/utah/cc in a file called .primary.  This seems simple
minded, but has proven to be quite effective (for us at least).
Now since all the data is predictably locatable, tools can now be
written to add, edit, or delete the data.  Serial numbers can now
be incremented automatically, named.boot files can now be
build automatically.  I can now forget everything I know about DNS...

-------------------------

What's in the package?

The DNS tools are in the bin directory, WWW wrappers for the tools are
in the web directory, and some sample data is in the dnsroot directory.
The dnsroot directory is where all the DNS data will be stored.

The set of tools is by no way complete.  What is there is enough to do
95% of routine DNS management.

-------------------------

How do I get started?

Edit the file bin/dns_lib.perl.  This file contains all of the configuration
for all of the scripts (except the setup scripts).

You may also need to make /usr/bin/perl exist or edit every script to change
to cookie.

NOTE: The setup scripts are the worst part of these tools.  If you survive
these scripts and get the data transformed, the rest will be easy.  These
scripts really need to be re-visited by me to improve the friendlyness of
them.

Copy your current BIND data files and named.boot to some directory.  Edit
bin/setup_maketree.  You will need to change $named_boot to point at your old
named.boot file, $db_files to point at the directory your old data files are
in, and $tree_root to be the place you want the new data tree to exist.  Also
check for other paths in the scripts which need to be fixed.

run setup_maketree (in bin/util)

Known bugs:

 - Per record TTLs will cause the recored to be invalid.  The fix is to
   edit the pattern match to include the TTL.

What will happen?

setup_maketree will walk your old named.boot file creating the new tree as
it goes.  The data for primary zones will be extracted and placed into
.primary files, all SOA records will be placed into .soa files, and
sources for secondary data (in named.boot) will be placed in .secondary files.
Also, a file called .zoneinfo will be placed in dnsroot.  
This file is a quick listing of all the directories created.  
DON'T trash this file!  It is used to quickly walk the
tree for the building of named.boot files.

run setup_checkin

This RCSes all of the new data files.

Next you need to edit the file dnsroot/.classinfo.  This file is used to seed
a classification of zones.  It allows us to keep all of the DNS data in
one place, but build named.boot files based on classes.  This works well
for secondary name servers.  Example: ns.utah.edu is primary for utah.edu. as
well as k12.ut.us.  It's nice to have the other secondary name servers on 
campus be only secondary for utah.edu. not both.  The classifications allow
us to do this.

run build_class

This will add classifications to your .zoneinfo file.


Optional:  You can also run setup_fixglue.  This will look for glue records.

Optional: I would also recommend RCSing (if that's really a word) .access,
          .classinfo, and .subnets.

----------------------

Now that you've ripped your data to pieces...

Tools for modification of the data (the name will say it all):

  *Most of the scripts take the --help option for help - way cool...

       add_* -- All of these tools will add data to .primary files
     build_* -- Makes something out of some parts.  See the next section.
       new_* -- Creates new zones.  Cool 'eh...
                NOTE: Currently there is no delete_zone tool.  Until
                One is created, zone can be deleted by removing and dot
                files in the directory, or the entire directry.
                Once this is done, .zoneinfo should be updated using
                build_zoneinfo.
    remove_* -- You guessed it... These remove data from .primary's
      show_* -- Allows you to look at your data files - NOT namespace!
                They really can be different...
     subinfo -- Subnet information (should be called show_zone, but
                I had an old util that did the same thing.  Habits die
                hard.)
    verify_* -- Verification of the data in some way.
util/setup_* -- Setup utilities.  Their trash now...
      util/* -- Various undocumented (as if the others were...) utils.

----------------------

OK, so I have data?

Now we'll put it all back together.

Three of the scripts ate going to help you with this:

          build_db -- Builds the database files bind wants to see.
                      WAY COOL: build_db also bumps your serial numbers
                      for you!
  build_named.boot -- Build your named.boot files for all of you machines
       dns_restart -- A utility utility. This scripts the utilites for you!

The restarting on the name servers will have to be crafted by you some what
currently.  I plan to make this easier to configure soon... real soon...

Here's what happens when you run dns_restart:

 - build_db is run which builds only those data files for BIND that it has to.

 - build_named.boot id run if any zones have been added of removed (Actually,
   if $tree_root/.rebuild exists which the tree modification tool touch).

 - The new named.boot files are FTPed to the secondaries if new were built.

 - A file called .reboot is placed in dnsroot.  This file contains a list
   of commands for the secondary name servers to run.

 - Now what happens on my boxes is that a cron job running as root
   notices that .reboot exists.  The cron job the runs named.restart and
   moved the file to .restarted.  Now another cron job running as nsmaint
   (my dns user) sees the .restarted file.  This job FTPs the file to the
   next down stream dns server using restart_downstream.  The crontabs are
   included...

 - The down stream guy does it all again if needed.

The scripts are currently set up for this model:


                                                          ------------------
                                                          |                |
                                                  ----->  | fiber - campus |
----------------          ------------------      |       |                |
|              |          |                |      |       ------------------
| sin - master |  ---->   | ns - all zones | -----|
|              |          |                |      |       ------------------
----------------          ------------------      |       |                |
                                                  ----->  |  hal - campus  |
                                                          |                |
                                                          ------------------

sin is the 'master' DNS server.  It hold the real DB files and the DNS tree.
It also runs the http server for WWW access.  All the data editing is done
here.  ns gets all it data from sin at startup. ns also acts as secondary
for everything sin knows about.  fiber and hal get all ther info from ns.
fiber and hal only deal with zones that are classified as 'campus' zones
in the .classinfo file.

----------------

How to do I set up the WWW Stuff?

First, setup some httpd on the machine that have access to the dns_tools and
data files.  It can be the same machine, or a different machine with the tools
and data NFS mounted.

Copy the the contents of web/web_root to your document root for your server.
Copy the cgi_lib stuff to some appropriate dir which the web user can access.

Next activte cgi as a file type for your server for the Scripts directory.

Now figure out which paths are broken and fix em.

You most likely want to edit .index.html to your needs.

---------------


Kirk.

