auto make -f Makefile.doc

Signed-off-by: coredns[bot] <bot@bot.coredns.io>

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
+
+