65 lines
2.8 KiB
Markdown
65 lines
2.8 KiB
Markdown
# CoreDNS NetBox Sync
|
|
|
|
This project automates the generation of DNS zone files for CoreDNS (or BIND) by synchronizing data from [NetBox](https://github.com/netbox-community/netbox). It fetches IPAM data (active IPs with DNS names) and DNS plugin entries to maintain up-to-date Forward and Reverse zones.
|
|
|
|
## Project Overview
|
|
|
|
* **Core Logic:** A Python script (`sync.py`) runs in a continuous loop, fetching data from the NetBox API.
|
|
* **Output:** Generates standard DNS zone files compatible with CoreDNS and BIND.
|
|
* **Resilience:** If the NetBox API is unreachable, the script preserves existing zone files to prevent DNS outages (NXDOMAIN).
|
|
* **Environment:** designed to run as a Docker container, sharing the generated zone files via a volume with the CoreDNS container.
|
|
|
|
## Key Files
|
|
|
|
* `sync.py`: The main application logic. Handles API authentication, data fetching, data formatting, and file writing.
|
|
* `Dockerfile`: Defines the minimal Python 3.11 Alpine-based image for running the script.
|
|
* `.env.example`: Template for required environment variables.
|
|
* `README.md`: Official project documentation (German).
|
|
|
|
## Configuration
|
|
|
|
Configuration is handled entirely via environment variables.
|
|
|
|
| Variable | Required | Default | Description |
|
|
| :--- | :---: | :--- | :--- |
|
|
| `NETBOX_URL` | Yes | - | Full URL to NetBox (e.g., `http://netbox.local`). |
|
|
| `NETBOX_TOKEN` | Yes | - | API Token (Read-only sufficient). |
|
|
| `ZONE_NAME` | No | `klenzel.net` | The DNS zone to manage. |
|
|
| `REVERSE_ZONE_NAME` | No | `172.in-addr.arpa` | The reverse lookup zone. |
|
|
| `REFRESH_INTERVAL` | No | `600` | Sync interval in seconds. |
|
|
| `OUTPUT_FILE_FWD` | No | `/zones/db.klenzel.net` | Path for the forward zone file. |
|
|
| `OUTPUT_FILE_REV` | No | `/zones/db.reverse.arpa` | Path for the reverse zone file. |
|
|
| `FALLBACK_NS_HOSTNAME`| No | `fks-01-cl-cdns` | Fallback NS hostname if none in NetBox. |
|
|
| `FALLBACK_NS_IP` | No | `172.25.16.152` | Fallback NS IP for glue record. |
|
|
|
|
## Development & Usage
|
|
|
|
### Building the Image
|
|
|
|
```bash
|
|
docker build -t local/dns-sync .
|
|
```
|
|
|
|
### Running Locally (for testing)
|
|
|
|
1. Create a `.env` file with your NetBox credentials.
|
|
2. Run the container:
|
|
|
|
```bash
|
|
docker run -d \
|
|
--name dns-sync-test \
|
|
--env-file .env \
|
|
-v $(pwd)/zones:/zones \
|
|
local/dns-sync
|
|
```
|
|
|
|
*(Ensure the `./zones` directory exists locally before running)*
|
|
|
|
### Logic Details
|
|
|
|
* **IPAM Fetch:** Queries `/api/ipam/ip-addresses/?status=active&dns_name__n=&limit=0`.
|
|
* **Plugin Fetch:** Queries `/api/plugins/netbox-dns/records/?zone__name={ZONE_NAME}&limit=0`.
|
|
* **Nameserver Logic:**
|
|
* If NetBox has NS records for the zone, the first one is used as the Primary SOA.
|
|
* If **no** NS records exist, it falls back to `FALLBACK_NS_HOSTNAME` and creates a Glue Record (A record) for it to ensure the zone is valid.
|