mirror of
https://github.com/coredns/coredns.git
synced 2026-10-27 12:45:43 -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:
Ben Kochie
GitHub
@@ -1,5 +1,5 @@
|
||||
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
||||
.TH "COREDNS-TEMPLATE" 7 "March 2026" "CoreDNS" "CoreDNS Plugins"
|
||||
.TH "COREDNS-TEMPLATE" 7 "October 2026" "CoreDNS" "CoreDNS Plugins"
|
||||
|
||||
.SH "NAME"
|
||||
.PP
|
||||
@@ -16,6 +16,8 @@ The \fItemplate\fP plugin allows you to dynamically respond to queries by just w
|
||||
.nf
|
||||
template CLASS TYPE [ZONE...] {
|
||||
match REGEX...
|
||||
var NAME EXPRESSION
|
||||
expr EXPRESSION
|
||||
answer RR
|
||||
additional RR
|
||||
authority RR
|
||||
@@ -40,11 +42,19 @@ Specifying no regex matches everything (default: \fB\fC.*\fR). First matching re
|
||||
must not exceed 10000 characters.
|
||||
.IP \(bu 4
|
||||
\fB\fCanswer|additional|authority\fR \fBRR\fP A RFC 1035
|
||||
\[la]https://tools.ietf.org/html/rfc1035#section-5\[ra] style resource record fragment
|
||||
\[la]https://www.rfc-editor.org/info/rfc1035/#section-5\[ra] style resource record fragment
|
||||
built by a Go template
|
||||
\[la]https://golang.org/pkg/text/template/\[ra] that contains the reply. Specifying no answer will result
|
||||
in a response with an empty answer section.
|
||||
.IP \(bu 4
|
||||
\fB\fCvar\fR \fBNAME\fP \fBEXPRESSION\fP sets the variable \fBNAME\fP to the result of \fBEXPRESSION\fP, evaluated for each matching query
|
||||
and available to the templates as \fB\fC.Var.NAME\fR. Multiple variables may be set; each one may use the variables declared before it.
|
||||
See the \fBExpressions\fP section.
|
||||
.IP \(bu 4
|
||||
\fB\fCexpr\fR \fBEXPRESSION\fP a condition that must evaluate to \fB\fCtrue\fR for the query to match. All conditions must be true for a
|
||||
complete match; otherwise the query is subject to \fB\fCfallthrough\fR, as if no regex had matched. Conditions may use the
|
||||
variables declared with \fB\fCvar\fR. See the \fBExpressions\fP section.
|
||||
.IP \(bu 4
|
||||
\fB\fCrcode\fR \fBCODE\fP A response code (\fB\fCNXDOMAIN, SERVFAIL, ...\fR). The default is \fB\fCNOERROR\fR. Valid response code values are
|
||||
per the \fB\fCRcodeToString\fR map defined by the \fB\fCmiekg/dns\fR package in \fB\fCmsg.go\fR.
|
||||
.IP \(bu 4
|
||||
@@ -85,6 +95,8 @@ Each resource record is a full-featured Go template
|
||||
.IP \(bu 4
|
||||
\fB\fC.Remote\fR client’s IP address
|
||||
.IP \(bu 4
|
||||
\fB\fC.Var\fR the variables defined with \fB\fCvar\fR (e.g. \fB\fC.Var.myvariable\fR).
|
||||
.IP \(bu 4
|
||||
\fB\fC.Meta\fR a function that takes a metadata name and returns the value, if the
|
||||
metadata plugin is enabled. For example, \fB\fC.Meta "kubernetes/client-namespace"\fR
|
||||
|
||||
@@ -100,7 +112,7 @@ and the following predefined template functions
|
||||
|
||||
.PP
|
||||
The output of the template must be a RFC 1035
|
||||
\[la]https://tools.ietf.org/html/rfc1035\[ra] style resource record (commonly referred to as a "zone file").
|
||||
\[la]https://www.rfc-editor.org/info/rfc1035/\[ra] style resource record (commonly referred to as a "zone file").
|
||||
|
||||
.PP
|
||||
\fBWARNING\fP there is a syntactical problem with Go templates and CoreDNS config files. Expressions
|
||||
@@ -108,6 +120,27 @@ The output of the template must be a RFC 1035
|
||||
Caddy) while \fB\fC{{ $var }}\fR will work. See Bugs
|
||||
\[la]#bugs\[ra] and corefile(5).
|
||||
|
||||
.SH "EXPRESSIONS"
|
||||
.PP
|
||||
The \fBEXPRESSION\fP of a \fB\fCvar\fR or \fB\fCexpr\fR is written in the expr language, the same as used by the \fIview\fP plugin. See
|
||||
https://expr-lang.org/docs/language-definition
|
||||
\[la]https://expr-lang.org/docs/language-definition\[ra] as a detailed reference for valid syntax.
|
||||
|
||||
.PP
|
||||
Expressions can reference the DNS query functions and utility functions listed in the \fIview\fP plugin's documentation, the
|
||||
variables declared by preceding \fB\fCvar\fR options, and
|
||||
|
||||
.IP \(bu 4
|
||||
\fB\fCgroup(name string) string\fR: the capture group named \fIname\fP of the matching regex, or \fB\fC""\fR if there is no such group.
|
||||
.IP \(bu 4
|
||||
\fB\fCgroup(index int) string\fR: the \fIindex\fP-th capture group of the matching regex, \fB\fCgroup(0)\fR being the entire match, or \fB\fC""\fR
|
||||
if there is no such group.
|
||||
|
||||
|
||||
.PP
|
||||
A variable name must be a valid identifier and must not be the name of an existing function, or of a keyword or literal of
|
||||
the expr language, such as \fB\fClen\fR or \fB\fCtrue\fR.
|
||||
|
||||
.SH "METRICS"
|
||||
.PP
|
||||
If monitoring is enabled (via the \fIprometheus\fP plugin) then the following metrics are exported:
|
||||
@@ -153,7 +186,7 @@ The answer is always NXDOMAIN
|
||||
.SS "RESOLVE .INVALID AS NXDOMAIN"
|
||||
.PP
|
||||
The \fB\fC.invalid\fR domain is a reserved TLD (see RFC 2606 Reserved Top Level DNS Names
|
||||
\[la]https://tools.ietf.org/html/rfc2606#section-2\[ra]) to indicate invalid domains.
|
||||
\[la]https://www.rfc-editor.org/info/rfc2606/#section-2\[ra]) to indicate invalid domains.
|
||||
|
||||
.PP
|
||||
.RS
|
||||
@@ -270,6 +303,44 @@ Having templates to map certain PTR/A pairs is a common pattern.
|
||||
.PP
|
||||
Fallthrough is needed for mixed domains where only some responses are templated.
|
||||
|
||||
.SS "RESOLVE DEVICE ADDRESSES FOR HTTPS ON LAN"
|
||||
.PP
|
||||
For an embedded device on a local network to be trusted, it needs to have a certificate signed by a
|
||||
CA and the CA needs to verify that the device controls the name for which it is issued. As the local
|
||||
address may change, a certificate is issued for the wildcard subdomain \fB\fC*.<id>.example.com\fR instead,
|
||||
where \fB\fC<id>\fR is a unique id for the given device. The same trick as in the example above can be used
|
||||
to find out the actual IP address.
|
||||
|
||||
.PP
|
||||
Resolving to public IP addresses would allow for this to be used in phishing attacks, so an
|
||||
additional expression must be satisfied to limit the allowed IP range.
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
forward . 8.8.8.8
|
||||
|
||||
template IN A example.com {
|
||||
match ^(?P<ip>[0\-9]{1,3}(\-[0\-9]{1,3}){3})[.](?P<id>[a\-z2\-7]{26})[.]example[.]com[.]$
|
||||
var ip replace(group('ip'), '\-', '.')
|
||||
expr "any(['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', '169.254.0.0/16'], incidr(ip, #))"
|
||||
answer "{{ .Name }} 60 IN A {{ .Var.ip }}"
|
||||
fallthrough
|
||||
}
|
||||
}
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
The regular expression for the unique device id matches a base32 encoded string of a 128-bit device
|
||||
id, with the padding removed.
|
||||
|
||||
.PP
|
||||
Note that an expression using \fB\fC#\fR must be quoted, or it will be interpreted as a comment.
|
||||
|
||||
.SS "RESOLVE HEXADECIMAL IP PATTERN USING PARSEINT"
|
||||
.PP
|
||||
.RS
|
||||
@@ -400,8 +471,8 @@ RE2 syntax reference
|
||||
\[la]https://github.com/google/re2/wiki/Syntax\[ra] for details about the regex syntax
|
||||
.IP \(bu 4
|
||||
RFC 1034
|
||||
\[la]https://tools.ietf.org/html/rfc1034#section-3.6.1\[ra] and RFC 1035
|
||||
\[la]https://tools.ietf.org/html/rfc1035#section-5\[ra] for the resource record format
|
||||
\[la]https://www.rfc-editor.org/info/rfc1034/#section-3.6.1\[ra] and RFC 1035
|
||||
\[la]https://www.rfc-editor.org/info/rfc1035/#section-5\[ra] for the resource record format
|
||||
.IP \(bu 4
|
||||
Go template
|
||||
\[la]https://golang.org/pkg/text/template/\[ra] for the template language reference
|
||||
|
||||
Reference in New Issue
Block a user