122 lines
5.1 KiB
Markdown
122 lines
5.1 KiB
Markdown
# 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`.
|
|
|
|
Configuration is keyed by Bind *view* and supports multiple views as well as
|
|
automatic management of catalog zones.
|
|
|
|
## Requirements
|
|
|
|
* [Bind](https://www.isc.org/bind/)
|
|
* [Bind-Tools](https://www.isc.org/bind/) (if not bundled with Bind)
|
|
* [dnspython](https://www.dnspython.org)
|
|
* [prettytable](https://zetcode.com/python/prettytable/)
|
|
* [pyyaml](https://pyyaml.org)
|
|
|
|
A running Bind server and a config file are required to run any command.
|
|
|
|
## Installation
|
|
|
|
Install directly from the git repository:
|
|
|
|
```
|
|
pip install git+ssh://git@git.ccc-rheintal.ch/spacefreak/dns-manager.git
|
|
```
|
|
|
|
## Configuration
|
|
|
|
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.
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
| ------------------- | ------------------------------------------------------ |
|
|
| `dns-list-zones` | List zones (view, status, managed). |
|
|
| `dns-zone-add` | Add a zone (and its catalog member, if configured). |
|
|
| `dns-zone-delete` | Delete a zone (and its catalog member, if configured). |
|
|
| `dns-zone-list` | Show the records of a zone. |
|
|
| `dns-record-add` | Add a record via DDNS. |
|
|
| `dns-record-delete` | Delete a record via DDNS. |
|
|
| `dns-confgen` | Regenerate per-view Bind config and run `rndc reconfig`. |
|
|
|
|
All commands support `--help` for the full list of options.
|
|
|
|
Commands prompt interactively when arguments are omitted and ask for
|
|
confirmation before applying changes. Pass `-b`/`--batch` to require all
|
|
arguments and skip prompts for non-interactive use.
|
|
|
|
## Usage
|
|
|
|
Zones are addressed as `ZONE[@VIEWS]`, where `VIEWS` is a comma-separated list
|
|
of views or `*` for all views. Omitting `@VIEWS` only works when the target is
|
|
unambiguously in the default view. In record names, `@` refers to the zone apex.
|
|
|
|
```
|
|
# List all managed zones
|
|
dns-list-zones
|
|
|
|
# Add a zone
|
|
dns-zone-add example.tld
|
|
|
|
# Show the records of a zone
|
|
dns-zone-list example.tld
|
|
|
|
# Add an A record
|
|
dns-record-add example.tld www 3600 A 192.0.2.1
|
|
```
|
|
|
|
## Hooks
|
|
|
|
Executable scripts placed in the hooks base directory (`hooks_dir`, default
|
|
`<etc_dir>/hooks`) are run around zone and record mutations. The tree narrows
|
|
progressively and every level is optional:
|
|
|
|
```
|
|
hooks/ -> every action and phase (zone+record, add+delete, pre+post)
|
|
zone/ -> all zone actions/phases
|
|
add/ -> zone add, both phases
|
|
pre/ -> zone add, pre only
|
|
post/ -> zone add, post only
|
|
delete/{pre,post}/
|
|
record/
|
|
add/{pre,post}/
|
|
delete/{pre,post}/
|
|
```
|
|
|
|
For a given event `(kind, action, phase)` all matching hooks across every
|
|
existing level along that event's path (`hooks/` → `hooks/<kind>/` →
|
|
`hooks/<kind>/<action>/` → `hooks/<kind>/<action>/<phase>/`) are collected and
|
|
run sorted by filename (run-parts style), so a numeric prefix (e.g. `50-`)
|
|
controls execution order regardless of directory depth. A hook placed shallower
|
|
in the tree fires for more events; distinguish the concrete event via the
|
|
environment variables. Each hook inherits the terminal, so its stdout and stderr
|
|
appear live and in order, and a hook may be interactive: it can print prompts and
|
|
read the user's input from stdin. In batch mode (`-b`) stdin is redirected to
|
|
`/dev/null`, so a hook that reads input gets an immediate EOF instead of blocking
|
|
(hooks that prompt should guard on a tty/EOF).
|
|
Only executable regular files are run; everything else (including the
|
|
`zone`/`record`/`add`/`delete`/`pre`/`post` subdirectories) is skipped, and
|
|
missing directories are no-ops.
|
|
|
|
Each hook receives context via environment variables:
|
|
|
|
* Common env: `DNSMGR_KIND` (zone|record), `DNSMGR_ACTION` (add|delete),
|
|
`DNSMGR_PHASE` (pre|post), `DNSMGR_ZONE` (origin, no trailing dot), `DNSMGR_VIEW`.
|
|
* Record-only env: `DNSMGR_RECORD_NAME`, `DNSMGR_RECORD_TTL`,
|
|
`DNSMGR_RECORD_TYPE`, `DNSMGR_RECORD_VALUE` (values joined by newlines).
|
|
* `DNSMGR_ZONE_FILE` (zone file path): set only for managed zones and not for zone add pre-hooks and not for zone delete post-hooks.
|
|
|
|
A `pre` hook exiting non-zero aborts the operation before any change is applied
|
|
(exit code 190); a `post` hook failure only prints an `ERROR:` and continues.
|
|
|
|
Pass `-n`/`--no-hooks` to `dns-zone-add`, `dns-zone-delete`, `dns-record-add` or
|
|
`dns-record-delete` to skip all hook execution for that run.
|