Document configuration options

README.rst

@@ -11,7 +11,6 @@ Main features
  - ``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 standard library is used
 
-.. _named-compilezone(8): https://linux.die.net/man/8/named-compilezone
 
 Requirements
 ------------
@@ -25,3 +24,123 @@ Instalation and usage
 ---------------------
 
 Please note that this project is not finished yet. Detailed instructions will follow later.
+
+Configuration options
+---------------------
+
+All configuration options are stored in `git-config(1)`_ in section named ``dzonegit``.
+All boolean options default to *False*.
+
+
+*dzonegit.ignorewhitespaceerrors*
+  Ignore white space errors in ``pre-commit`` and ``pre-receive``/``update`` hooks.
+
+*dzonegit.noserialupdate*
+  Do not try to automatically update zone serial number if necessary.
+  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, whose 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.
+
+*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.
+
+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.
+
+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.
+
+*zonevars*
+  An object mapping zone names (without the final dot) to a zone-specific
+  variable to which template variable ``$zonevar`` would expand to.
+
+In the template strings, these placeholders are supported:
+
+``$datetime``
+  Current timestamp
+
+``$zonename``
+  Zone name, without trailing dot
+
+``$zonefile``
+  Full path to the zone file
+
+``$zonevar``
+  Per-zone specific variable, see above
+
+Example JSON template for Knot DNS
+..................................
+
+.. code-block:: json
+
+    {
+      "header": "# Managed by dzonegit, do not edit.\n",
+      "footer": "",
+      "item": " - zone: \"$zonename\"\n   file: \"$zonefile\"\n   $zonevar\n",
+      "defaultvar": "template: default",
+      "zonevars": {
+        "example.com": "template: signed"
+      }
+    }
+
+
+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