Metadata-Version: 2.4
Name: netbox-plugin-bind-provisioner
Version: 1.0.7
Summary: A Bind provisioning plugin that uses netbox_dns for its data source
Author: Sven Luethi
License: GPL-2.0
Project-URL: Homepage, https://github.com/Suraxius/netbox-plugin-bind-provisioner
Project-URL: Issues, https://github.com/Suraxius/netbox-plugin-bind-provisioner/issues
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: netbox-plugin-dns
Dynamic: license-file

# Netbox Bind Provisioner
The Netbox Bind Provisioner plugin implements a lightweight DNS server inside
Netbox and builds a bridge for BIND and other DNS Servers implementing RFC9432
to retrieve DNS Zones directly from Netbox using DNS native mechanisms.

[![PyPi](https://img.shields.io/pypi/v/netbox-plugin-bind-provisioner)](https://pypi.org/project/netbox-plugin-bind-provisioner/)
[![Stars Badge](https://img.shields.io/github/stars/suraxius/netbox-plugin-bind-provisioner?style=flat)](https://github.com/suraxius/netbox-plugin-bind-provisioner/stargazers)
[![Forks Badge](https://img.shields.io/github/forks/suraxius/netbox-plugin-bind-provisioner?style=flat)](https://github.com/suraxius/netbox-plugin-bind-provisioner/network/members)
[![Issues Badge](https://img.shields.io/github/issues/suraxius/netbox-plugin-bind-provisioner)](https://github.com/suraxius/netbox-plugin-bind-provisioner/issues)
[![Pull Requests Badge](https://img.shields.io/github/issues-pr/suraxius/netbox-plugin-bind-provisioner)](https://github.com/suraxius/netbox-plugin-bind-provisioner/pulls)
[![GitHub contributors](https://img.shields.io/github/contributors/suraxius/netbox-plugin-bind-provisioner?color=2b9348)](https://github.com/suraxius/netbox-plugin-bind-provisioner/graphs/contributors)
[![License Badge](https://img.shields.io/github/license/suraxius/netbox-plugin-bind-provisioner?color=2b9348)](https://github.com/suraxius/netbox-plugin-bind-provisioner/blob/master/LICENSE)
[![Code Style Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Downloads](https://static.pepy.tech/personalized-badge/netbox-plugin-bind-provisioner?period=total&left_color=BLACK&right_color=BLUE&left_text=Downloads)](https://pepy.tech/project/netbox-plugin-bind-provisioner)
[![Downloads/Week](https://static.pepy.tech/personalized-badge/netbox-plugin-bind-provisioner?period=monthly&left_color=BLACK&right_color=BLUE&left_text=Downloads%2fMonth)](https://pepy.tech/project/netbox-plugin-bind-provisioner)
[![Downloads/Month](https://static.pepy.tech/personalized-badge/netbox-plugin-bind-provisioner?period=weekly&left_color=BLACK&right_color=BLUE&left_text=Downloads%2fWeek)](https://pepy.tech/project/netbox-plugin-bind-provisioner)

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

The plugin exposes one catalog zone per view. Each catalog zone is made available
under the special 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 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 in the foreground:
```
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).


### 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)

### Plugin settings
Setting             | Description
--------------------| ---------------------------------------------------------
tsig_keys           | Maps a TSIG Key to be used for each view.

## Installation guide
This setup provisions a BIND9 server directly with DNS data from NetBox.
BIND9 can optionally run on a separate server. If so, any reference to
127.0.0.1 in step 6 must be replaced with the IP address of the NetBox host.
TCP and UDP traffic from the BIND9 server to the NetBox host must be allowed on
port 5354 (or the port you have configured).

This guide assumes:
- Netbox has been installed under /opt/netbox
- Bind9 is installed on the same host as Netbox
- The Netbox DNS Plugin netbox-plugin-dns is installed
- The following dns views exist in Netbox DNS:
    - `public` (the default)
    - `private`

1. Preliminaries
    - Install Bind9 on the same host that netbox is on.
    - Generate a TSIG Key for the `public` and `private` dns views respectively.

2. Adding required package
    ```
    cd netbox
    echo netbox-plugin-bind-provisioner >> local_requirements.txt
    . venv/bin/activate
    pip install -r local_requirements.txt
    ```

3. Updating netbox plugin configuration (configuration.py)
    Change following line from
    ```
    PLUGINS = ['netbox_dns']
    ```
    to
    ```
    PLUGINS = ['netbox_dns', 'netbox_plugin_bind_provisioner']
    ```

    Configure the Bind Exporter Plugin using the PLUGINS_CONFIG dictionary.
    Change
    ```
    PLUGINS_CONFIG = {}
    ```
    to
    ```
    PLUGINS_CONFIG = {
        "netbox_plugin_bind_provisioner": {
            "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_plugin_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.

4. Run migrations
    ```
    python3 netbox/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.
    ```
    python3 netbox/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;
    };

    ########## ZONES ##########

    view "public" {
        key "public_view_key" {
            algorithm hmac-sha256;
            secret "base64-encoded-secret";
        };

        match-clients { public; };

        catalog-zones {
            zone "catz"
                default-masters { 127.0.0.1 port 5354 key "public_view_key"; }
                zone-directory "/var/lib/bind/zones"
                min-update-interval 1;
        };

        zone "catz" {
            type slave;
            file "/var/lib/bind/zones/catz_public";
            masters { 127.0.0.1 port 5354 key "public_view_key"; };
            notify no;
        };
    };

    view "private" {
        key "private_view_key" {
            algorithm hmac-sha256;
            secret "base64-encoded-secret";
        };

        match-clients { private; };

        catalog-zones {
            zone "catz"
                default-masters { 127.0.0.1 port 5354 key "private_view_key"; }
                zone-directory "/var/lib/bind/zones"
                min-update-interval 1;
        };

        zone "catz" {
            type slave;
            file "/var/lib/bind/zones/catz_private";
            masters { 127.0.0.1 port 5354 key "private_view_key"; };
            notify no;
        };
    };
    ```

7. Restart bind - Done

