temptxt
Name
temptxt - serves TXT records for validation purposes (eg. ACME DNS-01 challenge) updated through a HTTP api.
Description
The temptxt plugin is useful for delegating the configuration of TXT records for purposes such as certificate validation (eg. ACME DNS-01).
Users can update the content of the TXT records through a HTTP API. Authentication to the API is handled by a HTTP header passed
from the upstream reverse proxy.
Syntax
temptxt [PREFIX] [SUFFIX] {
[txt FQDN REGEXP1 REGEXP2 ...]
[txt_alias ACTUAL_FQDN UPDATE_FQDN REGEXP1 REGEXP2 ...]
[auth_header X-Forwarded-User]
[clean_interval DURATION]
[max_age DURATION]
[listen ADDRESS]
}
PREFIX
- Prefix to add to FQDNs. This only affects DNS queries. Updates through the API need to use the FQDN without the prefix (txt_alias doesn't used prefix).
SUFFIX
- Suffix to add to FQDNs. This only affects DNS queries. Updates through the API need to use the FQDN without the suffix (txt_alias doesn't used suffix).
txt
- FQDN to serve txt records for. If one of the regexps matches the username, the API request will be allowed. Regexps are automatically anchored with ^
and $
.
txt_alias
- Useful in use cases like example 2. UPDATE_FQDN is the FQDN that is used when calling the API, but the TXT record for ACTUAL_FQDN will be the one that is actually updated.
auth_header
- The header that contains the username for API authentication. Make sure that this a user cannot set the contents of the header. Default: X-Forwarded-User
clean_interval
- The interval that records will be periodically cleared. Set to 0 to disable cleaning. Default: 0
.
max_age
- If the time since the record has last been updated is greater than the given duration, the contents will be cleared. Default: 15m0s
listen
- The address to listen on. Default: :8080
Example 1 - ACME DNS-01
Use temptxt for acme DNS-01 validation for test1.example.com
and test2.example.com
. CoreDNS is authoritative for example.com
.
Configuration
-
CoreDNS configuration
temptxt _acme-challenge. {
txt test1.example.com user1
txt test2.example.com user[0-2] user4
}
Also equivalent:
temptxt {
txt _acme-challenge.test1.example.com user1
txt _acme-challenge.test2.example.com user[0-2] user4
}
-
Configure the ACME client to call the temptxt
API.
Outcome
-
The content of _acme-challenge.test1.example.com
can be updated by user1
.
-
The content of _acme-challenge.test2.example.com
can be updated by user1
, user2
, and user4
.
-
Queries for other _acme-challenge.*.example.com
records will fallthrough.
-
If the content of the txt record is ""
, NXDOMAIN
will be returned.
Example 2 - ACME DNS Alias
- The is similar to acme-dns. It allows temptxt to be used for validation when CoreDNS is not the authoritative server for a given zone using CNAMEs.
Configuration
-
Create NS records for acme-dns.example.com
pointing to this server.
-
Create a CNAME from _acme-challenge.www.example.com
to www.acme-dns.example.com
on the DNS server for example.com
-
Configure CoreDNS
temptxt {
txt_alias www.acme-dns.example.com www.example.com user1
}
-
Configure the ACME client to call the temptxt
API.
Results
-
The ACME client will update the TXT record for www.acme-dns.example.com
using the API.
-
Since there is a CNAME from _acme-challenge.www.example.com
the ACME server will query temptxt for the validation string.
Example certbot hooks
Update using basic auth
curl -X PUT \
-d "fqdn=www.example.com&content=$CERTBOT_TOKEN" \
-u username:password \
https://acme-dns.example.com/update
Clear the record using certificate auth
curl -X PUT \
-d "fqdn=www.example.com&content=" \
--cert ./cert.crt \
--key ./cert.key \
https://acme-dns.example.com/update