From 5999db72f9ce57856e3bf8e07463d353784a195d Mon Sep 17 00:00:00 2001 From: Sven Luethi Date: Tue, 29 Sep 2026 14:01:40 +0200 Subject: [PATCH] modified: README.md deleted: docs/architecture-overview.drawio deleted: docs/architecture-overview.svg modified: docs/install-systemd-service.md new file: docs/installation-guide.md Documentation cleanup modified: pyproject.toml change old provisioner link to bridge --- README.md | 500 ++++++++++++++---------------- docs/architecture-overview.drawio | 76 ----- docs/architecture-overview.svg | 4 - docs/install-systemd-service.md | 14 +- docs/installation-guide.md | 192 ++++++++++++ pyproject.toml | 4 +- 6 files changed, 441 insertions(+), 349 deletions(-) delete mode 100644 docs/architecture-overview.drawio delete mode 100644 docs/architecture-overview.svg create mode 100644 docs/installation-guide.md diff --git a/README.md b/README.md index 0146955..d35c984 100644 --- a/README.md +++ b/README.md @@ -6,73 +6,185 @@ and your existing DNS infrastructure, leveraging native DNS mechanisms for seaml These include zone transfers (RFC 5936), catalog zones (RFC 9432), and notifying clients about zone changes (RFC 1996). -PyPi -Stars Badge -Forks Badge -Issues Badge -Pull Requests Badge -GitHub contributors -License Badge -Code Style Black -Downloads -Downloads/Month -Downloads/Week + +PyPI + + +Stars Badge + + +Forks Badge + + +Issues Badge + + +Pull Requests Badge + + +GitHub contributors + + +License Badge + + +Code Style Black + + +Downloads + + +Downloads/Month + + +Downloads/Week + +## Contents -# Plugin configuration -While providing Zone transfers via AXFR, the Server also exposes specialized catalog zones that BIND -and other RFC9432 compliant DNS Servers use to automatically discover newly created zones and remove -deleted ones. The plugin supports views and basic DNS security via TSIG. +- [Overview](#overview) +- [Compatibility](#compatibility) +- [Requirements](#requirements) +- [Installation](#installation) +- [Configuration](#configuration) + - [Settings reference](#settings-reference) + - [Catalog zone naming](#catalog-zone-naming) + - [TSIG authentication](#tsig-authentication) + - [NOTIFY](#notify) +- [Running the transfer endpoint](#running-the-transfer-endpoint) +- [Notes and troubleshooting](#notes-and-troubleshooting) +- [License](#license) -The plugin exposes one catalog zone per view. The catalog zone name is configurable (see -[Catalog Zone Naming](#catalog-zone-naming) below) and defaults to **"catz"**. It may be queried -through the built-in DNS server just like any other dns zone. +## Overview -For proper operation, each view requires an installed TSIG key, and the `dns-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. +```mermaid +flowchart LR + subgraph netbox ["NetBox"] + subgraph plugins ["NetBox Plugins"] + IPAM[IPAM] + DNS["NetBox DNS"] + subgraph bridge ["NetBox DNS Bridge"] + TE["Transfer
Endpoint"] + end + end + end -To start the transfer endpoint service in the foreground: + DNSSRV["DNS Server
(RFC 9432)
e.g. BIND9"] + + DNSSRV -- "AXFR (RFC 5936)
Catalog Zone (RFC 9432)" --> TE + TE -.->|"NOTIFY (RFC 1996)"| DNSSRV ``` -manage.py dns-transfer-endpoint --port 5354 -``` -This process needs to be scheduled as a background service for the built-in DNS Server to work -correctly. For Linux users with Systemd (Ubuntu, etc), Matt Kollross provides a startup unit and -instructions [here](docs/install-systemd-service.md). +- **Zone transfers (RFC 5936)** — DNS servers pull authoritative zone data directly from NetBox. +- **Catalog zones (RFC 9432)** — consumers automatically discover newly created and deleted zones. + One catalog zone is exposed per view and may be queried through the built-in DNS server just like + any other zone. The catalog zone name is configurable (see + [Catalog zone naming](#catalog-zone-naming)) and defaults to `catz`. +- **NOTIFY (RFC 1996)** — clients and zone nameservers are informed about zone changes so they can + request a fresh zone transfer (see [NOTIFY](#notify)). +- **Views and TSIG** — each view requires its own TSIG key, which is also used to map incoming + requests to the correct view (see [TSIG authentication](#tsig-authentication)). +- **DNSSEC** — not supported yet; will be added once BIND9 provides a mechanism to configure it + through the catalog zones system. -## Service parameters -Parameter | Description ---------- | ------------------------------------------------------------------- ---port | Port to listen on for requests (defaults to 5354) ---address | IP of interface to bind to (defaults to 0.0.0.0) +## Compatibility +This plugin extends netbox-plugin-dns, and versioning is aligned with it: the major and minor +version of both plugins must match. For example, when using netbox-plugin-dns `v1.5.5`, install +netbox-plugin-dns-bridge `v1.5.x`. -## Plugin settings -Plugin settings should be configured under `PLUGINS_CONFIG` in `netbox_dns_bridge`: -``` +| netbox-plugin-dns | netbox-plugin-dns-bridge | +| :---------------: | :----------------------: | +| 1.5.x | 1.5.x | +| 1.6.x | 1.6.x | +| 1.7.x | 1.7.x (current) | + +NetBox and Python version requirements follow netbox-plugin-dns; see its +[documentation](https://github.com/sys4/netbox-plugin-dns). + +## Requirements + +- [NetBox](https://github.com/netbox-community/netbox) with the + [netbox-plugin-dns](https://github.com/sys4/netbox-plugin-dns) plugin installed. +- A DNS server with RFC 9432 catalog zone support (e.g. BIND9) as the consumer. +- Network reachability from the consumer to the NetBox host on TCP and UDP port `5354` (or the + port you have configured). +- At least one running `rq-worker` service if you enable any of the NOTIFY features, since they + use NetBox's background job system. + +## Installation + +The full walkthrough — including a complete BIND9 configuration with two views — is available in +[docs/installation-guide.md](docs/installation-guide.md). The short version: + +1. Install the package: + + ``` + cd netbox + echo netbox-plugin-dns-bridge >> local_requirements.txt + . venv/bin/activate + pip install -r local_requirements.txt + ``` + +2. Enable the plugin in `configuration.py`: + + ```python + PLUGINS = ['netbox_dns', 'netbox_dns_bridge'] + ``` + +3. Configure the plugin under `PLUGINS_CONFIG` (see [Configuration](#configuration)). + +4. Run migrations: + + ``` + manage.py migrate + ``` + +5. Start the transfer endpoint as a background service (see + [Running the transfer endpoint](#running-the-transfer-endpoint)). + +## Configuration + +Plugin settings are configured under `PLUGINS_CONFIG` in `configuration.py`: + +```python PLUGINS_CONFIG = { 'netbox_dns_bridge': { ... - ... } } ``` -### Catalog Zone Naming +### Settings reference + +| Setting | Type | Default | Description | +| ------- | ---- | ------- | ----------- | +| `catalog_zone_name` | string | `catz` | Name of the catalog zone exposed for each view | +| `catalog_zone_name_includes_view` | bool | `False` | Prepend the view name: `.` | +| `tsig_keys` | dict | — | Per-view TSIG keys used to authenticate transfers and sign NOTIFY messages | +| `notify_over_tcp` | bool | `False` | Send NOTIFY messages over TCP instead of UDP | +| `notify_clients` | bool | `False` | NOTIFY clients that have queried the transfer endpoint | +| `notify_client_alive_threshold_hours` | int | `24` | How long a client is considered "alive" after its last query | +| `notify_client_port` | int | `53` | Destination port for client NOTIFY messages | +| `notify_ns_custom_field_name` | string | — | Boolean zone custom field enabling NS NOTIFY per zone | +| `notify_ns_all_zones` | bool | `False` | Send NS NOTIFY for every zone on serial change | +| `notify_ns_port` | int | `53` | Destination port for NS NOTIFY messages | + +### Catalog zone naming + The name of the catalog zone exposed for each view is configurable: -Setting | Default | Description -------- | ------- | ----------------------------------------------------------- -`catalog_zone_name` | `catz` | The name of the catalog zone. May be a full DNS name. -`catalog_zone_name_includes_view` | `False` | Prepend the view name: `.`. +| Setting | Default | Description | +| ------- | ------- | ----------- | +| `catalog_zone_name` | `catz` | The name of the catalog zone. May be a full DNS name. | +| `catalog_zone_name_includes_view` | `False` | Prepend the view name: `.`. | `catalog_zone_name` accepts full DNS names with multiple labels. Case and a trailing dot are irrelevant — names are handled and compared as `dns.name.Name` objects. With `catalog_zone_name_includes_view` disabled (the default), the plain `catalog_zone_name` is used for every view; when enabled, the view name is prepended (e.g. `_default_.catz`). -``` +```python 'netbox_dns_bridge': { 'catalog_zone_name': 'catz', 'catalog_zone_name_includes_view': False, @@ -84,12 +196,14 @@ Note that the DNS server consuming the catalog zone must be configured with the e.g. BIND9's `catalog-zones { zone "" ... }` statement and the corresponding slave zone declaration must match. -### TSIG Authentication -Following sets the TSIG key that allows clients to query the transfer endpoint and also the key to -be used to sign NOTIFY messages to clients on zone changes. Each view should have its own unique -key to allow the plugin to identify the view the client is trying to access. Re-using the key for -multiple views yields unpredicted behavior. -``` +### TSIG authentication + +The TSIG keys allow clients to query the transfer endpoint and are also used to sign NOTIFY +messages sent to clients on zone changes. Each view should have its own unique key so the plugin +can identify the view the client is trying to access. Reusing a key for multiple views yields +unpredictable behavior. + +```python 'tsig_keys': { 'the-view-name-here': { 'keyname': 'the-tsig-key-name-here', @@ -99,281 +213,145 @@ multiple views yields unpredicted behavior. } ``` +The `keyname`, `algorithm` and `secret` attributes form a dictionary under the following Python +structure path: + +``` +PLUGINS_CONFIG.netbox_dns_bridge.tsig_keys. +``` + ### NOTIFY + The plugin has 2 different NOTIFY mechanisms that may be turned on individually or together. -1. [Client Notify](#client-notify) - Notify clients that are regularly contacting the transfer endpoint for zone updates. +1. [Client NOTIFY](#client-notify) — notify clients that are regularly contacting the transfer + endpoint for zone updates. +2. [NS NOTIFY](#ns-notify) — notify the zone's NS servers when a zone changes. + - [Per zone](#ns-notify-per-zone) — for zones that have a specific custom field set to true. + - [For all zones](#ns-notify-for-all-zones) — for all zones. This makes the *per zone* + mechanism redundant; there is no point in enabling both. -2. [NS Notify](#ns-notify) - Notify the zone's NS Servers when a zone changes. +#### Global NOTIFY settings - - [Per Zone](#ns-notify-per-zone) - Notify NS servers for zones that have a specific custom field set to true. - - - [For all Zones](#ns-notify-for-all-zones) - Notify NS servers for all zones. - Note: This makes the *Per Zone* mechanism redundant. There is no point in enabling both. - -#### Global NOTIFY Settings ``` 'notify_over_tcp': True ``` -Switch to using TCP instead of UDP. Defaults to False + +Switch to using TCP instead of UDP. Defaults to `False`. #### Client NOTIFY -Clients may be notified of zone changes using the NOTIFY mechanism defined in RFC 1996. -When enabled, the zone transfer endpoint keeps track of any client that successfully queried the -endpoint. Once a zone has changed, NetBox informs each client about the zone changed so that the + +Clients may be notified of zone changes using the NOTIFY mechanism defined in RFC 1996. When +enabled, the zone transfer endpoint keeps track of any client that successfully queried the +endpoint. Once a zone has changed, NetBox informs each client that the zone changed so that the client can request a new zone transfer. -Note that this feature uses NetBox's background job system to schedule the messages asynchronously. -In order to work, you need at least one `rq-worker` service running in the background to handle -the queued jobs. +Note that this feature uses NetBox's background job system to schedule the messages +asynchronously. In order to work, you need at least one `rq-worker` service running in the +background to handle the queued jobs. ``` 'notify_clients': True ``` -This enables the NOTIFY system. Defaults to False + +This enables the NOTIFY system. Defaults to `False`. ``` 'notify_client_alive_threshold_hours': 24 ``` -This sets how long a client is considred "alive" after it last queried the transfer endpoint. -Once the client has failed to check in for this amout of time, it is automatically removed from the + +This sets how long a client is considered "alive" after it last queried the transfer endpoint. Once +the client has failed to check in for this amount of time, it is automatically removed from the list of clients to be notified on zone changes. Default is 24 hours. ``` 'notify_client_port': 53 ``` + Destination port used to send NOTIFY messages to clients. Defaults to 53. - - #### NS NOTIFY + In addition to notifying clients that queried the transfer endpoint, the plugin can send a NOTIFY directly to a zone's own nameservers whenever that zone's SOA serial number changes. This is useful -when you want nameservers to pull updates immediately, independent of the `notify_clients` mechanism. -Only a change of the SOA serial triggers this — other zone edits that leave the serial untouched do -not. +when you want nameservers to pull updates immediately, independent of the `notify_clients` +mechanism. Only a change of the SOA serial triggers this — other zone edits that leave the serial +untouched do not. -This can be enabled per zone, globally, or both. If neither of the settings below is configured, the -feature is disabled entirely. +This can be enabled per zone, globally, or both. If neither of the settings below is configured, +the feature is disabled entirely. +##### NS NOTIFY per zone -##### NS NOTIFY per Zone -This uses a True/False custom field attached to each Zone to enable/disable NOTIFY for each +This uses a True/False custom field attached to each zone to enable/disable NOTIFY for each individually. -Create a boolean custom field (e.g. `dns_bridge_notify_ns`) that applies -to `netbox_dns > zone`, then point the plugin at it: -``` +Create a boolean custom field (e.g. `dns_bridge_notify_ns`) that applies to `netbox_dns > zone`, +then point the plugin at it: + +```python 'notify_ns_custom_field_name': 'dns_bridge_notify_ns' ``` + A NOTIFY is then sent for any zone whose custom field is set to `True`. This lets you toggle the behavior per zone straight from the NetBox UI, without changing the plugin config. +##### NS NOTIFY for all zones -##### NS NOTIFY for all Zones ``` 'notify_ns_all_zones': True ``` + When enabled, a NOTIFY is sent for every zone on serial change, regardless of the custom field. -Defaults to `False`. The two options coexist: a NOTIFY is sent if the global switch is on **or** the -zone's custom field is set. +Defaults to `False`. The two options coexist: a NOTIFY is sent if the global switch is on **or** +the zone's custom field is set. - -##### NS NOTIFY Settings +##### NS NOTIFY settings The nameserver addresses are resolved from NetBox DNS itself by looking up active A/AAAA records -(within the zone's view) matching each nameserver's hostname. The NOTIFY messages are signed with the -same per-view TSIG key configured under `tsig_keys`, so the receiving nameservers must accept NOTIFY -signed with that key (e.g. BIND's `allow-notify { key "..."; };`). +(within the zone's view) matching each nameserver's hostname. The NOTIFY messages are signed with +the same per-view TSIG key configured under `tsig_keys`, so the receiving nameservers must accept +NOTIFY signed with that key (e.g. BIND's `allow-notify { key "..."; };`). ``` 'notify_ns_port': 53 ``` + Destination port used for these NOTIFY messages. Defaults to 53. As with the client NOTIFY feature, this uses NetBox's background job system, so at least one `rq-worker` service must be running. +## Running the transfer endpoint -## Plugin compatibility -This plugin extends the netbox-plugin-dns plugin. As such the versioning was changed to match the -one of netbox-plugin-dns more closely. To guarantee compatability, ensure that the major and minor -version match between both plugins. For example, when using netbox-plugin-dns `v1.5.5` install -netbox-plugin-dns-bridge `v1.5.x`. +To start the transfer endpoint in the foreground: +``` +manage.py dns-transfer-endpoint --port 5354 +``` -## 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). +| Parameter | Description | +| --------- | ----------- | +| `--port` | Port to listen on for requests (defaults to 5354) | +| `--address` | IP of interface to bind to (defaults to 0.0.0.0) | -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` +This process needs to run as a background service for the built-in DNS server to work correctly. +For Linux users with systemd (Ubuntu, etc), Matt Kollross provides a startup unit and instructions +in [docs/install-systemd-service.md](docs/install-systemd-service.md). Remember to activate the +venv when running the service in the background. -1. Preliminaries - - Install Bind9 on the same host that netbox is on. - - Generate a TSIG Key for the `public` and `private` dns views respectively. +## Notes and troubleshooting -2. Adding required package - ``` - cd netbox - echo netbox-plugin-dns-bridge >> 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_dns_bridge'] - ``` - - Configure the DNS Bridge Plugin using the PLUGINS_CONFIG dictionary. - Change - ``` - PLUGINS_CONFIG = {} - ``` - to - ``` - PLUGINS_CONFIG = { - "netbox_dns_bridge": { - "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_dns_bridge.tsig_keys. - ``` - This allows the plugin to map requests to the right dns view using the tsig - signature from each request. - -4. Run migrations - ``` - manage.py migrate - ``` - -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. A guide for setting up a systemd service on - Ubuntu is provided by Matt Kollross [here](docs/install-systemd-service.md). 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. - ``` - manage.py dns-transfer-endpoint --port 5354 - ``` - -6. Configuring a Bind9 to interact with NetBox via the dns-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 ########## - - options { - allow-update { none; }; - allow-query { any; }; - allow-recursion { none; }; - notify yes; - min-refresh-time 60; - }; - - ########## ACLs ########## - - acl public { - !10.0.0.0/8; - !172.16.0.0/12; - !192.168.0.0/16; - any; - }; - - acl private { - 10.0.0.0/8; - 172.16.0.0/12; - 192.168.0.0/16; - }; - - ######## TSIG Keys ######## - key "public_view_key" { - algorithm hmac-sha256; - secret "base64-encoded-secret"; - }; - - key "private_view_key" { - algorithm hmac-sha256; - secret "base64-encoded-secret"; - }; - ########################### - - - ########## ZONES ########## - view "public" { - match-clients { public; }; - allow-notify { key "public_view_key"; }; - - 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; - }; - }; - - view "private" { - match-clients { private; }; - allow-notify { key "private_view_key"; }; - - 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 +- **TSIG key reuse** — each view must have its own unique TSIG key. Reusing a key across multiple + views yields unpredictable behavior, since the plugin uses the key to map requests to views. +- **Catalog zone name mismatch** — the zone name configured on the consumer (e.g. BIND9's + `catalog-zones { zone "..." }` statement and the corresponding slave zone declaration) must match + the plugin's `catalog_zone_name` setting. +- **NS NOTIFY not firing** — NS NOTIFY is only triggered by a change of the zone's SOA serial + number. Other zone edits that leave the serial untouched do not trigger a NOTIFY. +- **NOTIFY jobs are not sent** — both NOTIFY mechanisms require at least one `rq-worker` service to + be running, since the messages are scheduled through NetBox's background job system. +## License +This project is licensed under the [MIT License](LICENSE.md). diff --git a/docs/architecture-overview.drawio b/docs/architecture-overview.drawio deleted file mode 100644 index 60bd606..0000000 --- a/docs/architecture-overview.drawio +++ /dev/null @@ -1,76 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/architecture-overview.svg b/docs/architecture-overview.svg deleted file mode 100644 index ad48af9..0000000 --- a/docs/architecture-overview.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
Netbox
DNS
IPAM
DHCP
(WIP)
Transfer
Endpoint
Dynamic Update
Endpoint
DNS Bridge
AXFR
DNS Server
(RFC9432)
Client
(RFC2136)
Update
 \ No newline at end of file diff --git a/docs/install-systemd-service.md b/docs/install-systemd-service.md index 86a1417..85a8106 100644 --- a/docs/install-systemd-service.md +++ b/docs/install-systemd-service.md @@ -1,4 +1,6 @@ -1. Create System Unit file +# NetBox DNS transfer endpoint systemd service + +1. Create a systemd unit file ``` cat < /etc/systemd/system/netbox-dns-endpoint.service [Unit] @@ -6,21 +8,21 @@ Documentation=https://github.com/Suraxius/netbox-plugin-dns-bridge After=network-online.target Wants=network-online.target - + [Service] Type=simple - + User=netbox Group=netbox PIDFile=/var/tmp/netbox.pid WorkingDirectory=/opt/netbox - + ExecStart=/opt/netbox/venv/bin/python3 /opt/netbox/netbox/manage.py dns-transfer-endpoint --address 0.0.0.0 --port 5354 - + Restart=on-failure RestartSec=30 PrivateTmp=true - + [Install] WantedBy=multi-user.target EOF diff --git a/docs/installation-guide.md b/docs/installation-guide.md new file mode 100644 index 0000000..031ac25 --- /dev/null +++ b/docs/installation-guide.md @@ -0,0 +1,192 @@ +# 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-dns-bridge >> local_requirements.txt +. venv/bin/activate +pip install -r local_requirements.txt +``` + +## 3. Updating netbox plugin configuration (configuration.py) + +Change the following line from + +``` +PLUGINS = ['netbox_dns'] +``` + +to + +``` +PLUGINS = ['netbox_dns', 'netbox_dns_bridge'] +``` + +Configure the DNS Bridge plugin using the `PLUGINS_CONFIG` dictionary. Change + +``` +PLUGINS_CONFIG = {} +``` + +to + +``` +PLUGINS_CONFIG = { + "netbox_dns_bridge": { + "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 the following +Python structure path: + +``` +PLUGINS_CONFIG.netbox_dns_bridge.tsig_keys. +``` + +This allows the plugin to map requests to the right DNS view using the TSIG signature from each +request. + +## 4. Run migrations + +``` +manage.py migrate +``` + +## 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. A guide for setting up a systemd service on Ubuntu is +provided in [install-systemd-service.md](install-systemd-service.md). Don't 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. + +``` +manage.py dns-transfer-endpoint --port 5354 +``` + +## 6. Configuring BIND9 + +Configure BIND9 to interact with NetBox via the dns-transfer-endpoint endpoint. Note that it is +not possible to give all the correct details of the `options` block as it is heavily dependent on +the operating system used. Please don't forget to adjust it as required. + +> **Note:** Since BIND 9.18, `type slave` is deprecated in favor of `type secondary` and +> `masters` in favor of `primaries`. Both still work, but newer deployments may prefer the new +> keywords. + +``` +########## OPTIONS ########## + +options { + allow-update { none; }; + allow-query { any; }; + allow-recursion { none; }; + notify yes; + min-refresh-time 60; +}; + +########## ACLs ########## + +acl public { + !10.0.0.0/8; + !172.16.0.0/12; + !192.168.0.0/16; + any; +}; + +acl private { + 10.0.0.0/8; + 172.16.0.0/12; + 192.168.0.0/16; +}; + +######## TSIG Keys ######## + +key "public_view_key" { + algorithm hmac-sha256; + secret "base64-encoded-secret"; +}; + +key "private_view_key" { + algorithm hmac-sha256; + secret "base64-encoded-secret"; +}; + +########## VIEWS & ZONES ########## + +view "public" { + match-clients { public; }; + allow-notify { key "public_view_key"; }; + + 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; + }; +}; + +view "private" { + match-clients { private; }; + allow-notify { key "private_view_key"; }; + + 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 BIND9 + +Restart BIND9 — done. The server will now discover zones in its views through the catalog zone and +transfer them from NetBox. diff --git a/pyproject.toml b/pyproject.toml index ff44e30..428dd9b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -32,5 +32,5 @@ where = ["."] version = { attr = "netbox_dns_bridge.__version__" } [project.urls] -Homepage = "https://github.com/Suraxius/netbox-plugin-bind-provisioner" -Issues = "https://github.com/Suraxius/netbox-plugin-bind-provisioner/issues" +Homepage = "https://github.com/Suraxius/netbox-plugin-dns-bridge" +Issues = "https://github.com/Suraxius/netbox-plugin-dns-bridge/issues"