131 lines
2.8 KiB
Markdown
131 lines
2.8 KiB
Markdown
# dns-sync modular
|
|
|
|
A plugin-based DNS reconciliation service.
|
|
|
|
## Plugin contract
|
|
|
|
The reconciliation runtime is adapter-based.
|
|
|
|
Adapter plugins expose:
|
|
|
|
- `Plugin`
|
|
- `configured_endpoints(config)`
|
|
|
|
Each adapter declares object-specific discovery, apply, and verification
|
|
capabilities. Built-in adapters live under `dns_sync/plugins/adapters/`.
|
|
External adapters are loaded from `DNS_SYNC_PLUGIN_PATH` and must be
|
|
explicitly enabled through `ENABLED_PLUGINS`.
|
|
|
|
## Plugins
|
|
|
|
The generic reconciliation engine uses adapter plugins.
|
|
|
|
Built-in adapters:
|
|
|
|
- `npm` - Nginx Proxy Manager proxy hosts and certificates
|
|
|
|
External adapters are loaded from `DNS_SYNC_PLUGIN_PATH` and must also be
|
|
explicitly enabled through `ENABLED_PLUGINS`.
|
|
|
|
Example:
|
|
|
|
```text
|
|
ENABLED_PLUGINS=npm,verizon
|
|
DNS_SYNC_PLUGIN_PATH=/plugins
|
|
```
|
|
|
|
The Verizon adapter lives under `external_plugins/verizon` and is deliberately
|
|
not copied into the dns-sync container image. The external plugin directory is
|
|
mounted read-only at runtime.
|
|
|
|
## Container runtime
|
|
|
|
The container periodically executes the generic reconciliation engine:
|
|
|
|
```text
|
|
python -m dns_sync reconcile
|
|
```
|
|
|
|
The default container mode is read-only.
|
|
|
|
```text
|
|
SYNC_INTERVAL=1
|
|
DNS_SYNC_APPLY=false
|
|
DNS_SYNC_STATE_DB=/var/lib/dns-sync/state.sqlite3
|
|
DNS_SYNC_PLUGIN_PATH=/plugins
|
|
ENABLED_PLUGINS=npm,verizon
|
|
```
|
|
|
|
`SYNC_INTERVAL` is expressed in minutes. The interval begins after each
|
|
reconciliation completes, so runs do not overlap.
|
|
|
|
To permit planned changes to be applied and verified:
|
|
|
|
```text
|
|
DNS_SYNC_APPLY=true
|
|
```
|
|
|
|
An optional mutation budget can be specified:
|
|
|
|
```text
|
|
DNS_SYNC_MAX_CHANGES=10
|
|
```
|
|
|
|
When `DNS_SYNC_APPLY=false`, reconciliation still performs discovery,
|
|
normalization, desired-state reconciliation, planning, and state persistence,
|
|
but no endpoint mutations are executed.
|
|
|
|
The SQLite database should be stored on persistent storage.
|
|
|
|
External plugins should be mounted read-only at `/plugins`.
|
|
|
|
## Main environment
|
|
|
|
```text
|
|
NPM_ENDPOINTS=192.168.1.3,192.168.1.4,192.168.1.5
|
|
PROXY_API_PORT=81
|
|
PROXY_API_SCHEME=http
|
|
DNS_TARGET_IP=192.168.1.101
|
|
|
|
VERIZON_ENDPOINTS=192.168.1.1
|
|
|
|
DOMAIN_MATCHING=false
|
|
DOMAIN=example.com
|
|
|
|
NPM_IDENTITY=...
|
|
NPM_SECRET=...
|
|
ROUTER_PASSWORD=...
|
|
```
|
|
|
|
## Domain filtering
|
|
|
|
Filtering is performed centrally after adapter discovery and before
|
|
reconciliation, so endpoint-specific adapters get identical behavior.
|
|
|
|
```text
|
|
DOMAIN_MATCHING=true
|
|
DOMAIN=example.com
|
|
```
|
|
|
|
This includes the apex and every subdomain:
|
|
|
|
```text
|
|
example.com
|
|
app.example.com
|
|
deep.app.example.com
|
|
*.example.com
|
|
```
|
|
|
|
It excludes unrelated names such as:
|
|
|
|
```text
|
|
example.net
|
|
notexample.com
|
|
example.com.evil.net
|
|
```
|
|
|
|
When `DOMAIN_MATCHING=false`, `DOMAIN` is ignored and all discovered records are
|
|
eligible for reconciliation.
|
|
|
|
When `DOMAIN_MATCHING=true`, `DOMAIN` is required.
|