Change README.md

2026-07-18 22:06:28 +02:00
parent 23cd9a9b77
commit 08a18d39ab
1 changed files with 66 additions and 2 deletions
@@ -1,10 +1,74 @@
 # DNS-Manager

-Manage DNS zones and dynamic records.
+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

-## Dependencies
 * [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-list`     | Show the records of a zone.                            |
+| `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-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.
+
+## 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
+
+# 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
+
+# Add a zone
+dns-zone-add example.tld
+```
+
+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.