c742ec03f5
* Upgrade antonmedv/expr to expr-lang/expr The project has moved. This also upgrades from 1.15.5 to 1.16.9. The expr project lacks a changelog but tests pass and the changes don't seem to change it much - but there were a lot of changes. Signed-off-by: Kevin Lyda <kevin@lyda.ie> * Upgrade build image In reviewing the build results I see the old build image was deprecated so upgrading to something newer. Signed-off-by: Kevin Lyda <kevin@lyda.ie> --------- Signed-off-by: Kevin Lyda <kevin@lyda.ie>
184 lines
4.5 KiB
Groff
184 lines
4.5 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-VIEW" 7 "September 2022" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIview\fP - defines conditions that must be met for a DNS request to be routed to the server block.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
\fIview\fP defines an expression that must evaluate to true for a DNS request to be routed to the server block.
|
|
This enables advanced server block routing functions such as split dns.
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
view NAME {
|
|
expr EXPRESSION
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fB\fCview\fR \fBNAME\fP - The name of the view used by metrics and exported as metadata for requests that match the
|
|
view's expression
|
|
.IP \(bu 4
|
|
\fB\fCexpr\fR \fBEXPRESSION\fP - CoreDNS will only route incoming queries to the enclosing server block
|
|
if the \fBEXPRESSION\fP evaluates to true. See the \fBExpressions\fP section for available variables and functions.
|
|
If multiple instances of view are defined, all \fBEXPRESSION\fP must evaluate to true for CoreDNS will only route
|
|
incoming queries to the enclosing server block.
|
|
|
|
|
|
.PP
|
|
For expression syntax and examples, see the Expressions and Examples sections.
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Implement CIDR based split DNS routing. This will return a different
|
|
answer for \fB\fCtest.\fR depending on client's IP address. It returns ...
|
|
* \fB\fCtest. 3600 IN A 1.1.1.1\fR, for queries with a source address in 127.0.0.0/24
|
|
* \fB\fCtest. 3600 IN A 2.2.2.2\fR, for queries with a source address in 192.168.0.0/16
|
|
* \fB\fCtest. 3600 IN A 3.3.3.3\fR, for all others
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
view example1 {
|
|
expr incidr(client\_ip(), '127.0.0.0/24')
|
|
}
|
|
hosts {
|
|
1.1.1.1 test
|
|
}
|
|
}
|
|
|
|
\&. {
|
|
view example2 {
|
|
expr incidr(client\_ip(), '192.168.0.0/16')
|
|
}
|
|
hosts {
|
|
2.2.2.2 test
|
|
}
|
|
}
|
|
|
|
\&. {
|
|
hosts {
|
|
3.3.3.3 test
|
|
}
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Send all \fB\fCA\fR and \fB\fCAAAA\fR requests to \fB\fC10.0.0.6\fR, and all other requests to \fB\fC10.0.0.1\fR.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
view example {
|
|
expr type() in ['A', 'AAAA']
|
|
}
|
|
forward . 10.0.0.6
|
|
}
|
|
|
|
\&. {
|
|
forward . 10.0.0.1
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Send all requests for \fB\fCabc.*.example.com\fR (where * can be any number of labels), to \fB\fC10.0.0.2\fR, and all other
|
|
requests to \fB\fC10.0.0.1\fR.
|
|
Note that the regex pattern is enclosed in single quotes, and backslashes are escaped with backslashes.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
view example {
|
|
expr name() matches '^abc\\\\..*\\\\.example\\\\.com\\\\.$'
|
|
}
|
|
forward . 10.0.0.2
|
|
}
|
|
|
|
\&. {
|
|
forward . 10.0.0.1
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SH "EXPRESSIONS"
|
|
.PP
|
|
To evaluate expressions, \fIview\fP uses the expr-lang/expr package (https://github.com/expr-lang/expr
|
|
\[la]https://github.com/expr-lang/expr\[ra]).
|
|
For example, an expression could look like:
|
|
\fB\fC(type() == 'A' && name() == 'example.com') || client_ip() == '1.2.3.4'\fR.
|
|
|
|
.PP
|
|
All expressions should be written to evaluate to a boolean value.
|
|
|
|
.PP
|
|
See https://github.com/expr-lang/expr/blob/master/docs/Language-Definition.md
|
|
\[la]https://github.com/expr-lang/expr/blob/master/docs/Language-Definition.md\[ra] as a detailed reference for valid syntax.
|
|
|
|
.SS "AVAILABLE EXPRESSION FUNCTIONS"
|
|
.PP
|
|
In the context of the \fIview\fP plugin, expressions can reference DNS query information by using utility
|
|
functions defined below.
|
|
|
|
.SS "DNS QUERY FUNCTIONS"
|
|
.IP \(bu 4
|
|
\fB\fCbufsize() int\fR: the EDNS0 buffer size advertised in the query
|
|
.IP \(bu 4
|
|
\fB\fCclass() string\fR: class of the request (IN, CH, ...)
|
|
.IP \(bu 4
|
|
\fB\fCclient_ip() string\fR: client's IP address, for IPv6 addresses these are enclosed in brackets: \fB\fC[::1]\fR
|
|
.IP \(bu 4
|
|
\fB\fCdo() bool\fR: the EDNS0 DO (DNSSEC OK) bit set in the query
|
|
.IP \(bu 4
|
|
\fB\fCid() int\fR: query ID
|
|
.IP \(bu 4
|
|
\fB\fCname() string\fR: name of the request (the domain name requested)
|
|
.IP \(bu 4
|
|
\fB\fCopcode() int\fR: query OPCODE
|
|
.IP \(bu 4
|
|
\fB\fCport() string\fR: client's port
|
|
.IP \(bu 4
|
|
\fB\fCproto() string\fR: protocol used (tcp or udp)
|
|
.IP \(bu 4
|
|
\fB\fCserver_ip() string\fR: server's IP address; for IPv6 addresses these are enclosed in brackets: \fB\fC[::1]\fR
|
|
.IP \(bu 4
|
|
\fB\fCserver_port() string\fR : client's port
|
|
.IP \(bu 4
|
|
\fB\fCsize() int\fR: request size in bytes
|
|
.IP \(bu 4
|
|
\fB\fCtype() string\fR: type of the request (A, AAAA, TXT, ...)
|
|
|
|
|
|
.SS "UTILITY FUNCTIONS"
|
|
.IP \(bu 4
|
|
\fB\fCincidr(ip string, cidr string) bool\fR: returns true if \fIip\fP is within \fIcidr\fP
|
|
.IP \(bu 4
|
|
\fB\fCmetadata(label string)\fR - returns the value for the metadata matching \fIlabel\fP
|
|
|
|
|
|
.SH "METADATA"
|
|
.PP
|
|
The view plugin will publish the following metadata, if the \fImetadata\fP
|
|
plugin is also enabled:
|
|
|
|
.IP \(bu 4
|
|
\fB\fCview/name\fR: the name of the view handling the current request
|
|
|
|
|