dnscvsutil
==========

  This package consists of two programs to maintain your DNS zone
files under CVS control, and possibly automatically updating reverse
zones. The main part of this package is called "dns-update", and it is
written by yours truly, Tommi Virtanen <[email protected]>. dns-update can
use mkrdns to create the reverse zones. mkrdns was written by Theo Van
Dinter <[email protected]>, <[email protected]>. The mkrdns homepage
is at http://www.mkrdns.org/

Both dnscvsutil and mkrdns are licensed under the GNU Generic Public
License.

  There are no proper documents currently (help appreciated!), but
here's a quick rundown on the setup:

Directories:
        /var/lib/dnscvsutil/cvs
                - holds the CVS repository that is used to manage 
                  the zone files.
        /var/lib/dnscvsutil/domains
                - holds a central checked out copy of the CVS 
                  repository. Used to generate the actual zone files.
        /var/lib/dnscvsutil/compiled
                - holds the generated zone files.

Files:
        /etc/dns-update.conf
                - configuration file for dns-update.
        /var/lib/dnscvsutil/compiled/named-primary.conf
                - generated named.conf snippet -- include in your
                  /etc/bind/named.conf with a line like this:
include "/var/lib/dnscvsutil/compiled/named-primary.conf";

Groups:
        dnsadmin - the people who should have access to
                   dnscvsutil zones should be added here.

Commands:
        cvs -d /var/lib/dnscvsutil/cvs co domains
        - check out a working directory for you
        dns-update
        - update the DNS information from the CVS


File format
===========

  The files in CVS have simple formatting rules.
The files themselves are just bodies of normal zone files,
with the SOA record replaced with

!template

at the beginning of a line.

  You can add options to !template to change e.g. the email
address of the hostmaster, or various time-related SOA values.

  Entries can span multiple lines by escaping the newlines with
a backslash, like this:

!template \
        [email protected] \
	origin=ns1.example.com \
        minttl=60000

  The default hostmaster is the one set in dns-update.conf, the
default origin is the current host name (you should override this on
a per-domain basis to point to the primary nameserver name for that
domain.

  The final domain name of a single zone file is constructed
like this: reverse the order of directories and join with a period.
Join this with a period to the file name. The file should have the
extension ".domain", which will be stripped off.

  Example: all of the following file names would generate the
domain "clear-blue.cluster.development.example.com".

example.com/development/cluster/clear-blue.domain
example.com/cluster.development/clear-blue.domain
com/example/development/clear-blue.cluster.domain

..so you can choose whatever way pleases you.


Autoupdating reverse zones
==========================

  dns-update can run mkrdns to autoupdate the reverse zones. See
/etc/dns-update.conf on how to configure this. To make mkrdns work,
you just have to create the reverse zone files once (you shouldn't
even need to fill them with data), and ensure the proper users (group
dnsadmin, most probably) can write to the files.


Pre-existing zones
==================

  If you are moving pre-existing zones under dnscvsutil control,
please make sure your SOA serial numbers are not messed up. dnscvsutil 
uses serial numbers of the form YYYYMMDDnn, where nn is 01..99.


Restrictions
============

  dns-update cannot handle more than 99 updates per day. If you do
more than that, switch to run it from crontab every 24/99 hours ;)
(It won't update the zones unless it really is necessary).


Final words
===========

  Comments, source, patches, docs, pointers to similar utils, etc.
are welcome. Please tell me what you think of this program.

                                         Tommi Virtanen, <[email protected]>