mirror of
https://github.com/coredns/coredns.git
synced 2026-10-28 21:25:42 -04:00
Improve RFC links (#8612)
The `tools.ietf.org` site now redirects to `www.rfc-editor.org`. * Update various URLs to the new site. * Make links to `www.rfc-editor.org` consistent. Signed-off-by: SuperQ <superq@gmail.com>
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
||||
.TH "COREDNS-TLS" 7 "March 2026" "CoreDNS" "CoreDNS Plugins"
|
||||
.TH "COREDNS-TLS" 7 "October 2026" "CoreDNS" "CoreDNS Plugins"
|
||||
|
||||
.SH "NAME"
|
||||
.PP
|
||||
@@ -39,6 +39,7 @@ Parameter CA is optional. If not set, system CAs can be used to verify the clien
|
||||
.nf
|
||||
tls CERT KEY [CA] {
|
||||
client\_auth nocert|request|require|verify\_if\_given|require\_and\_verify
|
||||
keylog FILE
|
||||
}
|
||||
|
||||
.fi
|
||||
@@ -51,6 +52,64 @@ The option value corresponds to the ClientAuthType values of the Go tls package
|
||||
The default is "nocert". Note that it makes no sense to specify parameter CA unless this option is
|
||||
set to verify_if_given or require_and_verify.
|
||||
|
||||
.PP
|
||||
The keylog can be specified to export TLS master secrets in key log format to allow external programs
|
||||
to decrypt TLS connections. It compromises security and should only be used for debugging!
|
||||
|
||||
.PP
|
||||
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 \fB\fCcrypto/tls\fR defaults.
|
||||
|
||||
.PP
|
||||
Certificates can instead be obtained and renewed automatically with ACME:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
tls {
|
||||
acme DOMAIN...
|
||||
email EMAIL
|
||||
ca URL
|
||||
storage DIRECTORY
|
||||
ca\_root FILE
|
||||
resolver ADDRESS
|
||||
}
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
The \fB\fCacme\fR property enables automatic certificate management for one or more domain names. CoreDNS
|
||||
uses the DNS-01 challenge and answers the temporary \fB\fC_acme-challenge\fR 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.
|
||||
|
||||
.PP
|
||||
The remaining properties are optional:
|
||||
|
||||
.IP \(bu 4
|
||||
\fB\fCemail\fR sets the ACME account contact address.
|
||||
.IP \(bu 4
|
||||
\fB\fCca\fR sets the ACME directory URL. It defaults to the Let's Encrypt production directory.
|
||||
.IP \(bu 4
|
||||
\fB\fCstorage\fR sets the directory for ACME accounts, certificates, and private keys. It defaults to
|
||||
\fB\fC.coredns/acme\fR below the Corefile root.
|
||||
.IP \(bu 4
|
||||
\fB\fCca_root\fR adds a PEM certificate bundle for connecting to a private ACME server.
|
||||
.IP \(bu 4
|
||||
\fB\fCresolver\fR sets the DNS resolver used to reach the ACME server and must use \fB\fCHOST:PORT\fR syntax.
|
||||
|
||||
|
||||
.PP
|
||||
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.
|
||||
|
||||
.PP
|
||||
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.
|
||||
|
||||
.SH "EXAMPLES"
|
||||
.PP
|
||||
Start a DNS-over-TLS server that picks up incoming DNS-over-TLS queries on port 5553 and uses the
|
||||
@@ -100,11 +159,35 @@ https://. {
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Only Knot DNS' \fB\fCkdig\fR supports DNS-over-TLS queries, no command line client supports gRPC making
|
||||
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.
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&.:53 {
|
||||
file example.org
|
||||
}
|
||||
|
||||
tls://.:853 {
|
||||
tls {
|
||||
acme dns.example.org
|
||||
email hostmaster@example.org
|
||||
}
|
||||
forward . /etc/resolv.conf
|
||||
}
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Knot DNS' \fB\fCkdig\fR as well as Bind9' \fB\fCdig\fR (since 9.17.7, via \fB\fC+tls\fR) can be used to make DNS-over-TLS queries. No command line client supports gRPC making
|
||||
debugging these transports harder than it should be.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
RFC 7858 and https://grpc.io
|
||||
RFC 7858
|
||||
\[la]https://www.rfc-editor.org/info/rfc7858/\[ra] and https://grpc.io
|
||||
\[la]https://grpc.io\[ra].
|
||||
|
||||
|
||||
Reference in New Issue
Block a user