Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2026-08-20 23:08:28 -04:00
Code Issues Packages Projects Releases Wiki Activity

plugin/tls: manage certificates with ACME DNS-01 (#8310)

Browse Source 
* plugin/tls: add automatic ACME certificates

Signed-off-by: houyuwushang <liuluoqianqiu@outlook.com>

* chore: add houyuwushang to CODEOWNERS

Signed-off-by: houyuwushang <liuluoqianqiu@outlook.com>

* chore: regenerate maintainer owners

Signed-off-by: houyuwushang <liuluoqianqiu@outlook.com>

---------

Signed-off-by: houyuwushang <liuluoqianqiu@outlook.com>
This commit is contained in:
houyuwushang
2026-07-30 10:24:22 +08:00
committed by GitHub
parent 03260d5b67
commit 546fac83ea
13 changed files with 1369 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
plugin/tls/README.md
View File

@@ -42,6 +42,40 @@ to decrypt TLS connections. It compromises security and should only be used for
CoreDNS sets the minimum TLS version to TLS 1.2. The maximum TLS version, TLS 1.2 cipher suites, and
key exchange mechanisms use the Go `crypto/tls` defaults.
Certificates can instead be obtained and renewed automatically with ACME:
~~~ txt
tls {
acme DOMAIN...
email EMAIL
ca URL
storage DIRECTORY
ca_root FILE
resolver ADDRESS
}
~~~
The `acme` property enables automatic certificate management for one or more domain names. CoreDNS
uses the DNS-01 challenge and answers the temporary `_acme-challenge` TXT queries on every DNS
listener in the same CoreDNS instance. The domains' authoritative DNS must therefore reach this
CoreDNS instance over port 53. HTTP-01 and TLS-ALPN-01 challenges are not used.
The remaining properties are optional:
* `email` sets the ACME account contact address.
* `ca` sets the ACME directory URL. It defaults to the Let's Encrypt production directory.
* `storage` sets the directory for ACME accounts, certificates, and private keys. It defaults to
`.coredns/acme` below the Corefile root.
* `ca_root` adds a PEM certificate bundle for connecting to a private ACME server.
* `resolver` sets the DNS resolver used to reach the ACME server and must use `HOST:PORT` syntax.
Certificate management starts in the background after all listeners are active. A new encrypted
listener can reject TLS handshakes until its first certificate has been obtained. Renewed certificates
are used without restarting CoreDNS.
The DNS-01 challenge state is local to one CoreDNS process. When authoritative DNS is served by
multiple replicas, validation queries must be routed to the replica performing the ACME operation.
## Examples
Start a DNS-over-TLS server that picks up incoming DNS-over-TLS queries on port 5553 and uses the
@@ -72,6 +106,23 @@ https://. {
}
~~~
Obtain and renew a certificate for a DoT server. The plain DNS server answers the DNS-01 challenge;
both server blocks must be in the same CoreDNS process.
~~~
.:53 {
file example.org
}
tls://.:853 {
tls {
acme dns.example.org
email hostmaster@example.org
}
forward . /etc/resolv.conf
}
~~~
Only Knot DNS' `kdig` supports DNS-over-TLS queries, no command line client supports gRPC making
debugging these transports harder than it should be.