Skip to content

RFC 2136 (Dynamic DNS)

RFC 2136 is the industry-standard protocol for programmatic DNS updates, supported by virtually all authoritative DNS servers. This provider enables dnsweaver to manage records on any RFC 2136-compliant server.

Supported DNS Servers

Server RFC 2136 Notes
BIND ✅ Most widely deployed; requires allow-update or TSIG
Windows DNS ✅ Active Directory integrated; secure dynamic updates
PowerDNS ✅ Via dnsupdate=yes in zone settings
Knot DNS ✅ High-performance; TSIG recommended
NSD ✅ Lightweight; TSIG required
Technitium ✅ Also has dedicated HTTP API provider
CoreDNS ✅ With nsupdate plugin

When to use RFC 2136 vs dedicated providers

Use RFC 2136 when your DNS server supports it but has no dedicated dnsweaver provider, or when you want a single configuration for multiple RFC 2136 servers.

Use dedicated providers (Technitium, Cloudflare, etc.) when they offer richer features like proxy mode, zone management, or better observability.

Basic Configuration

environment:
  - DNSWEAVER_INSTANCES=bind

  - DNSWEAVER_BIND_TYPE=rfc2136
  - DNSWEAVER_BIND_SERVER=ns1.example.com:53
  - DNSWEAVER_BIND_ZONE=example.com.
  - DNSWEAVER_BIND_DOMAINS=*.example.com
  - DNSWEAVER_BIND_RECORD_TYPE=A
  - DNSWEAVER_BIND_TARGET=10.0.0.100

  # TSIG Authentication (strongly recommended)
  - DNSWEAVER_BIND_TSIG_KEY_NAME=dnsweaver.
  - DNSWEAVER_BIND_TSIG_SECRET_FILE=/run/secrets/tsig_key
  - DNSWEAVER_BIND_TSIG_ALGORITHM=hmac-sha256

Configuration Reference

Variable Required Default Description
TYPE Yes - Must be rfc2136
SERVER Yes - DNS server address (host:port)
ZONE Yes - Zone name (must end with .)
DOMAINS Yes - Glob patterns to match
RECORD_TYPE Yes - A, AAAA, CNAME, SRV, or TXT
TARGET Yes - Record value
TSIG_KEY_NAME No - TSIG key name (must end with .)
TSIG_SECRET No - Base64-encoded TSIG secret
TSIG_SECRET_FILE No - Path to file containing TSIG secret
TSIG_ALGORITHM No hmac-sha256 hmac-sha256, hmac-sha512, hmac-md5
TTL No 300 Record TTL in seconds
TIMEOUT No 10 DNS operation timeout (seconds)
USE_TCP No false Force TCP transport

TSIG Authentication

TSIG (Transaction SIGnature) provides authentication for DNS updates. While optional, it's strongly recommended for production use.

Generating a Key

tsig-keygen -a hmac-sha256 dnsweaver

dnssec-keygen -a HMAC-SHA256 -b 256 -n HOST dnsweaver

openssl rand -base64 32

Server Configuration

# /etc/bind/named.conf.local
key "dnsweaver." {
    algorithm hmac-sha256;
    secret "your-base64-secret-here";
};

zone "example.com" {
    type master;
    file "/etc/bind/zones/example.com.zone";
    allow-update { key "dnsweaver."; };
};
  1. Go to Settings → General → enable Enable DNS-over-UDP Dynamic Updates
  2. Configure TSIG key under Settings → TSIG Keys
  3. Set zone to allow updates from the TSIG key
# pdns.conf
dnsupdate=yes
allow-dnsupdate-from=10.0.0.0/8

Record Types

Type Supported Notes
A ✅ IPv4 address
AAAA ✅ IPv6 address
CNAME ✅ Alias
TXT ✅ Used for ownership tracking
SRV ✅ Service discovery

MX and PTR records

MX and PTR are supported by the underlying protocol but not yet exposed in the provider interface.

Capabilities

The RFC 2136 provider supports:

  • Ownership TXT records: Full ownership tracking for orphan cleanup
  • Native updates: Atomic update operations via DNS UPDATE protocol
  • All major record types: A, AAAA, CNAME, TXT, SRV

List() limitation

RFC 2136 doesn't provide a standard way to enumerate records. The provider relies on ownership TXT records to track managed records rather than querying the full zone.

Troubleshooting

"REFUSED" Response

  • Check that the zone allows dynamic updates
  • Verify TSIG key name and secret match server configuration
  • Ensure the record name is within the configured zone

"NOTAUTH" Response

  • The DNS server is not authoritative for the zone
  • Check zone configuration on the server

"TSIG verification failed"

  • TSIG key name must end with a dot (e.g., dnsweaver.)
  • Secret must be base64-encoded
  • Algorithm must match server configuration

Timeout

  • Verify network connectivity to DNS server port 53
  • Check if UDP is blocked (try USE_TCP=true)
  • Increase TIMEOUT value

Security Considerations

Never allow unauthenticated updates in production

Always use TSIG authentication. Unauthenticated updates allow anyone to modify your DNS records.

  • Use TSIG authentication for all production deployments
  • Restrict update permissions on the DNS server to specific zones/records
  • Secure secret storage using Docker secrets or a vault
  • Network isolation — limit DNS update traffic to trusted networks

References

  • RFC 2136 — Dynamic Updates in the Domain Name System
  • RFC 2845 — Secret Key Transaction Authentication (TSIG)
  • RFC 4635 — HMAC SHA TSIG Algorithm Identifiers