DNS Providers¶
dnsweaver supports multiple DNS providers, each with different capabilities and configuration options.
Supported Providers¶
-
Cloudflare
Public DNS with CDN and proxy capabilities. REST API.
-
OVHcloud
Public DNS for OVH-hosted domains. REST API.
-
Technitium
Self-hosted, full-featured DNS server. REST API.
-
Pi-hole
Integrate with existing Pi-hole setups. API or file mode.
-
dnsmasq
Simple file-based DNS configuration.
-
Webhook
Custom integrations via HTTP callbacks.
-
RFC 2136
Industry-standard Dynamic DNS protocol. BIND, Windows DNS, PowerDNS, etc.
-
PowerDNS
PowerDNS Authoritative Server via its native HTTP API. REST API.
-
AdGuard Home
Network-wide ad blocker with DNS rewrite management. REST API.
-
:material-firewall:{ .lg .middle } OPNsense
Manage Unbound or Dnsmasq host overrides on OPNsense. REST API.
-
:material-firewall:{ .lg .middle } pfSense
Manage Unbound or Dnsmasq host overrides on pfSense. REST API.
Provider Comparison¶
| Provider | API Type | Record Types | Best For |
|---|---|---|---|
| Technitium | REST API | A, AAAA, CNAME, SRV, TXT | Self-hosted, full-featured DNS |
| Cloudflare | REST API | A, AAAA, CNAME, SRV, TXT | Public DNS with CDN/proxy |
| OVHcloud | REST API | A, AAAA, CNAME, SRV, TXT | Public DNS for OVH-hosted domains |
| RFC 2136 | DNS Protocol | A, AAAA, CNAME, SRV, TXT | BIND, Windows DNS, PowerDNS, Knot |
| PowerDNS | REST API | A, AAAA, CNAME, SRV, TXT | PowerDNS via native HTTP API |
| Pi-hole | REST API or File | A, CNAME | Existing Pi-hole setups |
| AdGuard Home | REST API | A, AAAA, CNAME | Existing AdGuard Home setups |
| OPNsense | REST API | A, AAAA | Unbound or Dnsmasq host overrides on OPNsense |
| pfSense | REST API | A, AAAA | Unbound or Dnsmasq host overrides on pfSense |
| dnsmasq | File | A, CNAME | Simple file-based DNS |
| Webhook | HTTP Callback | Any | Custom integrations |
Multi-Provider Architecture¶
dnsweaver is designed to manage multiple providers simultaneously. This enables:
- Split-horizon DNS: Same hostname resolves differently internally vs externally
- Redundancy: Records in multiple DNS providers for failover
- Migration: Gradual transition between DNS providers
Example: Split-Horizon Setup¶
DNSWEAVER_INSTANCES=internal,external
# Internal: Technitium for LAN resolution
DNSWEAVER_INTERNAL_TYPE=technitium
DNSWEAVER_INTERNAL_RECORD_TYPE=A
DNSWEAVER_INTERNAL_TARGET=192.0.2.100
DNSWEAVER_INTERNAL_DOMAINS=*.example.com
# External: Cloudflare for public resolution
DNSWEAVER_EXTERNAL_TYPE=cloudflare
DNSWEAVER_EXTERNAL_RECORD_TYPE=CNAME
DNSWEAVER_EXTERNAL_TARGET=proxy.example.com
DNSWEAVER_EXTERNAL_DOMAINS=*.example.com
With this configuration, when a container with label Host(app.example.com) starts, or a Kubernetes Ingress with host app.example.com is created:
- Technitium gets:
app.example.com → A → 192.0.2.100 - Cloudflare gets:
app.example.com → CNAME → proxy.example.com
Provider Selection¶
When a hostname is extracted from a container, dnsweaver checks it against each provider's domain patterns:
Container: app.home.example.com
Provider A (domains: *.home.example.com) → ✅ Match → Create record
Provider B (domains: *.example.com) → ✅ Match → Create record
Provider C (domains: *.other.com) → ❌ No match → Skip
Use EXCLUDE_DOMAINS to prevent overlapping matches when needed.
Common Settings¶
All providers share these configuration options:
| Variable | Required | Description |
|---|---|---|
TYPE |
Yes | Provider type |
RECORD_TYPE |
Yes | A, AAAA, CNAME, or SRV |
TARGET |
Yes | Record value (IP or hostname) |
DOMAINS |
Yes | Glob patterns to match |
EXCLUDE_DOMAINS |
No | Patterns to exclude |
TTL |
No | Record TTL in seconds |
Ownership Tracking¶
By default, dnsweaver creates TXT records alongside DNS records to track ownership:
app.example.com A 192.0.2.100
_dnsweaver.app.example.com TXT "owner=dnsweaver,source=docker,id=abc123"
This prevents dnsweaver from modifying records it didn't create. Disable with:
To adopt existing records (and take ownership):