Refactor: Generalisierung der Konfiguration und atomares Schreiben der Zonefiles

2025-12-09 16:20:11 +00:00
parent 573f387d84
commit 88bba9259c
5 changed files with 153 additions and 64 deletions
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -0,0 +1,64 @@
+# 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.