DNSMagic: install
*****************


We install critical systems like nameservers using our configs_ tool.

You will have downloaded an archive which is inteneded to be unpacked in
a directory structure used by configs_ the `latest archive is here`_.

.. _`latest archive is here`: http://www.crufty.net/ftp/pub/unix/config-sh.tar.gz

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
	$ tar zxf $HOME/config-sh.tar.gz
	$ tar zxf $HOME/configs-example.tar.gz
	$ tar zxf $HOME/DNSMagic.tar.gz

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/*`` (or whatever you set
``DNSMAGIC`` to) 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
--------------

As noted in DNSMagic_ we originally only supported CVS.
The latest release can work with GIT or Mercurial too.

We will assume that a suitable SCM and ``perl`` are installed and
that the repositorty will reside on the primary nameserver (not
required with GIT or Mercurial).


make
~~~~

The ``share/dns/Makefile`` ships setup for BSD make (bmake_).
If you prefer GNU make 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``.


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-9
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
~~~

::

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

GIT
~~~

::

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

where ``$GITS`` is where you store such things.


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

for GIT you would substitute something like::

	# git clone $GITS/named.git named


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.

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

or::

	$ cd
	$ git clone $GITS/named.git named
	$ cd named

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

	$ make depend
	$ make
	$ make regress

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

	$ cvs commit -m"some initial setup"

a bit more involved with git::

	$ git add changed/file
	$ git commit -m"some initial setup"
	$ git push

Until you ``push`` your changes, they will not be available to the
live ``named``.

Cut over
========

::

	# cd /var
	# mv named named.old
	# cvs checkout named
	...

or::

	# git clone $GITS/named.git named
	...

then::

	# 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

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.conf named.conf.old
	# ln -s /var/named/named.conf .
	# /etc/rc_d/bouncedns -f
	Stopping named
	Restarting named
	#


Enabling CVS pre-commit checks
==============================

If you are using GIT or Mercurial, the pre-commit checks are enabled
automatically the first time you run ``make``.

For CVS, 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.

--------

.. _configs: http://www.crufty.net/FreeWare/configs.html
.. _`dns_convert.sh(8)`: dns_convert.sh_8.htm
.. _bmake: http://www.crufty.net/help/sjg/bmake.htm
.. _`patch for CVS`: http://www.crufty.net/ftp/pub/unix/cvs-commit.fix
.. _DNSMagic: DNSMagic.htm

:Author: sjg@crufty.net */\* imagine something very witty here \*/*
:Revision: $Id: install.txt,v 1.1 2016/04/10 06:40:20 sjg Exp $
:Copyright: `Copyright (c) 1997-2001 Simon J. Gerraty`_

.. _`Copyright (c) 1997-2001 Simon J. Gerraty`: http://www.crufty.net/misc/copyrght.html
