add local plugin (#4262)

* add local plugin

See: #4260

Signed-off-by: Miek Gieben <miek@miek.nl>

* stickler bot

Signed-off-by: Miek Gieben <miek@miek.nl>

* See Also

Signed-off-by: Miek Gieben <miek@miek.nl>

1 files changed, 67 insertions, 0 deletions

diff --git a/man/coredns-local.7 b/man/coredns-local.7
new file mode 100644
index 000000000..f549db0da
--- /dev/null
+++ b/man/coredns-local.7
@@ -0,0 +1,67 @@
+.\" Generated by Mmark Markdown Processer - mmark.miek.nl
+.TH "COREDNS-LOCAL" 7 "November 2020" "CoreDNS" "CoreDNS Plugins"
+
+.SH "NAME"
+.PP
+\fIlocal\fP - respond to local names.
+
+.SH "DESCRIPTION"
+.PP
+\fIlocal\fP will respond with a basic reply to a "local request". Local request are defined to be
+names in the following zones: localhost, 0.in-addr.arpa, 127.in-addr.arpa and 255.in-addr.arpa \fIand\fP
+any query asking for \fB\fClocalhost.<domain>\fR. When seeing the latter a metric counter is increased and
+if \fIdebug\fP is enabled a debug log is emitted.
+
+.PP
+With \fIlocal\fP enabled any query falling under these zones will get a reply. The prevents the query
+from "escaping" to the internet and putting strain on external infrastructure.
+
+.PP
+The zones are mostly empty, only \fB\fClocalhost.\fR address records (A and AAAA) are defined and a
+\fB\fC1.0.0.127.in-addr.arpa.\fR reverse (PTR) record.
+
+.SH "SYNTAX"
+.PP
+.RS
+
+.nf
+local
+
+.fi
+.RE
+
+.SH "METRICS"
+.PP
+If monitoring is enabled (via the \fIprometheus\fP plugin) then the following metric is exported:
+
+.IP \(bu 4
+\fB\fCcoredns_local_localhost_requests_total{}\fR - a counter of the number of \fB\fClocalhost.<domain>\fR
+requests CoreDNS has seen. Note this does \fInot\fP count \fB\fClocalhost.\fR queries.
+
+
+.PP
+Note that this metric \fIdoes not\fP have a \fB\fCserver\fR label, because it's more interesting to find the
+client(s) performing these queries than to see which server handled it. You'll need to inspect the
+debug log to get the client IP address.
+
+.SH "EXAMPLES"
+.PP
+.RS
+
+.nf
+\&. {
+    local
+}
+
+.fi
+.RE
+
+.SH "BUGS"
+.PP
+Only the \fB\fCin-addr.arpa.\fR reverse zone is implemented, \fB\fCip6.arpa.\fR queries are not intercepted.
+
+.SH "ALSO SEE"
+.PP
+BIND9's configuration in Debian comes with these zones preconfigured. See the \fIdebug\fP plugin for
+enabling debug logging.
+