Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/oskar456/dzonegit

Git hooks to manage a repository of DNS zones
https://github.com/oskar456/dzonegit

dns dns-server git

Last synced: 3 months ago
JSON representation

Git hooks to manage a repository of DNS zones

Awesome Lists containing this project

README 

        
.. image:: https://travis-ci.org/oskar456/dzonegit.svg?branch=master

    :target: https://travis-ci.org/oskar456/dzonegit



Git hooks to manage a repository of DNS zones

=============================================



``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