Update README.md and example config file
This commit is contained in:
@@ -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
|
||||
zone transfers, and Bind itself is driven through `named-checkconf` and `rndc`.
|
||||
records without hand-editing zone files or reloading Bind manually. It provides
|
||||
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
|
||||
automatic management of catalog zones.
|
||||
Records are read via AXFR zone transfers and written live via DDNS/TSIG, so
|
||||
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
|
||||
key file is mandatory for any non-default view (and for any zone that requires a
|
||||
key to transfer or update). A view may also define a catalog zone, which is then
|
||||
managed automatically when zones are added or deleted.
|
||||
The per-view configuration lives under `zones_config`, keyed by Bind view; the
|
||||
default view is `_default`. A TSIG key file is mandatory for any non-default view
|
||||
(and for any zone that requires a key to transfer or update). A view may also
|
||||
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
|
||||
|
||||
|
||||
+3
-1
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user