Lightweight REST API for managing Bind9 zones and records across a primary/secondary nameserver setup.

The service runs in two modes:

• Primary — exposes the full zone/record CRUD API, persists data in SQLite, writes zone files and bind config to the local filesystem, and pushes updates to secondary instances via HTTP.
• Secondary — exposes only the bind-sync endpoints used by the primary to deliver zone files and named.conf. It writes received files to disk and reloads bind9.

Both modes are provided by the same binary; the runtime mode is controlled by DNSAPI_MODE.

cp docker-compose.yml.example docker-compose.yml   # adjust tokens and nameserver FQDNs
docker compose up -d

See docker-compose.yml for a full example with comments explaining the rndc setup.

The primary instance:

• Serves the REST API (zones, records, commit, export/import).
• On commit: writes the zone file locally, pushes it to each secondary via PUT /bind/zones/:domain, regenerates and writes named.conf.rosti locally, and pushes it to each secondary via PUT /bind/config.
• Reloads bind9 via the configured reload command after updating local config/zones.
• 10 seconds after commit, forces an rndc refresh on itself and all secondaries.

The secondary instance:

• Exposes only the bind-sync endpoints (protected by the same API token as primary).
• On receiving a zone file or bind config via HTTP, writes it to disk and reloads bind9.

All settings are environment variables with the DNSAPI_ prefix.

Primary (runs on the same host as bind9):

[Unit]
Description=dnsapi — primary
After=network.target

[Service]
WorkingDirectory=/etc/bind
Environment=DNSAPI_MODE=primary
Environment=DNSAPI_API_TOKEN=<strong-secret>
Environment=DNSAPI_PRIMARY_NAME_SERVER=ns1.example.com
Environment=DNSAPI_NAME_SERVERS=ns1.example.com,ns2.example.com
Environment=DNSAPI_SECONDARY_INSTANCES=https://ns2.example.com:1323
Environment=DNSAPI_ABUSE_EMAIL[email protected]
Environment=DNSAPI_DATABASE_PATH=/var/lib/dnsapi/db.sqlite
Environment=DNSAPI_PORT=1323
ExecStart=/usr/local/bin/dnsapi
Restart=on-failure

[Install]
WantedBy=multi-user.target

Secondary (runs on the same host as the secondary bind9):

[Unit]
Description=dnsapi — secondary
After=network.target

[Service]
WorkingDirectory=/etc/bind
Environment=DNSAPI_MODE=secondary
Environment=DNSAPI_API_TOKEN=<same-strong-secret>
Environment=DNSAPI_PORT=1323
ExecStart=/usr/local/bin/dnsapi
Restart=on-failure

[Install]
WantedBy=multi-user.target

Set DNSAPI_HTTPS=true, DNSAPI_PUBLIC_DOMAIN=ns1.example.com, and [email protected].

The service starts on port 443 (TLS) and opens an HTTP-01 challenge listener on port 80.
Certificates are cached in /var/cache/dnsapi/autocert.

When HTTPS is enabled, DNSAPI_PORT is ignored.

Swagger UI is served at /swagger/index.html (primary mode only).

All endpoints require Authorization: <token> header.

Versioned SQL migrations are embedded in the binary (pkg/dnsapi/migrations/*.sql) and applied automatically on startup. Migration state is tracked in the schema_migrations table.

go build ./...
go test ./...
make docs   # regenerate Swagger docs