Compare commits
6
Commits
v1.6.0-rc1
..
main
| Author | SHA1 | Date | |
|---|---|---|---|
 Sven Luthi
|
7536fc4e6c | ||
|
Sven Luthi
|
74d8e644d1 | ||
|
Sven Luethi
|
5999db72f9 | ||
 sven
|
3fa3cd6a01 | ||
|
sven
|
c15bdfca05 | ||
|
sven
|
fe24dbdd98 |
No files matched your search
@@ -0,0 +1,45 @@
|
|||||||
|
name: Publish Python package to PyPI
|
||||||
|
|
||||||
|
#on:
|
||||||
|
# push:
|
||||||
|
# tags:
|
||||||
|
# - "v*"
|
||||||
|
on:
|
||||||
|
release:
|
||||||
|
types: [published]
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
publish:
|
||||||
|
runs-on: self-hosted
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- name: Check out repository
|
||||||
|
uses: https://github.com/actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Create virtual environment
|
||||||
|
run: python3 -m venv .venv
|
||||||
|
|
||||||
|
- name: Install build tools
|
||||||
|
run: .venv/bin/pip install --upgrade build twine
|
||||||
|
|
||||||
|
- name: Verify tag matches package version
|
||||||
|
run: |
|
||||||
|
TAG="${GITHUB_REF_NAME}"
|
||||||
|
VERSION="$(grep -m1 '^version = ' pyproject.toml | cut -d '"' -f2)"
|
||||||
|
if [ "$TAG" != "v$VERSION" ]; then
|
||||||
|
echo "::error::Tag ${TAG} does not match package version v${VERSION}"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
- name: Build package
|
||||||
|
run: .venv/bin/python3 -m build
|
||||||
|
|
||||||
|
- name: Check package
|
||||||
|
run: .venv/bin/python3 -m twine check dist/*
|
||||||
|
|
||||||
|
- name: Publish to PyPI
|
||||||
|
env:
|
||||||
|
TWINE_USERNAME: __token__
|
||||||
|
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
|
||||||
|
TWINE_NON_INTERACTIVE: "1"
|
||||||
|
run: .venv/bin/python3 -m twine upload dist/*
|
||||||
File renamed without changes.
@@ -6,65 +6,204 @@ 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
|
These include zone transfers (RFC 5936), catalog zones (RFC 9432), and notifying clients about zone
|
||||||
changes (RFC 1996).
|
changes (RFC 1996).
|
||||||
|
|
||||||
<a href="https://pypi.org/project/netbox-plugin-dns-bridge/"><img src="https://img.shields.io/pypi/v/netbox-plugin-dns-bridge" alt="PyPi"></a>
|
<a href="https://pypi.org/project/netbox-plugin-dns-bridge/">
|
||||||
<a href="https://github.com/suraxius/netbox-plugin-dns-bridge/stargazers"><img src="https://img.shields.io/github/stars/suraxius/netbox-plugin-dns-bridge?style=flat" alt="Stars Badge"></a>
|
<img src="https://img.shields.io/pypi/v/netbox-plugin-dns-bridge" alt="PyPI">
|
||||||
<a href="https://github.com/suraxius/netbox-plugin-dns-bridge/network/members"><img src="https://img.shields.io/github/forks/suraxius/netbox-plugin-dns-bridge?style=flat" alt="Forks Badge"></a>
|
</a>
|
||||||
<a href="https://github.com/suraxius/netbox-plugin-dns-bridge/issues"><img src="https://img.shields.io/github/issues/suraxius/netbox-plugin-dns-bridge" alt="Issues Badge"></a>
|
<a href="https://github.com/Suraxius/netbox-plugin-dns-bridge/stargazers">
|
||||||
<a href="https://github.com/suraxius/netbox-plugin-dns-bridge/pulls"><img src="https://img.shields.io/github/issues-pr/suraxius/netbox-plugin-dns-bridge" alt="Pull Requests Badge"></a>
|
<img src="https://img.shields.io/github/stars/Suraxius/netbox-plugin-dns-bridge?style=flat" alt="Stars Badge">
|
||||||
<a href="https://github.com/suraxius/netbox-plugin-dns-bridge/graphs/contributors"><img src="https://img.shields.io/github/contributors/suraxius/netbox-plugin-dns-bridge?color=2b9348" alt="GitHub contributors"></a>
|
</a>
|
||||||
<a href="https://github.com/suraxius/netbox-plugin-dns-bridge/blob/master/LICENSE"><img src="https://img.shields.io/github/license/suraxius/netbox-plugin-dns-bridge?color=2b9348" alt="License Badge"></a>
|
<a href="https://github.com/Suraxius/netbox-plugin-dns-bridge/network/members">
|
||||||
<a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style Black"></a>
|
<img src="https://img.shields.io/github/forks/Suraxius/netbox-plugin-dns-bridge?style=flat" alt="Forks Badge">
|
||||||
<a href="https://pepy.tech/project/netbox-plugin-dns-bridge"><img src="https://static.pepy.tech/personalized-badge/netbox-plugin-dns-bridge?period=total&left_color=BLACK&right_color=BLUE&left_text=Downloads" alt="Downloads"></a>
|
</a>
|
||||||
<a href="https://pepy.tech/project/netbox-plugin-dns-bridge"><img src="https://static.pepy.tech/personalized-badge/netbox-plugin-dns-bridge?period=monthly&left_color=BLACK&right_color=BLUE&left_text=Downloads%2fMonth" alt="Downloads/Month"></a>
|
<a href="https://github.com/Suraxius/netbox-plugin-dns-bridge/issues">
|
||||||
<a href="https://pepy.tech/project/netbox-plugin-dns-bridge"><img src="https://static.pepy.tech/personalized-badge/netbox-plugin-dns-bridge?period=weekly&left_color=BLACK&right_color=BLUE&left_text=Downloads%2fWeek" alt="Downloads/Week"></a>
|
<img src="https://img.shields.io/github/issues/Suraxius/netbox-plugin-dns-bridge" alt="Issues Badge">
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/Suraxius/netbox-plugin-dns-bridge/pulls">
|
||||||
|
<img src="https://img.shields.io/github/issues-pr/Suraxius/netbox-plugin-dns-bridge" alt="Pull Requests Badge">
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/Suraxius/netbox-plugin-dns-bridge/graphs/contributors">
|
||||||
|
<img src="https://img.shields.io/github/contributors/Suraxius/netbox-plugin-dns-bridge?color=2b9348" alt="GitHub contributors">
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/Suraxius/netbox-plugin-dns-bridge/blob/master/LICENSE">
|
||||||
|
<img src="https://img.shields.io/github/license/suraxius/netbox-plugin-dns-bridge?color=2b9348" alt="License Badge">
|
||||||
|
</a>
|
||||||
|
<a href="https://github.com/psf/black">
|
||||||
|
<img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style Black">
|
||||||
|
</a>
|
||||||
|
<a href="https://pepy.tech/project/netbox-plugin-dns-bridge">
|
||||||
|
<img src="https://static.pepy.tech/personalized-badge/netbox-plugin-dns-bridge?period=total&left_color=BLACK&right_color=BLUE&left_text=Downloads" alt="Downloads">
|
||||||
|
</a>
|
||||||
|
<a href="https://pepy.tech/project/netbox-plugin-dns-bridge">
|
||||||
|
<img src="https://static.pepy.tech/personalized-badge/netbox-plugin-dns-bridge?period=monthly&left_color=BLACK&right_color=BLUE&left_text=Downloads%2fMonth" alt="Downloads/Month">
|
||||||
|
</a>
|
||||||
|
<a href="https://pepy.tech/project/netbox-plugin-dns-bridge">
|
||||||
|
<img src="https://static.pepy.tech/personalized-badge/netbox-plugin-dns-bridge?period=weekly&left_color=BLACK&right_color=BLUE&left_text=Downloads%2fWeek" alt="Downloads/Week">
|
||||||
|
</a>
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
# Plugin configuration
|
- [Overview](#overview)
|
||||||
While providing Zone transfers via AXFR, the Server also exposes specialized catalog zones that BIND
|
- [Compatibility](#compatibility)
|
||||||
and other RFC9432 compliant DNS Servers use to automatically discover newly created zones and remove
|
- [Requirements](#requirements)
|
||||||
deleted ones. The plugin supports views and basic DNS security via TSIG.
|
- [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. Each catalog zone is made available under the special
|
## Overview
|
||||||
zone name **"catz"** and addtionally under **"[viewname].catz"** and may be queried through the
|
|
||||||
built-in DNS server just like any other dns zone.
|
|
||||||
|
|
||||||
For proper operation, each view requires an installed TSIG key, and the `dns-transfer-endpoint` must
|
```mermaid
|
||||||
be running as a separate background service using the `manage.py` command. Note that DNSSEC support
|
flowchart LR
|
||||||
will be added once BIND9 provides a mechanism to configure it through the Catalog Zones system.
|
subgraph netbox ["NetBox"]
|
||||||
|
DNS[DNS]
|
||||||
|
QUEUE["Job Queue"]
|
||||||
|
subgraph bridge ["DNS Bridge"]
|
||||||
|
TE["Transfer<br/>Endpoint"]
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
To start the transfer endpoint service in the foreground:
|
DNSSRV["DNS Server<br/>(RFC 9432)<br/>e.g. BIND9"]
|
||||||
|
|
||||||
|
DNSSRV -- "AXFR (RFC 5936)<br/>Catalog Zone (RFC 9432)" --> TE
|
||||||
|
bridge -.->|"Listening for zone change signals"| DNS
|
||||||
|
bridge -- "Queue NOTIFY job on zone change" --> QUEUE
|
||||||
|
QUEUE -- "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
|
## Compatibility
|
||||||
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 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
|
| netbox-plugin-dns | netbox-plugin-dns-bridge |
|
||||||
Plugin settings should be configured under `PLUGINS_CONFIG` in `netbox_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 = {
|
PLUGINS_CONFIG = {
|
||||||
'netbox_dns_bridge': {
|
'netbox_dns_bridge': {
|
||||||
...
|
...
|
||||||
...
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### TSIG Authentication
|
### Settings reference
|
||||||
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
|
| Setting | Type | Default | Description |
|
||||||
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.
|
| `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: `<view>.<catalog_zone_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: `<view>.<catalog_zone_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,
|
||||||
|
...
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Note that the DNS server consuming the catalog zone must be configured with the same zone name,
|
||||||
|
e.g. BIND9's `catalog-zones { zone "<catalog_zone_name>" ... }` statement and the corresponding
|
||||||
|
slave zone declaration must match.
|
||||||
|
|
||||||
|
### 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': {
|
'tsig_keys': {
|
||||||
'the-view-name-here': {
|
'the-view-name-here': {
|
||||||
'keyname': 'the-tsig-key-name-here',
|
'keyname': 'the-tsig-key-name-here',
|
||||||
@@ -74,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.<dns_view_name>
|
||||||
|
```
|
||||||
|
|
||||||
### NOTIFY
|
### NOTIFY
|
||||||
|
|
||||||
The plugin has 2 different NOTIFY mechanisms that may be turned on individually or together.
|
The plugin has 2 different NOTIFY mechanisms that may be turned on individually or together.
|
||||||
|
|
||||||
1. [Client Notify](#client-notify)
|
1. [Client NOTIFY](#client-notify) — notify clients that are regularly contacting the transfer
|
||||||
Notify clients that are regularly contacting the transfer endpoint for zone updates.
|
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)
|
#### Global NOTIFY settings
|
||||||
Notify the zone's NS Servers when a zone changes.
|
|
||||||
|
|
||||||
- [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
|
'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
|
#### 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
|
Clients may be notified of zone changes using the NOTIFY mechanism defined in RFC 1996. When
|
||||||
endpoint. Once a zone has changed, NetBox informs each client about the zone changed so that the
|
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.
|
client can request a new zone transfer.
|
||||||
|
|
||||||
Note that this feature uses NetBox's background job system to schedule the messages asynchronously.
|
Note that this feature uses NetBox's background job system to schedule the messages
|
||||||
In order to work, you need at least one `rq-worker` service running in the background to handle
|
asynchronously. In order to work, you need at least one `rq-worker` service running in the
|
||||||
the queued jobs.
|
background to handle the queued jobs.
|
||||||
|
|
||||||
```
|
```
|
||||||
'notify_clients': True
|
'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
|
'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.
|
list of clients to be notified on zone changes. Default is 24 hours.
|
||||||
|
|
||||||
```
|
```
|
||||||
'notify_client_port': 53
|
'notify_client_port': 53
|
||||||
```
|
```
|
||||||
|
|
||||||
Destination port used to send NOTIFY messages to clients. Defaults to 53.
|
Destination port used to send NOTIFY messages to clients. Defaults to 53.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
#### NS NOTIFY
|
#### NS NOTIFY
|
||||||
|
|
||||||
In addition to notifying clients that queried the transfer endpoint, the plugin can send a 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
|
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.
|
when you want nameservers to pull updates immediately, independent of the `notify_clients`
|
||||||
Only a change of the SOA serial triggers this — other zone edits that leave the serial untouched do
|
mechanism. Only a change of the SOA serial triggers this — other zone edits that leave the serial
|
||||||
not.
|
untouched do not.
|
||||||
|
|
||||||
This can be enabled per zone, globally, or both. If neither of the settings below is configured, the
|
This can be enabled per zone, globally, or both. If neither of the settings below is configured,
|
||||||
feature is disabled entirely.
|
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.
|
individually.
|
||||||
|
|
||||||
Create a boolean custom field (e.g. `dns_bridge_notify_ns`) that applies
|
Create a boolean custom field (e.g. `dns_bridge_notify_ns`) that applies to `netbox_dns > zone`,
|
||||||
to `netbox_dns > zone`, then point the plugin at it:
|
then point the plugin at it:
|
||||||
```
|
|
||||||
|
```python
|
||||||
'notify_ns_custom_field_name': 'dns_bridge_notify_ns'
|
'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
|
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.
|
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
|
'notify_ns_all_zones': True
|
||||||
```
|
```
|
||||||
|
|
||||||
When enabled, a NOTIFY is sent for every zone on serial change, regardless of the custom field.
|
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
|
Defaults to `False`. The two options coexist: a NOTIFY is sent if the global switch is on **or**
|
||||||
zone's custom field is set.
|
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
|
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
|
(within the zone's view) matching each nameserver's hostname. The NOTIFY messages are signed with
|
||||||
same per-view TSIG key configured under `tsig_keys`, so the receiving nameservers must accept NOTIFY
|
the same per-view TSIG key configured under `tsig_keys`, so the receiving nameservers must accept
|
||||||
signed with that key (e.g. BIND's `allow-notify { key "..."; };`).
|
NOTIFY signed with that key (e.g. BIND's `allow-notify { key "..."; };`).
|
||||||
|
|
||||||
```
|
```
|
||||||
'notify_ns_port': 53
|
'notify_ns_port': 53
|
||||||
```
|
```
|
||||||
|
|
||||||
Destination port used for these NOTIFY messages. Defaults to 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
|
As with the client NOTIFY feature, this uses NetBox's background job system, so at least one
|
||||||
`rq-worker` service must be running.
|
`rq-worker` service must be running.
|
||||||
|
|
||||||
|
## Running the transfer endpoint
|
||||||
|
|
||||||
## Plugin compatibility
|
To start the transfer endpoint in the foreground:
|
||||||
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`.
|
|
||||||
|
|
||||||
|
```
|
||||||
|
manage.py dns-transfer-endpoint --port 5354
|
||||||
|
```
|
||||||
|
|
||||||
## Installation guide
|
| Parameter | Description |
|
||||||
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
|
| `--port` | Port to listen on for requests (defaults to 5354) |
|
||||||
of the NetBox host. TCP and UDP traffic from the BIND9 server to the NetBox host must be allowed on
|
| `--address` | IP of interface to bind to (defaults to 0.0.0.0) |
|
||||||
port 5354 (or the port you have configured).
|
|
||||||
|
|
||||||
This guide assumes:
|
This process needs to run as a background service for the built-in DNS server to work correctly.
|
||||||
- NetBox has been installed under /opt/netbox
|
For Linux users with systemd (Ubuntu, etc), Matt Kollross provides a startup unit and instructions
|
||||||
- Bind9 is installed on the same host as NetBox
|
in [docs/install-systemd-service.md](docs/install-systemd-service.md). Remember to activate the
|
||||||
- The NetBox DNS Plugin netbox-plugin-dns is installed
|
venv when running the service in the background.
|
||||||
- The following dns views exist in NetBox DNS:
|
|
||||||
- `public` (the default)
|
|
||||||
- `private`
|
|
||||||
|
|
||||||
1. Preliminaries
|
## Notes and troubleshooting
|
||||||
- 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
|
- **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.
|
||||||
cd netbox
|
- **Catalog zone name mismatch** — the zone name configured on the consumer (e.g. BIND9's
|
||||||
echo netbox-plugin-dns-bridge >> local_requirements.txt
|
`catalog-zones { zone "..." }` statement and the corresponding slave zone declaration) must match
|
||||||
. venv/bin/activate
|
the plugin's `catalog_zone_name` setting.
|
||||||
pip install -r local_requirements.txt
|
- **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
|
||||||
3. Updating netbox plugin configuration (configuration.py)
|
be running, since the messages are scheduled through NetBox's background job system.
|
||||||
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.<dns_view_name>
|
|
||||||
```
|
|
||||||
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
|
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is licensed under the [MIT License](LICENSE.md).
|
||||||
@@ -1,76 +0,0 @@
|
|||||||
<mxfile host="Electron" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/29.0.3 Chrome/140.0.7339.249 Electron/38.7.0 Safari/537.36" version="29.0.3">
|
|
||||||
<diagram name="Page-1" id="inkmD5hxPkRoHiEHOzAS">
|
|
||||||
<mxGraphModel dx="831" dy="2028" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
|
|
||||||
<root>
|
|
||||||
<mxCell id="0" />
|
|
||||||
<mxCell id="1" parent="0" />
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-24" value="" style="whiteSpace=wrap;html=1;aspect=fixed;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="560" y="457.5" width="80" height="80" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-13" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;fontColor=#333333;strokeColor=#666666;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="70" y="210" width="600" height="220" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-12" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="430" y="260" width="230" height="150" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-3" value="<font style="font-size: 18px;">Netbox</font>" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="80" y="220" width="60" height="30" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-4" value="DNS" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#dae8fc;strokeColor=#6c8ebf;rounded=1;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="300" y="260" width="100" height="100" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-6" value="IPAM" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#f8cecc;strokeColor=#b85450;gradientColor=none;rounded=1;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="80" y="260" width="100" height="100" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-7" value="DHCP<br>(WIP)" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#fff2cc;strokeColor=#d6b656;rounded=1;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="190" y="260" width="100" height="100" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="MSiTSJWh-g0ETCA7Z0x5-4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="WlUYMBEI5UY_wtPVGHlU-9" target="WlUYMBEI5UY_wtPVGHlU-4">
|
|
||||||
<mxGeometry relative="1" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-9" value="Transfer<br>Endpoint" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#d5e8d4;strokeColor=#82b366;rounded=1;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="440" y="300" width="100" height="100" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-10" value="Dynamic Update<br>Endpoint" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#d5e8d4;strokeColor=#82b366;rounded=1;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="550" y="300" width="100" height="100" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-11" value="DNS Bridge" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="440" y="270" width="90" height="30" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-18" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=none;endFill=0;startArrow=classic;startFill=1;" parent="1" source="WlUYMBEI5UY_wtPVGHlU-16" target="WlUYMBEI5UY_wtPVGHlU-9" edge="1">
|
|
||||||
<mxGeometry relative="1" as="geometry">
|
|
||||||
<Array as="points">
|
|
||||||
<mxPoint x="490" y="450" />
|
|
||||||
<mxPoint x="490" y="450" />
|
|
||||||
</Array>
|
|
||||||
</mxGeometry>
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-27" value="AXFR" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="WlUYMBEI5UY_wtPVGHlU-18" connectable="0" vertex="1">
|
|
||||||
<mxGeometry x="-0.2264" y="2" relative="1" as="geometry">
|
|
||||||
<mxPoint x="2" y="5" as="offset" />
|
|
||||||
</mxGeometry>
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-16" value="" style="whiteSpace=wrap;html=1;aspect=fixed;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="440" y="457.5" width="80" height="80" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-20" value="" style="whiteSpace=wrap;html=1;aspect=fixed;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="450" y="467.5" width="80" height="80" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-19" value="DNS Server<br>(RFC9432)" style="whiteSpace=wrap;html=1;aspect=fixed;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="460" y="477.5" width="80" height="80" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-23" value="" style="whiteSpace=wrap;html=1;aspect=fixed;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="570" y="467.5" width="80" height="80" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="WlUYMBEI5UY_wtPVGHlU-25" value="Client<br>(RFC2136)" style="whiteSpace=wrap;html=1;aspect=fixed;" parent="1" vertex="1">
|
|
||||||
<mxGeometry x="580" y="477.5" width="80" height="80" as="geometry" />
|
|
||||||
</mxCell>
|
|
||||||
<mxCell id="MSiTSJWh-g0ETCA7Z0x5-3" value="Update" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="WlUYMBEI5UY_wtPVGHlU-24" target="WlUYMBEI5UY_wtPVGHlU-10">
|
|
||||||
<mxGeometry x="-0.3913" relative="1" as="geometry">
|
|
||||||
<mxPoint y="1" as="offset" />
|
|
||||||
</mxGeometry>
|
|
||||||
</mxCell>
|
|
||||||
</root>
|
|
||||||
</mxGraphModel>
|
|
||||||
</diagram>
|
|
||||||
</mxfile>
|
|
||||||
@@ -1,4 +0,0 @@
|
|||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<!-- Do not edit this file with editors other than draw.io -->
|
|
||||||
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
|
|
||||||
<svg xmlns="http://www.w3.org/2000/svg" style="background: #ffffff; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); color-scheme: light dark;" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="601px" height="349px" viewBox="0 0 601 349" content="<mxfile host="Electron" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/29.0.3 Chrome/140.0.7339.249 Electron/38.7.0 Safari/537.36" version="29.0.3" scale="1" border="0"> <diagram name="Page-1" id="inkmD5hxPkRoHiEHOzAS"> <mxGraphModel dx="706" dy="1724" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0"> <root> <mxCell id="0" /> <mxCell id="1" parent="0" /> <mxCell id="WlUYMBEI5UY_wtPVGHlU-24" value="" style="whiteSpace=wrap;html=1;aspect=fixed;" parent="1" vertex="1"> <mxGeometry x="560" y="457.5" width="80" height="80" as="geometry" /> </mxCell> <mxCell id="WlUYMBEI5UY_wtPVGHlU-13" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;fontColor=#333333;strokeColor=#666666;" parent="1" vertex="1"> <mxGeometry x="70" y="210" width="600" height="220" as="geometry" /> </mxCell> <mxCell id="WlUYMBEI5UY_wtPVGHlU-12" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1"> <mxGeometry x="430" y="260" width="230" height="150" as="geometry" /> </mxCell> <mxCell id="WlUYMBEI5UY_wtPVGHlU-3" value="&lt;font style=&quot;font-size: 18px;&quot;&gt;Netbox&lt;/font&gt;" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;" parent="1" vertex="1"> <mxGeometry x="80" y="220" width="60" height="30" as="geometry" /> </mxCell> <mxCell id="WlUYMBEI5UY_wtPVGHlU-4" value="DNS" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#dae8fc;strokeColor=#6c8ebf;rounded=1;" parent="1" vertex="1"> <mxGeometry x="300" y="260" width="100" height="100" as="geometry" /> </mxCell> <mxCell id="WlUYMBEI5UY_wtPVGHlU-6" value="IPAM" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#f8cecc;strokeColor=#b85450;gradientColor=none;rounded=1;" parent="1" vertex="1"> <mxGeometry x="80" y="260" width="100" height="100" as="geometry" /> </mxCell> <mxCell id="WlUYMBEI5UY_wtPVGHlU-7" value="DHCP&lt;br&gt;(WIP)" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#fff2cc;strokeColor=#d6b656;rounded=1;" parent="1" vertex="1"> <mxGeometry x="190" y="260" width="100" height="100" as="geometry" /> </mxCell> <mxCell id="MSiTSJWh-g0ETCA7Z0x5-4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" parent="1" source="WlUYMBEI5UY_wtPVGHlU-9" target="WlUYMBEI5UY_wtPVGHlU-4" edge="1"> <mxGeometry relative="1" as="geometry" /> </mxCell> <mxCell id="WlUYMBEI5UY_wtPVGHlU-9" value="Transfer&lt;br&gt;Endpoint" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#d5e8d4;strokeColor=#82b366;rounded=1;" parent="1" vertex="1"> <mxGeometry x="440" y="300" width="100" height="100" as="geometry" /> </mxCell> <mxCell id="WlUYMBEI5UY_wtPVGHlU-10" value="Dynamic Update&lt;br&gt;Endpoint" style="whiteSpace=wrap;html=1;aspect=fixedLine truncated
|
|
||||||
|
Before Width: | Height: | Size: 112 KiB |
@@ -1,4 +1,6 @@
|
|||||||
1. Create System Unit file
|
# NetBox DNS transfer endpoint systemd service
|
||||||
|
|
||||||
|
1. Create a systemd unit file
|
||||||
```
|
```
|
||||||
cat <<EOF > /etc/systemd/system/netbox-dns-endpoint.service
|
cat <<EOF > /etc/systemd/system/netbox-dns-endpoint.service
|
||||||
[Unit]
|
[Unit]
|
||||||
|
|||||||
@@ -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.<dns_view_name>
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
@@ -1,7 +1,7 @@
|
|||||||
from netbox.plugins import PluginConfig
|
from netbox.plugins import PluginConfig
|
||||||
from django.conf import settings
|
from django.conf import settings
|
||||||
|
|
||||||
__version__ = "1.6.0-rc1"
|
__version__ = "1.7.0"
|
||||||
|
|
||||||
|
|
||||||
class DNSBridgeConfig(PluginConfig):
|
class DNSBridgeConfig(PluginConfig):
|
||||||
|
|||||||
+126
-158
@@ -12,14 +12,18 @@ from django.db import close_old_connections, OperationalError
|
|||||||
from netbox.jobs import JobRunner
|
from netbox.jobs import JobRunner
|
||||||
from netbox_dns.models import View, Zone, Record
|
from netbox_dns.models import View, Zone, Record
|
||||||
from netbox_dns_bridge.utils import get_logger
|
from netbox_dns_bridge.utils import get_logger
|
||||||
from netbox_dns_bridge.models import SeenTransferClient, CatalogZone
|
from netbox_dns_bridge.models import SeenTransferClient
|
||||||
|
|
||||||
LOGGER = get_logger(__name__)
|
LOGGER = get_logger(__name__)
|
||||||
SETTINGS = settings.PLUGINS_CONFIG.get("netbox_dns_bridge", {})
|
|
||||||
|
|
||||||
|
|
||||||
def _load_tsig_key(view_name: str) -> dns.tsig.Key:
|
class NotifyJobRunner(JobRunner):
|
||||||
tsig_keys = SETTINGS.get("tsig_keys", {})
|
"""Base class for NOTIFY jobs: shared plugin settings and helpers."""
|
||||||
|
|
||||||
|
SETTINGS = settings.PLUGINS_CONFIG.get("netbox_dns_bridge", {})
|
||||||
|
|
||||||
|
def load_tsig_key(self, view_name: str) -> dns.tsig.Key:
|
||||||
|
tsig_keys = self.SETTINGS.get("tsig_keys", {})
|
||||||
if view_name not in tsig_keys:
|
if view_name not in tsig_keys:
|
||||||
raise RuntimeError(f"No TSIG key configured for view '{view_name}'")
|
raise RuntimeError(f"No TSIG key configured for view '{view_name}'")
|
||||||
|
|
||||||
@@ -41,8 +45,8 @@ def _load_tsig_key(view_name: str) -> dns.tsig.Key:
|
|||||||
|
|
||||||
return dns.tsig.Key(name=key_name, secret=secret, algorithm=algorithm)
|
return dns.tsig.Key(name=key_name, secret=secret, algorithm=algorithm)
|
||||||
|
|
||||||
|
def send_notify(
|
||||||
def _send_notify(
|
self,
|
||||||
zone_name,
|
zone_name,
|
||||||
soa_serial,
|
soa_serial,
|
||||||
targets,
|
targets,
|
||||||
@@ -55,7 +59,7 @@ def _send_notify(
|
|||||||
soa_retry=10,
|
soa_retry=10,
|
||||||
soa_expire=1209600,
|
soa_expire=1209600,
|
||||||
soa_minimum=0,
|
soa_minimum=0,
|
||||||
):
|
):
|
||||||
"""Build a DNS NOTIFY message for *zone_name* and send it to every target IP."""
|
"""Build a DNS NOTIFY message for *zone_name* and send it to every target IP."""
|
||||||
fqdn = dns.name.from_text(zone_name, dns.name.root).to_text()
|
fqdn = dns.name.from_text(zone_name, dns.name.root).to_text()
|
||||||
msg = dns.message.make_query(fqdn, dns.rdatatype.SOA)
|
msg = dns.message.make_query(fqdn, dns.rdatatype.SOA)
|
||||||
@@ -88,99 +92,8 @@ def _send_notify(
|
|||||||
f" {view_name}/{fqdn} {soa_serial}: {e}"
|
f" {view_name}/{fqdn} {soa_serial}: {e}"
|
||||||
)
|
)
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
class SendClientNotify(JobRunner):
|
def get_soa_serial(zone: Zone):
|
||||||
class Meta:
|
|
||||||
name = "Send DNS NOTIFY"
|
|
||||||
|
|
||||||
def run(self, *args, **kwargs):
|
|
||||||
notify_over_tcp = SETTINGS.get("notify_over_tcp", False)
|
|
||||||
port = SETTINGS.get("notify_client_port", 53)
|
|
||||||
view_name = kwargs["view_name"]
|
|
||||||
zone_name = kwargs["zone_name"]
|
|
||||||
soa_serial = kwargs["soa_serial"]
|
|
||||||
soa_refresh = kwargs.get("soa_refresh", 60)
|
|
||||||
soa_retry = kwargs.get("soa_retry", 10)
|
|
||||||
soa_expire = kwargs.get("soa_expire", 1209600)
|
|
||||||
soa_minimum = kwargs.get("soa_minimum", 0)
|
|
||||||
|
|
||||||
try:
|
|
||||||
view = View.objects.get(name=view_name)
|
|
||||||
tsig_key = _load_tsig_key(view_name)
|
|
||||||
cutoff_hours = SETTINGS.get("notify_client_alive_threshold_hours", 24)
|
|
||||||
seen_cutoff = timezone.now() - timezone.timedelta(hours=cutoff_hours)
|
|
||||||
|
|
||||||
clients = list(
|
|
||||||
SeenTransferClient.objects.filter(
|
|
||||||
view=view, last_seen__gte=seen_cutoff
|
|
||||||
).values_list("source_ip", flat=True)
|
|
||||||
)
|
|
||||||
|
|
||||||
_send_notify(
|
|
||||||
zone_name, soa_serial, clients, tsig_key,
|
|
||||||
view_name, notify_over_tcp, port, log_prefix="NOTIFY",
|
|
||||||
soa_refresh=soa_refresh, soa_retry=soa_retry,
|
|
||||||
soa_expire=soa_expire, soa_minimum=soa_minimum,
|
|
||||||
)
|
|
||||||
|
|
||||||
except View.DoesNotExist as e:
|
|
||||||
LOGGER.error(f"Failed to get view for NOTIFY: {e}")
|
|
||||||
|
|
||||||
except OperationalError as e:
|
|
||||||
LOGGER.error(f"NOTIFY failed due to unexpected error: {e}")
|
|
||||||
close_old_connections()
|
|
||||||
|
|
||||||
|
|
||||||
class SendNSNotify(JobRunner):
|
|
||||||
"""Send a NOTIFY straight to a zone's own nameservers.
|
|
||||||
|
|
||||||
Unlike ``SendClientNotify`` (which notifies clients that previously queried
|
|
||||||
the transfer endpoint), this job resolves the addresses of the zone's
|
|
||||||
configured nameservers from NetBox DNS itself and notifies each of them so
|
|
||||||
they pick up the changed zone quickly.
|
|
||||||
"""
|
|
||||||
|
|
||||||
class Meta:
|
|
||||||
name = "Send DNS NOTIFY to zone nameservers"
|
|
||||||
|
|
||||||
def run(self, *args, **kwargs):
|
|
||||||
notify_over_tcp = SETTINGS.get("notify_over_tcp", False)
|
|
||||||
port = SETTINGS.get("notify_ns_port", 53)
|
|
||||||
view_name = kwargs["view_name"]
|
|
||||||
zone_name = kwargs["zone_name"]
|
|
||||||
soa_serial = kwargs["soa_serial"]
|
|
||||||
|
|
||||||
try:
|
|
||||||
zone = Zone.objects.get(pk=kwargs["zone_id"])
|
|
||||||
except Zone.DoesNotExist:
|
|
||||||
LOGGER.error(f"NS NOTIFY: zone id {kwargs['zone_id']} no longer exists")
|
|
||||||
return
|
|
||||||
except OperationalError as e:
|
|
||||||
LOGGER.error(f"NS NOTIFY failed due to unexpected error: {e}")
|
|
||||||
close_old_connections()
|
|
||||||
return
|
|
||||||
|
|
||||||
ns_targets = _resolve_zone_nameserver_ips(zone)
|
|
||||||
if not ns_targets:
|
|
||||||
LOGGER.warning(
|
|
||||||
f"NS NOTIFY: no nameserver addresses found in NetBox DNS for "
|
|
||||||
f"{view_name}/{zone_name} — skipping"
|
|
||||||
)
|
|
||||||
return
|
|
||||||
|
|
||||||
try:
|
|
||||||
tsig_key = _load_tsig_key(view_name)
|
|
||||||
except RuntimeError as e:
|
|
||||||
LOGGER.error(f"NS NOTIFY aborted for {view_name}/{zone_name}: {e}")
|
|
||||||
return
|
|
||||||
|
|
||||||
_send_notify(
|
|
||||||
zone_name, soa_serial, ns_targets, tsig_key,
|
|
||||||
view_name, notify_over_tcp, port, log_prefix="NS NOTIFY",
|
|
||||||
)
|
|
||||||
|
|
||||||
|
|
||||||
def _get_soa_serial(zone: Zone):
|
|
||||||
"""Return the current SOA serial of a zone parsed from its SOA record."""
|
"""Return the current SOA serial of a zone parsed from its SOA record."""
|
||||||
try:
|
try:
|
||||||
soa_record = Record.objects.filter(zone=zone, type="SOA", active=True).first()
|
soa_record = Record.objects.filter(zone=zone, type="SOA", active=True).first()
|
||||||
@@ -199,7 +112,115 @@ def _get_soa_serial(zone: Zone):
|
|||||||
return None
|
return None
|
||||||
|
|
||||||
|
|
||||||
def _resolve_zone_nameserver_ips(zone: Zone) -> list:
|
class SendClientNotify(NotifyJobRunner):
|
||||||
|
class Meta:
|
||||||
|
name = "Send DNS NOTIFY"
|
||||||
|
|
||||||
|
def run(self, *args, **kwargs):
|
||||||
|
notify_over_tcp = self.SETTINGS.get("notify_over_tcp", False)
|
||||||
|
port = self.SETTINGS.get("notify_client_port", 53)
|
||||||
|
view_name = kwargs["view_name"]
|
||||||
|
zone_name = kwargs["zone_name"]
|
||||||
|
soa_serial = kwargs["soa_serial"]
|
||||||
|
soa_refresh = kwargs.get("soa_refresh", 60)
|
||||||
|
soa_retry = kwargs.get("soa_retry", 10)
|
||||||
|
soa_expire = kwargs.get("soa_expire", 1209600)
|
||||||
|
soa_minimum = kwargs.get("soa_minimum", 0)
|
||||||
|
|
||||||
|
try:
|
||||||
|
view = View.objects.get(name=view_name)
|
||||||
|
tsig_key = self.load_tsig_key(view_name)
|
||||||
|
cutoff_hours = self.SETTINGS.get("notify_client_alive_threshold_hours", 24)
|
||||||
|
seen_cutoff = timezone.now() - timezone.timedelta(hours=cutoff_hours)
|
||||||
|
|
||||||
|
clients = list(
|
||||||
|
SeenTransferClient.objects.filter(
|
||||||
|
view=view, last_seen__gte=seen_cutoff
|
||||||
|
).values_list("source_ip", flat=True)
|
||||||
|
)
|
||||||
|
|
||||||
|
self.send_notify(
|
||||||
|
zone_name, soa_serial, clients, tsig_key,
|
||||||
|
view_name, notify_over_tcp, port, log_prefix="NOTIFY",
|
||||||
|
soa_refresh=soa_refresh, soa_retry=soa_retry,
|
||||||
|
soa_expire=soa_expire, soa_minimum=soa_minimum,
|
||||||
|
)
|
||||||
|
|
||||||
|
except View.DoesNotExist as e:
|
||||||
|
LOGGER.error(f"Failed to get view for NOTIFY: {e}")
|
||||||
|
|
||||||
|
except OperationalError as e:
|
||||||
|
LOGGER.error(f"NOTIFY failed due to unexpected error: {e}")
|
||||||
|
close_old_connections()
|
||||||
|
|
||||||
|
|
||||||
|
class SendNSNotify(NotifyJobRunner):
|
||||||
|
"""Send a NOTIFY straight to a zone's own nameservers.
|
||||||
|
|
||||||
|
Unlike ``SendClientNotify`` (which notifies clients that previously queried
|
||||||
|
the transfer endpoint), this job resolves the addresses of the zone's
|
||||||
|
configured nameservers from NetBox DNS itself and notifies each of them so
|
||||||
|
they pick up the changed zone quickly.
|
||||||
|
"""
|
||||||
|
|
||||||
|
class Meta:
|
||||||
|
name = "Send DNS NOTIFY to zone nameservers"
|
||||||
|
|
||||||
|
def run(self, *args, **kwargs):
|
||||||
|
notify_over_tcp = self.SETTINGS.get("notify_over_tcp", False)
|
||||||
|
port = self.SETTINGS.get("notify_ns_port", 53)
|
||||||
|
view_name = kwargs["view_name"]
|
||||||
|
zone_name = kwargs["zone_name"]
|
||||||
|
soa_serial = kwargs["soa_serial"]
|
||||||
|
|
||||||
|
try:
|
||||||
|
zone = Zone.objects.get(pk=kwargs["zone_id"])
|
||||||
|
except Zone.DoesNotExist:
|
||||||
|
LOGGER.error(f"NS NOTIFY: zone id {kwargs['zone_id']} no longer exists")
|
||||||
|
return
|
||||||
|
except OperationalError as e:
|
||||||
|
LOGGER.error(f"NS NOTIFY failed due to unexpected error: {e}")
|
||||||
|
close_old_connections()
|
||||||
|
return
|
||||||
|
|
||||||
|
ns_targets = self.resolve_zone_nameserver_ips(zone)
|
||||||
|
if not ns_targets:
|
||||||
|
LOGGER.warning(
|
||||||
|
f"NS NOTIFY: no nameserver addresses found in NetBox DNS for "
|
||||||
|
f"{view_name}/{zone_name} — skipping"
|
||||||
|
)
|
||||||
|
return
|
||||||
|
|
||||||
|
try:
|
||||||
|
tsig_key = self.load_tsig_key(view_name)
|
||||||
|
except RuntimeError as e:
|
||||||
|
LOGGER.error(f"NS NOTIFY aborted for {view_name}/{zone_name}: {e}")
|
||||||
|
return
|
||||||
|
|
||||||
|
self.send_notify(
|
||||||
|
zone_name, soa_serial, ns_targets, tsig_key,
|
||||||
|
view_name, notify_over_tcp, port, log_prefix="NS NOTIFY",
|
||||||
|
)
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def notify_ns_enabled(cls, zone) -> bool:
|
||||||
|
"""Return True if a NOTIFY to the zone's nameservers should be sent.
|
||||||
|
|
||||||
|
Enabled either globally for every zone via ``notify_ns_all_zones`` or per
|
||||||
|
zone when the boolean custom field named by ``notify_ns_custom_field_name``
|
||||||
|
is set to True on the zone.
|
||||||
|
"""
|
||||||
|
if cls.SETTINGS.get("notify_ns_all_zones", False):
|
||||||
|
return True
|
||||||
|
|
||||||
|
cf_name = cls.SETTINGS.get("notify_ns_custom_field_name")
|
||||||
|
if not cf_name:
|
||||||
|
return False
|
||||||
|
|
||||||
|
custom_fields = getattr(zone, "custom_field_data", None) or {}
|
||||||
|
return custom_fields.get(cf_name) is True
|
||||||
|
|
||||||
|
def resolve_zone_nameserver_ips(self, zone: Zone) -> list:
|
||||||
"""Resolve the zone's nameserver hostnames to IPs using NetBox DNS records.
|
"""Resolve the zone's nameserver hostnames to IPs using NetBox DNS records.
|
||||||
|
|
||||||
For each nameserver assigned to the zone, matching active A/AAAA records
|
For each nameserver assigned to the zone, matching active A/AAAA records
|
||||||
@@ -234,29 +255,11 @@ def _resolve_zone_nameserver_ips(zone: Zone) -> list:
|
|||||||
return ips
|
return ips
|
||||||
|
|
||||||
|
|
||||||
def _notify_ns_enabled(zone) -> bool:
|
|
||||||
"""Return True if a NOTIFY to the zone's nameservers should be sent.
|
|
||||||
|
|
||||||
Enabled either globally for every zone via ``notify_ns_all_zones`` or per
|
|
||||||
zone when the boolean custom field named by ``notify_ns_custom_field_name``
|
|
||||||
is set to True on the zone.
|
|
||||||
"""
|
|
||||||
if SETTINGS.get("notify_ns_all_zones", False):
|
|
||||||
return True
|
|
||||||
|
|
||||||
cf_name = SETTINGS.get("notify_ns_custom_field_name")
|
|
||||||
if not cf_name:
|
|
||||||
return False
|
|
||||||
|
|
||||||
custom_fields = getattr(zone, "custom_field_data", None) or {}
|
|
||||||
return custom_fields.get(cf_name) is True
|
|
||||||
|
|
||||||
|
|
||||||
def schedule_client_notify(zone: Zone):
|
def schedule_client_notify(zone: Zone):
|
||||||
if not SETTINGS.get("notify_clients", False):
|
if not SendClientNotify.SETTINGS.get("notify_clients", False):
|
||||||
return
|
return
|
||||||
|
|
||||||
soa_serial = _get_soa_serial(zone)
|
soa_serial = SendClientNotify.get_soa_serial(zone)
|
||||||
if soa_serial is None:
|
if soa_serial is None:
|
||||||
return
|
return
|
||||||
|
|
||||||
@@ -268,10 +271,10 @@ def schedule_client_notify(zone: Zone):
|
|||||||
|
|
||||||
|
|
||||||
def schedule_ns_notify(zone: Zone):
|
def schedule_ns_notify(zone: Zone):
|
||||||
if not _notify_ns_enabled(zone):
|
if not SendNSNotify.notify_ns_enabled(zone):
|
||||||
return
|
return
|
||||||
|
|
||||||
soa_serial = _get_soa_serial(zone)
|
soa_serial = SendNSNotify.get_soa_serial(zone)
|
||||||
if soa_serial is None:
|
if soa_serial is None:
|
||||||
return
|
return
|
||||||
|
|
||||||
@@ -281,38 +284,3 @@ def schedule_ns_notify(zone: Zone):
|
|||||||
view_name=zone.view.name,
|
view_name=zone.view.name,
|
||||||
soa_serial=soa_serial,
|
soa_serial=soa_serial,
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
def schedule_catalog_zone_notify(view: View):
|
|
||||||
if not SETTINGS.get("notify_clients", False):
|
|
||||||
return
|
|
||||||
|
|
||||||
try:
|
|
||||||
catalog_zone = view.catalog_zone
|
|
||||||
except CatalogZone.DoesNotExist:
|
|
||||||
return
|
|
||||||
|
|
||||||
serial = catalog_zone.soa_serial
|
|
||||||
soa_refresh = catalog_zone.soa_refresh
|
|
||||||
soa_retry = catalog_zone.soa_retry
|
|
||||||
soa_expire = catalog_zone.soa_expire
|
|
||||||
soa_minimum = catalog_zone.soa_minimum
|
|
||||||
|
|
||||||
SendClientNotify.enqueue(
|
|
||||||
zone_name="catz",
|
|
||||||
soa_serial=serial,
|
|
||||||
view_name=view.name,
|
|
||||||
soa_refresh=soa_refresh,
|
|
||||||
soa_retry=soa_retry,
|
|
||||||
soa_expire=soa_expire,
|
|
||||||
soa_minimum=soa_minimum,
|
|
||||||
)
|
|
||||||
SendClientNotify.enqueue(
|
|
||||||
zone_name=f"{view.name}.catz",
|
|
||||||
soa_serial=serial,
|
|
||||||
view_name=view.name,
|
|
||||||
soa_refresh=soa_refresh,
|
|
||||||
soa_retry=soa_retry,
|
|
||||||
soa_expire=soa_expire,
|
|
||||||
soa_minimum=soa_minimum,
|
|
||||||
)
|
|
||||||
+57
-5
@@ -8,11 +8,37 @@ from netbox_dns_bridge.models import CatalogZone, CatalogZoneMember
|
|||||||
from netbox_dns_bridge.jobs import notify
|
from netbox_dns_bridge.jobs import notify
|
||||||
from uuid import uuid4
|
from uuid import uuid4
|
||||||
from base64 import b32encode
|
from base64 import b32encode
|
||||||
|
from django.conf import settings
|
||||||
from django.db import transaction, close_old_connections, OperationalError
|
from django.db import transaction, close_old_connections, OperationalError
|
||||||
|
|
||||||
|
|
||||||
LOGGER = get_logger(__name__)
|
LOGGER = get_logger(__name__)
|
||||||
|
|
||||||
|
SETTINGS = settings.PLUGINS_CONFIG.get("netbox_dns_bridge", {})
|
||||||
|
|
||||||
|
|
||||||
|
def catalog_zone_name(view_name: str) -> dns.name.Name:
|
||||||
|
"""Return the fully qualified catalog zone name for a view as a
|
||||||
|
dns.name.Name.
|
||||||
|
|
||||||
|
The name is configured via the ``catalog_zone_name`` setting (fallback:
|
||||||
|
``catz``). With ``catalog_zone_name_includes_view`` enabled, the view
|
||||||
|
name is prepended: ``<view>.<catalog_zone_name>``.
|
||||||
|
"""
|
||||||
|
base = dns.name.from_text(SETTINGS.get("catalog_zone_name") or "catz")
|
||||||
|
if SETTINGS.get("catalog_zone_name_includes_view", False):
|
||||||
|
return dns.name.from_text(view_name, origin=base)
|
||||||
|
return base
|
||||||
|
|
||||||
|
|
||||||
|
def is_catalog_zone_query(qname: dns.name.Name, view_name: str) -> bool:
|
||||||
|
"""Check whether a queried name is the catalog zone name of a view.
|
||||||
|
|
||||||
|
dns.name.Name equality is case-insensitive, so queries from BIND match
|
||||||
|
regardless of case.
|
||||||
|
"""
|
||||||
|
return qname == catalog_zone_name(view_name)
|
||||||
|
|
||||||
|
|
||||||
def increment_soa_serial(view: NBView) -> int:
|
def increment_soa_serial(view: NBView) -> int:
|
||||||
with transaction.atomic():
|
with transaction.atomic():
|
||||||
@@ -47,13 +73,13 @@ def increment_soa_serial(view: NBView) -> int:
|
|||||||
close_old_connections()
|
close_old_connections()
|
||||||
return None
|
return None
|
||||||
|
|
||||||
notify.schedule_catalog_zone_notify(view)
|
schedule_catalog_zone_notify(view)
|
||||||
return serial
|
return serial
|
||||||
|
|
||||||
|
|
||||||
def create_zone(name, view_name) -> dns.zone.Zone:
|
def create_zone(view_name) -> dns.zone.Zone:
|
||||||
# Zone origin
|
# Zone origin: the configured catalog zone name for this view
|
||||||
origin = dns.name.from_text(name, dns.name.root)
|
origin = catalog_zone_name(view_name)
|
||||||
|
|
||||||
# Create a new empty zone
|
# Create a new empty zone
|
||||||
zone = dns.zone.Zone(origin)
|
zone = dns.zone.Zone(origin)
|
||||||
@@ -117,7 +143,7 @@ def create_zone(name, view_name) -> dns.zone.Zone:
|
|||||||
ns_rdataset = _create_ns_rdataset()
|
ns_rdataset = _create_ns_rdataset()
|
||||||
zone_root_node.rdatasets.append(ns_rdataset)
|
zone_root_node.rdatasets.append(ns_rdataset)
|
||||||
|
|
||||||
# version.catz. record
|
# version.<catalog zone name>. record
|
||||||
version_rdataset = _create_version_rdataset()
|
version_rdataset = _create_version_rdataset()
|
||||||
zone_version_node = zone.find_node(
|
zone_version_node = zone.find_node(
|
||||||
dns.name.from_text("version", origin), create=True
|
dns.name.from_text("version", origin), create=True
|
||||||
@@ -158,6 +184,32 @@ def update_member(zone: NBZone) -> None:
|
|||||||
close_old_connections()
|
close_old_connections()
|
||||||
|
|
||||||
|
|
||||||
|
def schedule_catalog_zone_notify(view: NBView) -> None:
|
||||||
|
"""Schedule a NOTIFY for the catalog zone of a view.
|
||||||
|
|
||||||
|
Notifies transfer clients for the single configured catalog zone name
|
||||||
|
(see ``catalog_zone_name``). The job receives the name as text, since
|
||||||
|
job kwargs are serialized to JSON.
|
||||||
|
"""
|
||||||
|
if not SETTINGS.get("notify_clients", False):
|
||||||
|
return
|
||||||
|
|
||||||
|
try:
|
||||||
|
catalog_zone = view.catalog_zone
|
||||||
|
except CatalogZone.DoesNotExist:
|
||||||
|
return
|
||||||
|
|
||||||
|
notify.SendClientNotify.enqueue(
|
||||||
|
zone_name=catalog_zone_name(view.name).to_text(omit_final_dot=True),
|
||||||
|
soa_serial=catalog_zone.soa_serial,
|
||||||
|
view_name=view.name,
|
||||||
|
soa_refresh=catalog_zone.soa_refresh,
|
||||||
|
soa_retry=catalog_zone.soa_retry,
|
||||||
|
soa_expire=catalog_zone.soa_expire,
|
||||||
|
soa_minimum=catalog_zone.soa_minimum,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
def _create_soa_rdataset(view: NBView) -> dns.rdataset:
|
def _create_soa_rdataset(view: NBView) -> dns.rdataset:
|
||||||
try:
|
try:
|
||||||
serial_obj, _ = CatalogZone.objects.get_or_create(
|
serial_obj, _ = CatalogZone.objects.get_or_create(
|
||||||
|
|||||||
@@ -289,9 +289,8 @@ class DNSBaseRequestHandler(socketserver.BaseRequestHandler):
|
|||||||
return
|
return
|
||||||
|
|
||||||
# Check if catalog zone
|
# Check if catalog zone
|
||||||
dname_lower = dname.lower()
|
if catzm.is_catalog_zone_query(qname, nb_view.name):
|
||||||
if dname_lower == "catz" or dname_lower == f"{nb_view.name.lower()}.catz":
|
zone = catzm.create_zone(nb_view.name)
|
||||||
zone = catzm.create_zone(dname_lower, nb_view.name)
|
|
||||||
else:
|
else:
|
||||||
zone = self._get_zone_from_nb(dname, nb_view.name)
|
zone = self._get_zone_from_nb(dname, nb_view.name)
|
||||||
# When zone was not found, let client know
|
# When zone was not found, let client know
|
||||||
|
|||||||
+2
-2
@@ -32,5 +32,5 @@ where = ["."]
|
|||||||
version = { attr = "netbox_dns_bridge.__version__" }
|
version = { attr = "netbox_dns_bridge.__version__" }
|
||||||
|
|
||||||
[project.urls]
|
[project.urls]
|
||||||
Homepage = "https://github.com/Suraxius/netbox-plugin-bind-provisioner"
|
Homepage = "https://github.com/Suraxius/netbox-plugin-dns-bridge"
|
||||||
Issues = "https://github.com/Suraxius/netbox-plugin-bind-provisioner/issues"
|
Issues = "https://github.com/Suraxius/netbox-plugin-dns-bridge/issues"
|
||||||
Reference in new issue
Block a user