netbox-plugin-dns-bridge/docs/installation-guide.md

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. 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.