diff options
| -rw-r--r-- | man/coredns-view.7 | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/man/coredns-view.7 b/man/coredns-view.7 new file mode 100644 index 000000000..0eb2d88b3 --- /dev/null +++ b/man/coredns-view.7 @@ -0,0 +1,184 @@ +.\" 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 antonmedv/expr package (https://github.com/antonmedv/expr +\[la]https://github.com/antonmedv/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/antonmedv/expr/blob/master/docs/Language-Definition.md +\[la]https://github.com/antonmedv/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 + + |