dns-sync/README.md

dns-sync modular

A plugin-based DNS reconciliation service.

Plugin contract

Source modules live under dns_sync/plugins/sources/ and export a class named Plugin with:

• name
• discover() -> list[DesiredRecord]

Provider modules live under dns_sync/plugins/providers/ and export Plugin with:

• name
• capabilities
• connect()
• list_records()
• add_record()
• update_record()
• delete_record()
• verify_record()
• capacity()

Plugins are convention-loaded from environment variables. No registry edit is needed:

• PROXY=npm loads dns_sync.plugins.sources.npm.Plugin
• DNS_PROVIDER=verizon loads dns_sync.plugins.providers.verizon.Plugin

Current plugins

Sources: npm, file

Providers: verizon

Main environment

PROXY=npm
PROXY_IP=192.168.1.101
PROXY_API_PORT=81
PROXY_API_SCHEME=http
DNS_PROVIDER=verizon
DOMAIN_MATCHING=false
DOMAIN=example.com
SYNC_INTERVAL=1
NPM_IDENTITY=...
NPM_SECRET=...
ROUTER_PASSWORD=...

DNS_TARGET_IP optionally overrides the default DNS destination, which is PROXY_IP.

Domain filtering

Filtering is performed by the central engine after source discovery and before reconciliation, so all source plugins get identical behavior.

DOMAIN_MATCHING=true
DOMAIN=example.com

This includes the apex and every subdomain:

example.com
app.example.com
deep.app.example.com
*.example.com

It excludes unrelated names such as:

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.