sven/netbox-plugin-dns-bridge
0
0 Fork 0
Code Actions Packages Releases Wiki Activity

modified: README.md

Browse Source
This commit is contained in:
Sven Luethi committed 2025-11-17 22:44:06 +01:00
1 parent 86457cc858
commit 8c1e9502f4
1 file changed
+176 -101
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+176 -101
View File
@@ -1,30 +1,39 @@
# Netbox Bind Provisioner # Netbox Bind Provisioner
A Netbox Plugin that provides a minimal DNS Server for the automatic A NetBox plugin that implements a lightweight DNS server to automate the
provisioning of a Bind9 Server from Netbox DNS data (netbox-plugin-dns). provisioning and configuration of a BIND9 server based on DNS records
maintained in NetBox. (netbox-plugin-dns).
## Plugin configuration ## Plugin configuration
The plugin was re-worked; Instead of exporting zone files, it provides an The plugin has been reworked: instead of exporting zone files, it now provides
entire (though minimal) DNS Server that is fed directly from Netbox's DNS data. a minimal DNS server that is fed directly from NetBox’s DNS data. This server
The Server also provides specialized "catalog" zones that bind uses to also exposes specialized catalog zones that BIND uses to automatically discover
automatically discover new zones and remove deleted ones. The plugin supports newly created zones and remove deleted ones. The plugin supports BIND views and
view as well as basic dns security using TSIG. basic DNS security via TSIG.
To work correctly, each view needs a tsig key installed and the The plugin exposes one catalog zone per view. Each catalog zone is available
bind-transfer-endpoint needs to be running as its own service in the background under the special zone name **"catz"** and can be queried through the built-in
via the `manage.py` command. Note that dnssec support will be implemented as DNS server like any other zone.
soon as bind9 has a mechanism to allow configuration of such via the Catalog
Zones mechanism.
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 manage.py bind-transfer-endpoint --port 5354
``` ```
The plugin also currently needs a file that tracks the current state of the The plugin currently requires a file to track the SOA serial of the catalog zone.
catalog zone's SOA serial. The serial represents the catalog zone's SOA record This serial represents the SOA record’s version number and allows downstream
serial number and is used by downstream DNS Servers to determine if the catalog DNS servers to determine when the catalog zone has changed (for example,
zone was updated (e.g. if a zone is added/modified/removed from netbox). when a zone is added, modified, or removed in NetBox). The file ensures the
The file is used to persist the SOA record's serial across service restarts. serial persists across service restarts. It will be replaced with a
It will be replaced by a database entry once the plugin has its own models. 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 ### Service parameters
Parameter | Description Parameter | Description
@@ -38,104 +47,170 @@ Setting | Description
catalog_serial_file | The catalog serial counter. The file needs to be writable. 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. tsig_keys | Maps a TSIG Key to be used for each view.
### Plugin example configuration ## Installation guide
``` This setup provisions a BIND9 server directly with DNS data from NetBox.
PLUGINS_CONFIG = { BIND9 can optionally run on a separate server. If so, any reference to
"netbox_bind_provisioner": { 127.0.0.1 in step 6 must be replaced with the IP address of the NetBox host.
"catalog_serial_file": "/opt/netbox/catalog-serial.txt", TCP and UDP traffic from the BIND9 server to the NetBox host must be allowed on
"tsig_keys": { port 5354 (or the port you have configured).
"key1name": {
"view": "public", This guide assumes:
"keyname": "view1key", - Netbox has been installed under /opt/netbox
"algorithm": "hmac-sha256", - Bind9 is installed on the same host as Netbox
"secret": "base64-encoded-secret" - The Netbox DNS Plugin netbox-plugin-dns is installed
}, - The following dns views exist in Netbox DNS:
"key2name": { - `public` (the default)
"view": "private", - `private`
"keyname": "view2key",
"algorithm": "hmac-sha256", 1. Preliminaries
"secret": "base64-encoded-secret" - 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.<dns_view_name>
```
This allows the plugin to map requests to the right dns view using the tsig
signature from each request.
## Bind example configuration 4. Run migrations (This step is not yet required. Just adding for completeness)
``` ```
options { python3 netbox/manage.py migrate
... ```
...
allow-update { none; };
allow-query { any; };
allow-recursion { none; };
notify yes;
min-refresh-time 60;
...
...
};
# 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 { 6. Configuring a Bind9 to interact with Netbox via the bind-transfer-endpoint
!10.0.0.0/8; endpoint. Note that its not possible to give all the correct details of the
!172.16.0.0/12; `options` block as it is heavily dependent on the Operating System used.
!192.168.0.0/16; Please dont forget to adjust as required.
any;
}; ```
########## OPTIONS ##########
acl private { options {
10.0.0.0/8; allow-update { none; };
172.16.0.0/12; allow-query { any; };
192.168.0.0/16; allow-recursion { none; };
}; notify yes;
min-refresh-time 60;
# Zone definitions
view "public" {
key "key1name" {
algorithm hmac-sha256;
secret "base64-encoded-secret";
}; };
match-clients { public; }; ########## ACLs ##########
catalog-zones { acl public {
zone "catz" !10.0.0.0/8;
default-masters { 127.0.0.1 port 5354 key "key1name"; } !172.16.0.0/12;
zone-directory "/var/lib/bind/zones" !192.168.0.0/16;
min-update-interval 1; any;
}; };
zone "catz" { acl private {
type slave; 10.0.0.0/8;
file "/var/lib/bind/zones/catz_public"; 172.16.0.0/12;
masters { 127.0.0.1 port 5354 key "key1name"; }; 192.168.0.0/16;
notify no;
};
};
view "private" {
key "key2name" {
algorithm hmac-sha256;
secret "base64-encoded-secret";
}; };
match-clients { private; }; ########## ZONES ##########
catalog-zones { view "public" {
zone "catz" key "public_view_key" {
default-masters { 127.0.0.1 port 5354 key "key2name"; } algorithm hmac-sha256;
zone-directory "/var/lib/bind/zones" secret "base64-encoded-secret";
min-update-interval 1; };
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" { view "private" {
type slave; key "private_view_key" {
file "/var/lib/bind/zones/catz_private"; algorithm hmac-sha256;
masters { 127.0.0.1 port 5354 key "key2name"; }; secret "base64-encoded-secret";
notify no; };
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