INSTALL

We install critical systems like nameservers using our configs tool. You will have downloaded an archive which is inteneded to be unpack in a directory structure used by configs (you can obtain the lastest version of the tool here, it is a cpio(1) archive to make it easier to not overwrite new files with old).

We will assume below that your configs tree lives in /configs and that you have downloaded the archives to your home directory and further, that you are using a shell that understands Bourne shell syntax (ie. not *csh). Also note that in the examples below '$' indicates a command issued by a non-root user while '#' indicates the super user.

Unpacking

$ cd /configs
$ gzcat $HOME/config-sh.cpio.gz | cpio -icdm
$ gzcat $HOME/configs-example.cpio.gz | cpio -icdm
$ gzcat $HOME/DNSMagic.cpio.gz | cpio -icdm

At most sites we share /configs via NFS so the above need only be done once.

You should NEVER need to modify anything in /configs/share/dns since configs will always prefer files that it finds deeper in the configs tree. If you are sharing the /configs tree accross a big site and you have your systems setup such that hostname(1) returns a fully qualified domain name (FQDN), you might want to:

$ mkdir -p `./bin/fqdn_site`

which for the host zen.crufty.net creates NET/CRUFTY with each directory being able to act as the root of a filesystem containing customized files that will be installed in preference to those higher in the tree. See the configs man pages for more detail.

If the above doesn't suit your site, you can just use local as a subdirectory of /configs, but the fqdn model is preferred.

The directory created by fqdn_site and local will be searched by configs if the SITE variable is not explicitly set.

In any case, creating share/dns/* (actually usr/local/share/dns/* but we make usr/local/share a symlink to ../../share) under an appropriate subdirectory of /configs is the supported way of adding to the config or overriding the content of files in the distribution.

pre-requisites

We will assume that CVS (1.9 or later) or GIT and perl-5 are installed and that the repositorty will reside on the primary nameserver.

make

The share/dns/Makefile ships setup for BSD make. If you prefer gmake use share/dns/GNUmakefile Both will include dnsmagic.mk which is where the rules are.

Installing

# /configs/update_file -l dnsmagic.list

will install DNSMagic into /usr/local/share/dns

cron jobs

If you want to have cron(8) help with scheduled changes and other automated DNS frobbing, you should

# /configs/update_file -l dnsmagic-cron.list

to install the core files needed and then to setup a daily and hourly cron job you can:

# CRONJOB=/usr/local/share/dns/daily /configs/update_file -l dnsmagic-cronjob.list
# CRONJOB=/usr/local/share/dns/hourly /configs/update_file -l dnsmagic-cronjob.list

and add /usr/local/share/dns/daily and /usr/local/share/dns/hourly to the appropriate crontab. You can then add files named 'S*' to hourly.d and daily.d to do whatever you want (which may simply be symlinks to some of our utils in cron.d) and cron(8) will mail you a report when the jobs run and have something to say.

If you are going to be using cron to automate things you should create the file /usr/local/share/dns/cron.d/lsetup.sh which sets WORK_DIR to where you want said jobs to play. For example:

# mkdir -p /home/cron
# cd /home/cron
# cvs checkout named
$ echo WORK_DIR=/home/cron/named >> /configs/local/usr/local/share/dns/cron.d/lsetup.sh

If you want to use updrev.pl to automatically generate PTR records on a regular basis you can use:

# CRONJOB=/usr/local/share/dns/daily /configs/update_file -l dnsmagic-updrevs.list

rather than the command shown previously. dnsmagic-updrevs.list will include dnsmagic-cronjob.list but also setup the links suitable for running updrevs.

Otherwise you probably should ensure that one of your regular cron jobs runs /etc/rc_d/dnsmagic to keep the live DNS tree up to date.

Migrating DNS data

The dns_convert.sh script takes care of the tedious job of stripping SOA records and converting named.boot to named.conf.

$ mkdir /tmp/named
$ cd /tmp/named
$ /configs/share/dns/bin/dns_convert.sh

will do most of what needs to be done to convert a BIND-4 or BIND-8 DNS to use DNSMagic. If both /etc/named.conf and /etc/named.boot exist it will assume /etc/named.conf is the current setup. You can set NDBOOT on the command line to name another file.

$ NDBOOT=/etc/named.boot OUTFILE=named.conf /configs/share/dns/bin/dns_convert.sh

will convert BIND-4 to BIND-8, the NDBOOT setting is only needed if /etc/named.conf also exists.

When dns_convert.sh is finished you should be ready to import into the SCM. It is a good idea to do that before making any changes.

$ cvs import -m"original data" named NAMED NAMED_0

$ git init
$ git add --all
$ git commit -m"original data"
$ git clone --bare . /share/gits/named.git

Making changes

If the file ns.list exists it is assumed to contain a list of NS records for your primary and secondary nameservers. When updsoa.pl is run it will spot this file and reference it in the .soa files it creates. If you have lots of zones delegated to the same nameservers you might find this handy.

As mentioned by dns_convert.sh(8) you may need to create/edit several .*rc files.

$ cd
$ cvs checkout named
$ cd named

make all the changes you want and then, run the regression suite to check all is well.

$ make depend
$ make
$ /usr/local/share/dns/regress . named.conf

once everything is setup the above will happen automatically, if all is well you can commit.

$ cvs commit -m"some initial setup"

Cut over

# cd /var
# mv named named.old
# cvs checkout named
...
# cd named
# make
dnsdeps -N named.boot
updsoa hosts/crufty.net.soa
bouncedns
...

At this point you are almost ready. If your namservers perform secondary service for other sites, you may want to pre-seed /var/named/secondary with the the files from your previous setup - but we may need to rename some. You can do something like:

# sed '/directory/s/named/named.old/' /etc/named.boot > /tmp/named.boot
# NDBOOT=/tmp/named.boot OUTFILE=named.conf /configs/share/dns/bin/dns_convert.sh secondary

(substitute named.conf for named.boot as necessary) to copy the existing secondary zone files refered to by the old setup to the names expected by the new. If this all seems too hard, you can skip this step and named will just transfer them from the primary nameservers.

To complete the cut over you need to:

# cd /etc
# mv named.boot named.boot.old
# ln -s /var/named/named.boot .
# /etc/rc_d/bouncedns -f
Stopping named
Restarting named
#

again, substitute named.conf for named.boot as appropriate.

Enabling CVS pre-commit checks

When you are happy that the regression suite is working for you, you can configure cvs to force it to be run whenever changes are committed to the repository:

# cd /tmp
# cvs checkout CVSROOT
# cd CVSROOT
# echo "^named  /usr/local/share/dns/regress" >> commitinfo
# cvs commit -m"force pre-commit checks for named" commitinfo

cvs patch

Note that if you have a big DNS system (say 150+ zone files) you may need our patch for CVS to ensure that pre-commit checks do not fail due to OS command line length limits. If you have a CVS version after 1.11 and the patch does not apply cleanly, you may have a version that already fixes the problem.

With the patch installed you can use:

# echo "^named  |xargs /usr/local/share/dns/regress" >> commitinfo

for the commitinfo entry described above.