DNS Update (RFC2136)

Code: dnsupdate
Since: v0.3.0

Here is an example bash command using the DNS Update (RFC2136) provider:

DNSUPDATE_NAMESERVER=127.0.0.1 \
DNSUPDATE_TSIG_KEY=example.com \
DNSUPDATE_TSIG_ALGORITHM=hmac-sha256. \
DNSUPDATE_TSIG_SECRET=YWJjZGVmZGdoaWprbG1ub3BxcnN0dXZ3eHl6MTIzNDU= \
lego run --dns dnsupdate -d '*.example.com' -d example.com

## ---

keyname=example.com; keyfile=example.com.key; tsig-keygen $keyname > $keyfile

DNSUPDATE_NAMESERVER=127.0.0.1 \
DNSUPDATE_TSIG_FILE="$keyfile" \
lego run --dns dnsupdate -d '*.example.com' -d example.com

## --- TSIG-GSS / RFC3645 / Kerberos

DNSUPDATE_NAMESERVER=127.0.0.1 \
DNSUPDATE_TSIG_ALGORITHM=gss-tsig. \
DNSUPDATE_TSIG_GSS_REALM=realm.example
DNSUPDATE_TSIG_GSS_USERNAME='xxx'
DNSUPDATE_TSIG_GSS_PASSWORD='yyy'
lego run --dns dnsupdate -d '*.example.com' -d example.com

## --- TSIG-GSS / RFC3645 / Kerberos (keytab)

DNSUPDATE_NAMESERVER="127.0.0.1" \
DNSUPDATE_TSIG_ALGORITHM=gss-tsig. \
DNSUPDATE_TSIG_GSS_REALM=realm.example \
DNSUPDATE_TSIG_GSS_USERNAME='xxx' \
DNSUPDATE_TSIG_GSS_KEYTAB_FILE="/path/to/my.keytab" \
lego run --dns dnsupdate -d '*.example.com' -d example.com

Credentials

Environment Variable Name	Description
`DNSUPDATE_NAMESERVER`	Network address in the form “host” or “host:port”

The environment variable names can be suffixed by _FILE to reference a file instead of a value. More information here.

Additional Configuration

Environment Variable Name	Description
`DNSUPDATE_DNS_TIMEOUT`	API request timeout in seconds (Default: 10)
`DNSUPDATE_POLLING_INTERVAL`	Time between DNS propagation check in seconds (Default: 2)
`DNSUPDATE_PROPAGATION_TIMEOUT`	Maximum waiting time for DNS propagation in seconds (Default: 60)
`DNSUPDATE_SEQUENCE_INTERVAL`	Time between sequential requests in seconds (Default: 60)
`DNSUPDATE_TSIG_ALGORITHM`	TSIG algorithm. See miekg/dns#tsig.go for supported values. To disable TSIG authentication, leave the `DNSUPDATE_TSIG_KEY` or `DNSUPDATE_TSIG_SECRET` variables unset.
`DNSUPDATE_TSIG_FILE`	Path to a key file generated by tsig-keygen
`DNSUPDATE_TSIG_GSS_KEYTAB_FILE`	Path to Kerberos keytab file. The TSIG algorithm must be `gss-tsig.`.
`DNSUPDATE_TSIG_GSS_PASSWORD`	Kerberos password. The TSIG algorithm must be `gss-tsig.`.
`DNSUPDATE_TSIG_GSS_REALM`	Kerberos realm. The TSIG algorithm must be `gss-tsig.`.
`DNSUPDATE_TSIG_GSS_USERNAME`	Kerberos username. The TSIG algorithm must be `gss-tsig.`.
`DNSUPDATE_TSIG_KEY`	Name of the secret key as defined in DNS server configuration. To disable TSIG authentication, leave the `DNSUPDATE_TSIG_KEY` variable unset.
`DNSUPDATE_TSIG_SECRET`	Secret key payload. To disable TSIG authentication, leave the `DNSUPDATE_TSIG_SECRET` variable unset.
`DNSUPDATE_TTL`	The TTL of the TXT record used for the DNS challenge in seconds (Default: 120)
`DNSUPDATE_ZONES`	List of potential zones (separated by commas)

The environment variable names can be suffixed by _FILE to reference a file instead of a value. More information here.

TSIG-GSS / RFC3645 / Kerberos

To ease the usage of DNS Update in some environments, lego provides some aliases for RFC3645.

DNSUPDATE_RFC3645_REALM is an alias on DNSUPDATE_TSIG_GSS_REALM
DNSUPDATE_RFC3645_USERNAME is an alias on DNSUPDATE_TSIG_GSS_USERNAME
DNSUPDATE_RFC3645_PASSWORD is an alias on DNSUPDATE_TSIG_GSS_PASSWORD
DNSUPDATE_RFC3645_KEYTAB_FILE is an alias on DNSUPDATE_TSIG_GSS_KEYTAB_FILE

Examples

# Using password

DNSUPDATE_NAMESERVER=127.0.0.1 \
DNSUPDATE_TSIG_ALGORITHM=gss-tsig. \
DNSUPDATE_RFC3645_REALM=realm.example
DNSUPDATE_RFC3645_USERNAME='xxx'
DNSUPDATE_RFC3645_PASSWORD='yyy'
lego run --dns dnsupdate -d '*.example.com' -d example.com

# Using a keytab file.

DNSUPDATE_NAMESERVER="127.0.0.1" \
DNSUPDATE_TSIG_ALGORITHM=gss-tsig. \
DNSUPDATE_RFC3645_REALM=realm.example \
DNSUPDATE_RFC3645_USERNAME='xxx' \
DNSUPDATE_RFC3645_KEYTAB_FILE="/path/to/my.keytab" \
lego run --dns dnsupdate -d '*.example.com' -d example.com

More information

API documentation