Skip to content

--- title: RFC 2136 Dynamic DNS Provider description: Automate DNS records on HMAC-TSIG-compatible authoritative servers such as BIND, PowerDNS, Knot DNS, and Technitium via RFC 2136 dynamic updates. ---

RFC 2136 (Dynamic DNS)

RFC 2136 defines programmatic DNS updates. Server support alone is not enough: the server's update authorization must also match the authentication dnsweaver implements.

dnsweaver supports unsigned updates and shared-secret TSIG using HMAC-MD5, HMAC-SHA256, or HMAC-SHA512. It does not implement Kerberos/TKEY negotiation (GSS-TSIG) or SIG(0). Use HMAC-SHA256 or HMAC-SHA512 for production and restrict the key to the records dnsweaver manages.

Supported DNS Servers

This is a protocol and authentication compatibility map, not a retained live-version qualification matrix. The repository's RFC 2136 integration tests are opt-in and do not establish support for every server/version below.

Server Server capability Compatibility with dnsweaver Notes
BIND 9 RFC 2136 with update policy/TSIG Expected compatible with HMAC TSIG Configure allow-update or update-policy for the dnsweaver key.
PowerDNS Authoritative RFC 2136 when dnsupdate=yes; backend support varies Expected compatible with HMAC TSIG Enable a supported backend and bind the zone to the key with TSIG-ALLOW-DNSUPDATE.
Knot DNS RFC 2136 via an ACL with the update action Expected compatible with HMAC TSIG Attach a TSIG key to the update ACL and restrict owners/types where practical.
Technitium DNS Server RFC 2136 for primary zones with TSIG policy Expected compatible with HMAC TSIG The dedicated HTTP provider remains available when API-specific behavior is needed.
Windows DNS RFC 2136; AD-integrated zones default to Kerberos secure updates Not compatible with secure-only zones dnsweaver has no GSS-TSIG/Kerberos client. Unsigned updates require a zone that allows nonsecure updates and are not recommended.
NSD Does not implement dynamic update Not compatible NSD's TSIG support is for transfers/control paths, not RFC 2136 updates.

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=192.0.2.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 shared-secret authentication for DNS updates. While optional in dnsweaver, it is strongly recommended for production use. This is HMAC TSIG, not the Kerberos-backed GSS-TSIG used by Windows secure dynamic updates.

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

PowerDNS can additionally require a valid TSIG key with dnsupdate-require-tsig=yes and per-zone TSIG-ALLOW-DNSUPDATE metadata. Backend support varies; consult the linked PowerDNS documentation.

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 maintains dnsweaver catalog TXT records, then queries each catalogued hostname and its ownership record. It does not enumerate arbitrary zone contents and does not require AXFR for ordinary reconciliation.

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