W Anders
152 lines
5.1 KiB
Markdown
152 lines
5.1 KiB
Markdown
# netboxdns
|
|
|
|
[](https://pkg.go.dev/github.com/doubleu-labs/coredns-netbox-plugin-dns)
|
|
[](https://sonarcloud.io/summary/overall?id=doubleu-labs_coredns-netbox-plugin-dns)
|
|
[](https://goreportcard.com/report/github.com/doubleu-labs/coredns-netbox-plugin-dns)
|
|
|
|
*netboxdns* - provides resolution using
|
|
[Netbox DNS Plugin (netbox-plugin-dns)](https://github.com/peteeckel/netbox-plugin-dns)
|
|
|
|
## Description
|
|
|
|
The *netboxdns* plugin provides resolution for zones configured using
|
|
[netbox-plugin-dns](https://github.com/peteeckel/netbox-plugin-dns).
|
|
|
|
**Depends on `netbox-plugin-dns` version `0.22.8` or greater.**
|
|
|
|
**Validated for `netbox` >= v4.0.2 and `netbox-plugin-dns` >= v1.0.0.**
|
|
|
|
The account that the API token is tied to will need the following permissions:
|
|
|
|
- `netbox_dns.view_zone`
|
|
- `netbox_dns.view_record`
|
|
|
|
## Syntax
|
|
|
|
Available configuration options:
|
|
|
|
```nginx
|
|
netboxdns [ZONES...] {
|
|
token TOKEN
|
|
url URL
|
|
timeout DURATION
|
|
fallthrough [ZONES...]
|
|
tls CERT KET CACERT
|
|
}
|
|
```
|
|
|
|
* **ZONES**: A space-delimited list of zones that the plugin will answer for
|
|
|
|
* **`token TOKEN` (REQUIRED)**: The API token used to authenticate requests
|
|
to the Netbox instance
|
|
|
|
* **`url URL` (REQUIRED)**: The URL that Netbox is accessible at
|
|
|
|
* **`timeout DURATION`** (DEFAULT=`5s`): A duration to time-out requests to the
|
|
Netbox API
|
|
|
|
* **`fallthrough`**: If no record exists, send the request to the next plugin.
|
|
* **(OPTIONAL) `ZONES...`**: A space-delimited list of zones that requests
|
|
should be forwarded to the next plugin. If requests are not in the specified
|
|
zones, an empty reponse is returned.
|
|
|
|
* **`tls`**: Used to authenticate to the Netbox instance if it is using HTTPS.
|
|
* `0 arguments`: Creates a TLS configuration that uses system CA certificates
|
|
to validate the connection to the Netbox instance. Use when Netbox is using
|
|
a server certificate signed by a public CA. The client is not authenticated
|
|
by the server.
|
|
|
|
* `1 argument`: Path to the CA PEM file. Creates a TLS configuration that uses
|
|
the specified CA certificate to validate the connection to the Netbox
|
|
instance. Use when Netbox is using a server certificate signed by a private
|
|
CA. The client is not authenticated by the server.
|
|
|
|
* `2 arguments`: Paths to the client certificate and private key PEM files.
|
|
Creates a TLS configuration that uses system CA certificates to validate the
|
|
connection to the Netbox instance. Use when certificates are needed to
|
|
authenticate to the Netbox instance (mTLS) (Netbox Cloud).
|
|
|
|
* `3 arguments`: Paths to the client certificate, private key, and CA PEM
|
|
files. Creates a TLS configuration that uses the specified CA certificate to
|
|
validate the connection to the Netbox instance. Use when certificates are
|
|
needed to authenticate to the Netbox instance (mTLS) and Netbox is using a
|
|
server certificate signed by a private CA.
|
|
|
|
## Building
|
|
|
|
Clone the [coredns](https://github.com/coredns/coredns) repository and change
|
|
into it's directory.
|
|
|
|
```sh
|
|
git clone https://github.com/coredns/coredns.git
|
|
```
|
|
|
|
```sh
|
|
cd coredns
|
|
```
|
|
|
|
Fetch the plugin and add it to `coredns`'s `go.mod` file:
|
|
|
|
```sh
|
|
go get -u github.com/doubleu-labs/coredns-netbox-plugin-dns
|
|
```
|
|
|
|
Update `plugin.cfg` in the root of the directory. The `netboxdns` declaration
|
|
should be inserted after `cache` if you want responses from Netbox to be
|
|
cached.
|
|
|
|
```sh
|
|
# Using sed
|
|
sed -i '/^cache:cache/a netboxdns:github.com/doubleu-labs/coredns-netbox-plugin-dns' plugin.cfg
|
|
```
|
|
|
|
```powershell
|
|
# Using Powershell
|
|
(Get-Content plugin.cfg).`
|
|
Replace("cache:cache", "cache:cache`nnetboxdns:github.com/doubleu-labs/coredns-netbox-plugin-dns") | `
|
|
Set-Content -Path plugin.cfg
|
|
```
|
|
|
|
Build using `make`:
|
|
|
|
```sh
|
|
make
|
|
```
|
|
|
|
Or if `make` is not available, simply run:
|
|
|
|
```sh
|
|
go generate && go build
|
|
```
|
|
|
|
The `coredns` binary will be in the root of the project directory, unless
|
|
otherwise specified by the `-o` flag.
|
|
|
|
## Contributing
|
|
|
|
A [Docker Compose file](./.testing/docker-compose.yml) is provided to setup a
|
|
minimal Netbox instance to run tests against. If using Visual Studio Code, two
|
|
tasks are configured to start and stop this instance. Use `Ctrl+Shift+P` and
|
|
select `[Start] Netbox test instance`.
|
|
|
|
Check that Netbox is finished with the initial setup by watching the container
|
|
logs using:
|
|
|
|
```sh
|
|
docker logs -f coredns-netbox-plugin-dns-netbox-1
|
|
```
|
|
|
|
The test instance will be available at
|
|
[http://localhost:9999](http://localhost:9999/) with the `admin:admin` username
|
|
and password. When you see healthcheck requests, invoke
|
|
[init.go](./.testing/init/init.go) to populate the test dataset.
|
|
|
|
```sh
|
|
go run .testing/init/init.go
|
|
```
|
|
|
|
This standalone application POSTs the contents of the
|
|
JSON files in [.testing/init](./.testing/init/) to populate the database. If
|
|
adding a new feature or bugfix that requires additional records, be sure to add
|
|
the Zone or Record to the appropriate JSON file.
|