Metadata-Version: 2.1
Name: dzonegit
Version: 0.14
Summary: Git hooks to manage a repository of DNS zones
Home-page: https://github.com/oskar456/dzonegit
Author: Ondřej Caletka
Author-email: ondrej@caletka.cz
License: MIT
Description: .. 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
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.5
Description-Content-Type: text/x-rst
