From 8c1e9502f4f534a3f8746cad9483953086d4a676 Mon Sep 17 00:00:00 2001 From: Sven Luethi Date: Mon, 17 Nov 2025 21:43:39 +0100 Subject: [PATCH] modified: README.md --- README.md | 277 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 176 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index f49d12a..8a30c8f 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,39 @@ # Netbox Bind Provisioner -A Netbox Plugin that provides a minimal DNS Server for the automatic -provisioning of a Bind9 Server from Netbox DNS data (netbox-plugin-dns). +A NetBox plugin that implements a lightweight DNS server to automate the +provisioning and configuration of a BIND9 server based on DNS records +maintained in NetBox. (netbox-plugin-dns). ## Plugin configuration -The plugin was re-worked; Instead of exporting zone files, it provides an -entire (though minimal) DNS Server that is fed directly from Netbox's DNS data. -The Server also provides specialized "catalog" zones that bind uses to -automatically discover new zones and remove deleted ones. The plugin supports -view as well as basic dns security using TSIG. +The plugin has been reworked: instead of exporting zone files, it now provides +a minimal DNS server that is fed directly from NetBox’s DNS data. This server +also exposes specialized catalog zones that BIND uses to automatically discover +newly created zones and remove deleted ones. The plugin supports BIND views and +basic DNS security via TSIG. -To work correctly, each view needs a tsig key installed and the -bind-transfer-endpoint needs to be running as its own service in the background -via the `manage.py` command. Note that dnssec support will be implemented as -soon as bind9 has a mechanism to allow configuration of such via the Catalog -Zones mechanism. +The plugin exposes one catalog zone per view. Each catalog zone is available +under the special zone name **"catz"** and can be queried through the built-in +DNS server like any other zone. +For proper operation, each view requires an installed TSIG key, and the +`bind-transfer-endpoint` must be running as a separate background service using +the `manage.py` command. Note that DNSSEC support will be added once BIND9 +provides a mechanism to configure it through the Catalog Zones system. + +To start the service: ``` manage.py bind-transfer-endpoint --port 5354 ``` -The plugin also currently needs a file that tracks the current state of the -catalog zone's SOA serial. The serial represents the catalog zone's SOA record -serial number and is used by downstream DNS Servers to determine if the catalog -zone was updated (e.g. if a zone is added/modified/removed from netbox). -The file is used to persist the SOA record's serial across service restarts. -It will be replaced by a database entry once the plugin has its own models. +The plugin currently requires a file to track the SOA serial of the catalog zone. +This serial represents the SOA record’s version number and allows downstream +DNS servers to determine when the catalog zone has changed (for example, +when a zone is added, modified, or removed in NetBox). The file ensures the +serial persists across service restarts. It will be replaced with a +database-backed value once the plugin introduces its own models. + +When configuring the plugin, you need to provide a path on the filesystem for +this file where the plugin can create and manage it. Please do not update it by +hand or remove it unless you know what you are doing. ### Service parameters Parameter | Description @@ -38,104 +47,170 @@ Setting | Description catalog_serial_file | The catalog serial counter. The file needs to be writable. tsig_keys | Maps a TSIG Key to be used for each view. -### Plugin example configuration -``` -PLUGINS_CONFIG = { - "netbox_bind_provisioner": { - "catalog_serial_file": "/opt/netbox/catalog-serial.txt", - "tsig_keys": { - "key1name": { - "view": "public", - "keyname": "view1key", - "algorithm": "hmac-sha256", - "secret": "base64-encoded-secret" - }, - "key2name": { - "view": "private", - "keyname": "view2key", - "algorithm": "hmac-sha256", - "secret": "base64-encoded-secret" +## Installation guide +This setup provisions a BIND9 server directly with DNS data from NetBox. +BIND9 can optionally run on a separate server. If so, any reference to +127.0.0.1 in step 6 must be replaced with the IP address of the NetBox host. +TCP and UDP traffic from the BIND9 server to the NetBox host must be allowed on +port 5354 (or the port you have configured). + +This guide assumes: +- Netbox has been installed under /opt/netbox +- Bind9 is installed on the same host as Netbox +- The Netbox DNS Plugin netbox-plugin-dns is installed +- The following dns views exist in Netbox DNS: + - `public` (the default) + - `private` + +1. Preliminaries + - Install Bind9 on the same host that netbox is on. + - Generate a TSIG Key for the `public` and `private` dns views respectively. + +2. Adding required package + ``` + cd netbox + echo netbox-plugin-bind-provisioner >> local_requirements.txt + . venv/bin/activate + pip install -r local_requirements.txt + ``` + +3. Updating netbox plugin configuration (configuration.py) + Change following line from + ``` + PLUGINS = ['netbox_dns'] + ``` + to + ``` + PLUGINS = ['netbox_dns', 'netbox_plugin_bind_provisioner'] + ``` + + Configure the Bind Exporter Plugin using the PLUGINS_CONFIG dictionary. + Change + ``` + PLUGINS_CONFIG = {} + ``` + to + ``` + PLUGINS_CONFIG = { + "netbox_bind_provisioner": { + "catalog_serial_file": "/opt/netbox/catalog-serial.txt", + "tsig_keys": { + "public": { + "keyname": "public_view_key", + "algorithm": "hmac-sha256", + "secret": "base64-encoded-secret" + }, + "private": { + "keyname": "private_view_key", + "algorithm": "hmac-sha256", + "secret": "base64-encoded-secret" + } } - }, + } } -} -``` + ``` + Note that the tsig-key attributes keyname, algorithm and secret form a + dictionary in following python structure path: + ``` + PLUGINS_CONFIG.netbox_bind_provisioner.tsig_keys. + ``` + This allows the plugin to map requests to the right dns view using the tsig + signature from each request. -## Bind example configuration -``` -options { - ... - ... - allow-update { none; }; - allow-query { any; }; - allow-recursion { none; }; - notify yes; - min-refresh-time 60; - ... - ... -}; +4. Run migrations (This step is not yet required. Just adding for completeness) + ``` + python3 netbox/manage.py migrate + ``` -# ACLs +5. Start listener + This step runs the DNS endpoint used by bind to configure itself. You may want + to write a service wrapper that runs this in the background. Dont forget to + activate the venv if you do decide to run this service in the background. + Note that `--port 5354` is optional. The listener will bind this port + by default. + ``` + python3 netbox/manage.py bind-transfer-endpoint --port 5354 + ``` -acl public { - !10.0.0.0/8; - !172.16.0.0/12; - !192.168.0.0/16; - any; -}; +6. Configuring a Bind9 to interact with Netbox via the bind-transfer-endpoint + endpoint. Note that its not possible to give all the correct details of the + `options` block as it is heavily dependent on the Operating System used. + Please dont forget to adjust as required. + + ``` + ########## OPTIONS ########## -acl private { - 10.0.0.0/8; - 172.16.0.0/12; - 192.168.0.0/16; -}; - -# Zone definitions - -view "public" { - key "key1name" { - algorithm hmac-sha256; - secret "base64-encoded-secret"; + options { + allow-update { none; }; + allow-query { any; }; + allow-recursion { none; }; + notify yes; + min-refresh-time 60; }; - match-clients { public; }; + ########## ACLs ########## - catalog-zones { - zone "catz" - default-masters { 127.0.0.1 port 5354 key "key1name"; } - zone-directory "/var/lib/bind/zones" - min-update-interval 1; + acl public { + !10.0.0.0/8; + !172.16.0.0/12; + !192.168.0.0/16; + any; }; - zone "catz" { - type slave; - file "/var/lib/bind/zones/catz_public"; - masters { 127.0.0.1 port 5354 key "key1name"; }; - notify no; - }; -}; - -view "private" { - key "key2name" { - algorithm hmac-sha256; - secret "base64-encoded-secret"; + acl private { + 10.0.0.0/8; + 172.16.0.0/12; + 192.168.0.0/16; }; - match-clients { private; }; + ########## ZONES ########## - catalog-zones { - zone "catz" - default-masters { 127.0.0.1 port 5354 key "key2name"; } - zone-directory "/var/lib/bind/zones" - min-update-interval 1; + view "public" { + key "public_view_key" { + algorithm hmac-sha256; + secret "base64-encoded-secret"; + }; + + match-clients { public; }; + + catalog-zones { + zone "catz" + default-masters { 127.0.0.1 port 5354 key "public_view_key"; } + zone-directory "/var/lib/bind/zones" + min-update-interval 1; + }; + + zone "catz" { + type slave; + file "/var/lib/bind/zones/catz_public"; + masters { 127.0.0.1 port 5354 key "public_view_key"; }; + notify no; + }; }; - zone "catz" { - type slave; - file "/var/lib/bind/zones/catz_private"; - masters { 127.0.0.1 port 5354 key "key2name"; }; - notify no; + view "private" { + key "private_view_key" { + algorithm hmac-sha256; + secret "base64-encoded-secret"; + }; + + match-clients { private; }; + + catalog-zones { + zone "catz" + default-masters { 127.0.0.1 port 5354 key "private_view_key"; } + zone-directory "/var/lib/bind/zones" + min-update-interval 1; + }; + + zone "catz" { + type slave; + file "/var/lib/bind/zones/catz_private"; + masters { 127.0.0.1 port 5354 key "private_view_key"; }; + notify no; + }; }; -}; -``` + ``` + +7. Restart bind - Done