Update README.md and example config file

README.md

@@ -1,11 +1,19 @@
 # DNS-Manager
 
 A CLI toolset to manage [Bind](https://www.isc.org/bind/) DNS zones and dynamic
-records. Zones are updated live via DDNS/TSIG, zone contents are read via AXFR
+records without hand-editing zone files or reloading Bind manually. It provides
-zone transfers, and Bind itself is driven through `named-checkconf` and `rndc`.
+a small set of commands for day-to-day operations: listing zones, adding and
+deleting zones, and adding, listing and deleting records.
 
-Configuration is keyed by Bind *view* and supports multiple views as well as
+Records are read via AXFR zone transfers and written live via DDNS/TSIG, so
-automatic management of catalog zones.
+record changes take effect immediately without a reload. Zones are added or
+deleted by writing (or removing) a per-zone `.conf` and zone file, regenerating
+the per-view config that `named.conf` includes, and running `rndc reconfig`.
+Bind itself is inspected and driven through `named-checkconf` and `rndc`.
+
+Configuration is keyed by Bind *view* and supports multiple views, optional
+automatic management of catalog-zone membership, and user-defined hooks that run
+around zone and record mutations.
 
 ## Requirements
 
@@ -30,10 +38,36 @@ pip install git+ssh://git@git.ccc-rheintal.ch/spacefreak/dns-manager.git
 By default the tools read `/etc/dns-manager/config.yml` (override with `-c`).
 A documented example config is provided in [`files/config.yml`](files/config.yml).
 
-The configuration is keyed by Bind view; the default view is `_default`. A TSIG
+The per-view configuration lives under `zones_config`, keyed by Bind view; the
-key file is mandatory for any non-default view (and for any zone that requires a
+default view is `_default`. A TSIG key file is mandatory for any non-default view
-key to transfer or update). A view may also define a catalog zone, which is then
+(and for any zone that requires a key to transfer or update). A view may also
-managed automatically when zones are added or deleted.
+define a catalog zone, which is then managed automatically when zones are added
+or deleted.
+
+### Top-level options
+
+| Option            | Default                | Description                                                                                                                                                          |
+| ----------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `etc_dir`         | `/etc/dns-manager`     | Base config directory; used to derive other defaults.                                                                                                               |
+| `named_checkconf` | auto-detected on `PATH` | Path to the `named-checkconf` binary (used to list zones).                                                                                                         |
+| `rndc`            | `rndc` on `PATH`       | Path to the `rndc` binary (used to reconfigure Bind).                                                                                                               |
+| `named_conf`      | Bind default           | Path to `named.conf`, passed to `named-checkconf` when set.                                                                                                         |
+| `dns_ip`          | `127.0.0.1`            | IP address of the DNS server for AXFR and DDNS.                                                                                                                     |
+| `hooks_dir`       | `<etc_dir>/hooks`      | Base directory of the [hook](#hooks) tree.                                                                                                                          |
+| `dns_keyfiles`    | —                      | Map of `view` or `zone@view` → TSIG key file, used for transfers and DDNS updates. **Mandatory for any non-default view** or zone needing a key. The first key found in a file wins. |
+| `control_key`     | rndc default key       | Key file passed to `rndc -k` when reconfiguring Bind on zone add/delete.                                                                                            |
+| `zones_config`    | —                      | **Mandatory.** Map of Bind view → per-view options (see below).                                                                                                     |
+
+### Per-view options (`zones_config.<view>`)
+
+| Option              | Default                    | Description                                                                                                                                       |
+| ------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `config_dir`        | `<etc_dir>/<view>.zones`   | Directory holding one `.conf` per managed zone.                                                                                                  |
+| `config_file`       | —                          | **Mandatory.** File included from `named.conf`; every `.conf` in `config_dir` is concatenated into it (Bind cannot wildcard-include).             |
+| `zone_dir`          | —                          | **Mandatory.** Directory holding this view's Bind zone files (typically `/etc/bind/dyn` in a single-view setup).                                  |
+| `catalog_zone`      | —                          | Catalog zone (optionally `zone@view`) that will be managed automatically on zone add/delete. Best created manually in Bind to avoid accidental deletion. |
+| `templates.config`  | —                          | Config template used when creating a zone. Required to add a zone unless overridden with `dns-zone-add -t`.                                        |
+| `templates.zone`    | —                          | Zone-file template used when creating a zone. Required to add a zone unless overridden with `dns-zone-add -z`.                                     |
 
 ## Commands
 

files/config.yml

@@ -6,6 +6,7 @@
 
 #
 # Optional paths to named_checkconf and rndc binaries.
+# If unset, both are looked up on PATH.
 #
 
 #named_checkconf: /usr/bin/named-checkconf
@@ -101,7 +102,8 @@ zones_config:
     #catalog_zone: catalog.example.tld
 
     #
-    # Optional paths to config and zone default templates used when adding zones.
+    # Paths to config and zone default templates used when adding zones.
+    # Required to add a zone unless overridden per-invocation via dns-zone-add -t/-z.
     #
 
     #templates: