oskar456-dzonegit

``dzonegit`` is a set of Git hooks allowing you to manage DNS zone files in a
git repository. First, zone file sanity checks are run by ``pre-commit`` hook
on your computer. After pushing changes to a bare repository on the DNS server,
the sanity checks are run again on the server and if everything is OK,
repository is checked out to a directory, DNS software configuration
snippets are re-generated from a simple template and finally reload command
is issued.

Main features
-------------

- check if zone file compiles properly using `named-compilezone(8)`_
- autodetect zone name from file name or ``$ORIGIN`` directive
- enforce updating serial number when zone content is changed
- optional ``smudge`` filter to replace ``$UNIXTIME`` directive with current UNIX time
- both ``pre-commit`` and ``pre-receive``/``update`` hooks to enforce similar checks in the remote repository
- ``post-receive`` hook to checkout the working copy from a bare repository, generate config snippets for various DNS server software and reload them
- only Python 3.5+ standard library is used

Requirements
------------

- Python 3.5+
- `named-compilezone(8)`_ (part of `bind9utils` package)
- git

Simple instalation (especially for workstations)
------------------------------------------------

Since there is no other Python dependency than the standard library, you can
simply download the `dzonegit.py` file, make it executable and rename/symlink
it to an appropriate hook location inside the Git repository
`.git/hooks/pre-commit`. This is especially handy for the end users not
experienced with Python packaging ecosystem.

Full instalation and usage
--------------------------

- install all the requirements
- install ``dzonegit`` Python package using your
favourite tool (``virtualenvwrapper``, ``venv``, ``pipenv``, etc.)
- in the local repository, create a symlink for the ``pre-commit`` hook:
``$ ln -s $(which dzonegit-pre-commit) /path/to/repo/.git/hooks/pre-commit``
- on the server, install some git repository management software,
preferably Gitolite_
- on the server, install either ``pre-receive`` or ``update`` hook
(both do the same) as well as the ``post-receive`` hook. See `Gitolite
documentation on how to add custom hooks`_
- on the server, set up the configuration options for each repository

Support for $UNIXTIME directive
-------------------------------

If you want to use ``$UNIXTIME`` in your zone files instead of serial number,
you have to install a `smudge` filter on the server, that will replace the
directive with current unix time on every checkout. First, set up the filter
in the Git configuration:

.. code-block:: shell

$ git config --global filter.dzonegit.smudge $(which dzonegit-smudge-serial)

Then, apply the filter on all zone files using either ``.git/info/attributes``
or directly ``.gitattributes`` file inside the repository:

.. code-block::

*.zone filter=dzonegit

Configuration options
---------------------

All configuration options are stored in `git-config(1)`_ in the section
named ``dzonegit``. All boolean options default to *False*.

*dzonegit.ignorewhitespaceerrors*
Ignore white space errors in ``pre-commit`` and ``pre-receive``/``update`` hooks.

*dzonegit.allowfancynames*
In ``pre-commit`` and ``pre-receive``/``update`` hooks, do not enforce zone
file name to be similar to the name of the zone.

*dzonegit.noserialupdate*
Do not try to automatically update zone serial number if necessary.
Valid only in the ``pre-commit`` hook.

*dzonegit.nomissingdotcheck*
Do not check for forgotten final dot on the right-hand side of PTR records.
Valid only in the ``pre-commit`` hook.

*dzonegit.checkoutpath*
Path to a writable directory, to which ``post-receive`` hook checks out
current *HEAD* after each update.

*dzonegit.conffiletemplate*
Path to a JSON file containing template for generating DNS server
configuration snippet. See below for file format specification. More
files can be provided by appending single digit from 1 to 9 to this option.

*dzonegit.conffilepath*
Path to a writable file to generate DNS server configuration snippet.
More files can be provided by appending single digit from 1 to 9 to this
option. Each file is generated using the template with corresponding suffix.

*dzonegit.reconfigcmd*
A command to run when zones are introduced, deleted or renamed in the
repository. Should do something like ``rndc reconfig``. More commands
can be provided by appending single digit from 1 to 9 to this option.

*dzonegit.zonereloadcmd*
A command to run for each zone, where zone file has been modified. Zone
name is automatically appended as the last argument. Should do something
like ``rndc reload``. More commands can be provided by appending single digit
from 1 to 9 to this option.

*dzonegit.zoneblacklist*
Path to a text file containing list of zone names without trailing dots,
one per line. If zone is found on the blacklist, it is ignored when
``post-receive`` hook generates configuration. Wildcards can be used as
well, see `JSON template`_ below.

*dzonegit.zonewhitelist*
Path to a text file containing list of zone names without trailing dots,
one per line. If not empty and zone is not found on the whitelist,
it is ignored when ``post-receive`` hook generates configuration. Wildcards
can be used as well, see `JSON template`_ below.

JSON template
-------------

The DNS server configuration snippets are generated using a simple JSON-based
template. All keys are optional but please make sure the file is a valid JSON
file. It is possible to define a zone-specific options, for instance for
changing DNSSEC parameters per zone. Those zone-specific options allow usage of
wildcards; if an exact match of zone name is not found, the leftmost label is
substituted with `*`. If still no match is found, the leftmost label is dropped
and the second one is again substituted with `*`. In the end, a single `*` is
checked. Only if even this key is not found, the value of *defaultvar* is used
as the zone-specific option.

Valid keys are:

*header*
A string that is templated to the begining of the output file.

*footer*
A string that is templated to the end of the output file.

*item*
A string that is templated for each zone.

*defaultvar*
A string that would template variable ``$zonevar`` expand to if there is not
a zone-specific variable defined, nor any wildcard matched.

*zonevars*
An object mapping zone names (without the final dot) to a zone-specific
variable to which template variable ``$zonevar`` would expand to. Using
wildcards is possible by replacing the leftmost label with `*`. Ultimately,
a key with label `*` will match every single zone (making *defaultvar*
option litte bit pointless)

In the template strings, these placeholders are supported:

``$datetime``
Current date and time in human readable format

``$zonename``
Zone name, without the trailing dot

``$zonefile``
Full path to the zone file

``$zonerelfile``
Path to the zone file, relative to checkout path (useful for chroot environments)

``$zonevar``
Per-zone specific variable, see above

Example JSON template for Knot DNS
..................................

.. code-block:: json

{
"header": "# Managed by dzonegit, do not edit.\nzone:",
"footer": "",
"item": " - domain: \"$zonename\"\n file: \"$zonefile\"\n $zonevar\n",
"defaultvar": "template: default",
"zonevars": {
"example.com": "template: signed",
"*.cz": "template: czdomains",
"*.in-addr.arpa": "template: ipv4reverse"
}
}

Example JSON template for BIND
..............................

.. code-block:: json

{
"header": "# Autogenerated by dzonegit on $datetime. Do not edit.\n",
"item": "zone \"$zonename\" {\n type master;\n file \"$zonefile\";\n};"
}

.. _named-compilezone(8): https://linux.die.net/man/8/named-compilezone
.. _git-config(1): https://linux.die.net/man/1/git-config
.. _Gitolite: http://gitolite.com/gitolite/index.html
.. _Gitolite documentation on how to add custom hooks: http://gitolite.com/gitolite/cookbook/#hooks