initial commit

2024-05-06 17:37:57 -06:00
commit 12bcac933a
35 changed files with 3027 additions and 0 deletions
@@ -0,0 +1,149 @@
+# netboxdns
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/doubleu-labs/coredns-netbox-plugin-dns.svg)](https://pkg.go.dev/github.com/doubleu-labs/coredns-netbox-plugin-dns)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=doubleu-labs_coredns-netbox-plugin-dns&metric=coverage)](https://sonarcloud.io/summary/overall?id=doubleu-labs_coredns-netbox-plugin-dns)
+[![Go Report Card](https://goreportcard.com/badge/github.com/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.**
+
+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.