TrueCloudLab/coredns
16
0
Fork 2
Code Issues Pull requests 4 Projects Releases Packages Wiki Activity Actions

docs: Regenerate all manpages using mmark (#2762)

Browse source 
Mmark recently became able to create manual pages. This removed the
dependency on 'ronn' and just uses mmark (Go program).

Re-hookup Makefile.doc to generate the correct header mmark needs to
see and regenate them all.

Spot checking a few pages suggest they look good and actually better
than rendered with ronn, esp. lists in lists.

Fixes #2757

Signed-off-by: Miek Gieben <miek@miek.nl>
This commit is contained in:
Miek Gieben 2019-04-06 08:42:40 +01:00 • committed by GitHub
parent 663271a7ca
commit f8aa208cc0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
42 changed files with 4835 additions and 4364 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
Makefile.doc
View file

@ -1,13 +1,12 @@
ORG:=organization=CoreDNS
RONN:=ronn -r
MMARK:=mmark -man
PLUGINS:=$(wildcard plugin/*/README.md)
READMES:=$(subst plugin/,,$(PLUGINS))
READMES:=$(subst /README.md,,$(READMES))
PLUGINS:=$(subst plugin/,coredns-,$(PLUGINS))
PLUGINS:=$(subst /README.md,(7),$(PLUGINS))
ifeq (, $(shell which ronn))
$(warning "No ronn in $$PATH, exiting")
ifeq (, $(shell which mmark))
$(warning "No mmark in $$PATH, exiting, see github.com/mmarkdown/mmark")
all:
@echo "noop"
else
@ -15,15 +14,17 @@ all: man/coredns.1 man/corefile.5 plugins
endif
man/coredns.1: coredns.1.md
sed -e 's/^\(#.*\)/\U\1/' $< > $@.md
sed -i -e "s/@@PLUGINS@@/$(PLUGINS)/" $@.md
$(RONN) --$(ORG) --manual='CoreDNS' $@.md
rm $@.md
@/bin/echo -e '%%%\n title = "coredns 1"\n' \
'area = "CoreDNS"\n workgroup = "CoreDNS"\n%%%\n\n' > $@.header
@cat $@.header $< > $@.md && rm $@.header
@sed -i -e "s/@@PLUGINS@@/$(PLUGINS)/" $@.md
$(MMARK) $@.md > $@ && rm $@.md
man/corefile.5: corefile.5.md
sed -e 's/^\(#.*\)/\U\1/' $< > $@.md
$(RONN) --$(ORG) --manual='CoreDNS' $@.md
rm $@.md
@/bin/echo -e '%%%\n title = "corefile 5"\n' \
'area = "CoreDNS"\n workgroup = "CoreDNS"\n%%%\n\n' > $@.header
@cat $@.header $< > $@.md && rm $@.header
$(MMARK) $@.md > $@ && rm $@.md
.PHONY: plugins
plugins:
@ -32,9 +33,10 @@ plugins:
done
man/coredns-%.7: plugin/%/README.md
sed -e 's/^\(#.*\)/\U\1/' $< > $@.md
$(RONN) --$(ORG) --manual='CoreDNS plugins' $@.md
rm $@.md
@/bin/echo -e "%%%\n title = \"`basename $@ | sed s\/\.7\/\/` 7\"\n" \
'area = "CoreDNS"\n workgroup = "CoreDNS Plugins"\n%%%\n\n' > $@.header
@cat $@.header $< > $@.md && rm $@.header
$(MMARK) $@.md > $@ && rm $@.md
PHONY: clean
clean:

14
corefile.5.md
View file

@ -57,7 +57,7 @@ You can use the `import` "plugin" to include parts of other files, see <https://
If you want to reuse a snippet you can define one with and then use it with *import*.
~~~ corefile {
~~~ corefile
(mysnippet) {
log
whoami
@ -73,7 +73,7 @@ If you want to reuse a snippet you can define one with and then use it with *imp
The **ZONE** is root zone `.`, the **PLUGIN** is chaos. The chaos plugin takes an argument:
`CoreDNS-001`. This text is returned on a CH class query: `dig CH txt version.bind @localhost`.
~~~ Corefile
~~~ corefile
. {
chaos CoreDNS-001
}
@ -82,7 +82,7 @@ The **ZONE** is root zone `.`, the **PLUGIN** is chaos. The chaos plugin takes a
When defining a new zone, you either create a new server, or add it to an existing one. Here we
define one server that handles two zones; that potentially chain different plugins:
~~~ Corefile
~~~ corefile
example.org {
whoami
}
@ -93,7 +93,7 @@ org {
Is identical to:
~~~ Corefile
~~~ corefile
example.org org {
whoami
}
@ -101,7 +101,7 @@ example.org org {
Reverse zones can be specified as domain names:
~~~ Corefile
~~~ corefile
0.0.10.in-addr.arpa {
whoami
}
@ -109,7 +109,7 @@ Reverse zones can be specified as domain names:
or by just using the CIDR notation:
~~~ Corefile
~~~ corefile
10.0.0.0/24 {
whoami
}
@ -117,7 +117,7 @@ or by just using the CIDR notation:
This also works on a non octet boundary:
~~~ Corefile
~~~ corefile
10.0.0.0/27 {
whoami
}

170
man/coredns-auto.7
View file

@ -1,97 +1,113 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-AUTO" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIauto\fR \- enables serving zone data from an RFC 1035\-style master file, which is automatically picked up from disk\.
.
.SH "DESCRIPTION"
The \fIauto\fR plugin is used for an "old\-style" DNS server\. It serves from a preloaded file that exists on disk\. If the zone file contains signatures (i\.e\. is signed, i\.e\. using DNSSEC) correct DNSSEC answers are returned\. Only NSEC is supported! If you use this setup \fIyou\fR are responsible for re\-signing the zonefile\. New or changed zones are automatically picked up from disk\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-AUTO" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
auto [ZONES\.\.\.] {
directory DIR [REGEXP ORIGIN_TEMPLATE [TIMEOUT]]
.SH AUTO
.SH NAME
.PP
\fIauto\fP - enables serving zone data from an RFC 1035-style master file, which is automatically picked up from disk.
.SH DESCRIPTION
.PP
The \fIauto\fP plugin is used for an "old-style" DNS server. It serves from a preloaded file that exists
on disk. If the zone file contains signatures (i.e. is signed, i.e. using DNSSEC) correct DNSSEC answers
are returned. Only NSEC is supported! If you use this setup \fIyou\fP are responsible for re-signing the
zonefile. New or changed zones are automatically picked up from disk.
.SH SYNTAX
.PP
.RS
.nf
auto [ZONES...] {
directory DIR [REGEXP ORIGIN\_TEMPLATE]
transfer to ADDRESS...
reload DURATION
no_reload
upstream
}
.
.fi
.
.P
\fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block are used\.
.
.IP "\(bu" 4
\fBdirectory\fR loads zones from the specified \fBDIR\fR\. If a file name matches \fBREGEXP\fR it will be used to extract the origin\. \fBORIGIN_TEMPLATE\fR will be used as a template for the origin\. Strings like \fB{<number>}\fR are replaced with the respective matches in the file name, e\.g\. \fB{1}\fR is the first match, \fB{2}\fR is the second\. The default is: \fBdb\e\.(\.*) {1}\fR i\.e\. from a file with the name \fBdb\.example\.com\fR, the extracted origin will be \fBexample\.com\fR\. \fBTIMEOUT\fR is deprecated and will be removed in a subsequent version\. \fBreload\fR will be used, if not defined (it specifies how often CoreDNS should scan the directory to watch for file removal and addition; the default is every 60 seconds\. This value is in seconds\. The minimum value is 1 second\.)
.
.IP "\(bu" 4
\fBreload\fR interval to perform reloads of zones if SOA version changes and zonefiles\. Default is one minute\. Value of \fB0\fR means to not scan for changes and reload\. eg\. \fB30s\fR checks zonefile every 30 seconds and reloads zone when serial changes\.
.
.IP "\(bu" 4
\fBno_reload\fR deprecated\. Sets reload to 0\.
.
.IP "\(bu" 4
\fBupstream\fR defines upstream resolvers to be used resolve external names found (think CNAMEs) pointing to external names\. CoreDNS will resolve CNAMEs against itself\.
.
.IP "" 0
.
.P
All directives from the \fIfile\fR plugin are supported\. Note that \fIauto\fR will load all zones found, even though the directive might only receive queries for a specific zone\. I\.e:
.
.IP "" 4
.
.nf
\&\. {
auto example\.org {
.fi
.RE
.PP
\fBZONES\fP zones it should be authoritative for. If empty, the zones from the configuration block
are used.
.IP \(bu 4
\fB\fCdirectory\fR loads zones from the specified \fBDIR\fP. If a file name matches \fBREGEXP\fP it will be
used to extract the origin. \fBORIGIN_TEMPLATE\fP will be used as a template for the origin. Strings
like \fB\fC{<number>}\fR are replaced with the respective matches in the file name, e.g. \fB\fC{1}\fR is the
first match, \fB\fC{2}\fR is the second. The default is: \fB\fCdb\.(.*) {1}\fR i.e. from a file with the
name \fB\fCdb.example.com\fR, the extracted origin will be \fB\fCexample.com\fR.
.IP \(bu 4
\fB\fCtransfer\fR enables zone transfers. It may be specified multiples times. \fB\fCTo\fR or \fB\fCfrom\fR signals
the direction. \fBADDRESS\fP must be denoted in CIDR notation (e.g., 127.0.0.1/32) or just as plain
addresses. The special wildcard \fB\fC*\fR means: the entire internet (only valid for 'transfer to').
When an address is specified a notify message will be send whenever the zone is reloaded.
.IP \(bu 4
\fB\fCreload\fR interval to perform reloads of zones if SOA version changes and zonefiles. It specifies how often CoreDNS should scan the directory to watch for file removal and addition. Default is one minute.
Value of \fB\fC0\fR means to not scan for changes and reload. eg. \fB\fC30s\fR checks zonefile every 30 seconds
and reloads zone when serial changes.
.IP \(bu 4
\fB\fCupstream\fR defines upstream resolvers to be used resolve external names found (think CNAMEs)
pointing to external names. CoreDNS will resolve CNAMEs against itself.
.PP
All directives from the \fIfile\fP plugin are supported. Note that \fIauto\fP will load all zones found,
even though the directive might only receive queries for a specific zone. I.e:
.PP
.RS
.nf
\&. {
auto example.org {
directory /etc/coredns/zones
}
}
.
.fi
.
.IP "" 0
.
.P
Will happily pick up a zone for \fBexample\.COM\fR, except it will never be queried, because the \fIauto\fR directive only is authoritative for \fBexample\.ORG\fR\.
.
.SH "EXAMPLES"
Load \fBorg\fR domains from \fB/etc/coredns/zones/org\fR and allow transfers to the internet, but send notifies to 10\.240\.1\.1
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Will happily pick up a zone for \fB\fCexample.COM\fR, except it will never be queried, because the \fIauto\fP
directive only is authoritative for \fB\fCexample.ORG\fR.
.SH EXAMPLES
.PP
Load \fB\fCorg\fR domains from \fB\fC/etc/coredns/zones/org\fR and allow transfers to the internet, but send
notifies to 10.240.1.1
.PP
.RS
.nf
\&. {
auto org {
directory /etc/coredns/zones/org
transfer to *
transfer to 10\.240\.1\.1
transfer to 10.240.1.1
}
}
.
.fi
.
.IP "" 0
.
.P
Load \fBorg\fR domains from \fB/etc/coredns/zones/org\fR and looks for file names as \fBwww\.db\.example\.org\fR, where \fBexample\.org\fR is the origin\. Scan every 45 seconds\.
.
.IP "" 4
.
.nf
.fi
.RE
.PP
Load \fB\fCorg\fR domains from \fB\fC/etc/coredns/zones/org\fR and looks for file names as \fB\fCwww.db.example.org\fR,
where \fB\fCexample.org\fR is the origin. Scan every 45 seconds.
.PP
.RS
.nf
org {
auto {
directory /etc/coredns/zones/org www\e\.db\e\.(\.*) {1} 45
directory /etc/coredns/zones/org www\\.db\\.(.*) {1}
reload 45s
}
}
.
.fi
.
.IP "" 0
.fi
.RE

134
man/coredns-autopath.7
View file

@ -1,67 +1,81 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-AUTOPATH" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIautopath\fR \- allows for server\-side search path completion\.
.
.SH "DESCRIPTION"
If it sees a query that matches the first element of the configured search path, \fIautopath\fR will follow the chain of search path elements and return the first reply that is not NXDOMAIN\. On any failures, the original reply is returned\. Because \fIautopath\fR returns a reply for a name that wasn\'t the original question it will add a CNAME that points from the original name (with the search path element in it) to the name of this answer\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-AUTOPATH" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH AUTOPATH
.SH NAME
.PP
\fIautopath\fP - allows for server-side search path completion.
.SH DESCRIPTION
.PP
If it sees a query that matches the first element of the configured search path, \fIautopath\fP will
follow the chain of search path elements and return the first reply that is not NXDOMAIN. On any
failures, the original reply is returned. Because \fIautopath\fP returns a reply for a name that wasn't
the original question it will add a CNAME that points from the original name (with the search path
element in it) to the name of this answer.
.SH SYNTAX
.PP
.RS
.nf
autopath [ZONE...] RESOLV\-CONF
autopath [ZONE\.\.\.] RESOLV\-CONF
.
.fi
.
.IP "\(bu" 4
\fBZONES\fR zones \fIautopath\fR should be authoritative for\.
.
.IP "\(bu" 4
\fBRESOLV\-CONF\fR points to a \fBresolv\.conf\fR like file or uses a special syntax to point to another plugin\. For instance \fB@kubernetes\fR, will call out to the kubernetes plugin (for each query) to retrieve the search list it should use\.
.
.IP "" 0
.
.P
If a plugin implements the \fBAutoPather\fR interface then it can be used\.
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metric is exported:
.
.IP "\(bu" 4
\fBcoredns_autopath_success_count_total{server}\fR \- counter of successfully autopath\-ed queries\.
.
.IP "" 0
.
.P
The \fBserver\fR label is explained in the \fImetrics\fR plugin documentation\.
.
.SH "EXAMPLES"
.
.nf
.RE
.IP \(bu 4
\fBZONES\fP zones \fIautopath\fP should be authoritative for.
.IP \(bu 4
\fBRESOLV-CONF\fP points to a \fB\fCresolv.conf\fR like file or uses a special syntax to point to another
plugin. For instance \fB\fC@kubernetes\fR, will call out to the kubernetes plugin (for each
query) to retrieve the search list it should use.
.PP
If a plugin implements the \fB\fCAutoPather\fR interface then it can be used.
.SH METRICS
.PP
If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric is exported:
.IP \(bu 4
\fB\fCcoredns_autopath_success_count_total{server}\fR - counter of successfully autopath-ed queries.
.PP
The \fB\fCserver\fR label is explained in the \fImetrics\fP plugin documentation.
.SH EXAMPLES
.PP
.RS
.nf
autopath my\-resolv.conf
autopath my\-resolv\.conf
.
.fi
.
.P
Use \fBmy\-resolv\.conf\fR as the file to get the search path from\. This file only needs so have one line: \fBsearch domain1 domain2 \.\.\.\fR
.
.IP "" 4
.
.nf
.RE
.PP
Use \fB\fCmy-resolv.conf\fR as the file to get the search path from. This file only needs so have one line:
\fB\fCsearch domain1 domain2 ...\fR
.PP
.RS
.nf
autopath @kubernetes
.
.fi
.
.IP "" 0
.
.P
Use the search path dynamically retrieved from the \fIkubernetes\fR plugin\.
.
.SH "KNOWN ISSUES"
Autopath is not compatible with pods running from Windows nodes\.
.RE
.PP
Use the search path dynamically retrieved from the \fIkubernetes\fP plugin.
.SH KNOWN ISSUES
.PP
In Kubernetes, \fIautopath\fP is not compatible with pods running from Windows nodes.
.PP
If the server side search ultimately results in a negative answer (e.g. \fB\fCNXDOMAIN\fR), then the client will fruitlessly search all paths manually, thus negating the \fIautopath\fP optimization.

128
man/coredns-bind.7
View file

@ -1,74 +1,78 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-BIND" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIbind\fR \- overrides the host to which the server should bind\.
.
.SH "DESCRIPTION"
Normally, the listener binds to the wildcard host\. However, you may want the listener to bind to another IP instead\.
.
.P
If several addresses are provided, a listener will be open on each of the IP provided\.
.
.P
Each address has to be an IP of one of the interfaces of the host\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-BIND" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH BIND
.SH NAME
.PP
\fIbind\fP - overrides the host to which the server should bind.
.SH DESCRIPTION
.PP
Normally, the listener binds to the wildcard host. However, you may want the listener to bind to
another IP instead.
.PP
If several addresses are provided, a listener will be open on each of the IP provided.
.PP
Each address has to be an IP of one of the interfaces of the host.
.SH SYNTAX
.PP
.RS
.nf
bind ADDRESS ...
bind ADDRESS \.\.\.
.
.fi
.
.P
\fBADDRESS\fR is an IP address to bind to\. When several addresses are provided a listener will be opened on each of the addresses\.
.
.SH "EXAMPLES"
To make your socket accessible only to that machine, bind to IP 127\.0\.0\.1 (localhost):
.
.IP "" 4
.
.nf
.RE
\&\. {
bind 127\.0\.0\.1
.PP
\fBADDRESS\fP is an IP address to bind to.
When several addresses are provided a listener will be opened on each of the addresses.
.SH EXAMPLES
.PP
To make your socket accessible only to that machine, bind to IP 127.0.0.1 (localhost):
.PP
.RS
.nf
\&. {
bind 127.0.0.1
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
To allow processing DNS requests only local host on both IPv4 and IPv6 stacks, use the syntax:
.
.IP "" 4
.
.nf
\&\. {
bind 127\.0\.0\.1 ::1
.PP
.RS
.nf
\&. {
bind 127.0.0.1 ::1
}
.
.fi
.
.IP "" 0
.
.P
If the configuration comes up with several \fIbind\fR directives, all addresses are consolidated together: The following sample is equivalent to the preceding:
.
.IP "" 4
.
.nf
\&\. {
bind 127\.0\.0\.1
.fi
.RE
.PP
If the configuration comes up with several \fIbind\fP directives, all addresses are consolidated together:
The following sample is equivalent to the preceding:
.PP
.RS
.nf
\&. {
bind 127.0.0.1
bind ::1
}
.
.fi
.
.IP "" 0
.fi
.RE

252
man/coredns-cache.7
View file

@ -1,140 +1,152 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-CACHE" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIcache\fR \- enables a frontend cache\.
.
.SH "DESCRIPTION"
With \fIcache\fR enabled, all records except zone transfers and metadata records will be cached for up to 3600s\. Caching is mostly useful in a scenario when fetching data from the backend (upstream, database, etc\.) is expensive\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-CACHE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH CACHE
.SH NAME
.PP
\fIcache\fP - enables a frontend cache.
.SH DESCRIPTION
.PP
With \fIcache\fP enabled, all records except zone transfers and metadata records will be cached for up to
3600s. Caching is mostly useful in a scenario when fetching data from the backend (upstream,
database, etc.) is expensive.
.PP
This plugin can only be used once per Server Block.
.SH SYNTAX
.PP
.RS
.nf
cache [TTL] [ZONES...]
cache [TTL] [ZONES\.\.\.]
.
.fi
.
.IP "\(bu" 4
\fBTTL\fR max TTL in seconds\. If not specified, the maximum TTL will be used, which is 3600 for NOERROR responses and 1800 for denial of existence ones\. Setting a TTL of 300: \fBcache 300\fR would cache records up to 300 seconds\.
.
.IP "\(bu" 4
\fBZONES\fR zones it should cache for\. If empty, the zones from the configuration block are used\.
.
.IP "" 0
.
.P
Each element in the cache is cached according to its TTL (with \fBTTL\fR as the max)\. A cache is divided into 256 shards, each holding up to 39 items by default \- for a total size of 256 * 39 = 9984 items\.
.
.P
If you want more control:
.
.IP "" 4
.
.nf
.RE
cache [TTL] [ZONES\.\.\.] {
.IP \(bu 4
\fBTTL\fP max TTL in seconds. If not specified, the maximum TTL will be used, which is 3600 for
NOERROR responses and 1800 for denial of existence ones.
Setting a TTL of 300: \fB\fCcache 300\fR would cache records up to 300 seconds.
.IP \(bu 4
\fBZONES\fP zones it should cache for. If empty, the zones from the configuration block are used.
.PP
Each element in the cache is cached according to its TTL (with \fBTTL\fP as the max).
A cache is divided into 256 shards, each holding up to 39 items by default - for a total size
of 256 * 39 = 9984 items.
.PP
If you want more control:
.PP
.RS
.nf
cache [TTL] [ZONES...] {
success CAPACITY [TTL] [MINTTL]
denial CAPACITY [TTL] [MINTTL]
prefetch AMOUNT [[DURATION] [PERCENTAGE%]]
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBTTL\fR and \fBZONES\fR as above\.
.
.IP "\(bu" 4
\fBsuccess\fR, override the settings for caching successful responses\. \fBCAPACITY\fR indicates the maximum number of packets we cache before we start evicting (\fIrandomly\fR)\. \fBTTL\fR overrides the cache maximum TTL\. \fBMINTTL\fR overrides the cache minimum TTL (default 5), which can be useful to limit queries to the backend\.
.
.IP "\(bu" 4
\fBdenial\fR, override the settings for caching denial of existence responses\. \fBCAPACITY\fR indicates the maximum number of packets we cache before we start evicting (LRU)\. \fBTTL\fR overrides the cache maximum TTL\. \fBMINTTL\fR overrides the cache minimum TTL (default 5), which can be useful to limit queries to the backend\. There is a third category (\fBerror\fR) but those responses are never cached\.
.
.IP "\(bu" 4
\fBprefetch\fR will prefetch popular items when they are about to be expunged from the cache\. Popular means \fBAMOUNT\fR queries have been seen with no gaps of \fBDURATION\fR or more between them\. \fBDURATION\fR defaults to 1m\. Prefetching will happen when the TTL drops below \fBPERCENTAGE\fR, which defaults to \fB10%\fR, or latest 1 second before TTL expiration\. Values should be in the range \fB[10%, 90%]\fR\. Note the percent sign is mandatory\. \fBPERCENTAGE\fR is treated as an \fBint\fR\.
.
.IP "" 0
.
.SH "CAPACITY AND EVICTION"
If \fBCAPACITY\fR \fIis not\fR specified, the default cache size is 9984 per cache\. The minimum allowed cache size is 1024\. If \fBCAPACITY\fR \fIis\fR specified, the actual cache size used will be rounded down to the nearest number divisible by 256 (so all shards are equal in size)\.
.
.P
Eviction is done per shard\. In effect, when a shard reaches capacity, items are evicted from that shard\. Since shards don\'t fill up perfectly evenly, evictions will occur before the entire cache reaches full capacity\. Each shard capacity is equal to the total cache size / number of shards (256)\. Eviction is random, not TTL based\. Entries with 0 TTL will remain in the cache until randomly evicted when the shard reaches capacity\.
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
.
.IP "\(bu" 4
\fBcoredns_cache_size{server, type}\fR \- Total elements in the cache by cache type\.
.
.IP "\(bu" 4
\fBcoredns_cache_hits_total{server, type}\fR \- Counter of cache hits by cache type\.
.
.IP "\(bu" 4
\fBcoredns_cache_misses_total{server}\fR \- Counter of cache misses\.
.
.IP "\(bu" 4
\fBcoredns_cache_drops_total{server}\fR \- Counter of dropped messages\.
.
.IP "" 0
.
.P
Cache types are either "denial" or "success"\. \fBServer\fR is the server handling the request, see the metrics plugin for documentation\.
.
.SH "EXAMPLES"
Enable caching for all zones, but cap everything to a TTL of 10 seconds:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.IP \(bu 4
\fBTTL\fP and \fBZONES\fP as above.
.IP \(bu 4
\fB\fCsuccess\fR, override the settings for caching successful responses. \fBCAPACITY\fP indicates the maximum
number of packets we cache before we start evicting (\fIrandomly\fP). \fBTTL\fP overrides the cache maximum TTL.
\fBMINTTL\fP overrides the cache minimum TTL (default 5), which can be useful to limit queries to the backend.
.IP \(bu 4
\fB\fCdenial\fR, override the settings for caching denial of existence responses. \fBCAPACITY\fP indicates the maximum
number of packets we cache before we start evicting (LRU). \fBTTL\fP overrides the cache maximum TTL.
\fBMINTTL\fP overrides the cache minimum TTL (default 5), which can be useful to limit queries to the backend.
There is a third category (\fB\fCerror\fR) but those responses are never cached.
.IP \(bu 4
\fB\fCprefetch\fR will prefetch popular items when they are about to be expunged from the cache.
Popular means \fBAMOUNT\fP queries have been seen with no gaps of \fBDURATION\fP or more between them.
\fBDURATION\fP defaults to 1m. Prefetching will happen when the TTL drops below \fBPERCENTAGE\fP,
which defaults to \fB\fC10%\fR, or latest 1 second before TTL expiration. Values should be in the range \fB\fC[10%, 90%]\fR.
Note the percent sign is mandatory. \fBPERCENTAGE\fP is treated as an \fB\fCint\fR.
.SH CAPACITY AND EVICTION
.PP
If \fBCAPACITY\fP \fIis not\fP specified, the default cache size is 9984 per cache. The minimum allowed cache size is 1024.
If \fBCAPACITY\fP \fIis\fP specified, the actual cache size used will be rounded down to the nearest number divisible by 256 (so all shards are equal in size).
.PP
Eviction is done per shard. In effect, when a shard reaches capacity, items are evicted from that shard.
Since shards don't fill up perfectly evenly, evictions will occur before the entire cache reaches full capacity.
Each shard capacity is equal to the total cache size / number of shards (256). Eviction is random, not TTL based.
Entries with 0 TTL will remain in the cache until randomly evicted when the shard reaches capacity.
.SH METRICS
.PP
If monitoring is enabled (via the \fIprometheus\fP directive) then the following metrics are exported:
.IP \(bu 4
\fB\fCcoredns_cache_size{server, type}\fR - Total elements in the cache by cache type.
.IP \(bu 4
\fB\fCcoredns_cache_hits_total{server, type}\fR - Counter of cache hits by cache type.
.IP \(bu 4
\fB\fCcoredns_cache_misses_total{server}\fR - Counter of cache misses.
.IP \(bu 4
\fB\fCcoredns_cache_drops_total{server}\fR - Counter of dropped messages.
.PP
Cache types are either "denial" or "success". \fB\fCServer\fR is the server handling the request, see the
metrics plugin for documentation.
.SH EXAMPLES
.PP
Enable caching for all zones, but cap everything to a TTL of 10 seconds:
.PP
.RS
.nf
\&. {
cache 10
whoami
}
.
.fi
.
.IP "" 0
.
.P
Proxy to Google Public DNS and only cache responses for example\.org (or below)\.
.
.IP "" 4
.
.nf
\&\. {
forward \. 8\.8\.8\.8:53
cache example\.org
.fi
.RE
.PP
Proxy to Google Public DNS and only cache responses for example.org (or below).
.PP
.RS
.nf
\&. {
forward . 8.8.8.8:53
cache example.org
}
.
.fi
.
.IP "" 0
.
.P
Enable caching for all zones, keep a positive cache size of 5000 and a negative cache size of 2500:
.
.IP "" 4
.
.nf
\. {
.fi
.RE
.PP
Enable caching for all zones, keep a positive cache size of 5000 and a negative cache size of 2500:
.PP
.RS
.nf
. {
cache {
success 5000
denial 2500
}
}
.
.fi
.
.IP "" 0
.fi
.RE

106
man/coredns-cancel.7
View file

@ -1,61 +1,67 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-CANCEL" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIcancel\fR \- a plugin that cancels a request\'s context after 5001 milliseconds\.
.
.SH "DESCRIPTION"
The \fIcancel\fR plugin creates a canceling context for each request\. It adds a timeout that gets triggered after 5001 milliseconds\.
.
.P
The 5001 number is chosen because the default timeout for DNS clients is 5 seconds, after that they give up\.
.
.P
A plugin interested in the cancellation status should call \fBplugin\.Done()\fR on the context\. If the context was canceled due to a timeout the plugin should not write anything back to the client and return a value indicating CoreDNS should not either; a zero return value should suffice for that\.
.
.IP "" 4
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-CANCEL" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH CANCEL
.SH NAME
.PP
\fIcancel\fP - a plugin that cancels a request's context after 5001 milliseconds.
.SH DESCRIPTION
.PP
The \fIcancel\fP plugin creates a canceling context for each request. It adds a timeout that gets
triggered after 5001 milliseconds.
.PP
The 5001 number is chosen because the default timeout for DNS clients is 5 seconds, after that they
give up.
.PP
A plugin interested in the cancellation status should call \fB\fCplugin.Done()\fR on the context. If the
context was canceled due to a timeout the plugin should not write anything back to the client and
return a value indicating CoreDNS should not either; a zero return value should suffice for that.
.PP
.RS
.nf
cancel [TIMEOUT]
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBTIMEOUT\fR allows setting a custom timeout\. The default timeout is 5001 milliseconds (\fB5001 ms\fR)
.
.IP "" 0
.
.SH "EXAMPLES"
.
.nf
\&\. {
.fi
.RE
.IP \(bu 4
\fBTIMEOUT\fP allows setting a custom timeout. The default timeout is 5001 milliseconds (\fB\fC5001 ms\fR)
.SH EXAMPLES
.PP
.RS
.nf
\&. {
cancel
whoami
}
.
.fi
.
.P
Or with a custom timeout:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Or with a custom timeout:
.PP
.RS
.nf
\&. {
cancel 1s
whoami
}
.
.fi
.
.IP "" 0
.
.SH "ALSO SEE"
The Go documentation for the context package\.
.RE
.SH ALSO SEE
.PP
The Go documentation for the context package.

138
man/coredns-chaos.7
View file

@ -1,77 +1,79 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-CHAOS" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIchaos\fR \- allows for responding to TXT queries in the CH class\.
.
.SH "DESCRIPTION"
This is useful for retrieving version or author information from the server by querying a TXT record for a special domainname in the CH class\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-CHAOS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH CHAOS
.SH NAME
.PP
\fIchaos\fP - allows for responding to TXT queries in the CH class.
.SH DESCRIPTION
.PP
This is useful for retrieving version or author information from the server by querying a TXT record
for a special domainname in the CH class.
.SH SYNTAX
.PP
.RS
.nf
chaos [VERSION] [AUTHORS...]
chaos [VERSION] [AUTHORS\.\.\.]
.
.fi
.
.IP "\(bu" 4
\fBVERSION\fR is the version to return\. Defaults to \fBCoreDNS\-<version>\fR, if not set\.
.
.IP "\(bu" 4
\fBAUTHORS\fR is what authors to return\. No default\.
.
.IP "" 0
.
.P
Note that you have to make sure that this plugin will get actual queries for the following zones: \fBversion\.bind\fR, \fBversion\.server\fR, \fBauthors\.bind\fR, \fBhostname\.bind\fR and \fBid\.server\fR\.
.
.SH "EXAMPLES"
Specify all the zones in full\.
.
.IP "" 4
.
.nf
.RE
version\.bind version\.server authors\.bind hostname\.bind id\.server {
chaos CoreDNS\-001 info@coredns\.io
.IP \(bu 4
\fBVERSION\fP is the version to return. Defaults to \fB\fCCoreDNS-<version>\fR, if not set.
.IP \(bu 4
\fBAUTHORS\fP is what authors to return. This defaults to all GitHub handles in the OWNERS files.
.PP
Note that you have to make sure that this plugin will get actual queries for the
following zones: \fB\fCversion.bind\fR, \fB\fCversion.server\fR, \fB\fCauthors.bind\fR, \fB\fChostname.bind\fR and
\fB\fCid.server\fR.
.SH EXAMPLES
.PP
Specify all the zones in full.
.PP
.RS
.nf
version.bind version.server authors.bind hostname.bind id.server {
chaos CoreDNS\-001 info@coredns.io
}
.
.fi
.
.IP "" 0
.
.P
Or just default to \fB\.\fR:
.
.IP "" 4
.
.nf
\&\. {
chaos CoreDNS\-001 info@coredns\.io
.fi
.RE
.PP
Or just default to \fB\fC.\fR:
.PP
.RS
.nf
\&. {
chaos CoreDNS\-001 info@coredns.io
}
.
.fi
.
.IP "" 0
.
.P
And test with \fBdig\fR:
.
.IP "" 4
.
.nf
% dig @localhost CH TXT version\.bind
\.\.\.
.fi
.RE
.PP
And test with \fB\fCdig\fR:
.PP
.RS
.nf
% dig @localhost CH TXT version.bind
\&...
;; ANSWER SECTION:
version\.bind\. 0 CH TXT "CoreDNS\-001"
\.\.\.
.
.fi
.
.IP "" 0
version.bind. 0 CH TXT "CoreDNS\-001"
\&...
.fi
.RE

109
man/coredns-debug.7
View file

@ -1,61 +1,70 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-DEBUG" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIdebug\fR \- disables the automatic recovery upon a crash so that you\'ll get a nice stack trace\.
.
.SH "DESCRIPTION"
Normally CoreDNS will recover from panics, using \fIdebug\fR inhibits this\. The main use of \fIdebug\fR is to help testing\. A side effect of using \fIdebug\fR is that \fBlog\.Debug\fR and \fBlog\.Debugf\fR will be printed to standard output\.
.
.P
Note that the \fIerrors\fR plugin (if loaded) will also set a \fBrecover\fR negating this setting\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-DEBUG" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH DEBUG
.SH NAME
.PP
\fIdebug\fP - disables the automatic recovery upon a crash so that you'll get a nice stack trace.
.SH DESCRIPTION
.PP
Normally CoreDNS will recover from panics, using \fIdebug\fP inhibits this. The main use of \fIdebug\fP is
to help testing. A side effect of using \fIdebug\fP is that \fB\fClog.Debug\fR and \fB\fClog.Debugf\fR will be printed
to standard output.
.PP
Note that the \fIerrors\fP plugin (if loaded) will also set a \fB\fCrecover\fR negating this setting.
.SH SYNTAX
.PP
.RS
.nf
debug
.
.fi
.
.P
Some plugin will debug log DNS messages\. This is done in the following format:
.
.IP "" 4
.
.nf
.fi
.RE
.PP
Some plugin will debug log DNS messages. This is done in the following format:
.PP
.RS
.nf
debug: 000000 00 0a 01 00 00 01 00 00 00 00 00 01 07 65 78 61
debug: 000010 6d 70 6c 65 05 6c 6f 63 61 6c 00 00 01 00 01 00
debug: 000020 00 29 10 00 00 00 80 00 00 00
debug: 00002a
.
.fi
.
.IP "" 0
.
.P
Using \fBtext2pcap\fR (part of Wireshark) this can be converted back to binary, with the following command line: \fBtext2pcap \-i 17 \-u 53,53\fR\. Where 17 is the protocol (UDP) and 53 are the ports\. These ports allow wireshark to detect these packets as DNS messages\.
.
.P
Each plugin can decide to dump messages to aid in debugging\.
.
.SH "EXAMPLES"
Disable the ability to recover from crashes and show debug logging:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Using \fB\fCtext2pcap\fR (part of Wireshark) this can be converted back to binary, with the following
command line: \fB\fCtext2pcap -i 17 -u 53,53\fR. Where 17 is the protocol (UDP) and 53 are the ports. These
ports allow wireshark to detect these packets as DNS messages.
.PP
Each plugin can decide to dump messages to aid in debugging.
.SH EXAMPLES
.PP
Disable the ability to recover from crashes and show debug logging:
.PP
.RS
.nf
\&. {
debug
}
.
.fi
.
.IP "" 0
.
.SH "ALSO SEE"
https://www\.wireshark\.org/docs/man\-pages/text2pcap\.html\.
.RE
.SH ALSO SEE
.PP
https://www.wireshark.org/docs/man-pages/text2pcap.html
\[la]https://www.wireshark.org/docs/man-pages/text2pcap.html\[ra].

200
man/coredns-dnssec.7
View file

@ -1,110 +1,120 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-DNSSEC" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIdnssec\fR \- enable on\-the\-fly DNSSEC signing of served data\.
.
.SH "DESCRIPTION"
With \fIdnssec\fR any reply that doesn\'t (or can\'t) do DNSSEC will get signed on the fly\. Authenticated denial of existence is implemented with NSEC black lies\. Using ECDSA as an algorithm is preferred as this leads to smaller signatures (compared to RSA)\. NSEC3 is \fInot\fR supported\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-DNSSEC" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
dnssec [ZONES\.\.\. ] {
key file KEY\.\.\.
cache_capacity CAPACITY
.SH DNSSEC
.SH NAME
.PP
\fIdnssec\fP - enable on-the-fly DNSSEC signing of served data.
.SH DESCRIPTION
.PP
With \fIdnssec\fP any reply that doesn't (or can't) do DNSSEC will get signed on the fly. Authenticated
denial of existence is implemented with NSEC black lies. Using ECDSA as an algorithm is preferred as
this leads to smaller signatures (compared to RSA). NSEC3 is \fInot\fP supported.
.PP
This plugin can only be used once per Server Block.
.SH SYNTAX
.PP
.RS
.nf
dnssec [ZONES... ] {
key file KEY...
cache\_capacity CAPACITY
}
.
.fi
.
.P
The signing behavior depends on the keys specified\. If multiple keys are specified of which there is at least one key with the SEP bit set and at least one key with the SEP bit unset, signing will happen in split ZSK/KSK mode\. DNSKEY records will be signed with all keys that have the SEP bit set\. All other records will be signed with all keys that do not have the SEP bit set\.
.
.P
In any other case, each specified key will be treated as a CSK (common signing key), forgoing the ZSK/KSK split\. All signing operations are done online\. Authenticated denial of existence is implemented with NSEC black lies\. Using ECDSA as an algorithm is preferred as this leads to smaller signatures (compared to RSA)\. NSEC3 is \fInot\fR supported\.
.
.P
If multiple \fIdnssec\fR plugins are specified in the same zone, the last one specified will be used (See \fIbugs\fR)\.
.
.IP "\(bu" 4
\fBZONES\fR zones that should be signed\. If empty, the zones from the configuration block are used\.
.
.IP "\(bu" 4
\fBkey file\fR indicates that \fBKEY\fR file(s) should be read from disk\. When multiple keys are specified, RRsets will be signed with all keys\. Generating a key can be done with \fBdnssec\-keygen\fR: \fBdnssec\-keygen \-a ECDSAP256SHA256 <zonename>\fR\. A key created for zone \fIA\fR can be safely used for zone \fIB\fR\. The name of the key file can be specified in one of the following formats
.
.IP "\(bu" 4
basename of the generated key \fBKexample\.org+013+45330\fR
.
.IP "\(bu" 4
generated public key \fBKexample\.org+013+45330\.key\fR
.
.IP "\(bu" 4
generated private key \fBKexample\.org+013+45330\.private\fR
.
.IP "" 0
.RE
.PP
The signing behavior depends on the keys specified. If multiple keys are specified of which there is
at least one key with the SEP bit set and at least one key with the SEP bit unset, signing will happen
in split ZSK/KSK mode. DNSKEY records will be signed with all keys that have the SEP bit set. All other
records will be signed with all keys that do not have the SEP bit set.
.PP
In any other case, each specified key will be treated as a CSK (common signing key), forgoing the
ZSK/KSK split. All signing operations are done online.
Authenticated denial of existence is implemented with NSEC black lies. Using ECDSA as an algorithm
is preferred as this leads to smaller signatures (compared to RSA). NSEC3 is \fInot\fP supported.
.PP
If multiple \fIdnssec\fP plugins are specified in the same zone, the last one specified will be
used (See bugs
\[la]#bugs\[ra]).
.IP \(bu 4
\fBZONES\fP zones that should be signed. If empty, the zones from the configuration block
are used.
.IP \(bu 4
\fB\fCkey file\fR indicates that \fBKEY\fP file(s) should be read from disk. When multiple keys are specified, RRsets
will be signed with all keys. Generating a key can be done with \fB\fCdnssec-keygen\fR: \fB\fCdnssec-keygen -a
ECDSAP256SHA256 <zonename>\fR. A key created for zone \fIA\fP can be safely used for zone \fIB\fP. The name of the
key file can be specified in one of the following formats
.RS
.IP \(en 4
basename of the generated key \fB\fCKexample.org+013+45330\fR
.IP \(en 4
generated public key \fB\fCKexample.org+013+45330.key\fR
.IP \(en 4
generated private key \fB\fCKexample.org+013+45330.private\fR
.RE
.IP \(bu 4
\fB\fCcache_capacity\fR indicates the capacity of the cache. The dnssec plugin uses a cache to store
RRSIGs. The default for \fBCAPACITY\fP is 10000.
.SH METRICS
.PP
If monitoring is enabled (via the \fIprometheus\fP directive) then the following metrics are exported:
.IP \(bu 4
\fB\fCcoredns_dnssec_cache_size{server, type}\fR - total elements in the cache, type is "signature".
.IP \(bu 4
\fB\fCcoredns_dnssec_cache_hits_total{server}\fR - Counter of cache hits.
.IP \(bu 4
\fB\fCcoredns_dnssec_cache_misses_total{server}\fR - Counter of cache misses.
.PP
The label \fB\fCserver\fR indicated the server handling the request, see the \fImetrics\fP plugin for details.
.SH EXAMPLES
.PP
Sign responses for \fB\fCexample.org\fR with the key "Kexample.org.+013+45330.key".
.PP
.RS
.
.IP "\(bu" 4
\fBcache_capacity\fR indicates the capacity of the cache\. The dnssec plugin uses a cache to store RRSIGs\. The default for \fBCAPACITY\fR is 10000\.
.
.IP "" 0
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
.
.IP "\(bu" 4
\fBcoredns_dnssec_cache_size{server, type}\fR \- total elements in the cache, type is "signature"\.
.
.IP "\(bu" 4
\fBcoredns_dnssec_cache_hits_total{server}\fR \- Counter of cache hits\.
.
.IP "\(bu" 4
\fBcoredns_dnssec_cache_misses_total{server}\fR \- Counter of cache misses\.
.
.IP "" 0
.
.P
The label \fBserver\fR indicated the server handling the request, see the \fImetrics\fR plugin for details\.
.
.SH "EXAMPLES"
Sign responses for \fBexample\.org\fR with the key "Kexample\.org\.+013+45330\.key"\.
.
.IP "" 4
.
.nf
example\.org {
example.org {
dnssec {
key file Kexample\.org\.+013+45330
key file Kexample.org.+013+45330
}
whoami
}
.
.fi
.
.IP "" 0
.
.P
Sign responses for a kubernetes zone with the key "Kcluster\.local+013+45129\.key"\.
.
.IP "" 4
.
.nf
cluster\.local {
.fi
.RE
.PP
Sign responses for a kubernetes zone with the key "Kcluster.local+013+45129.key".
.PP
.RS
.nf
cluster.local {
kubernetes
dnssec {
key file Kcluster\.local+013+45129
key file Kcluster.local+013+45129
}
}
.
.fi
.
.IP "" 0
.fi
.RE

235
man/coredns-dnstap.7
View file

@ -1,139 +1,146 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-DNSTAP" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIdnstap\fR \- enable logging to dnstap\.
.
.SH "DESCRIPTION"
dnstap is a flexible, structured binary log format for DNS software: http://dnstap\.info\. With this plugin you make CoreDNS output dnstap logging\.
.
.P
Note that there is an internal buffer, so expect at least 13 requests before the server sends its dnstap messages to the socket\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-DNSTAP" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH DNSTAP
.SH NAME
.PP
\fIdnstap\fP - enable logging to dnstap.
.SH DESCRIPTION
.PP
dnstap is a flexible, structured binary log format for DNS software: http://dnstap.info
\[la]http://dnstap.info\[ra]. With this
plugin you make CoreDNS output dnstap logging.
.PP
Note that there is an internal buffer, so expect at least 13 requests before the server sends its
dnstap messages to the socket.
.SH SYNTAX
.PP
.RS
.nf
dnstap SOCKET [full]
.
.fi
.
.IP "\(bu" 4
\fBSOCKET\fR is the socket path supplied to the dnstap command line tool\.
.
.IP "\(bu" 4
\fBfull\fR to include the wire\-format DNS message\.
.
.IP "" 0
.
.SH "EXAMPLES"
Log information about client requests and responses to \fI/tmp/dnstap\.sock\fR\.
.
.IP "" 4
.
.nf
dnstap /tmp/dnstap\.sock
.
.fi
.
.IP "" 0
.
.P
Log information including the wire\-format DNS message about client requests and responses to \fI/tmp/dnstap\.sock\fR\.
.
.IP "" 4
.
.nf
.RE
.IP \(bu 4
\fBSOCKET\fP is the socket path supplied to the dnstap command line tool.
.IP \(bu 4
\fB\fCfull\fR to include the wire-format DNS message.
.SH EXAMPLES
.PP
Log information about client requests and responses to \fI/tmp/dnstap.sock\fP.
.PP
.RS
.nf
dnstap /tmp/dnstap.sock
dnstap unix:///tmp/dnstap\.sock full
.
.fi
.
.IP "" 0
.
.P
Log to a remote endpoint\.
.
.IP "" 4
.
.nf
.RE
.PP
Log information including the wire-format DNS message about client requests and responses to \fI/tmp/dnstap.sock\fP.
.PP
.RS
.nf
dnstap unix:///tmp/dnstap.sock full
dnstap tcp://127\.0\.0\.1:6000 full
.
.fi
.
.IP "" 0
.
.SH "COMMAND LINE TOOL"
Dnstap has a command line tool that can be used to inspect the logging\. The tool can be found at Github: \fIhttps://github\.com/dnstap/golang\-dnstap\fR\. It\'s written in Go\.
.
.P
The following command listens on the given socket and decodes messages to stdout\.
.
.IP "" 4
.
.nf
.RE
.PP
Log to a remote endpoint.
.PP
.RS
.nf
dnstap tcp://127.0.0.1:6000 full
$ dnstap \-u /tmp/dnstap\.sock
.
.fi
.
.IP "" 0
.
.P
The following command listens on the given socket and saves message payloads to a binary dnstap\-format log file\.
.
.IP "" 4
.
.nf
.RE
.SH COMMAND LINE TOOL
.PP
Dnstap has a command line tool that can be used to inspect the logging. The tool can be found
at Github: https://github.com/dnstap/golang-dnstap
\[la]https://github.com/dnstap/golang-dnstap\[ra]. It's written in Go.
.PP
The following command listens on the given socket and decodes messages to stdout.
.PP
.RS
.nf
$ dnstap \-u /tmp/dnstap.sock
$ dnstap \-u /tmp/dnstap\.sock \-w /tmp/test\.dnstap
.
.fi
.
.IP "" 0
.
.P
Listen for dnstap messages on port 6000\.
.
.IP "" 4
.
.nf
.RE
.PP
The following command listens on the given socket and saves message payloads to a binary dnstap-format log file.
.PP
.RS
.nf
$ dnstap \-u /tmp/dnstap.sock \-w /tmp/test.dnstap
$ dnstap \-l 127\.0\.0\.1:6000
.
.fi
.
.IP "" 0
.
.SH "USING DNSTAP IN YOUR PLUGIN"
.
.nf
.RE
.PP
Listen for dnstap messages on port 6000.
.PP
.RS
.nf
$ dnstap \-l 127.0.0.1:6000
.fi
.RE
.SH USING DNSTAP IN YOUR PLUGIN
.PP
.RS
.nf
import (
"github\.com/coredns/coredns/plugin/dnstap"
"github\.com/coredns/coredns/plugin/dnstap/msg"
"github.com/coredns/coredns/plugin/dnstap"
"github.com/coredns/coredns/plugin/dnstap/msg"
)
func (h Dnstap) ServeDNS(ctx context\.Context, w dns\.ResponseWriter, r *dns\.Msg) (int, error) {
func (h Dnstap) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error) {
// log client query to Dnstap
if t := dnstap\.TapperFromContext(ctx); t != nil {
b := msg\.New()\.Time(time\.Now())\.Addr(w\.RemoteAddr())
if t\.Pack() {
b\.Msg(r)
if t := dnstap.TapperFromContext(ctx); t != nil {
b := msg.New().Time(time.Now()).Addr(w.RemoteAddr())
if t.Pack() {
b.Msg(r)
}
if m, err := b\.ToClientQuery(); err == nil {
t\.TapMessage(m)
if m, err := b.ToClientQuery(); err == nil {
t.TapMessage(m)
}
}
// \.\.\.
// ...
}
.
.fi
.
.SH "SEE ALSO"
dnstap\.info \fIhttp://dnstap\.info\fR\.
.RE
.SH SEE ALSO
.PP
dnstap.info
\[la]http://dnstap.info\[ra].

199
man/coredns-erratic.7
View file

@ -1,125 +1,138 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ERRATIC" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIerratic\fR \- a plugin useful for testing client behavior\.
.
.SH "DESCRIPTION"
\fIerratic\fR returns a static response to all queries, but the responses can be delayed, dropped or truncated\. The \fIerratic\fR plugin will respond to every A or AAAA query\. For any other type it will return a SERVFAIL response\. The reply for A will return 192\.0\.2\.53 (see RFC 5737 \fIhttps://tools\.ietf\.org/html/rfc5737\fR, for AAAA it returns 2001:DB8::53 (see RFC 3849 \fIhttps://tools\.ietf\.org/html/rfc3849\fR) and for an AXFR request it will respond with a small zone transfer\.
.
.P
\fIerratic\fR can also be used in conjunction with the \fIautopath\fR plugin\. This is mostly to aid in testing\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-ERRATIC" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH ERRATIC
.SH NAME
.PP
\fIerratic\fP - a plugin useful for testing client behavior.
.SH DESCRIPTION
.PP
\fIerratic\fP returns a static response to all queries, but the responses can be delayed, dropped or truncated.
The \fIerratic\fP plugin will respond to every A or AAAA query. For any other type it will return
a SERVFAIL response. The reply for A will return 192.0.2.53 (see RFC
5737
\[la]https://tools.ietf.org/html/rfc5737\[ra],
for AAAA it returns 2001:DB8::53 (see RFC 3849
\[la]https://tools.ietf.org/html/rfc3849\[ra]) and for an
AXFR request it will respond with a small zone transfer.
.PP
\fIerratic\fP can also be used in conjunction with the \fIautopath\fP plugin. This is mostly to aid in
testing.
.SH SYNTAX
.PP
.RS
.nf
erratic {
drop [AMOUNT]
truncate [AMOUNT]
delay [AMOUNT [DURATION]]
}
.
.fi
.
.IP "\(bu" 4
\fBdrop\fR: drop 1 per \fBAMOUNT\fR of queries, the default is 2\.
.
.IP "\(bu" 4
\fBtruncate\fR: truncate 1 per \fBAMOUNT\fR of queries, the default is 2\.
.
.IP "\(bu" 4
\fBdelay\fR: delay 1 per \fBAMOUNT\fR of queries for \fBDURATION\fR, the default for \fBAMOUNT\fR is 2 and the default for \fBDURATION\fR is 100ms\.
.
.IP "" 0
.
.P
In case of a zone transfer and truncate the final SOA record \fIisn\'t\fR added to the response\.
.
.SH "READY"
This plugin reports readiness to the ready plugin\.
.
.SH "EXAMPLES"
.
.nf
\&\. {
.fi
.RE
.IP \(bu 4
\fB\fCdrop\fR: drop 1 per \fBAMOUNT\fP of queries, the default is 2.
.IP \(bu 4
\fB\fCtruncate\fR: truncate 1 per \fBAMOUNT\fP of queries, the default is 2.
.IP \(bu 4
\fB\fCdelay\fR: delay 1 per \fBAMOUNT\fP of queries for \fBDURATION\fP, the default for \fBAMOUNT\fP is 2 and
the default for \fBDURATION\fP is 100ms.
.PP
In case of a zone transfer and truncate the final SOA record \fIisn't\fP added to the response.
.SH READY
.PP
This plugin reports readiness to the ready plugin.
.SH EXAMPLES
.PP
.RS
.nf
\&. {
erratic {
drop 3
}
}
.
.fi
.
.P
Or even shorter if the defaults suits you\. Note this only drops queries, it does not delay them\.
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Or even shorter if the defaults suits you. Note this only drops queries, it does not delay them.
.PP
.RS
.nf
\&. {
erratic
}
.
.fi
.
.IP "" 0
.
.P
Delay 1 in 3 queries for 50ms
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Delay 1 in 3 queries for 50ms
.PP
.RS
.nf
\&. {
erratic {
delay 3 50ms
}
}
.
.fi
.
.IP "" 0
.
.P
Delay 1 in 3 and truncate 1 in 5\.
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Delay 1 in 3 and truncate 1 in 5.
.PP
.RS
.nf
\&. {
erratic {
delay 3 5ms
truncate 5
}
}
.
.fi
.
.IP "" 0
.
.P
Drop every second query\.
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Drop every second query.
.PP
.RS
.nf
\&. {
erratic {
drop 2
truncate 2
}
}
.
.fi
.
.IP "" 0
.
.SH "ALSO SEE"
RFC 3849 \fIhttps://tools\.ietf\.org/html/rfc3849\fR and RFC 5737 \fIhttps://tools\.ietf\.org/html/rfc5737\fR\.
.RE
.SH ALSO SEE
.PP
RFC 3849
\[la]https://tools.ietf.org/html/rfc3849\[ra] and
RFC 5737
\[la]https://tools.ietf.org/html/rfc5737\[ra].

152
man/coredns-errors.7
View file

@ -1,96 +1,94 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ERRORS" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIerrors\fR \- enable error logging\.
.
.SH "DESCRIPTION"
Any errors encountered during the query processing will be printed to standard output\. The errors of particular type can be consolidated and printed once per some period of time\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "SYNTAX"
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-ERRORS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH ERRORS
.SH NAME
.PP
\fIerrors\fP - enable error logging.
.SH DESCRIPTION
.PP
Any errors encountered during the query processing will be printed to standard output. The errors of particular type can be consolidated and printed once per some period of time.
.PP
This plugin can only be used once per Server Block.
.SH SYNTAX
.PP
The basic syntax is:
.
.IP "" 4
.
.nf
.PP
.RS
.nf
errors
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Extra knobs are available with an expanded syntax:
.
.IP "" 4
.
.nf
.PP
.RS
.nf
errors {
consolidate DURATION REGEXP
consolidate DURATION REGEXP
}
.
.fi
.
.IP "" 0
.
.P
Option \fBconsolidate\fR allows collecting several error messages matching the regular expression \fBREGEXP\fR during \fBDURATION\fR\. After the \fBDURATION\fR since receiving the first such message, the consolidated message will be printed to standard output, e\.g\.
.
.IP "" 4
.
.nf
2 errors like \'^read udp \.* i/o timeout$\' occurred in last 30s
.
.fi
.
.IP "" 0
.
.P
Multiple \fBconsolidate\fR options with different \fBDURATION\fR and \fBREGEXP\fR are allowed\. In case if some error message corresponds to several defined regular expressions the message will be associated with the first appropriate \fBREGEXP\fR\.
.
.P
For better performance, it\'s recommended to use the \fB^\fR or \fB$\fR metacharacters in regular expression when filtering error messages by prefix or suffix, e\.g\. \fB^failed to \.*\fR, or \fB\.* timeout$\fR\.
.
.SH "EXAMPLES"
Use the \fIwhoami\fR to respond to queries and Log errors to standard output\.
.
.IP "" 4
.
.nf
.RE
\&\. {
.PP
Option \fB\fCconsolidate\fR allows collecting several error messages matching the regular expression \fBREGEXP\fP during \fBDURATION\fP. After the \fBDURATION\fP since receiving the first such message, the consolidated message will be printed to standard output, e.g.
.PP
.RS
.nf
2 errors like '^read udp .* i/o timeout$' occurred in last 30s
.fi
.RE
.PP
Multiple \fB\fCconsolidate\fR options with different \fBDURATION\fP and \fBREGEXP\fP are allowed. In case if some error message corresponds to several defined regular expressions the message will be associated with the first appropriate \fBREGEXP\fP.
.PP
For better performance, it's recommended to use the \fB\fC^\fR or \fB\fC$\fR metacharacters in regular expression when filtering error messages by prefix or suffix, e.g. \fB\fC^failed to .*\fR, or \fB\fC.* timeout$\fR.
.SH EXAMPLES
.PP
Use the \fIwhoami\fP to respond to queries and Log errors to standard output.
.PP
.RS
.nf
\&. {
whoami
errors
}
.
.fi
.
.IP "" 0
.
.P
Use the \fIforward\fR to resolve queries via 8\.8\.8\.8 and print consolidated error messages for errors with suffix " i/o timeout" or with prefix "Failed to "\.
.
.IP "" 4
.
.nf
\&\. {
forward \. 8\.8\.8\.8
.fi
.RE
.PP
Use the \fIforward\fP to resolve queries via 8.8.8.8 and print consolidated error messages for errors with suffix " i/o timeout" or with prefix "Failed to ".
.PP
.RS
.nf
\&. {
forward . 8.8.8.8
errors {
consolidate 5m "\.* i/o timeout$"
consolidate 30s "^Failed to \.+"
consolidate 5m ".* i/o timeout$"
consolidate 30s "^Failed to .+"
}
}
.
.fi
.
.IP "" 0
.fi
.RE

554
man/coredns-etcd.7
View file

@ -1,278 +1,356 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ETCD" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIetcd\fR \- enables reading zone data from an etcd version 3 instance\.
.
.SH "DESCRIPTION"
The data in etcd instance has to be encoded as a message \fIhttps://github\.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service\.go#L26\fR like SkyDNS \fIhttps://github\.com/skynetservices/skydns\fR\. It should also work just like SkyDNS\.
.
.P
The etcd plugin makes extensive use of the forward plugin to forward and query other servers in the network\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-ETCD" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH ETCD
.SH NAME
.PP
\fIetcd\fP - enables reading zone data from an etcd version 3 instance.
.SH DESCRIPTION
.PP
The data in etcd instance has to be encoded as
a message
\[la]https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26\[ra]
like SkyDNS
\[la]https://github.com/skynetservices/skydns\[ra]. It should also work just like SkyDNS.
.PP
The etcd plugin makes extensive use of the forward plugin to forward and query other servers in the
network.
.SH SYNTAX
.PP
.RS
.nf
etcd [ZONES...]
etcd [ZONES\.\.\.]
.
.fi
.
.IP "\(bu" 4
\fBZONES\fR zones etcd should be authoritative for\.
.
.IP "" 0
.
.P
The path will default to \fB/skydns\fR the local etcd3 proxy (http://localhost:2379)\. If no zones are specified the block\'s zone will be used as the zone\.
.
.P
If you want to \fBround robin\fR A and AAAA responses look at the \fBloadbalance\fR plugin\.
.
.IP "" 4
.
.nf
.RE
etcd [ZONES\.\.\.] {
fallthrough [ZONES\.\.\.]
.IP \(bu 4
\fBZONES\fP zones etcd should be authoritative for.
.PP
The path will default to \fB\fC/skydns\fR the local etcd3 proxy (http://localhost:2379
\[la]http://localhost:2379\[ra]). If no zones are
specified the block's zone will be used as the zone.
.PP
If you want to \fB\fCround robin\fR A and AAAA responses look at the \fB\fCloadbalance\fR plugin.
.PP
.RS
.nf
etcd [ZONES...] {
fallthrough [ZONES...]
path PATH
endpoint ENDPOINT\.\.\.
endpoint ENDPOINT...
credentials USERNAME PASSWORD
upstream [ADDRESS\.\.\.]
upstream [ADDRESS...]
tls CERT KEY CACERT
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBfallthrough\fR If zone matches but no record can be generated, pass request to the next plugin\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.IP "\(bu" 4
\fBPATH\fR the path inside etcd\. Defaults to "/skydns"\.
.
.IP "\(bu" 4
\fBENDPOINT\fR the etcd endpoints\. Defaults to "http://localhost:2379"\.
.
.IP "\(bu" 4
\fBcredentials\fR is used to set the \fBUSERNAME\fR and \fBPASSWORD\fR for accessing the etcd cluster\.
.
.IP "\(bu" 4
\fBupstream\fR upstream resolvers to be used resolve external names found in etcd (think CNAMEs) pointing to external names\. If you want CoreDNS to act as a proxy for clients, you\'ll need to add the \fIforward\fR plugin\. If no \fBADDRESS\fR is given, CoreDNS will resolve CNAMEs against itself\. \fBADDRESS\fR can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\.
.
.IP "\(bu" 4
\fBtls\fR followed by:
.
.IP "\(bu" 4
no arguments, if the server certificate is signed by a system\-installed CA and no client cert is needed
.
.IP "\(bu" 4
.RE
.IP \(bu 4
\fB\fCfallthrough\fR If zone matches but no record can be generated, pass request to the next plugin.
If \fB[ZONES...]\fP is omitted, then fallthrough happens for all zones for which the plugin
is authoritative. If specific zones are listed (for example \fB\fCin-addr.arpa\fR and \fB\fCip6.arpa\fR), then only
queries for those zones will be subject to fallthrough.
.IP \(bu 4
\fBPATH\fP the path inside etcd. Defaults to "/skydns".
.IP \(bu 4
\fBENDPOINT\fP the etcd endpoints. Defaults to "http://localhost:2379"
\[la]http://localhost:2379"\[ra].
.IP \(bu 4
\fB\fCcredentials\fR is used to set the \fBUSERNAME\fP and \fBPASSWORD\fP for accessing the etcd cluster.
.IP \(bu 4
\fB\fCupstream\fR upstream resolvers to be used resolve external names found in etcd (think CNAMEs)
pointing to external names. If you want CoreDNS to act as a proxy for clients, you'll need to add
the \fIforward\fP plugin. If no \fBADDRESS\fP is given, CoreDNS will resolve CNAMEs against itself.
\fBADDRESS\fP can be an IP address, and IP:port or a string pointing to a file that is structured
as /etc/resolv.conf.
.IP \(bu 4
\fB\fCtls\fR followed by:
.RS
.IP \(en 4
no arguments, if the server certificate is signed by a system-installed CA and no client cert is needed
.IP \(en 4
a single argument that is the CA PEM file, if the server cert is not signed by a system CA and no client cert is needed
.
.IP "\(bu" 4
two arguments \- path to cert PEM file, the path to private key PEM file \- if the server certificate is signed by a system\-installed CA and a client certificate is needed
.
.IP "\(bu" 4
three arguments \- path to cert PEM file, path to client private key PEM file, path to CA PEM file \- if the server certificate is not signed by a system\-installed CA and client certificate is needed\.
.
.IP "" 0
.IP \(en 4
two arguments - path to cert PEM file, the path to private key PEM file - if the server certificate is signed by a system-installed CA and a client certificate is needed
.IP \(en 4
three arguments - path to cert PEM file, path to client private key PEM file, path to CA PEM
file - if the server certificate is not signed by a system-installed CA and client certificate
is needed.
.
.IP "" 0
.
.SH "SPECIAL BEHAVIOUR"
CoreDNS etcd plugin leverages directory structure to look for related entries\. For example an entry \fB/skydns/test/skydns/mx\fR would have entries like \fB/skydns/test/skydns/mx/a\fR, \fB/skydns/test/skydns/mx/b\fR and so on\. Similarly a directory \fB/skydns/test/skydns/mx1\fR will have all \fBmx1\fR entries\.
.
.P
With etcd3, support for hierarchical keys are dropped \fIhttps://coreos\.com/etcd/docs/latest/learning/api\.html\fR\. This means there are no directories but only flat keys with prefixes in etcd3\. To accommodate lookups, etcdv3 plugin now does a lookup on prefix \fB/skydns/test/skydns/mx/\fR to search for entries like \fB/skydns/test/skydns/mx/a\fR etc, and if there is nothing found on \fB/skydns/test/skydns/mx/\fR, it looks for \fB/skydns/test/skydns/mx\fR to find entries like \fB/skydns/test/skydns/mx1\fR\.
.
.P
This causes two lookups from CoreDNS to etcdv3 in certain cases\.
.
.SH "MIGRATION TO <code>ETCDV3</code> API"
With CoreDNS release \fB1\.2\.0\fR, you\'ll need to migrate existing CoreDNS related data (if any) on your etcd server to etcdv3 API\. This is because with \fBetcdv3\fR support, CoreDNS can\'t see the data stored to an etcd server using \fBetcdv2\fR API\.
.
.P
Refer this blog by CoreOS team \fIhttps://coreos\.com/blog/migrating\-applications\-etcd\-v3\.html\fR to migrate to etcdv3 API\.
.
.SH "EXAMPLES"
.RE
.SH SPECIAL BEHAVIOUR
.PP
CoreDNS etcd plugin leverages directory structure to look for related entries. For example an entry \fB\fC/skydns/test/skydns/mx\fR would have entries like \fB\fC/skydns/test/skydns/mx/a\fR, \fB\fC/skydns/test/skydns/mx/b\fR and so on. Similarly a directory \fB\fC/skydns/test/skydns/mx1\fR will have all \fB\fCmx1\fR entries.
.PP
With etcd3, support for hierarchical keys are dropped
\[la]https://coreos.com/etcd/docs/latest/learning/api.html\[ra]. This means there are no directories but only flat keys with prefixes in etcd3. To accommodate lookups, etcdv3 plugin now does a lookup on prefix \fB\fC/skydns/test/skydns/mx/\fR to search for entries like \fB\fC/skydns/test/skydns/mx/a\fR etc, and if there is nothing found on \fB\fC/skydns/test/skydns/mx/\fR, it looks for \fB\fC/skydns/test/skydns/mx\fR to find entries like \fB\fC/skydns/test/skydns/mx1\fR.
.PP
This causes two lookups from CoreDNS to etcdv3 in certain cases.
.SH MIGRATION TO \fB\fCetcdv3\fR API
.PP
With CoreDNS release \fB\fC1.2.0\fR, you'll need to migrate existing CoreDNS related data (if any) on your etcd server to etcdv3 API. This is because with \fB\fCetcdv3\fR support, CoreDNS can't see the data stored to an etcd server using \fB\fCetcdv2\fR API.
.PP
Refer this blog by CoreOS team
\[la]https://coreos.com/blog/migrating-applications-etcd-v3.html\[ra] to migrate to etcdv3 API.
.SH EXAMPLES
.PP
This is the default SkyDNS setup, with everything specified in full:
.
.IP "" 4
.
.nf
\&\. {
etcd skydns\.local {
.PP
.RS
.nf
\&. {
etcd skydns.local {
path /skydns
endpoint http://localhost:2379
upstream
}
prometheus
cache 160 skydns\.local
cache 160 skydns.local
loadbalance
forward \. 8\.8\.8\.8:53 8\.8\.4\.4:53
forward . 8.8.8.8:53 8.8.4.4:53
}
.
.fi
.
.IP "" 0
.
.P
Or a setup where we use \fB/etc/resolv\.conf\fR as the basis for the proxy and the upstream when resolving external pointing CNAMEs\.
.
.IP "" 4
.
.nf
\&\. {
etcd skydns\.local {
.fi
.RE
.PP
Or a setup where we use \fB\fC/etc/resolv.conf\fR as the basis for the proxy and the upstream
when resolving external pointing CNAMEs.
.PP
.RS
.nf
\&. {
etcd skydns.local {
path /skydns
upstream
}
cache 160 skydns\.local
forward \. /etc/resolv\.conf
cache 160 skydns.local
forward . /etc/resolv.conf
}
.
.fi
.
.IP "" 0
.
.P
Multiple endpoints are supported as well\.
.
.IP "" 4
.
.nf
etcd skydns\.local {
.fi
.RE
.PP
Multiple endpoints are supported as well.
.PP
.RS
.nf
etcd skydns.local {
endpoint http://localhost:2379 http://localhost:4001
\.\.\.
.
.fi
.
.IP "" 0
.
.P
Before getting started with these examples, please setup \fBetcdctl\fR (with \fBetcdv3\fR API) as explained here \fIhttps://coreos\.com/etcd/docs/latest/dev\-guide/interacting_v3\.html\fR\. This will help you to put sample keys in your etcd server\.
.
.P
If you prefer, you can use \fBcurl\fR to populate the \fBetcd\fR server, but with \fBcurl\fR the endpoint URL depends on the version of \fBetcd\fR\. For instance, \fBetcd v3\.2\fR or before uses only [CLIENT\-URL]/v3alpha/\fIwhile \fBetcd v3\.5\fR or later uses [CLIENT\-URL]/v3/\fR \. Also, Key and Value must be base64 encoded in the JSON payload\. With \fBetcdctl\fR these details are automatically taken care off\. You can check this document \fIhttps://github\.com/coreos/etcd/blob/master/Documentation/dev\-guide/api_grpc_gateway\.md#notes\fR for details\.
.
.SS "REVERSE ZONES"
Reverse zones are supported\. You need to make CoreDNS aware of the fact that you are also authoritative for the reverse\. For instance if you want to add the reverse for 10\.0\.0\.0/24, you\'ll need to add the zone \fB0\.0\.10\.in\-addr\.arpa\fR to the list of zones\. Showing a snippet of a Corefile:
.
.IP "" 4
.
.nf
\&...
etcd skydns\.local 10\.0\.0\.0/24 {
\.\.\.
.
.fi
.
.IP "" 0
.
.P
Next you\'ll need to populate the zone with reverse records, here we add a reverse for 10\.0\.0\.127 pointing to reverse\.skydns\.local\.
.
.IP "" 4
.
.nf
.RE
.PP
Before getting started with these examples, please setup \fB\fCetcdctl\fR (with \fB\fCetcdv3\fR API) as explained here
\[la]https://coreos.com/etcd/docs/latest/dev-guide/interacting_v3.html\[ra]. This will help you to put sample keys in your etcd server.
.PP
If you prefer, you can use \fB\fCcurl\fR to populate the \fB\fCetcd\fR server, but with \fB\fCcurl\fR the endpoint URL depends on the version of \fB\fCetcd\fR. For instance, \fB\fCetcd v3.2\fR or before uses only [CLIENT-URL]/v3alpha/* while \fB\fCetcd v3.5\fR or later uses [CLIENT-URL]/v3/* . Also, Key and Value must be base64 encoded in the JSON payload. With \fB\fCetcdctl\fR these details are automatically taken care off. You can check this document
\[la]https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/api_grpc_gateway.md#notes\[ra] for details.
.SS REVERSE ZONES
.PP
Reverse zones are supported. You need to make CoreDNS aware of the fact that you are also
authoritative for the reverse. For instance if you want to add the reverse for 10.0.0.0/24, you'll
need to add the zone \fB\fC0.0.10.in-addr.arpa\fR to the list of zones. Showing a snippet of a Corefile:
.PP
.RS
.nf
etcd skydns.local 10.0.0.0/24 {
\&...
% etcdctl put /skydns/arpa/in\-addr/10/0/0/127 \'{"host":"reverse\.skydns\.local\."}\'
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Next you'll need to populate the zone with reverse records, here we add a reverse for
10.0.0.127 pointing to reverse.skydns.local.
.PP
.RS
.nf
% etcdctl put /skydns/arpa/in\-addr/10/0/0/127 '{"host":"reverse.skydns.local."}'
.fi
.RE
.PP
Querying with dig:
.
.IP "" 4
.
.nf
% dig @localhost \-x 10\.0\.0\.127 +short
reverse\.skydns\.local\.
.
.fi
.
.IP "" 0
.
.SS "ZONE NAME AS A RECORD"
The zone name itself can be used as A record\. This behavior can be achieved by writing special entries to the ETCD path of your zone\. If your zone is named \fBskydns\.local\fR for example, you can create an \fBA\fR record for this zone as follows:
.
.IP "" 4
.
.nf
.PP
.RS
% etcdctl put /skydns/local/skydns/ \'{"host":"1\.1\.1\.1","ttl":60}\'
.
.fi
.
.IP "" 0
.
.P
If you query the zone name itself, you will receive the created \fBA\fR record:
.
.IP "" 4
.
.nf
% dig @localhost \-x 10.0.0.127 +short
reverse.skydns.local.
% dig +short skydns\.local @localhost
1\.1\.1\.1
.
.fi
.
.IP "" 0
.
.P
If you would like to use DNS RR for the zone name, you can set the following: ~~~ % etcdctl put /skydns/local/skydns/x1 \'{"host":"1\.1\.1\.1","ttl":60}\' % etcdctl put /skydns/local/skydns/x2 \'{"host":"1\.1\.1\.2","ttl":60}\' ~~~
.
.P
.RE
.SS ZONE NAME AS A RECORD
.PP
The zone name itself can be used as A record. This behavior can be achieved by writing special entries to the ETCD path of your zone. If your zone is named \fB\fCskydns.local\fR for example, you can create an \fB\fCA\fR record for this zone as follows:
.PP
.RS
.nf
% etcdctl put /skydns/local/skydns/ '{"host":"1.1.1.1","ttl":60}'
.fi
.RE
.PP
If you query the zone name itself, you will receive the created \fB\fCA\fR record:
.PP
.RS
.nf
% dig +short skydns.local @localhost
1.1.1.1
.fi
.RE
.PP
If you would like to use DNS RR for the zone name, you can set the following:
.PP
.RS
.nf
% etcdctl put /skydns/local/skydns/x1 '{"host":"1.1.1.1","ttl":60}'
% etcdctl put /skydns/local/skydns/x2 '{"host":"1.1.1.2","ttl":60}'
.fi
.RE
.PP
If you query the zone name now, you will get the following response:
.
.IP "" 4
.
.nf
% dig +short skydns\.local @localhost
1\.1\.1\.1
1\.1\.1\.2
.
.fi
.
.IP "" 0
.
.SS "ZONE NAME AS AAAA RECORD"
If you would like to use \fBAAAA\fR records for the zone name too, you can set the following: ~~~ % etcdctl put /skydns/local/skydns/x3 \'{"host":"2003::8:1","ttl":60}\' % etcdctl put /skydns/local/skydns/x4 \'{"host":"2003::8:2","ttl":60}\' ~~~
.
.P
If you query the zone name for \fBAAAA\fR now, you will get the following response: ~~~ sh % dig +short skydns\.local AAAA @localhost 2003::8:1 2003::8:2 ~~~
.
.SS "SRV RECORD"
If you would like to use \fBSRV\fR records, you can set the following: ~~~ % etcdctl put /skydns/local/skydns/x5 \'{"host":"skydns\-local\.server","ttl":60,"priority":10,"port":8080}\' ~~~ Please notice that the key \fBhost\fR is the \fBtarget\fR in \fBSRV\fR, so it should be a domain name\.
.
.P
If you query the zone name for \fBSRV\fR now, you will get the following response:
.
.IP "" 4
.
.nf
.PP
.RS
.nf
% dig +short skydns.local @localhost
1.1.1.1
1.1.1.2
% dig +short skydns\.local SRV @localhost
10 100 8080 skydns\-local\.server\.
.
.fi
.
.IP "" 0
.
.SS "TXT RECORD"
If you would like to use \fBTXT\fR records, you can set the following: ~~~ % etcdctl put /skydns/local/skydns/x6 \'{"ttl":60,"text":"this is a random text message\."}\' ~~~
.
.P
If you query the zone name for \fBTXT\fR now, you will get the following response: ~~~ sh % dig +short skydns\.local TXT @localhost "this is a random text message\." ~~~
.RE
.SS ZONE NAME AS AAAA RECORD
.PP
If you would like to use \fB\fCAAAA\fR records for the zone name too, you can set the following:
.PP
.RS
.nf
% etcdctl put /skydns/local/skydns/x3 '{"host":"2003::8:1","ttl":60}'
% etcdctl put /skydns/local/skydns/x4 '{"host":"2003::8:2","ttl":60}'
.fi
.RE
.PP
If you query the zone name for \fB\fCAAAA\fR now, you will get the following response:
.PP
.RS
.nf
% dig +short skydns.local AAAA @localhost
2003::8:1
2003::8:2
.fi
.RE
.SS SRV RECORD
.PP
If you would like to use \fB\fCSRV\fR records, you can set the following:
.PP
.RS
.nf
% etcdctl put /skydns/local/skydns/x5 '{"host":"skydns\-local.server","ttl":60,"priority":10,"port":8080}'
.fi
.RE
.PP
Please notice that the key \fB\fChost\fR is the \fB\fCtarget\fR in \fB\fCSRV\fR, so it should be a domain name.
.PP
If you query the zone name for \fB\fCSRV\fR now, you will get the following response:
.PP
.RS
.nf
% dig +short skydns.local SRV @localhost
10 100 8080 skydns\-local.server.
.fi
.RE
.SS TXT RECORD
.PP
If you would like to use \fB\fCTXT\fR records, you can set the following:
.PP
.RS
.nf
% etcdctl put /skydns/local/skydns/x6 '{"ttl":60,"text":"this is a random text message."}'
.fi
.RE
.PP
If you query the zone name for \fB\fCTXT\fR now, you will get the following response:
.PP
.RS
.nf
% dig +short skydns.local TXT @localhost
"this is a random text message."
.fi
.RE

121
man/coredns-federation.7
View file

@ -1,73 +1,78 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-FEDERATION" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIfederation\fR \- enables federated queries to be resolved via the kubernetes plugin\.
.
.SH "DESCRIPTION"
Enabling this plugin allows Federated \fIhttps://kubernetes\.io/docs/tasks/federation/federation\-service\-discovery/\fR queries to be resolved via the kubernetes plugin\.
.
.P
Enabling \fIfederation\fR without also having \fIkubernetes\fR is a noop\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-FEDERATION" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
federation [ZONES\.\.\.] {
.SH FEDERATION
.SH NAME
.PP
\fIfederation\fP - enables federated queries to be resolved via the kubernetes plugin.
.SH DESCRIPTION
.PP
Enabling this plugin allows
Federated
\[la]https://kubernetes.io/docs/tasks/federation/federation-service-discovery/\[ra] queries to be
resolved via the kubernetes plugin.
.PP
Enabling \fIfederation\fP without also having \fIkubernetes\fP is a noop.
.SH SYNTAX
.PP
.RS
.nf
federation [ZONES...] {
NAME DOMAIN
upstream
}
.
.fi
.
.IP "\(bu" 4
Each \fBNAME\fR and \fBDOMAIN\fR defines federation membership\. One entry for each\. A duplicate \fBNAME\fR will silently overwrite any previous value\.
.
.IP "\(bu" 4
\fBupstream\fR [\fBADDRESS\fR\.\.\.] resolve the \fBCNAME\fR target produced by this plugin\. CoreDNS will resolve External Services against itself\.
.
.IP "" 0
.
.SH "EXAMPLES"
Here we handle all service requests in the \fBprod\fR and \fBstage\fR federations\.
.
.IP "" 4
.
.nf
\&\. {
kubernetes cluster\.local
federation cluster\.local {
prod prod\.feddomain\.com
staging staging\.feddomain\.com
.fi
.RE
.IP \(bu 4
Each \fBNAME\fP and \fBDOMAIN\fP defines federation membership. One entry for each. A duplicate
\fBNAME\fP will silently overwrite any previous value.
.IP \(bu 4
\fB\fCupstream\fR [\fBADDRESS\fP...] resolve the \fB\fCCNAME\fR target produced by this plugin. CoreDNS
will resolve External Services against itself.
.SH EXAMPLES
.PP
Here we handle all service requests in the \fB\fCprod\fR and \fB\fCstage\fR federations.
.PP
.RS
.nf
\&. {
kubernetes cluster.local
federation cluster.local {
prod prod.feddomain.com
staging staging.feddomain.com
upstream
}
}
.
.fi
.
.IP "" 0
.
.P
Or slightly shorter:
.
.IP "" 4
.
.nf
cluster\.local {
.fi
.RE
.PP
Or slightly shorter:
.PP
.RS
.nf
cluster.local {
kubernetes
federation {
prod prod\.feddomain\.com
staging staging\.feddomain\.com
prod prod.feddomain.com
staging staging.feddomain.com
upstream
}
}
.
.fi
.
.IP "" 0
.fi
.RE

161
man/coredns-file.7
View file

@ -1,95 +1,100 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-FILE" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIfile\fR \- enables serving zone data from an RFC 1035\-style master file\.
.
.SH "DESCRIPTION"
The file plugin is used for an "old\-style" DNS server\. It serves from a preloaded file that exists on disk\. If the zone file contains signatures (i\.e\., is signed using DNSSEC), correct DNSSEC answers are returned\. Only NSEC is supported! If you use this setup \fIyou\fR are responsible for re\-signing the zonefile\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-FILE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH FILE
.SH NAME
.PP
\fIfile\fP - enables serving zone data from an RFC 1035-style master file.
.SH DESCRIPTION
.PP
The file plugin is used for an "old-style" DNS server. It serves from a preloaded file that exists
on disk. If the zone file contains signatures (i.e., is signed using DNSSEC), correct DNSSEC answers
are returned. Only NSEC is supported! If you use this setup \fIyou\fP are responsible for re-signing the
zonefile.
.SH SYNTAX
.PP
.RS
.nf
file DBFILE [ZONES...]
file DBFILE [ZONES\.\.\.]
.
.fi
.
.IP "\(bu" 4
\fBDBFILE\fR the database file to read and parse\. If the path is relative, the path from the \fIroot\fR directive will be prepended to it\.
.
.IP "\(bu" 4
\fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block are used\.
.
.IP "" 0
.
.P
If you want to round\-robin A and AAAA responses look at the \fIloadbalance\fR plugin\.
.
.IP "" 4
.
.nf
.RE
file DBFILE [ZONES\.\.\. ] {
transfer to ADDRESS\.\.\.
.IP \(bu 4
\fBDBFILE\fP the database file to read and parse. If the path is relative, the path from the \fIroot\fP
directive will be prepended to it.
.IP \(bu 4
\fBZONES\fP zones it should be authoritative for. If empty, the zones from the configuration block
are used.
.PP
If you want to round-robin A and AAAA responses look at the \fIloadbalance\fP plugin.
.PP
.RS
.nf
file DBFILE [ZONES... ] {
transfer to ADDRESS...
reload DURATION
no_reload
upstream
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBtransfer\fR enables zone transfers\. It may be specified multiples times\. \fBTo\fR or \fBfrom\fR signals the direction\. \fBADDRESS\fR must be denoted in CIDR notation (e\.g\., 127\.0\.0\.1/32) or just as plain addresses\. The special wildcard \fB*\fR means: the entire internet (only valid for \'transfer to\')\. When an address is specified a notify message will be send whenever the zone is reloaded\.
.
.IP "\(bu" 4
\fBreload\fR interval to perform a reload of the zone if the SOA version changes\. Default is one minute\. Value of \fB0\fR means to not scan for changes and reload\. For example, \fB30s\fR checks the zonefile every 30 seconds and reloads the zone when serial changes\.
.
.IP "\(bu" 4
\fBno_reload\fR deprecated\. Sets reload to 0\.
.
.IP "\(bu" 4
\fBupstream\fR resolve external names found (think CNAMEs) pointing to external names\. This is only really useful when CoreDNS is configured as a proxy; for normal authoritative serving you don\'t need \fIor\fR want to use this\. CoreDNS will resolve CNAMEs against itself\.
.
.IP "" 0
.
.SH "EXAMPLES"
Load the \fBexample\.org\fR zone from \fBexample\.org\.signed\fR and allow transfers to the internet, but send notifies to 10\.240\.1\.1
.
.IP "" 4
.
.nf
example\.org {
file example\.org\.signed {
.fi
.RE
.IP \(bu 4
\fB\fCtransfer\fR enables zone transfers. It may be specified multiples times. \fB\fCTo\fR or \fB\fCfrom\fR signals
the direction. \fBADDRESS\fP must be denoted in CIDR notation (e.g., 127.0.0.1/32) or just as plain
addresses. The special wildcard \fB\fC*\fR means: the entire internet (only valid for 'transfer to').
When an address is specified a notify message will be send whenever the zone is reloaded.
.IP \(bu 4
\fB\fCreload\fR interval to perform a reload of the zone if the SOA version changes. Default is one minute.
Value of \fB\fC0\fR means to not scan for changes and reload. For example, \fB\fC30s\fR checks the zonefile every 30 seconds
and reloads the zone when serial changes.
.IP \(bu 4
\fB\fCupstream\fR resolve external names found (think CNAMEs) pointing to external names. This is only
really useful when CoreDNS is configured as a proxy; for normal authoritative serving you don't
need \fIor\fP want to use this. CoreDNS will resolve CNAMEs against itself.
.SH EXAMPLES
.PP
Load the \fB\fCexample.org\fR zone from \fB\fCexample.org.signed\fR and allow transfers to the internet, but send
notifies to 10.240.1.1
.PP
.RS
.nf
example.org {
file example.org.signed {
transfer to *
transfer to 10\.240\.1\.1
transfer to 10.240.1.1
}
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Or use a single zone file for multiple zones:
.
.IP "" 4
.
.nf
\&\. {
file example\.org\.signed example\.org example\.net {
.PP
.RS
.nf
\&. {
file example.org.signed example.org example.net {
transfer to *
transfer to 10\.240\.1\.1
transfer to 10.240.1.1
}
}
.
.fi
.
.IP "" 0
.fi
.RE

482
man/coredns-forward.7
View file

@ -1,264 +1,282 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-FORWARD" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIforward\fR \- facilitates proxying DNS messages to upstream resolvers\.
.
.SH "DESCRIPTION"
The \fIforward\fR plugin re\-uses already opened sockets to the upstreams\. It supports UDP, TCP and DNS\-over\-TLS and uses in band health checking\.
.
.P
When it detects an error a health check is performed\. This checks runs in a loop, every \fI0\.5s\fR, for as long as the upstream reports unhealthy\. Once healthy we stop health checking (until the next error)\. The health checks use a recursive DNS query (\fB\. IN NS\fR) to get upstream health\. Any response that is not a network error (REFUSED, NOTIMPL, SERVFAIL, etc) is taken as a healthy upstream\. The health check uses the same protocol as specified in \fBTO\fR\. If \fBmax_fails\fR is set to 0, no checking is performed and upstreams will always be considered healthy\.
.
.P
When \fIall\fR upstreams are down it assumes health checking as a mechanism has failed and will try to connect to a random upstream (which may or may not work)\.
.
.P
This plugin can only be used once per Server Block\.
.
.P
How does \fIforward\fR relate to \fIproxy\fR? This plugin is the "new" version of \fIproxy\fR and is faster because it re\-uses connections to the upstreams\. It also does in\-band health checks \- using DNS instead of HTTP\. Since it is newer it has a little less (production) mileage on it\.
.
.SH "SYNTAX"
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-FORWARD" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH FORWARD
.SH NAME
.PP
\fIforward\fP - facilitates proxying DNS messages to upstream resolvers.
.SH DESCRIPTION
.PP
The \fIforward\fP plugin re-uses already opened sockets to the upstreams. It supports UDP, TCP and
DNS-over-TLS and uses in band health checking.
.PP
When it detects an error a health check is performed. This checks runs in a loop, every \fI0.5s\fP, for
as long as the upstream reports unhealthy. Once healthy we stop health checking (until the next
error). The health checks use a recursive DNS query (\fB\fC. IN NS\fR) to get upstream health. Any response
that is not a network error (REFUSED, NOTIMPL, SERVFAIL, etc) is taken as a healthy upstream. The
health check uses the same protocol as specified in \fBTO\fP. If \fB\fCmax_fails\fR is set to 0, no checking
is performed and upstreams will always be considered healthy.
.PP
When \fIall\fP upstreams are down it assumes health checking as a mechanism has failed and will try to
connect to a random upstream (which may or may not work).
.PP
This plugin can only be used once per Server Block.
.PP
How does \fIforward\fP relate to \fIproxy\fP? This plugin is the "new" version of \fIproxy\fP and is faster
because it re-uses connections to the upstreams. It also does in-band health checks - using DNS
instead of HTTP. Since it is newer it has a little less (production) mileage on it.
.SH SYNTAX
.PP
In its most basic form, a simple forwarder uses this syntax:
.
.IP "" 4
.
.nf
forward FROM TO\.\.\.
.
.PP
.RS
.nf
forward FROM TO...
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBFROM\fR is the base domain to match for the request to be forwarded\.
.
.IP "\(bu" 4
\fBTO\.\.\.\fR are the destination endpoints to forward to\. The \fBTO\fR syntax allows you to specify a protocol, \fBtls://9\.9\.9\.9\fR or \fBdns://\fR (or no protocol) for plain DNS\. The number of upstreams is limited to 15\.
.
.IP "" 0
.
.P
Multiple upstreams are randomized (see \fBpolicy\fR) on first use\. When a healthy proxy returns an error during the exchange the next upstream in the list is tried\.
.
.P
.RE
.IP \(bu 4
\fBFROM\fP is the base domain to match for the request to be forwarded.
.IP \(bu 4
\fBTO...\fP are the destination endpoints to forward to. The \fBTO\fP syntax allows you to specify
a protocol, \fB\fCtls://9.9.9.9\fR or \fB\fCdns://\fR (or no protocol) for plain DNS. The number of upstreams is
limited to 15.
.PP
Multiple upstreams are randomized (see \fB\fCpolicy\fR) on first use. When a healthy proxy returns an error
during the exchange the next upstream in the list is tried.
.PP
Extra knobs are available with an expanded syntax:
.
.IP "" 4
.
.nf
forward FROM TO\.\.\. {
except IGNORED_NAMES\.\.\.
force_tcp
prefer_udp
.PP
.RS
.nf
forward FROM TO... {
except IGNORED\_NAMES...
force\_tcp
prefer\_udp
expire DURATION
max_fails INTEGER
max\_fails INTEGER
tls CERT KEY CA
tls_servername NAME
policy random|round_robin|sequential
health_check DURATION
tls\_servername NAME
policy random|round\_robin|sequential
health\_check DURATION
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBFROM\fR and \fBTO\.\.\.\fR as above\.
.
.IP "\(bu" 4
\fBIGNORED_NAMES\fR in \fBexcept\fR is a space\-separated list of domains to exclude from forwarding\. Requests that match none of these names will be passed through\.
.
.IP "\(bu" 4
\fBforce_tcp\fR, use TCP even when the request comes in over UDP\.
.
.IP "\(bu" 4
\fBprefer_udp\fR, try first using UDP even when the request comes in over TCP\. If response is truncated (TC flag set in response) then do another attempt over TCP\. In case if both \fBforce_tcp\fR and \fBprefer_udp\fR options specified the \fBforce_tcp\fR takes precedence\.
.
.IP "\(bu" 4
\fBmax_fails\fR is the number of subsequent failed health checks that are needed before considering an upstream to be down\. If 0, the upstream will never be marked as down (nor health checked)\. Default is 2\.
.
.IP "\(bu" 4
\fBexpire\fR \fBDURATION\fR, expire (cached) connections after this time, the default is 10s\.
.
.IP "\(bu" 4
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCA\fR define the TLS properties for TLS connection\. From 0 to 3 arguments can be provided with the meaning as described below
.
.IP "\(bu" 4
\fBtls\fR \- no client authentication is used, and the system CAs are used to verify the server certificate
.
.IP "\(bu" 4
\fBtls\fR \fBCA\fR \- no client authentication is used, and the file CA is used to verify the server certificate
.
.IP "\(bu" 4
\fBtls\fR \fBCERT\fR \fBKEY\fR \- client authentication is used with the specified cert/key pair\. The server certificate is verified with the system CAs
.
.IP "\(bu" 4
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCA\fR \- client authentication is used with the specified cert/key pair\. The server certificate is verified using the specified CA file
.
.IP "" 0
.
.IP "\(bu" 4
\fBtls_servername\fR \fBNAME\fR allows you to set a server name in the TLS configuration; for instance 9\.9\.9\.9 needs this to be set to \fBdns\.quad9\.net\fR\. Multiple upstreams are still allowed in this scenario, but they have to use the same \fBtls_servername\fR\. E\.g\. mixing 9\.9\.9\.9 (QuadDNS) with 1\.1\.1\.1 (Cloudflare) will not work\.
.
.IP "\(bu" 4
\fBpolicy\fR specifies the policy to use for selecting upstream servers\. The default is \fBrandom\fR\.
.
.IP "\(bu" 4
\fBhealth_check\fR, use a different \fBDURATION\fR for health checking, the default duration is 0\.5s\.
.
.IP "" 0
.
.P
Also note the TLS config is "global" for the whole forwarding proxy if you need a different \fBtls\-name\fR for different upstreams you\'re out of luck\.
.
.P
On each endpoint, the timeouts of the communication are set by default and automatically tuned depending early results\.
.
.IP "\(bu" 4
.fi
.RE
.IP \(bu 4
\fBFROM\fP and \fBTO...\fP as above.
.IP \(bu 4
\fBIGNORED_NAMES\fP in \fB\fCexcept\fR is a space-separated list of domains to exclude from forwarding.
Requests that match none of these names will be passed through.
.IP \(bu 4
\fB\fCforce_tcp\fR, use TCP even when the request comes in over UDP.
.IP \(bu 4
\fB\fCprefer_udp\fR, try first using UDP even when the request comes in over TCP. If response is truncated
(TC flag set in response) then do another attempt over TCP. In case if both \fB\fCforce_tcp\fR and
\fB\fCprefer_udp\fR options specified the \fB\fCforce_tcp\fR takes precedence.
.IP \(bu 4
\fB\fCmax_fails\fR is the number of subsequent failed health checks that are needed before considering
an upstream to be down. If 0, the upstream will never be marked as down (nor health checked).
Default is 2.
.IP \(bu 4
\fB\fCexpire\fR \fBDURATION\fP, expire (cached) connections after this time, the default is 10s.
.IP \(bu 4
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP \fBCA\fP define the TLS properties for TLS connection. From 0 to 3 arguments can be
provided with the meaning as described below
.RS
.IP \(en 4
\fB\fCtls\fR - no client authentication is used, and the system CAs are used to verify the server certificate
.IP \(en 4
\fB\fCtls\fR \fBCA\fP - no client authentication is used, and the file CA is used to verify the server certificate
.IP \(en 4
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP - client authentication is used with the specified cert/key pair.
The server certificate is verified with the system CAs
.IP \(en 4
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP \fBCA\fP - client authentication is used with the specified cert/key pair.
The server certificate is verified using the specified CA file
.RE
.IP \(bu 4
\fB\fCtls_servername\fR \fBNAME\fP allows you to set a server name in the TLS configuration; for instance 9.9.9.9
needs this to be set to \fB\fCdns.quad9.net\fR. Multiple upstreams are still allowed in this scenario,
but they have to use the same \fB\fCtls_servername\fR. E.g. mixing 9.9.9.9 (QuadDNS) with 1.1.1.1
(Cloudflare) will not work.
.IP \(bu 4
\fB\fCpolicy\fR specifies the policy to use for selecting upstream servers. The default is \fB\fCrandom\fR.
.RS
.IP \(en 4
\fB\fCrandom\fR is a policy that implements random upstream selection.
.IP \(en 4
\fB\fCround_robin\fR is a policy that selects hosts based on round robin ordering.
.IP \(en 4
\fB\fCsequential\fR is a policy that selects hosts based on sequential ordering.
.RE
.IP \(bu 4
\fB\fChealth_check\fR, use a different \fBDURATION\fP for health checking, the default duration is 0.5s.
.PP
Also note the TLS config is "global" for the whole forwarding proxy if you need a different
\fB\fCtls-name\fR for different upstreams you're out of luck.
.PP
On each endpoint, the timeouts of the communication are set by default and automatically tuned depending early results.
.IP \(bu 4
dialTimeout by default is 30 sec, and can decrease automatically down to 100ms
.
.IP "\(bu" 4
.IP \(bu 4
readTimeout by default is 2 sec, and can decrease automatically down to 200ms
.
.IP "" 0
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metric are exported:
.
.IP "\(bu" 4
\fBcoredns_forward_request_duration_seconds{to}\fR \- duration per upstream interaction\.
.
.IP "\(bu" 4
\fBcoredns_forward_request_count_total{to}\fR \- query count per upstream\.
.
.IP "\(bu" 4
\fBcoredns_forward_response_rcode_total{to, rcode}\fR \- count of RCODEs per upstream\.
.
.IP "\(bu" 4
\fBcoredns_forward_healthcheck_failure_count_total{to}\fR \- number of failed health checks per upstream\.
.
.IP "\(bu" 4
\fBcoredns_forward_healthcheck_broken_count_total{}\fR \- counter of when all upstreams are unhealthy, and we are randomly (this always uses the \fBrandom\fR policy) spraying to an upstream\.
.
.IP "\(bu" 4
\fBcoredns_forward_socket_count_total{to}\fR \- number of cached sockets per upstream\.
.
.IP "" 0
.
.P
Where \fBto\fR is one of the upstream servers (\fBTO\fR from the config), \fBproto\fR is the protocol used by the incoming query ("tcp" or "udp"), and family the transport family ("1" for IPv4, and "2" for IPv6)\.
.
.SH "EXAMPLES"
Proxy all requests within \fBexample\.org\.\fR to a nameserver running on a different port:
.
.IP "" 4
.
.nf
example\.org {
forward \. 127\.0\.0\.1:9005
.SH METRICS
.PP
If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric are exported:
.IP \(bu 4
\fB\fCcoredns_forward_request_duration_seconds{to}\fR - duration per upstream interaction.
.IP \(bu 4
\fB\fCcoredns_forward_request_count_total{to}\fR - query count per upstream.
.IP \(bu 4
\fB\fCcoredns_forward_response_rcode_total{to, rcode}\fR - count of RCODEs per upstream.
.IP \(bu 4
\fB\fCcoredns_forward_healthcheck_failure_count_total{to}\fR - number of failed health checks per upstream.
.IP \(bu 4
\fB\fCcoredns_forward_healthcheck_broken_count_total{}\fR - counter of when all upstreams are unhealthy,
and we are randomly (this always uses the \fB\fCrandom\fR policy) spraying to an upstream.
.IP \(bu 4
\fB\fCcoredns_forward_socket_count_total{to}\fR - number of cached sockets per upstream.
.PP
Where \fB\fCto\fR is one of the upstream servers (\fBTO\fP from the config), \fB\fCproto\fR is the protocol used by
the incoming query ("tcp" or "udp"), and family the transport family ("1" for IPv4, and "2" for
IPv6).
.SH EXAMPLES
.PP
Proxy all requests within \fB\fCexample.org.\fR to a nameserver running on a different port:
.PP
.RS
.nf
example.org {
forward . 127.0.0.1:9005
}
.
.fi
.
.IP "" 0
.
.P
Load balance all requests between three resolvers, one of which has a IPv6 address\.
.
.IP "" 4
.
.nf
\&\. {
forward \. 10\.0\.0\.10:53 10\.0\.0\.11:1053 [2003::1]:53
.fi
.RE
.PP
Load balance all requests between three resolvers, one of which has a IPv6 address.
.PP
.RS
.nf
\&. {
forward . 10.0.0.10:53 10.0.0.11:1053 [2003::1]:53
}
.
.fi
.
.IP "" 0
.
.P
Forward everything except requests to \fBexample\.org\fR
.
.IP "" 4
.
.nf
\&\. {
forward \. 10\.0\.0\.10:1234 {
except example\.org
.fi
.RE
.PP
Forward everything except requests to \fB\fCexample.org\fR
.PP
.RS
.nf
\&. {
forward . 10.0.0.10:1234 {
except example.org
}
}
.
.fi
.
.IP "" 0
.
.P
Proxy everything except \fBexample\.org\fR using the host\'s \fBresolv\.conf\fR\'s nameservers:
.
.IP "" 4
.
.nf
\&\. {
forward \. /etc/resolv\.conf {
except example\.org
.fi
.RE
.PP
Proxy everything except \fB\fCexample.org\fR using the host's \fB\fCresolv.conf\fR's nameservers:
.PP
.RS
.nf
\&. {
forward . /etc/resolv.conf {
except example.org
}
}
.
.fi
.
.IP "" 0
.
.P
Proxy all requests to 9\.9\.9\.9 using the DNS\-over\-TLS protocol, and cache every answer for up to 30 seconds\. Note the \fBtls_servername\fR is mandatory if you want a working setup, as 9\.9\.9\.9 can\'t be used in the TLS negotiation\. Also set the health check duration to 5s to not completely swamp the service with health checks\.
.
.IP "" 4
.
.nf
\&\. {
forward \. tls://9\.9\.9\.9 {
tls_servername dns\.quad9\.net
health_check 5s
.fi
.RE
.PP
Proxy all requests to 9.9.9.9 using the DNS-over-TLS protocol, and cache every answer for up to 30
seconds. Note the \fB\fCtls_servername\fR is mandatory if you want a working setup, as 9.9.9.9 can't be
used in the TLS negotiation. Also set the health check duration to 5s to not completely swamp the
service with health checks.
.PP
.RS
.nf
\&. {
forward . tls://9.9.9.9 {
tls\_servername dns.quad9.net
health\_check 5s
}
cache 30
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Or with multiple upstreams from the same provider
.
.IP "" 4
.
.nf
\&\. {
forward \. tls://1\.1\.1\.1 tls://1\.0\.0\.1 {
tls_servername cloudflare\-dns\.com
health_check 5s
.PP
.RS
.nf
\&. {
forward . tls://1.1.1.1 tls://1.0.0.1 {
tls\_servername cloudflare\-dns.com
health\_check 5s
}
cache 30
}
.
.fi
.
.IP "" 0
.
.SH "BUGS"
The TLS config is global for the whole forwarding proxy if you need a different \fBtls_servername\fR for different upstreams you\'re out of luck\.
.
.SH "ALSO SEE"
RFC 7858 \fIhttps://tools\.ietf\.org/html/rfc7858\fR for DNS over TLS\.
.RE
.SH BUGS
.PP
The TLS config is global for the whole forwarding proxy if you need a different \fB\fCtls_servername\fR for
different upstreams you're out of luck.
.SH ALSO SEE
.PP
RFC 7858
\[la]https://tools.ietf.org/html/rfc7858\[ra] for DNS over TLS.

353
man/coredns-grpc.7
View file

@ -1,207 +1,206 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-GRPC" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIgrpc\fR \- facilitates proxying DNS messages to upstream resolvers via gRPC protocol\.
.
.SH "DESCRIPTION"
The \fIgrpc\fR plugin supports gRPC and TLS\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "SYNTAX"
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-GRPC" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH GRPC
.SH NAME
.PP
\fIgrpc\fP - facilitates proxying DNS messages to upstream resolvers via gRPC protocol.
.SH DESCRIPTION
.PP
The \fIgrpc\fP plugin supports gRPC and TLS.
.PP
This plugin can only be used once per Server Block.
.SH SYNTAX
.PP
In its most basic form:
.
.IP "" 4
.
.nf
grpc FROM TO\.\.\.
.
.PP
.RS
.nf
grpc FROM TO...
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBFROM\fR is the base domain to match for the request to be proxied\.
.
.IP "\(bu" 4
\fBTO\.\.\.\fR are the destination endpoints to proxy to\. The number of upstreams is limited to 15\.
.
.IP "" 0
.
.P
Multiple upstreams are randomized (see \fBpolicy\fR) on first use\. When a proxy returns an error the next upstream in the list is tried\.
.
.P
.RE
.IP \(bu 4
\fBFROM\fP is the base domain to match for the request to be proxied.
.IP \(bu 4
\fBTO...\fP are the destination endpoints to proxy to. The number of upstreams is
limited to 15.
.PP
Multiple upstreams are randomized (see \fB\fCpolicy\fR) on first use. When a proxy returns an error
the next upstream in the list is tried.
.PP
Extra knobs are available with an expanded syntax:
.
.IP "" 4
.
.nf
grpc FROM TO\.\.\. {
except IGNORED_NAMES\.\.\.
.PP
.RS
.nf
grpc FROM TO... {
except IGNORED\_NAMES...
tls CERT KEY CA
tls_servername NAME
policy random|round_robin|sequential
tls\_servername NAME
policy random|round\_robin|sequential
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBFROM\fR and \fBTO\.\.\.\fR as above\.
.
.IP "\(bu" 4
\fBIGNORED_NAMES\fR in \fBexcept\fR is a space\-separated list of domains to exclude from proxying\. Requests that match none of these names will be passed through\.
.
.IP "\(bu" 4
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCA\fR define the TLS properties for TLS connection\. From 0 to 3 arguments can be provided with the meaning as described below
.
.IP "\(bu" 4
\fBtls\fR \- no client authentication is used, and the system CAs are used to verify the server certificate
.
.IP "\(bu" 4
\fBtls\fR \fBCA\fR \- no client authentication is used, and the file CA is used to verify the server certificate
.
.IP "\(bu" 4
\fBtls\fR \fBCERT\fR \fBKEY\fR \- client authentication is used with the specified cert/key pair\. The server certificate is verified with the system CAs
.
.IP "\(bu" 4
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCA\fR \- client authentication is used with the specified cert/key pair\. The server certificate is verified using the specified CA file
.
.IP "" 0
.RE
.IP \(bu 4
\fBFROM\fP and \fBTO...\fP as above.
.IP \(bu 4
\fBIGNORED_NAMES\fP in \fB\fCexcept\fR is a space-separated list of domains to exclude from proxying.
Requests that match none of these names will be passed through.
.IP \(bu 4
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP \fBCA\fP define the TLS properties for TLS connection. From 0 to 3 arguments can be
provided with the meaning as described below
.RS
.IP \(en 4
\fB\fCtls\fR - no client authentication is used, and the system CAs are used to verify the server certificate
.IP \(en 4
\fB\fCtls\fR \fBCA\fP - no client authentication is used, and the file CA is used to verify the server certificate
.IP \(en 4
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP - client authentication is used with the specified cert/key pair.
The server certificate is verified with the system CAs
.IP \(en 4
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP \fBCA\fP - client authentication is used with the specified cert/key pair.
The server certificate is verified using the specified CA file
.RE
.IP \(bu 4
\fB\fCtls_servername\fR \fBNAME\fP allows you to set a server name in the TLS configuration; for instance 9.9.9.9
needs this to be set to \fB\fCdns.quad9.net\fR. Multiple upstreams are still allowed in this scenario,
but they have to use the same \fB\fCtls_servername\fR. E.g. mixing 9.9.9.9 (QuadDNS) with 1.1.1.1
(Cloudflare) will not work.
.IP \(bu 4
\fB\fCpolicy\fR specifies the policy to use for selecting upstream servers. The default is \fB\fCrandom\fR.
.PP
Also note the TLS config is "global" for the whole grpc proxy if you need a different
\fB\fCtls-name\fR for different upstreams you're out of luck.
.SH METRICS
.PP
If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric are exported:
.IP \(bu 4
\fB\fCcoredns_grpc_request_duration_seconds{to}\fR - duration per upstream interaction.
.IP \(bu 4
\fB\fCcoredns_grpc_request_count_total{to}\fR - query count per upstream.
.IP \(bu 4
\fB\fCcoredns_grpc_response_rcode_total{to, rcode}\fR - count of RCODEs per upstream.
and we are randomly (this always uses the \fB\fCrandom\fR policy) spraying to an upstream.
.SH EXAMPLES
.PP
Proxy all requests within \fB\fCexample.org.\fR to a nameserver running on a different port:
.PP
.RS
.
.IP "\(bu" 4
\fBtls_servername\fR \fBNAME\fR allows you to set a server name in the TLS configuration; for instance 9\.9\.9\.9 needs this to be set to \fBdns\.quad9\.net\fR\. Multiple upstreams are still allowed in this scenario, but they have to use the same \fBtls_servername\fR\. E\.g\. mixing 9\.9\.9\.9 (QuadDNS) with 1\.1\.1\.1 (Cloudflare) will not work\.
.
.IP "\(bu" 4
\fBpolicy\fR specifies the policy to use for selecting upstream servers\. The default is \fBrandom\fR\.
.
.IP "" 0
.
.P
Also note the TLS config is "global" for the whole grpc proxy if you need a different \fBtls\-name\fR for different upstreams you\'re out of luck\.
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metric are exported:
.
.IP "\(bu" 4
\fBcoredns_grpc_request_duration_seconds{to}\fR \- duration per upstream interaction\.
.
.IP "\(bu" 4
\fBcoredns_grpc_request_count_total{to}\fR \- query count per upstream\.
.
.IP "\(bu" 4
\fBcoredns_grpc_response_rcode_total{to, rcode}\fR \- count of RCODEs per upstream\. and we are randomly (this always uses the \fBrandom\fR policy) spraying to an upstream\.
.
.IP "" 0
.
.SH "EXAMPLES"
Proxy all requests within \fBexample\.org\.\fR to a nameserver running on a different port:
.
.IP "" 4
.
.nf
example\.org {
grpc \. 127\.0\.0\.1:9005
example.org {
grpc . 127.0.0.1:9005
}
.
.fi
.
.IP "" 0
.
.P
Load balance all requests between three resolvers, one of which has a IPv6 address\.
.
.IP "" 4
.
.nf
\&\. {
grpc \. 10\.0\.0\.10:53 10\.0\.0\.11:1053 [2003::1]:53
.fi
.RE
.PP
Load balance all requests between three resolvers, one of which has a IPv6 address.
.PP
.RS
.nf
\&. {
grpc . 10.0.0.10:53 10.0.0.11:1053 [2003::1]:53
}
.
.fi
.
.IP "" 0
.
.P
Forward everything except requests to \fBexample\.org\fR
.
.IP "" 4
.
.nf
\&\. {
grpc \. 10\.0\.0\.10:1234 {
except example\.org
.fi
.RE
.PP
Forward everything except requests to \fB\fCexample.org\fR
.PP
.RS
.nf
\&. {
grpc . 10.0.0.10:1234 {
except example.org
}
}
.
.fi
.
.IP "" 0
.
.P
Proxy everything except \fBexample\.org\fR using the host\'s \fBresolv\.conf\fR\'s nameservers:
.
.IP "" 4
.
.nf
\&\. {
grpc \. /etc/resolv\.conf {
except example\.org
.fi
.RE
.PP
Proxy everything except \fB\fCexample.org\fR using the host's \fB\fCresolv.conf\fR's nameservers:
.PP
.RS
.nf
\&. {
grpc . /etc/resolv.conf {
except example.org
}
}
.
.fi
.
.IP "" 0
.
.P
Proxy all requests to 9\.9\.9\.9 using the TLS protocol, and cache every answer for up to 30 seconds\. Note the \fBtls_servername\fR is mandatory if you want a working setup, as 9\.9\.9\.9 can\'t be used in the TLS negotiation\.
.
.IP "" 4
.
.nf
\&\. {
grpc \. 9\.9\.9\.9 {
tls_servername dns\.quad9\.net
.fi
.RE
.PP
Proxy all requests to 9.9.9.9 using the TLS protocol, and cache every answer for up to 30
seconds. Note the \fB\fCtls_servername\fR is mandatory if you want a working setup, as 9.9.9.9 can't be
used in the TLS negotiation.
.PP
.RS
.nf
\&. {
grpc . 9.9.9.9 {
tls\_servername dns.quad9.net
}
cache 30
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Or with multiple upstreams from the same provider
.
.IP "" 4
.
.nf
\&\. {
grpc \. 1\.1\.1\.1 1\.0\.0\.1 {
tls_servername cloudflare\-dns\.com
.PP
.RS
.nf
\&. {
grpc . 1.1.1.1 1.0.0.1 {
tls\_servername cloudflare\-dns.com
}
cache 30
}
.
.fi
.
.IP "" 0
.
.SH "BUGS"
The TLS config is global for the whole grpc proxy if you need a different \fBtls_servername\fR for different upstreams you\'re out of luck\.
.RE
.SH BUGS
.PP
The TLS config is global for the whole grpc proxy if you need a different \fB\fCtls_servername\fR for
different upstreams you're out of luck.

178
man/coredns-health.7
View file

@ -1,52 +1,57 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-HEALTH" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIhealth\fR \- enables a health check endpoint\.
.
.SH "DESCRIPTION"
Enabled process wide health endpoint\. When CoreDNS is up and running this returns a 200 OK http status code\. The health is exported, by default, on port 8080/health \.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-HEALTH" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH HEALTH
.SH NAME
.PP
\fIhealth\fP - enables a health check endpoint.
.SH DESCRIPTION
.PP
Enabled process wide health endpoint. When CoreDNS is up and running this returns a 200 OK http
status code. The health is exported, by default, on port 8080/health .
.SH SYNTAX
.PP
.RS
.nf
health [ADDRESS]
.
.fi
.
.P
Optionally takes an address; the default is \fB:8080\fR\. The health path is fixed to \fB/health\fR\. The health endpoint returns a 200 response code and the word "OK" when this server is healthy\.
.
.P
An extra option can be set with this extended syntax:
.
.IP "" 4
.
.nf
.fi
.RE
.PP
Optionally takes an address; the default is \fB\fC:8080\fR. The health path is fixed to \fB\fC/health\fR. The
health endpoint returns a 200 response code and the word "OK" when this server is healthy.
.PP
An extra option can be set with this extended syntax:
.PP
.RS
.nf
health [ADDRESS] {
lameduck DURATION
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
Where \fBlameduck\fR will make the process unhealthy then \fIwait\fR for \fBDURATION\fR before the process shuts down\.
.
.IP "" 0
.
.P
If you have multiple Server Blocks, \fIhealth\fR should only be enabled in one of them (as it is process wide)\. If you really need multiple endpoints, you must run health endpoints on different ports:
.
.IP "" 4
.
.nf
.fi
.RE
.IP \(bu 4
Where \fB\fClameduck\fR will make the process unhealthy then \fIwait\fP for \fBDURATION\fP before the process
shuts down.
.PP
If you have multiple Server Blocks, \fIhealth\fP should only be enabled in one of them (as it is process
wide). If you really need multiple endpoints, you must run health endpoints on different ports:
.PP
.RS
.nf
com {
whoami
health :8080
@ -56,53 +61,60 @@ net {
erratic
health :8081
}
.
.fi
.
.IP "" 0
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metric is exported:
.
.IP "\(bu" 4
\fBcoredns_health_request_duration_seconds{}\fR \- duration to process a /health query\. As this should be a local operation it should be fast\. A (large) increases in this duration indicates the CoreDNS process is having trouble keeping up with its query load\.
.
.IP "" 0
.
.P
Note that this metric \fIdoes not\fR have a \fBserver\fR label, because being overloaded is a symptom of the running process, \fInot\fR a specific server\.
.
.SH "EXAMPLES"
Run another health endpoint on http://localhost:8091\.
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.SH METRICS
.PP
If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric is exported:
.IP \(bu 4
\fB\fCcoredns_health_request_duration_seconds{}\fR - duration to process a /health query. As this should
be a local operation it should be fast. A (large) increases in this duration indicates the
CoreDNS process is having trouble keeping up with its query load.
.PP
Note that this metric \fIdoes not\fP have a \fB\fCserver\fR label, because being overloaded is a symptom of
the running process, \fInot\fP a specific server.
.SH EXAMPLES
.PP
Run another health endpoint on http://localhost:8091
\[la]http://localhost:8091\[ra].
.PP
.RS
.nf
\&. {
health localhost:8091
}
.
.fi
.
.IP "" 0
.
.P
Set a lameduck duration of 1 second:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Set a lameduck duration of 1 second:
.PP
.RS
.nf
\&. {
health localhost:8092 {
lameduck 1s
}
}
.
.fi
.
.IP "" 0
.
.SH "BUGS"
When reloading, the health handler is stopped before the new server instance is started\. If that new server fails to start, then the initial server instance is still available and DNS queries still served, but health handler stays down\. Health will not reply HTTP request until a successful reload or a complete restart of CoreDNS\.
.RE
.SH BUGS
.PP
When reloading, the health handler is stopped before the new server instance is started. If that
new server fails to start, then the initial server instance is still available and DNS queries still
served, but health handler stays down. Health will not reply HTTP request until a successful reload
or a complete restart of CoreDNS.

257
man/coredns-hosts.7
View file

@ -1,146 +1,157 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-HOSTS" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIhosts\fR \- enables serving zone data from a \fB/etc/hosts\fR style file\.
.
.SH "DESCRIPTION"
The hosts plugin is useful for serving zones from a \fB/etc/hosts\fR file\. It serves from a preloaded file that exists on disk\. It checks the file for changes and updates the zones accordingly\. This plugin only supports A, AAAA, and PTR records\. The hosts plugin can be used with readily available hosts files that block access to advertising servers\.
.
.P
The plugin reloads the content of the hosts file every 5 seconds\. Upon reload, CoreDNS will use the new definitions\. Should the file be deleted, any inlined content will continue to be served\. When the file is restored, it will then again be used\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "THE HOSTS FILE"
Commonly the entries are of the from \fBIP_address canonical_hostname [aliases\.\.\.]\fR as explained by the hosts(5) man page\.
.
.P
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-HOSTS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH HOSTS
.SH NAME
.PP
\fIhosts\fP - enables serving zone data from a \fB\fC/etc/hosts\fR style file.
.SH DESCRIPTION
.PP
The hosts plugin is useful for serving zones from a \fB\fC/etc/hosts\fR file. It serves from a preloaded
file that exists on disk. It checks the file for changes and updates the zones accordingly. This
plugin only supports A, AAAA, and PTR records. The hosts plugin can be used with readily
available hosts files that block access to advertising servers.
.PP
The plugin reloads the content of the hosts file every 5 seconds. Upon reload, CoreDNS will use the new definitions.
Should the file be deleted, any inlined content will continue to be served. When the file is restored, it will then again be used.
.PP
This plugin can only be used once per Server Block.
.SH THE HOSTS FILE
.PP
Commonly the entries are of the from \fB\fCIP_address canonical_hostname [aliases...]\fR as explained by the hosts(5) man page.
.PP
Examples:
.
.IP "" 4
.
.PP
.RS
.nf
# The following lines are desirable for IPv4 capable hosts
127.0.0.1 localhost
192.168.1.10 example.com example
# THE FOLLOWING LINES ARE DESIRABLE FOR IPV4 CAPABLE HOSTS
127\.0\.0\.1 localhost
192\.168\.1\.10 example\.com example
# THE FOLLOWING LINES ARE DESIRABLE FOR IPV6 CAPABLE HOSTS
# The following lines are desirable for IPv6 capable hosts
::1 localhost ip6\-localhost ip6\-loopback
fdfc:a744:27b5:3b0e::1 example\.com example
.
.fi
.
.IP "" 0
.
.SS "PTR RECORDS"
PTR records for reverse lookups are generated automatically by CoreDNS (based on the hosts file entries) and cannot be created manually\.
.
.SH "SYNTAX"
.
.nf
fdfc:a744:27b5:3b0e::1 example.com example
hosts [FILE [ZONES\.\.\.]] {
.fi
.RE
.SS PTR RECORDS
.PP
PTR records for reverse lookups are generated automatically by CoreDNS (based on the hosts file entries) and cannot be created manually.
.SH SYNTAX
.PP
.RS
.nf
hosts [FILE [ZONES...]] {
[INLINE]
ttl SECONDS
no_reverse
no\_reverse
reload DURATION
fallthrough [ZONES\.\.\.]
fallthrough [ZONES...]
}
.
.fi
.
.IP "\(bu" 4
\fBFILE\fR the hosts file to read and parse\. If the path is relative the path from the \fIroot\fR directive will be prepended to it\. Defaults to /etc/hosts if omitted\. We scan the file for changes every 5 seconds\.
.
.IP "\(bu" 4
\fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block are used\.
.
.IP "\(bu" 4
\fBINLINE\fR the hosts file contents inlined in Corefile\. If there are any lines before fallthrough then all of them will be treated as the additional content for hosts file\. The specified hosts file path will still be read but entries will be overridden\.
.
.IP "\(bu" 4
\fBttl\fR change the DNS TTL of the records generated (forward and reverse)\. The default is 3600 seconds (1 hour)\.
.
.IP "\(bu" 4
\fBreload\fR change the period between each hostsfile reload\. A time of zero seconds disable the feature\. Examples of valid durations: "300ms", "1\.5h" or "2h45m" are valid duration with units "ns" (nanosecond), "us" (or "µs" for microsecond), "ms" (millisecond), "s" (second), "m" (minute), "h" (hour)\.
.
.IP "\(bu" 4
\fBno_reverse\fR disable the automatic generation of the \fBin\-addr\.arpa\fR or \fBip6\.arpa\fR entries for the hosts
.
.IP "\(bu" 4
\fBfallthrough\fR If zone matches and no record can be generated, pass request to the next plugin\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.IP "" 0
.
.SH "EXAMPLES"
Load \fB/etc/hosts\fR file\.
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.IP \(bu 4
\fBFILE\fP the hosts file to read and parse. If the path is relative the path from the \fIroot\fP
directive will be prepended to it. Defaults to /etc/hosts if omitted. We scan the file for changes
every 5 seconds.
.IP \(bu 4
\fBZONES\fP zones it should be authoritative for. If empty, the zones from the configuration block
are used.
.IP \(bu 4
\fBINLINE\fP the hosts file contents inlined in Corefile. If there are any lines before fallthrough
then all of them will be treated as the additional content for hosts file. The specified hosts
file path will still be read but entries will be overridden.
.IP \(bu 4
\fB\fCttl\fR change the DNS TTL of the records generated (forward and reverse). The default is 3600 seconds (1 hour).
.IP \(bu 4
\fB\fCreload\fR change the period between each hostsfile reload. A time of zero seconds disable the feature. Examples of valid durations: "300ms", "1.5h" or "2h45m" are valid duration with units "ns" (nanosecond), "us" (or "µs" for microsecond), "ms" (millisecond), "s" (second), "m" (minute), "h" (hour).
.IP \(bu 4
\fB\fCno_reverse\fR disable the automatic generation of the \fB\fCin-addr.arpa\fR or \fB\fCip6.arpa\fR entries for the hosts
.IP \(bu 4
\fB\fCfallthrough\fR If zone matches and no record can be generated, pass request to the next plugin.
If \fB[ZONES...]\fP is omitted, then fallthrough happens for all zones for which the plugin
is authoritative. If specific zones are listed (for example \fB\fCin-addr.arpa\fR and \fB\fCip6.arpa\fR), then only
queries for those zones will be subject to fallthrough.
.SH EXAMPLES
.PP
Load \fB\fC/etc/hosts\fR file.
.PP
.RS
.nf
\&. {
hosts
}
.
.fi
.
.IP "" 0
.
.P
Load \fBexample\.hosts\fR file in the current directory\.
.
.IP "" 4
.
.nf
\&\. {
hosts example\.hosts
.fi
.RE
.PP
Load \fB\fCexample.hosts\fR file in the current directory.
.PP
.RS
.nf
\&. {
hosts example.hosts
}
.
.fi
.
.IP "" 0
.
.P
Load example\.hosts file and only serve example\.org and example\.net from it and fall through to the next plugin if query doesn\'t match\.
.
.IP "" 4
.
.nf
\&\. {
hosts example\.hosts example\.org example\.net {
.fi
.RE
.PP
Load example.hosts file and only serve example.org and example.net from it and fall through to the
next plugin if query doesn't match.
.PP
.RS
.nf
\&. {
hosts example.hosts example.org example.net {
fallthrough
}
}
.
.fi
.
.IP "" 0
.
.P
Load hosts file inlined in Corefile\.
.
.IP "" 4
.
.nf
\&\. {
hosts example\.hosts example\.org {
10\.0\.0\.1 example\.org
.fi
.RE
.PP
Load hosts file inlined in Corefile.
.PP
.RS
.nf
\&. {
hosts example.hosts example.org {
10.0.0.1 example.org
fallthrough
}
}
.
.fi
.
.IP "" 0
.
.SH "SEE ALSO"
The form of the entries in the \fB/etc/hosts\fR file are based on IETF RFC 952 \fIhttps://tools\.ietf\.org/html/rfc952\fR which was updated by IETF RFC 1123 \fIhttps://tools\.ietf\.org/html/rfc1123\fR\.
.RE
.SH SEE ALSO
.PP
The form of the entries in the \fB\fC/etc/hosts\fR file are based on IETF RFC 952
\[la]https://tools.ietf.org/html/rfc952\[ra] which was updated by IETF RFC 1123
\[la]https://tools.ietf.org/html/rfc1123\[ra].

180
man/coredns-import.7
View file

@ -1,103 +1,111 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-IMPORT" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIimport\fR \- include files or reference snippets from a Corefile\.
.
.SH "DESCRIPTION"
The \fIimport\fR plugin can be used to include files into the main configuration\. Another use it to reference predefined snippets\. Both can help to avoid some duplication\.
.
.P
This is a unique directive in that \fIimport\fR can appear outside of a server block\. In other words, it can appear at the top of a Corefile where an address would normally be\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-IMPORT" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH IMPORT
.SH NAME
.PP
\fIimport\fP - include files or reference snippets from a Corefile.
.SH DESCRIPTION
.PP
The \fIimport\fP plugin can be used to include files into the main configuration. Another use it to
reference predefined snippets. Both can help to avoid some duplication.
.PP
This is a unique directive in that \fIimport\fP can appear outside of a server block. In other words, it
can appear at the top of a Corefile where an address would normally be.
.SH SYNTAX
.PP
.RS
.nf
import PATTERN
.
.fi
.
.IP "\(bu" 4
\fBPATTERN\fR is the file, glob pattern (\fB*\fR) or snippet to include\. Its contents will replace this line, as if that file\'s contents appeared here to begin with\.
.
.IP "" 0
.
.SH "FILES"
You can use \fIimport\fR to include a file or files\. This file\'s location is relative to the Corefile\'s location\. It is an error if a specific file cannot be found, but an empty glob pattern is not an error\.
.
.SH "SNIPPETS"
You can define snippets to be reused later in your Corefile by defining a block with a single\-token label surrounded by parentheses:
.
.IP "" 4
.
.nf
.fi
.RE
.IP \(bu 4
\fBPATTERN\fP is the file, glob pattern (\fB\fC*\fR) or snippet to include. Its contents will replace
this line, as if that file's contents appeared here to begin with.
.SH FILES
.PP
You can use \fIimport\fP to include a file or files. This file's location is relative to the
Corefile's location. It is an error if a specific file cannot be found, but an empty glob pattern is
not an error.
.SH SNIPPETS
.PP
You can define snippets to be reused later in your Corefile by defining a block with a single-token
label surrounded by parentheses:
.PP
.RS
.nf
(mysnippet) {
\.\.\.
...
}
.
.fi
.
.IP "" 0
.
.P
Then you can invoke the snippet with \fIimport\fR:
.
.IP "" 4
.
.nf
.fi
.RE
.PP
Then you can invoke the snippet with \fIimport\fP:
.PP
.RS
.nf
import mysnippet
.
.fi
.
.IP "" 0
.
.SH "EXAMPLES"
.RE
.SH EXAMPLES
.PP
Import a shared configuration:
.
.IP "" 4
.
.nf
\&\. {
import config/common\.conf
.PP
.RS
.nf
\&. {
import config/common.conf
}
.
.fi
.
.IP "" 0
.
.P
Where \fBconfig/common\.conf\fR contains:
.
.IP "" 4
.
.nf
.fi
.RE
.PP
Where \fB\fCconfig/common.conf\fR contains:
.PP
.RS
.nf
prometheus
errors
log
.
.fi
.
.IP "" 0
.
.P
This imports files found in the zones directory:
.
.IP "" 4
.
.nf
import \.\./zones/*
.
.fi
.
.IP "" 0
.
.SH "ALSO SEE"
See corefile(5)\.
.RE
.PP
This imports files found in the zones directory:
.PP
.RS
.nf
import ../zones/*
.fi
.RE
.SH ALSO SEE
.PP
See corefile(5).

182
man/coredns-k8s_external.7
View file

@ -1,94 +1,112 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-K8S_EXTERNAL" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIk8s_external\fR \- resolve load balancer and external IPs from outside kubernetes clusters\.
.
.SH "DESCRIPTION"
This plugin allows an additional zone to resolve the external IP address(es) of a Kubernetes service\. This plugin is only useful if the \fIkubernetes\fR plugin is also loaded\.
.
.P
The plugin uses an external zone to resolve in\-cluster IP addresses\. It only handles queries for A, AAAA and SRV records, all others result in NODATA responses\. To make it a proper DNS zone it handles SOA and NS queries for the apex of the zone\.
.
.P
By default the apex of the zone will look like (assuming the zone used is \fBexample\.org\fR):
.
.IP "" 4
.
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-K8S_EXTERNAL" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH K8S_EXTERNAL
.SH NAME
.PP
\fIk8s_external\fP - resolve load balancer and external IPs from outside kubernetes clusters.
.SH DESCRIPTION
.PP
This plugin allows an additional zone to resolve the external IP address(es) of a Kubernetes
service. This plugin is only useful if the \fIkubernetes\fP plugin is also loaded.
.PP
The plugin uses an external zone to resolve in-cluster IP addresses. It only handles queries for A,
AAAA and SRV records, all others result in NODATA responses. To make it a proper DNS zone it handles
SOA and NS queries for the apex of the zone.
.PP
By default the apex of the zone will look like (assuming the zone used is \fB\fCexample.org\fR):
.PP
.RS
.nf
example.org. 5 IN SOA ns1.dns.example.org. hostmaster.example.org. (
12345 ; serial
14400 ; refresh (4 hours)
3600 ; retry (1 hour)
604800 ; expire (1 week)
5 ; minimum (4 hours)
)
example.org 5 IN NS ns1.dns.example.org.
example\.org\. 5 IN SOA ns1\.dns\.example\.org\. hostmaster\.example\.org\. (
12345 ; serial
14400 ; refresh (4 hours)
3600 ; retry (1 hour)
604800 ; expire (1 week)
5 ; minimum (4 hours)
)
example\.org 5 IN NS ns1\.dns\.example\.org\.
ns1.dns.example.org. 5 IN A ....
ns1.dns.example.org. 5 IN AAAA ....
ns1\.dns\.example\.org\. 5 IN A \.\.\.\.
ns1\.dns\.example\.org\. 5 IN AAAA \.\.\.\.
.
.fi
.
.IP "" 0
.
.P
Note we use the \fBdns\fR subdomain to place the records the DNS needs (see the \fBapex\fR directive)\. Also note the SOA\'s serial number is static\. The IP addresses of the nameserver records are those of the CoreDNS service\.
.
.P
The \fIk8s_external\fR plugin handles the subdomain \fBdns\fR and the apex of the zone by itself, all other queries are resolved to addresses in the cluster\.
.
.SH "SYNTAX"
.
.nf
.RE
.PP
Note we use the \fB\fCdns\fR subdomain to place the records the DNS needs (see the \fB\fCapex\fR directive). Also
note the SOA's serial number is static. The IP addresses of the nameserver records are those of the
CoreDNS service.
.PP
The \fIk8s_external\fP plugin handles the subdomain \fB\fCdns\fR and the apex of the zone by itself, all other
queries are resolved to addresses in the cluster.
.SH SYNTAX
.PP
.RS
.nf
k8s\_external [ZONE...]
k8s_external [ZONE\.\.\.]
.
.fi
.
.IP "\(bu" 4
\fBZONES\fR zones \fIk8s_external\fR should be authoritative for\.
.
.IP "" 0
.
.P
If you want to change the apex domain or use a different TTL for the return records you can use this extended syntax\.
.
.IP "" 4
.
.nf
.RE
k8s_external [ZONE\.\.\.] {
.IP \(bu 4
\fBZONES\fP zones \fIk8s_external\fP should be authoritative for.
.PP
If you want to change the apex domain or use a different TTL for the return records you can use
this extended syntax.
.PP
.RS
.nf
k8s\_external [ZONE...] {
apex APEX
ttl TTL
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBAPEX\fR is the name (DNS label) to use the apex records, defaults to \fBdns\fR\.
.
.IP "\(bu" 4
\fBttl\fR allows you to set a custom \fBTTL\fR for responses\. The default is 5 (seconds)\.
.
.IP "" 0
Enable names under \fBexample\.org\fR to be resolved to in cluster DNS addresses\.
.
.IP "" 4
.
.nf
\&\. {
kubernetes cluster\.local
k8s_external example\.org
}
.
.fi
.
.IP "" 0
For some background see resolve external IP address \fIhttps://github\.com/kubernetes/dns/issues/242\fR\. And A records for services with Load Balancer IP \fIhttps://github\.com/coredns/coredns/issues/1851\fR\.PTR queries for the reverse zone is not supported\.
.RE
.IP \(bu 4
\fBAPEX\fP is the name (DNS label) to use the apex records, defaults to \fB\fCdns\fR.
.IP \(bu 4
\fB\fCttl\fR allows you to set a custom \fBTTL\fP for responses. The default is 5 (seconds).
.SH EXAMPLES
.PP
Enable names under \fB\fCexample.org\fR to be resolved to in cluster DNS addresses.
.PP
.RS
.nf
\&. {
kubernetes cluster.local
k8s\_external example.org
}
.fi
.RE
.SH ALSO SEE
.PP
For some background see resolve external IP address
\[la]https://github.com/kubernetes/dns/issues/242\[ra].
And A records for services with Load Balancer IP
\[la]https://github.com/coredns/coredns/issues/1851\[ra].
.SH BUGS
.PP
PTR queries for the reverse zone is not supported.

496
man/coredns-kubernetes.7
View file

@ -1,266 +1,328 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-KUBERNETES" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIkubernetes\fR \- enables the reading zone data from a Kubernetes cluster\.
.
.SH "DESCRIPTION"
This plugin implements the Kubernetes DNS\-Based Service Discovery Specification \fIhttps://github\.com/kubernetes/dns/blob/master/docs/specification\.md\fR\.
.
.P
CoreDNS running the kubernetes plugin can be used as a replacement for kube\-dns in a kubernetes cluster\. See the deployment \fIhttps://github\.com/coredns/deployment\fR repository for details on how to deploy CoreDNS in Kubernetes \fIhttps://github\.com/coredns/deployment/tree/master/kubernetes\fR\.
.
.P
stubDomains and upstreamNameservers \fIhttps://kubernetes\.io/blog/2017/04/configuring\-private\-dns\-zones\-upstream\-nameservers\-kubernetes/\fR are implemented via the \fIforward\fR plugin and kubernetes \fIupstream\fR\. See the examples below\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-KUBERNETES" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH KUBERNETES
.SH NAME
.PP
\fIkubernetes\fP - enables the reading zone data from a Kubernetes cluster.
.SH DESCRIPTION
.PP
This plugin implements the Kubernetes DNS-Based Service Discovery
Specification
\[la]https://github.com/kubernetes/dns/blob/master/docs/specification.md\[ra].
.PP
CoreDNS running the kubernetes plugin can be used as a replacement for kube-dns in a kubernetes
cluster. See the deployment
\[la]https://github.com/coredns/deployment\[ra] repository for details on how
to deploy CoreDNS in Kubernetes
\[la]https://github.com/coredns/deployment/tree/master/kubernetes\[ra].
.PP
stubDomains and upstreamNameservers
\[la]https://kubernetes.io/blog/2017/04/configuring-private-dns-zones-upstream-nameservers-kubernetes/\[ra]
are implemented via the \fIforward\fP plugin and kubernetes \fIupstream\fP. See the examples below.
.PP
This plugin can only be used once per Server Block.
.SH SYNTAX
.PP
.RS
.nf
kubernetes [ZONES...]
kubernetes [ZONES\.\.\.]
.
.fi
.
.P
With only the directive specified, the \fIkubernetes\fR plugin will default to the zone specified in the server\'s block\. It will handle all queries in that zone and connect to Kubernetes in\-cluster\. It will not provide PTR records for services or A records for pods\. If \fBZONES\fR is used it specifies all the zones the plugin should be authoritative for\.
.
.IP "" 4
.
.nf
.RE
kubernetes [ZONES\.\.\.] {
.PP
With only the directive specified, the \fIkubernetes\fP plugin will default to the zone specified in
the server's block. It will handle all queries in that zone and connect to Kubernetes in-cluster. It
will not provide PTR records for services or A records for pods. If \fBZONES\fP is used it specifies
all the zones the plugin should be authoritative for.
.PP
.RS
.nf
kubernetes [ZONES...] {
resyncperiod DURATION
endpoint URL
tls CERT KEY CACERT
kubeconfig KUBECONFIG CONTEXT
namespaces NAMESPACE\.\.\.
namespaces NAMESPACE...
labels EXPRESSION
pods POD\-MODE
endpoint_pod_names
upstream [ADDRESS\.\.\.]
endpoint\_pod\_names
upstream [ADDRESS...]
ttl TTL
noendpoints
transfer to ADDRESS\.\.\.
fallthrough [ZONES\.\.\.]
ignore empty_service
transfer to ADDRESS...
fallthrough [ZONES...]
ignore empty\_service
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBresyncperiod\fR specifies the Kubernetes data API \fBDURATION\fR period\.
.
.IP "\(bu" 4
\fBendpoint\fR specifies the \fBURL\fR for a remote k8s API endpoint\. If omitted, it will connect to k8s in\-cluster using the cluster service account\.
.
.IP "\(bu" 4
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCACERT\fR are the TLS cert, key and the CA cert file names for remote k8s connection\. This option is ignored if connecting in\-cluster (i\.e\. endpoint is not specified)\.
.
.IP "\(bu" 4
\fBkubeconfig\fR \fBKUBECONFIG\fR \fBCONTEXT\fR authenticates the connection to a remote k8s cluster using a kubeconfig file\. It supports TLS, username and password, or token\-based authentication\. This option is ignored if connecting in\-cluster (i\.e\., the endpoint is not specified)\.
.
.IP "\(bu" 4
\fBnamespaces\fR \fBNAMESPACE [NAMESPACE\.\.\.]\fR only exposes the k8s namespaces listed\. If this option is omitted all namespaces are exposed
.
.IP "\(bu" 4
\fBnamespace_labels\fR \fBEXPRESSION\fR only expose the records for Kubernetes namespaces that match this label selector\. The label selector syntax is described in the Kubernetes User Guide \- Labels \fIhttp://kubernetes\.io/docs/user\-guide/labels/\fR\. An example that only exposes namespaces labeled as "istio\-injection=enabled", would use: \fBlabels istio\-injection=enabled\fR\.
.
.IP "\(bu" 4
\fBlabels\fR \fBEXPRESSION\fR only exposes the records for Kubernetes objects that match this label selector\. The label selector syntax is described in the Kubernetes User Guide \- Labels \fIhttps://kubernetes\.io/docs/user\-guide/labels/\fR\. An example that only exposes objects labeled as "application=nginx" in the "staging" or "qa" environments, would use: \fBlabels environment in (staging, qa),application=nginx\fR\.
.
.IP "\(bu" 4
\fBpods\fR \fBPOD\-MODE\fR sets the mode for handling IP\-based pod A records, e\.g\. \fB1\-2\-3\-4\.ns\.pod\.cluster\.local\. in A 1\.2\.3\.4\fR\. This option is provided to facilitate use of SSL certs when connecting directly to pods\. Valid values for \fBPOD\-MODE\fR:
.
.IP "\(bu" 4
\fBdisabled\fR: Default\. Do not process pod requests, always returning \fBNXDOMAIN\fR
.
.IP "\(bu" 4
\fBinsecure\fR: Always return an A record with IP from request (without checking k8s)\. This option is vulnerable to abuse if used maliciously in conjunction with wildcard SSL certs\. This option is provided for backward compatibility with kube\-dns\.
.
.IP "\(bu" 4
\fBverified\fR: Return an A record if there exists a pod in same namespace with matching IP\. This option requires substantially more memory than in insecure mode, since it will maintain a watch on all pods\.
.
.IP "" 0
.RE
.IP \(bu 4
\fB\fCresyncperiod\fR specifies the Kubernetes data API \fBDURATION\fP period. By
default resync is disabled (DURATION is zero).
.IP \(bu 4
\fB\fCendpoint\fR specifies the \fBURL\fP for a remote k8s API endpoint.
If omitted, it will connect to k8s in-cluster using the cluster service account.
.IP \(bu 4
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP \fBCACERT\fP are the TLS cert, key and the CA cert file names for remote k8s connection.
This option is ignored if connecting in-cluster (i.e. endpoint is not specified).
.IP \(bu 4
\fB\fCkubeconfig\fR \fBKUBECONFIG\fP \fBCONTEXT\fP authenticates the connection to a remote k8s cluster using a kubeconfig file. It supports TLS, username and password, or token-based authentication. This option is ignored if connecting in-cluster (i.e., the endpoint is not specified).
.IP \(bu 4
\fB\fCnamespaces\fR \fBNAMESPACE [NAMESPACE...]\fP only exposes the k8s namespaces listed.
If this option is omitted all namespaces are exposed
.IP \(bu 4
\fB\fCnamespace_labels\fR \fBEXPRESSION\fP only expose the records for Kubernetes namespaces that match this label selector.
The label selector syntax is described in the
Kubernetes User Guide - Labels
\[la]http://kubernetes.io/docs/user-guide/labels/\[ra]. An example that
only exposes namespaces labeled as "istio-injection=enabled", would use:
\fB\fClabels istio-injection=enabled\fR.
.IP \(bu 4
\fB\fClabels\fR \fBEXPRESSION\fP only exposes the records for Kubernetes objects that match this label selector.
The label selector syntax is described in the
Kubernetes User Guide - Labels
\[la]https://kubernetes.io/docs/user-guide/labels/\[ra]. An example that
only exposes objects labeled as "application=nginx" in the "staging" or "qa" environments, would
use: \fB\fClabels environment in (staging, qa),application=nginx\fR.
.IP \(bu 4
\fB\fCpods\fR \fBPOD-MODE\fP sets the mode for handling IP-based pod A records, e.g.
\fB\fC1-2-3-4.ns.pod.cluster.local. in A 1.2.3.4\fR.
This option is provided to facilitate use of SSL certs when connecting directly to pods. Valid
values for \fBPOD-MODE\fP:
.RS
.IP \(en 4
\fB\fCdisabled\fR: Default. Do not process pod requests, always returning \fB\fCNXDOMAIN\fR
.IP \(en 4
\fB\fCinsecure\fR: Always return an A record with IP from request (without checking k8s). This option
is vulnerable to abuse if used maliciously in conjunction with wildcard SSL certs. This
option is provided for backward compatibility with kube-dns.
.IP \(en 4
\fB\fCverified\fR: Return an A record if there exists a pod in same namespace with matching IP. This
option requires substantially more memory than in insecure mode, since it will maintain a watch
on all pods.
.RE
.IP \(bu 4
\fB\fCendpoint_pod_names\fR uses the pod name of the pod targeted by the endpoint as
the endpoint name in A records, e.g.,
\fB\fCendpoint-name.my-service.namespace.svc.cluster.local. in A 1.2.3.4\fR
By default, the endpoint-name name selection is as follows: Use the hostname
of the endpoint, or if hostname is not set, use the dashed form of the endpoint
IP address (e.g., \fB\fC1-2-3-4.my-service.namespace.svc.cluster.local.\fR)
If this directive is included, then name selection for endpoints changes as
follows: Use the hostname of the endpoint, or if hostname is not set, use the
pod name of the pod targeted by the endpoint. If there is no pod targeted by
the endpoint, use the dashed IP address form.
.IP \(bu 4
\fB\fCupstream\fR [\fBADDRESS\fP...] defines the upstream resolvers used for resolving services
that point to external hosts (aka External Services, aka CNAMEs). If no \fBADDRESS\fP is given, CoreDNS
will resolve External Services against itself. \fBADDRESS\fP can be an IP, an IP:port, or a path
to a file structured like resolv.conf.
.IP \(bu 4
\fB\fCttl\fR allows you to set a custom TTL for responses. The default is 5 seconds. The minimum TTL allowed is
0 seconds, and the maximum is capped at 3600 seconds. Setting TTL to 0 will prevent records from being cached.
.IP \(bu 4
\fB\fCnoendpoints\fR will turn off the serving of endpoint records by disabling the watch on endpoints.
All endpoint queries and headless service queries will result in an NXDOMAIN.
.IP \(bu 4
\fB\fCtransfer\fR enables zone transfers. It may be specified multiples times. \fB\fCTo\fR signals the direction
(only \fB\fCto\fR is allowed). \fBADDRESS\fP must be denoted in CIDR notation (127.0.0.1/32 etc.) or just as
plain addresses. The special wildcard \fB\fC*\fR means: the entire internet.
Sending DNS notifies is not supported.
Deprecated
\[la]https://github.com/kubernetes/dns/blob/master/docs/specification.md#26---deprecated-records\[ra] pod records in the subdomain \fB\fCpod.cluster.local\fR are not transferred.
.IP \(bu 4
\fB\fCfallthrough\fR \fB[ZONES...]\fP If a query for a record in the zones for which the plugin is authoritative
results in NXDOMAIN, normally that is what the response will be. However, if you specify this option,
the query will instead be passed on down the plugin chain, which can include another plugin to handle
the query. If \fB[ZONES...]\fP is omitted, then fallthrough happens for all zones for which the plugin
is authoritative. If specific zones are listed (for example \fB\fCin-addr.arpa\fR and \fB\fCip6.arpa\fR), then only
queries for those zones will be subject to fallthrough.
.IP \(bu 4
\fB\fCignore empty_service\fR returns NXDOMAIN for services without any ready endpoint addresses (e.g., ready pods).
This allows the querying pod to continue searching for the service in the search path.
The search path could, for example, include another Kubernetes cluster.
.SH READY
.PP
This plugin reports readiness to the ready plugin. This will happen after it has synced to the
Kubernetes API.
.SH EXAMPLES
.PP
Handle all queries in the \fB\fCcluster.local\fR zone. Connect to Kubernetes in-cluster. Also handle all
\fB\fCin-addr.arpa\fR \fB\fCPTR\fR requests for \fB\fC10.0.0.0/17\fR . Verify the existence of pods when answering pod
requests. Resolve upstream records against \fB\fC10.102.3.10\fR. Note we show the entire server block here:
.PP
.RS
.
.IP "\(bu" 4
\fBendpoint_pod_names\fR uses the pod name of the pod targeted by the endpoint as the endpoint name in A records, e\.g\., \fBendpoint\-name\.my\-service\.namespace\.svc\.cluster\.local\. in A 1\.2\.3\.4\fR By default, the endpoint\-name name selection is as follows: Use the hostname of the endpoint, or if hostname is not set, use the dashed form of the endpoint IP address (e\.g\., \fB1\-2\-3\-4\.my\-service\.namespace\.svc\.cluster\.local\.\fR) If this directive is included, then name selection for endpoints changes as follows: Use the hostname of the endpoint, or if hostname is not set, use the pod name of the pod targeted by the endpoint\. If there is no pod targeted by the endpoint, use the dashed IP address form\.
.
.IP "\(bu" 4
\fBupstream\fR [\fBADDRESS\fR\.\.\.] defines the upstream resolvers used for resolving services that point to external hosts (aka External Services, aka CNAMEs)\. If no \fBADDRESS\fR is given, CoreDNS will resolve External Services against itself\. \fBADDRESS\fR can be an IP, an IP:port, or a path to a file structured like resolv\.conf\.
.
.IP "\(bu" 4
\fBttl\fR allows you to set a custom TTL for responses\. The default is 5 seconds\. The minimum TTL allowed is 0 seconds, and the maximum is capped at 3600 seconds\. Setting TTL to 0 will prevent records from being cached\.
.
.IP "\(bu" 4
\fBnoendpoints\fR will turn off the serving of endpoint records by disabling the watch on endpoints\. All endpoint queries and headless service queries will result in an NXDOMAIN\.
.
.IP "\(bu" 4
\fBtransfer\fR enables zone transfers\. It may be specified multiples times\. \fBTo\fR signals the direction (only \fBto\fR is allowed)\. \fBADDRESS\fR must be denoted in CIDR notation (127\.0\.0\.1/32 etc\.) or just as plain addresses\. The special wildcard \fB*\fR means: the entire internet\. Sending DNS notifies is not supported\. Deprecated \fIhttps://github\.com/kubernetes/dns/blob/master/docs/specification\.md#26\-\-\-deprecated\-records\fR pod records in the subdomain \fBpod\.cluster\.local\fR are not transferred\.
.
.IP "\(bu" 4
\fBfallthrough\fR \fB[ZONES\.\.\.]\fR If a query for a record in the zones for which the plugin is authoritative results in NXDOMAIN, normally that is what the response will be\. However, if you specify this option, the query will instead be passed on down the plugin chain, which can include another plugin to handle the query\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.IP "\(bu" 4
\fBignore empty_service\fR returns NXDOMAIN for services without any ready endpoint addresses (e\.g\., ready pods)\. This allows the querying pod to continue searching for the service in the search path\. The search path could, for example, include another Kubernetes cluster\.
.
.IP "" 0
.
.SH "READY"
This plugin reports readiness to the ready plugin\. This will happen after it has synced to the Kubernetes API\.
.
.SH "EXAMPLES"
Handle all queries in the \fBcluster\.local\fR zone\. Connect to Kubernetes in\-cluster\. Also handle all \fBin\-addr\.arpa\fR \fBPTR\fR requests for \fB10\.0\.0\.0/17\fR \. Verify the existence of pods when answering pod requests\. Resolve upstream records against \fB10\.102\.3\.10\fR\. Note we show the entire server block here:
.
.IP "" 4
.
.nf
10\.0\.0\.0/17 cluster\.local {
10.0.0.0/17 cluster.local {
kubernetes {
pods verified
upstream 10\.102\.3\.10:53
upstream 10.102.3.10:53
}
}
.
.fi
.
.IP "" 0
.
.P
Or you can selectively expose some namespaces:
.
.IP "" 4
.
.nf
kubernetes cluster\.local {
.fi
.RE
.PP
Or you can selectively expose some namespaces:
.PP
.RS
.nf
kubernetes cluster.local {
namespaces test staging
}
.
.fi
.
.IP "" 0
.
.P
Connect to Kubernetes with CoreDNS running outside the cluster:
.
.IP "" 4
.
.nf
kubernetes cluster\.local {
.fi
.RE
.PP
Connect to Kubernetes with CoreDNS running outside the cluster:
.PP
.RS
.nf
kubernetes cluster.local {
endpoint https://k8s\-endpoint:8443
tls cert key cacert
}
.
.fi
.
.IP "" 0
.
.SH "STUBDOMAINS AND UPSTREAMNAMESERVERS"
Here we use the \fIforward\fR plugin to implement a stubDomain that forwards \fBexample\.local\fR to the nameserver \fB10\.100\.0\.10:53\fR\. The \fIupstream\fR option in the \fIkubernetes\fR plugin means that ExternalName services (CNAMEs) will be resolved using the respective proxy\. Also configured is an upstreamNameserver \fB8\.8\.8\.8:53\fR that will be used for resolving names that do not fall in \fBcluster\.local\fR or \fBexample\.local\fR\.
.
.IP "" 4
.
.nf
cluster\.local:53 {
kubernetes cluster\.local {
.fi
.RE
.SH STUBDOMAINS AND UPSTREAMNAMESERVERS
.PP
Here we use the \fIforward\fP plugin to implement a stubDomain that forwards \fB\fCexample.local\fR to the nameserver \fB\fC10.100.0.10:53\fR.
The \fIupstream\fP option in the \fIkubernetes\fP plugin means that ExternalName services (CNAMEs) will be resolved using the respective proxy.
Also configured is an upstreamNameserver \fB\fC8.8.8.8:53\fR that will be used for resolving names that do not fall in \fB\fCcluster.local\fR
or \fB\fCexample.local\fR.
.PP
.RS
.nf
cluster.local:53 {
kubernetes cluster.local {
upstream
}
}
example\.local {
forward \. 10\.100\.0\.10:53
example.local {
forward . 10.100.0.10:53
}
\. {
forward \. 8\.8\.8\.8:53
\&. {
forward . 8.8.8.8:53
}
.
.fi
.
.IP "" 0
.
.P
The configuration above represents the following Kube\-DNS stubDomains and upstreamNameservers configuration\.
.
.IP "" 4
.
.nf
.RE
.PP
The configuration above represents the following Kube-DNS stubDomains and upstreamNameservers configuration.
.PP
.RS
.nf
stubDomains: |
{“example\.local”: [“10\.100\.0\.10:53”]}
{“example.local”: [“10.100.0.10:53”]}
upstreamNameservers: |
[“8\.8\.8\.8:53”]
.
.fi
.
.IP "" 0
.
.SH "AUTOPATH"
The \fIkubernetes\fR plugin can be used in conjunction with the \fIautopath\fR plugin\. Using this feature enables server\-side domain search path completion in Kubernetes clusters\. Note: \fBpods\fR must be set to \fBverified\fR for this to function properly\.
.
.IP "" 4
.
.nf
[“8.8.8.8:53”]
cluster\.local {
.fi
.RE
.SH AUTOPATH
.PP
The \fIkubernetes\fP plugin can be used in conjunction with the \fIautopath\fP plugin. Using this
feature enables server-side domain search path completion in Kubernetes clusters. Note: \fB\fCpods\fR must
be set to \fB\fCverified\fR for this to function properly.
.PP
.RS
.nf
cluster.local {
autopath @kubernetes
kubernetes {
pods verified
}
}
.
.fi
.
.IP "" 0
.
.SH "FEDERATION"
The \fIkubernetes\fR plugin can be used in conjunction with the \fIfederation\fR plugin\. Using this feature enables serving federated domains from the Kubernetes clusters\.
.
.IP "" 4
.
.nf
cluster\.local {
.fi
.RE
.SH FEDERATION
.PP
The \fIkubernetes\fP plugin can be used in conjunction with the \fIfederation\fP plugin. Using this
feature enables serving federated domains from the Kubernetes clusters.
.PP
.RS
.nf
cluster.local {
federation {
prod prod\.example\.org
staging staging\.example\.org
prod prod.example.org
staging staging.example.org
}
kubernetes
}
.
.fi
.
.IP "" 0
.
.SH "WILDCARDS"
Some query labels accept a wildcard value to match any value\. If a label is a valid wildcard (*, or the word "any"), then that label will match all values\. The labels that accept wildcards are:
.
.IP "\(bu" 4
\fIendpoint\fR in an \fBA\fR record request: \fIendpoint\fR\.service\.namespace\.svc\.zone, e\.g\., \fB*\.nginx\.ns\.svc\.cluster\.local\fR
.
.IP "\(bu" 4
\fIservice\fR in an \fBA\fR record request: \fIservice\fR\.namespace\.svc\.zone, e\.g\., \fB*\.ns\.svc\.cluster\.local\fR
.
.IP "\(bu" 4
\fInamespace\fR in an \fBA\fR record request: service\.\fInamespace\fR\.svc\.zone, e\.g\., \fBnginx\.*\.svc\.cluster\.local\fR
.
.IP "\(bu" 4
\fIport and/or protocol\fR in an \fBSRV\fR request: \fBport_\.\fRprotocol_\.service\.namespace\.svc\.zone\., e\.g\., \fB_http\.*\.service\.ns\.svc\.cluster\.local\fR
.
.IP "\(bu" 4
multiple wildcards are allowed in a single query, e\.g\., \fBA\fR Request \fB*\.*\.svc\.zone\.\fR or \fBSRV\fR request \fB*\.*\.*\.*\.svc\.zone\.\fR
.
.IP "" 0
.
.P
For example, wildcards can be used to resolve all Endpoints for a Service as \fBA\fR records\. e\.g\.: \fB*\.service\.ns\.svc\.myzone\.local\fR will return the Endpoint IPs in the Service \fBservice\fR in namespace \fBdefault\fR: \fB*\.service\.default\.svc\.cluster\.local\. 5 IN A 192\.168\.10\.10 *\.service\.default\.svc\.cluster\.local\. 5 IN A 192\.168\.25\.15\fR This response can be randomized using the \fBloadbalance\fR plugin
.RE
.SH WILDCARDS
.PP
Some query labels accept a wildcard value to match any value. If a label is a valid wildcard (*,
or the word "any"), then that label will match all values. The labels that accept wildcards are:
.IP \(bu 4
\fIendpoint\fP in an \fB\fCA\fR record request: \fIendpoint\fP.service.namespace.svc.zone, e.g., \fB\fC*.nginx.ns.svc.cluster.local\fR
.IP \(bu 4
\fIservice\fP in an \fB\fCA\fR record request: \fIservice\fP.namespace.svc.zone, e.g., \fB\fC*.ns.svc.cluster.local\fR
.IP \(bu 4
\fInamespace\fP in an \fB\fCA\fR record request: service.\fInamespace\fP.svc.zone, e.g., \fB\fCnginx.*.svc.cluster.local\fR
.IP \(bu 4
\fIport and/or protocol\fP in an \fB\fCSRV\fR request: \fBport_.\fPprotocol_.service.namespace.svc.zone.,
e.g., \fB\fC_http.*.service.ns.svc.cluster.local\fR
.IP \(bu 4
multiple wildcards are allowed in a single query, e.g., \fB\fCA\fR Request \fB\fC*.*.svc.zone.\fR or \fB\fCSRV\fR request \fB\fC*.*.*.*.svc.zone.\fR
.PP
For example, wildcards can be used to resolve all Endpoints for a Service as \fB\fCA\fR records. e.g.: \fB\fC*.service.ns.svc.myzone.local\fR will return the Endpoint IPs in the Service \fB\fCservice\fR in namespace \fB\fCdefault\fR:
.PP
.RS
.nf
*.service.default.svc.cluster.local. 5 IN A 192.168.10.10
*.service.default.svc.cluster.local. 5 IN A 192.168.25.15
.fi
.RE
.PP
This response can be randomized using the \fB\fCloadbalance\fR plugin

78
man/coredns-loadbalance.7
View file

@ -1,43 +1,49 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-LOADBALANCE" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIloadbalance\fR \- randomize the order of A, AAAA and MX records\.
.
.SH "DESCRIPTION"
The \fIloadbalance\fR will act as a round\-robin DNS loadbalancer by randomizing the order of A, AAAA, and MX records in the answer\.
.
.P
See Wikipedia \fIhttps://en\.wikipedia\.org/wiki/Round\-robin_DNS\fR about the pros and cons on this setup\. It will take care to sort any CNAMEs before any address records, because some stub resolver implementations (like glibc) are particular about that\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-LOADBALANCE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH LOADBALANCE
.SH NAME
.PP
\fIloadbalance\fP - randomize the order of A, AAAA and MX records.
.SH DESCRIPTION
.PP
The \fIloadbalance\fP will act as a round-robin DNS loadbalancer by randomizing the order of A, AAAA,
and MX records in the answer.
.PP
See Wikipedia
\[la]https://en.wikipedia.org/wiki/Round-robin_DNS\[ra] about the pros and cons on this
setup. It will take care to sort any CNAMEs before any address records, because some stub resolver
implementations (like glibc) are particular about that.
.SH SYNTAX
.PP
.RS
.nf
loadbalance [POLICY]
.
.fi
.
.IP "\(bu" 4
\fBPOLICY\fR is how to balance, the default, and only option, is "round_robin"\.
.
.IP "" 0
.
.SH "EXAMPLES"
.RE
.IP \(bu 4
\fBPOLICY\fP is how to balance, the default, and only option, is "round_robin".
.SH EXAMPLES
.PP
Load balance replies coming back from Google Public DNS:
.
.IP "" 4
.
.PP
.RS
.nf
\&\. {
loadbalance round_robin
forward \. 8\.8\.8\.8 8\.8\.4\.4
\&. {
loadbalance round\_robin
forward . 8.8.8.8 8.8.4.4
}
.
.fi
.
.IP "" 0
.fi
.RE

448
man/coredns-log.7
View file

@ -1,279 +1,253 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-LOG" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIlog\fR \- enables query logging to standard output\.
.
.SH "DESCRIPTION"
By just using \fIlog\fR you dump all queries (and parts for the reply) on standard output\. Options exist to tweak the output a little\. The date/time prefix on log lines is RFC3339 formatted with milliseconds\.
.
.P
Note that for busy servers logging will incur a performance hit\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-LOG" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH LOG
.SH NAME
.PP
\fIlog\fP - enables query logging to standard output.
.SH DESCRIPTION
.PP
By just using \fIlog\fP you dump all queries (and parts for the reply) on standard output. Options exist
to tweak the output a little. The date/time prefix on log lines is RFC3339 formatted with
milliseconds.
.PP
Note that for busy servers logging will incur a performance hit.
.SH SYNTAX
.PP
.RS
.nf
log
.
.fi
.
.IP "\(bu" 4
With no arguments, a query log entry is written to \fIstdout\fR in the common log format for all requests
.
.IP "" 0
.
.P
.RE
.IP \(bu 4
With no arguments, a query log entry is written to \fIstdout\fP in the common log format for all requests
.PP
Or if you want/need slightly more control:
.
.IP "" 4
.
.nf
log [NAMES\.\.\.] [FORMAT]
.
.PP
.RS
.nf
log [NAMES...] [FORMAT]
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBNAMES\fR is the name list to match in order to be logged
.
.IP "\(bu" 4
\fBFORMAT\fR is the log format to use (default is Common Log Format), \fB{common}\fR is used as a shortcut for the Common Log Format\. You can also use \fB{combined}\fR for a format that adds the query opcode \fB{>opcode}\fR to the Common Log Format\.
.
.IP "" 0
.
.P
.RE
.IP \(bu 4
\fB\fCNAMES\fR is the name list to match in order to be logged
.IP \(bu 4
\fB\fCFORMAT\fR is the log format to use (default is Common Log Format), \fB\fC{common}\fR is used as a shortcut
for the Common Log Format. You can also use \fB\fC{combined}\fR for a format that adds the query opcode
\fB\fC{>opcode}\fR to the Common Log Format.
.PP
You can further specify the classes of responses that get logged:
.
.IP "" 4
.
.nf
log [NAMES\.\.\.] [FORMAT] {
class CLASSES\.\.\.
.PP
.RS
.nf
log [NAMES...] [FORMAT] {
class CLASSES...
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBCLASSES\fR is a space\-separated list of classes of responses that should be logged
.
.IP "" 0
.
.P
.RE
.IP \(bu 4
\fB\fCCLASSES\fR is a space-separated list of classes of responses that should be logged
.PP
The classes of responses have the following meaning:
.
.IP "\(bu" 4
\fBsuccess\fR: successful response
.
.IP "\(bu" 4
\fBdenial\fR: either NXDOMAIN or nodata responses (Name exists, type does not)\. A nodata response sets the return code to NOERROR\.
.
.IP "\(bu" 4
\fBerror\fR: SERVFAIL, NOTIMP, REFUSED, etc\. Anything that indicates the remote server is not willing to resolve the request\.
.
.IP "\(bu" 4
\fBall\fR: the default \- nothing is specified\. Using of this class means that all messages will be logged whatever we mix together with "all"\.
.
.IP "" 0
.
.P
If no class is specified, it defaults to \fIall\fR\.
.
.SH "LOG FORMAT"
You can specify a custom log format with any placeholder values\. Log supports both request and response placeholders\.
.
.P
.IP \(bu 4
\fB\fCsuccess\fR: successful response
.IP \(bu 4
\fB\fCdenial\fR: either NXDOMAIN or nodata responses (Name exists, type does not). A nodata response
sets the return code to NOERROR.
.IP \(bu 4
\fB\fCerror\fR: SERVFAIL, NOTIMP, REFUSED, etc. Anything that indicates the remote server is not willing to
resolve the request.
.IP \(bu 4
\fB\fCall\fR: the default - nothing is specified. Using of this class means that all messages will be
logged whatever we mix together with "all".
.PP
If no class is specified, it defaults to \fIall\fP.
.SH LOG FORMAT
.PP
You can specify a custom log format with any placeholder values. Log supports both request and
response placeholders.
.PP
The following place holders are supported:
.
.IP "\(bu" 4
\fB{type}\fR: qtype of the request
.
.IP "\(bu" 4
\fB{name}\fR: qname of the request
.
.IP "\(bu" 4
\fB{class}\fR: qclass of the request
.
.IP "\(bu" 4
\fB{proto}\fR: protocol used (tcp or udp)
.
.IP "\(bu" 4
\fB{remote}\fR: client\'s IP address, for IPv6 addresses these are enclosed in brackets: \fB[::1]\fR
.
.IP "\(bu" 4
\fB{local}\fR: server\'s IP address, for IPv6 addresses these are enclosed in brackets: \fB[::1]\fR
.
.IP "\(bu" 4
\fB{size}\fR: request size in bytes
.
.IP "\(bu" 4
\fB{port}\fR: client\'s port
.
.IP "\(bu" 4
\fB{duration}\fR: response duration
.
.IP "\(bu" 4
\fB{rcode}\fR: response RCODE
.
.IP "\(bu" 4
\fB{rsize}\fR: raw (uncompressed), response size (a client may receive a smaller response)
.
.IP "\(bu" 4
\fB{>rflags}\fR: response flags, each set flag will be displayed, e\.g\. "aa, tc"\. This includes the qr bit as well
.
.IP "\(bu" 4
\fB{>bufsize}\fR: the EDNS0 buffer size advertised in the query
.
.IP "\(bu" 4
\fB{>do}\fR: is the EDNS0 DO (DNSSEC OK) bit set in the query
.
.IP "\(bu" 4
\fB{>id}\fR: query ID
.
.IP "\(bu" 4
\fB{>opcode}\fR: query OPCODE
.
.IP "\(bu" 4
\fB{common}\fR: the default Common Log Format\.
.
.IP "\(bu" 4
\fB{combined}\fR: the Common Log Format with the query opcode\.
.
.IP "\(bu" 4
\fB{/LABEL}\fR: any metadata label is accepted as a place holder if it is enclosed between \fB{/\fR and \fB}\fR, the place holder will be replaced by the corresponding metadata value or the default value \fB\-\fR if label is not defined\. See the \fImetadata\fR plugin for more information\.
.
.IP "" 0
.
.P
.IP \(bu 4
\fB\fC{type}\fR: qtype of the request
.IP \(bu 4
\fB\fC{name}\fR: qname of the request
.IP \(bu 4
\fB\fC{class}\fR: qclass of the request
.IP \(bu 4
\fB\fC{proto}\fR: protocol used (tcp or udp)
.IP \(bu 4
\fB\fC{remote}\fR: client's IP address, for IPv6 addresses these are enclosed in brackets: \fB\fC[::1]\fR
.IP \(bu 4
\fB\fC{local}\fR: server's IP address, for IPv6 addresses these are enclosed in brackets: \fB\fC[::1]\fR
.IP \(bu 4
\fB\fC{size}\fR: request size in bytes
.IP \(bu 4
\fB\fC{port}\fR: client's port
.IP \(bu 4
\fB\fC{duration}\fR: response duration
.IP \(bu 4
\fB\fC{rcode}\fR: response RCODE
.IP \(bu 4
\fB\fC{rsize}\fR: raw (uncompressed), response size (a client may receive a smaller response)
.IP \(bu 4
\fB\fC{>rflags}\fR: response flags, each set flag will be displayed, e.g. "aa, tc". This includes the qr
bit as well
.IP \(bu 4
\fB\fC{>bufsize}\fR: the EDNS0 buffer size advertised in the query
.IP \(bu 4
\fB\fC{>do}\fR: is the EDNS0 DO (DNSSEC OK) bit set in the query
.IP \(bu 4
\fB\fC{>id}\fR: query ID
.IP \(bu 4
\fB\fC{>opcode}\fR: query OPCODE
.IP \(bu 4
\fB\fC{common}\fR: the default Common Log Format.
.IP \(bu 4
\fB\fC{combined}\fR: the Common Log Format with the query opcode.
.IP \(bu 4
\fB\fC{/LABEL}\fR: any metadata label is accepted as a place holder if it is enclosed between \fB\fC{/\fR and
\fB\fC}\fR, the place holder will be replaced by the corresponding metadata value or the default value
\fB\fC-\fR if label is not defined. See the \fImetadata\fP plugin for more information.
.PP
The default Common Log Format is:
.
.IP "" 4
.
.nf
.PP
.RS
.nf
`{remote}:{port} \- {>id} "{type} {class} {name} {proto} {size} {>do} {>bufsize}" {rcode} {>rflags} {rsize} {duration}`
.
.fi
.
.IP "" 0
.
.P
Each of these logs will be outputted with \fBlog\.Infof\fR, so a typical example looks like this:
.
.IP "" 4
.
.nf
2018\-10\-30T19:10:07\.547Z [INFO] [::1]:50759 \- 29008 "A IN example\.org\. udp 41 false 4096" NOERROR qr,rd,ra,ad 68 0\.037990251s
.
.fi
.
.IP "" 0
.
.SH "EXAMPLES"
.RE
.PP
Each of these logs will be outputted with \fB\fClog.Infof\fR, so a typical example looks like this:
.PP
.RS
.nf
2018\-10\-30T19:10:07.547Z [INFO] [::1]:50759 \- 29008 "A IN example.org. udp 41 false 4096" NOERROR qr,rd,ra,ad 68 0.037990251s
~~~~
## Examples
Log all requests to stdout
.
.IP "" 4
.
.nf
\&\. {
~~~ corefile
\&. {
log
whoami
}
.
.fi
.
.IP "" 0
.
.P
Custom log format, for all zones (\fB\.\fR)
.
.IP "" 4
.
.nf
\&\. {
log \. "{proto} Request: {name} {type} {>id}"
.fi
.RE
.PP
Custom log format, for all zones (\fB\fC.\fR)
.PP
.RS
.nf
\&. {
log . "{proto} Request: {name} {type} {>id}"
}
.
.fi
.
.IP "" 0
.
.P
Only log denials (NXDOMAIN and nodata) for example\.org (and below)
.
.IP "" 4
.
.nf
\&\. {
log example\.org {
.fi
.RE
.PP
Only log denials (NXDOMAIN and nodata) for example.org (and below)
.PP
.RS
.nf
\&. {
log example.org {
class denial
}
}
.
.fi
.
.IP "" 0
.
.P
Log all queries which were not resolved successfully in the Combined Log Format\.
.
.IP "" 4
.
.nf
\&\. {
log \. {combined} {
.fi
.RE
.PP
Log all queries which were not resolved successfully in the Combined Log Format.
.PP
.RS
.nf
\&. {
log . {combined} {
class denial error
}
}
.
.fi
.
.IP "" 0
.
.P
Log all queries on which we did not get errors
.
.IP "" 4
.
.nf
\&\. {
log \. {
.fi
.RE
.PP
Log all queries on which we did not get errors
.PP
.RS
.nf
\&. {
log . {
class denial success
}
}
.
.fi
.
.IP "" 0
.
.P
Also the multiple statements can be OR\-ed, for example, we can rewrite the above case as following:
.
.IP "" 4
.
.nf
\&\. {
log \. {
.fi
.RE
.PP
Also the multiple statements can be OR-ed, for example, we can rewrite the above case as following:
.PP
.RS
.nf
\&. {
log . {
class denial
class success
}
}
.
.fi
.
.IP "" 0
.fi
.RE

204
man/coredns-loop.7
View file

@ -1,102 +1,124 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-LOOP" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIloop\fR \- detect simple forwarding loops and halt the server\.
.
.SH "DESCRIPTION"
The \fIloop\fR plugin will send a random probe query to ourselves and will then keep track of how many times we see it\. If we see it more than twice, we assume CoreDNS has seen a forwarding loop and we halt the process\.
.
.P
The plugin will try to send the query for up to 30 seconds\. This is done to give CoreDNS enough time to start up\. Once a query has been successfully sent, \fIloop\fR disables itself to prevent a query of death\.
.
.P
The query sent is \fB<random number>\.<random number>\.zone\fR with type set to HINFO\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-LOOP" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH LOOP
.SH NAME
.PP
\fIloop\fP - detect simple forwarding loops and halt the server.
.SH DESCRIPTION
.PP
The \fIloop\fP plugin will send a random probe query to ourselves and will then keep track of how many times
we see it. If we see it more than twice, we assume CoreDNS has seen a forwarding loop and we halt the process.
.PP
The plugin will try to send the query for up to 30 seconds. This is done to give CoreDNS enough time
to start up. Once a query has been successfully sent, \fIloop\fP disables itself to prevent a query of
death.
.PP
The query sent is \fB\fC<random number>.<random number>.zone\fR with type set to HINFO.
.SH SYNTAX
.PP
.RS
.nf
loop
.
.fi
.
.SH "EXAMPLES"
Start a server on the default port and load the \fIloop\fR and \fIforward\fR plugins\. The \fIforward\fR plugin forwards to it self\.
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.SH EXAMPLES
.PP
Start a server on the default port and load the \fIloop\fP and \fIforward\fP plugins. The \fIforward\fP plugin
forwards to it self.
.PP
.RS
.nf
\&. {
loop
forward \. 127\.0\.0\.1
forward . 127.0.0.1
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
After CoreDNS has started it stops the process while logging:
.
.IP "" 4
.
.PP
.RS
.nf
plugin/loop: Loop (127.0.0.1:55953 \-> :1053) detected for zone ".", see https://coredns.io/plugins/loop#troubleshooting. Query: "HINFO 4547991504243258144.3688648895315093531."
plugin/loop: Loop (127\.0\.0\.1:55953 \-> :1053) detected for zone "\.", see https://coredns\.io/plugins/loop#troubleshooting\. Query: "HINFO 4547991504243258144\.3688648895315093531\."
.
.fi
.
.IP "" 0
.
.SH "LIMITATIONS"
This plugin only attempts to find simple static forwarding loops at start up time\. To detect a loop, the following must be true:
.
.IP "\(bu" 4
the loop must be present at start up time\.
.
.IP "\(bu" 4
the loop must occur for the \fBHINFO\fR query type\.
.
.IP "" 0
.
.SH "TROUBLESHOOTING"
When CoreDNS logs contain the message \fBLoop \.\.\. detected \.\.\.\fR, this means that the \fBloop\fR detection plugin has detected an infinite forwarding loop in one of the upstream DNS servers\. This is a fatal error because operating with an infinite loop will consume memory and CPU until eventual out of memory death by the host\.
.
.P
A forwarding loop is usually caused by:
.
.IP "\(bu" 4
Most commonly, CoreDNS forwarding requests directly to itself\. e\.g\. via a loopback address such as \fB127\.0\.0\.1\fR, \fB::1\fR or \fB127\.0\.0\.53\fR
.
.IP "\(bu" 4
Less commonly, CoreDNS forwarding to an upstream server that in turn, forwards requests back to CoreDNS\.
.
.IP "" 0
.
.P
To troubleshoot this problem, look in your Corefile for any \fBforward\fRs to the zone in which the loop was detected\. Make sure that they are not forwarding to a local address or to another DNS server that is forwarding requests back to CoreDNS\. If \fBforward\fR is using a file (e\.g\. \fB/etc/resolv\.conf\fR), make sure that file does not contain local addresses\.
.
.SS "TROUBLESHOOTING LOOPS IN KUBERNETES CLUSTERS"
When a CoreDNS Pod deployed in Kubernetes detects a loop, the CoreDNS Pod will start to "CrashLoopBackOff"\. This is because Kubernetes will try to restart the Pod every time CoreDNS detects the loop and exits\.
.
.P
A common cause of forwarding loops in Kubernetes clusters is an interaction with a local DNS cache on the host node (e\.g\. \fBsystemd\-resolved\fR)\. For example, in certain configurations \fBsystemd\-resolved\fR will put the loopback address \fB127\.0\.0\.53\fR as a nameserver into \fB/etc/resolv\.conf\fR\. Kubernetes (via \fBkubelet\fR) by default will pass this \fB/etc/resolv\.conf\fR file to all Pods using the \fBdefault\fR dnsPolicy rendering them unable to make DNS lookups (this includes CoreDNS Pods)\. CoreDNS uses this \fB/etc/resolv\.conf\fR as a list of upstreams to forward requests to\. Since it contains a loopback address, CoreDNS ends up forwarding requests to itself\.
.
.P
There are many ways to work around this issue, some are listed here:
.
.IP "\(bu" 4
Add the following to \fBkubelet\fR: \fB\-\-resolv\-conf <path\-to\-your\-real\-resolv\-conf\-file>\fR\. Your "real" \fBresolv\.conf\fR is the one that contains the actual IPs of your upstream servers, and no local/loopback address\. This flag tells \fBkubelet\fR to pass an alternate \fBresolv\.conf\fR to Pods\. For systems using \fBsystemd\-resolved\fR, \fB/run/systemd/resolve/resolv\.conf\fR is typically the location of the "real" \fBresolv\.conf\fR, although this can be different depending on your distribution\.
.
.IP "\(bu" 4
Disable the local DNS cache on host nodes, and restore \fB/etc/resolv\.conf\fR to the original\.
.
.IP "\(bu" 4
A quick and dirty fix is to edit your Corefile, replacing \fBforward \. /etc/resolv\.conf\fR with the ip address of your upstream DNS, for example \fBforward \. 8\.8\.8\.8\fR\. But this only fixes the issue for CoreDNS, kubelet will continue to forward the invalid \fBresolv\.conf\fR to all \fBdefault\fR dnsPolicy Pods, leaving them unable to resolve DNS\.
.
.IP "" 0
.RE
.SH LIMITATIONS
.PP
This plugin only attempts to find simple static forwarding loops at start up time. To detect a loop,
the following must be true:
.IP \(bu 4
the loop must be present at start up time.
.IP \(bu 4
the loop must occur for the \fB\fCHINFO\fR query type.
.SH TROUBLESHOOTING
.PP
When CoreDNS logs contain the message \fB\fCLoop ... detected ...\fR, this means that the \fB\fCloop\fR detection
plugin has detected an infinite forwarding loop in one of the upstream DNS servers. This is a fatal
error because operating with an infinite loop will consume memory and CPU until eventual out of
memory death by the host.
.PP
A forwarding loop is usually caused by:
.IP \(bu 4
Most commonly, CoreDNS forwarding requests directly to itself. e.g. via a loopback address such as \fB\fC127.0.0.1\fR, \fB\fC::1\fR or \fB\fC127.0.0.53\fR
.IP \(bu 4
Less commonly, CoreDNS forwarding to an upstream server that in turn, forwards requests back to CoreDNS.
.PP
To troubleshoot this problem, look in your Corefile for any \fB\fCforward\fRs to the zone
in which the loop was detected. Make sure that they are not forwarding to a local address or
to another DNS server that is forwarding requests back to CoreDNS. If \fB\fCforward\fR is
using a file (e.g. \fB\fC/etc/resolv.conf\fR), make sure that file does not contain local addresses.
.SS TROUBLESHOOTING LOOPS IN KUBERNETES CLUSTERS
.PP
When a CoreDNS Pod deployed in Kubernetes detects a loop, the CoreDNS Pod will start to "CrashLoopBackOff".
This is because Kubernetes will try to restart the Pod every time CoreDNS detects the loop and exits.
.PP
A common cause of forwarding loops in Kubernetes clusters is an interaction with a local DNS cache
on the host node (e.g. \fB\fCsystemd-resolved\fR). For example, in certain configurations \fB\fCsystemd-resolved\fR will
put the loopback address \fB\fC127.0.0.53\fR as a nameserver into \fB\fC/etc/resolv.conf\fR. Kubernetes (via \fB\fCkubelet\fR) by default
will pass this \fB\fC/etc/resolv.conf\fR file to all Pods using the \fB\fCdefault\fR dnsPolicy rendering them
unable to make DNS lookups (this includes CoreDNS Pods). CoreDNS uses this \fB\fC/etc/resolv.conf\fR
as a list of upstreams to forward requests to. Since it contains a loopback address, CoreDNS ends up forwarding
requests to itself.
.PP
There are many ways to work around this issue, some are listed here:
.IP \(bu 4
Add the following to \fB\fCkubelet\fR: \fB\fC--resolv-conf <path-to-your-real-resolv-conf-file>\fR. Your "real"
\fB\fCresolv.conf\fR is the one that contains the actual IPs of your upstream servers, and no local/loopback address.
This flag tells \fB\fCkubelet\fR to pass an alternate \fB\fCresolv.conf\fR to Pods. For systems using \fB\fCsystemd-resolved\fR,
\fB\fC/run/systemd/resolve/resolv.conf\fR is typically the location of the "real" \fB\fCresolv.conf\fR,
although this can be different depending on your distribution.
.IP \(bu 4
Disable the local DNS cache on host nodes, and restore \fB\fC/etc/resolv.conf\fR to the original.
.IP \(bu 4
A quick and dirty fix is to edit your Corefile, replacing \fB\fCforward . /etc/resolv.conf\fR with
the ip address of your upstream DNS, for example \fB\fCforward . 8.8.8.8\fR. But this only fixes the issue for CoreDNS,
kubelet will continue to forward the invalid \fB\fCresolv.conf\fR to all \fB\fCdefault\fR dnsPolicy Pods, leaving them unable to resolve DNS.

105
man/coredns-metadata.7
View file

@ -1,44 +1,65 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-METADATA" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fImetadata\fR \- enable a meta data collector\.
.
.SH "DESCRIPTION"
By enabling \fImetadata\fR any plugin that implements metadata\.Provider interface \fIhttps://godoc\.org/github\.com/coredns/coredns/plugin/metadata#Provider\fR will be called for each DNS query, at beginning of the process for that query, in order to add it\'s own meta data to context\.
.
.P
The meta data collected will be available for all plugins, via the Context parameter provided in the ServeDNS function\. The package (code) documentation has examples on how to inspect and retrieve metadata a plugin might be interested in\.
.
.P
The meta data is added by setting a label with a value in the context\. These labels should be named \fBplugin/NAME\fR, where \fBNAME\fR is something descriptive\. The only hard requirement the \fImetadata\fR plugin enforces is that the labels contains a slash\. See the documentation for \fBmetadata\.SetValueFunc\fR\.
.
.P
The value stored is a string\. The empty string signals "no meta data"\. See the documentation for \fBmetadata\.ValueFunc\fR on how to retrieve this\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-METADATA" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH METADATA
.SH NAME
.PP
\fImetadata\fP - enable a meta data collector.
.SH DESCRIPTION
.PP
By enabling \fImetadata\fP any plugin that implements metadata.Provider
interface
\[la]https://godoc.org/github.com/coredns/coredns/plugin/metadata#Provider\[ra] will be called for
each DNS query, at beginning of the process for that query, in order to add it's own meta data to
context.
.PP
The meta data collected will be available for all plugins, via the Context parameter provided in the
ServeDNS function. The package (code) documentation has examples on how to inspect and retrieve
metadata a plugin might be interested in.
.PP
The meta data is added by setting a label with a value in the context. These labels should be named
\fB\fCplugin/NAME\fR, where \fBNAME\fP is something descriptive. The only hard requirement the \fImetadata\fP
plugin enforces is that the labels contains a slash. See the documentation for
\fB\fCmetadata.SetValueFunc\fR.
.PP
The value stored is a string. The empty string signals "no meta data". See the documentation for
\fB\fCmetadata.ValueFunc\fR on how to retrieve this.
.SH SYNTAX
.PP
.RS
.nf
metadata [ZONES... ]
metadata [ZONES\.\.\. ]
.
.fi
.
.IP "\(bu" 4
\fBZONES\fR zones metadata should be invoked for\.
.
.IP "" 0
.
.SH "PLUGINS"
\fBmetadata\.Provider\fR interface needs to be implemented by each plugin willing to provide metadata information for other plugins\. It will be called by metadata and gather the information from all plugins in context\.
.
.P
Note: this method should work quickly, because it is called for every request\.
.
.SH "EXAMPLES"
The \fIrewrite\fR plugin uses meta data to rewrite requests\.
.
.SH "ALSO SEE"
The Provider interface \fIhttps://godoc\.org/github\.com/coredns/coredns/plugin/metadata#Provider\fR and the package level \fIhttps://godoc\.org/github\.com/coredns/coredns/plugin/metadata\fR documentation\.
.RE
.IP \(bu 4
\fBZONES\fP zones metadata should be invoked for.
.SH PLUGINS
.PP
\fB\fCmetadata.Provider\fR interface needs to be implemented by each plugin willing to provide metadata
information for other plugins. It will be called by metadata and gather the information from all
plugins in context.
.PP
Note: this method should work quickly, because it is called for every request.
.SH EXAMPLES
.PP
The \fIrewrite\fP plugin uses meta data to rewrite requests.
.SH ALSO SEE
.PP
The Provider interface
\[la]https://godoc.org/github.com/coredns/coredns/plugin/metadata#Provider\[ra] and
the package level
\[la]https://godoc.org/github.com/coredns/coredns/plugin/metadata\[ra] documentation.

219
man/coredns-metrics.7
View file

@ -1,118 +1,121 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-METRICS" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIprometheus\fR \- enables Prometheus \fIhttps://prometheus\.io/\fR metrics\.
.
.SH "DESCRIPTION"
With \fIprometheus\fR you export metrics from CoreDNS and any plugin that has them\. The default location for the metrics is \fBlocalhost:9153\fR\. The metrics path is fixed to \fB/metrics\fR\. The following metrics are exported:
.
.IP "\(bu" 4
\fBcoredns_build_info{version, revision, goversion}\fR \- info about CoreDNS itself\.
.
.IP "\(bu" 4
\fBcoredns_panic_count_total{}\fR \- total number of panics\.
.
.IP "\(bu" 4
\fBcoredns_dns_request_count_total{server, zone, proto, family}\fR \- total query count\.
.
.IP "\(bu" 4
\fBcoredns_dns_request_duration_seconds{server, zone}\fR \- duration to process each query\.
.
.IP "\(bu" 4
\fBcoredns_dns_request_size_bytes{server, zone, proto}\fR \- size of the request in bytes\.
.
.IP "\(bu" 4
\fBcoredns_dns_request_do_count_total{server, zone}\fR \- queries that have the DO bit set
.
.IP "\(bu" 4
\fBcoredns_dns_request_type_count_total{server, zone, type}\fR \- counter of queries per zone and type\.
.
.IP "\(bu" 4
\fBcoredns_dns_response_size_bytes{server, zone, proto}\fR \- response size in bytes\.
.
.IP "\(bu" 4
\fBcoredns_dns_response_rcode_count_total{server, zone, rcode}\fR \- response per zone and rcode\.
.
.IP "\(bu" 4
\fBcoredns_plugin_enabled{server, zone, name}\fR \- indicates whether a plugin is enabled on per server and zone basis\.
.
.IP "" 0
.
.P
Each counter has a label \fBzone\fR which is the zonename used for the request/response\.
.
.P
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-METRICS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH PROMETHEUS
.SH NAME
.PP
\fIprometheus\fP - enables Prometheus
\[la]https://prometheus.io/\[ra] metrics.
.SH DESCRIPTION
.PP
With \fIprometheus\fP you export metrics from CoreDNS and any plugin that has them.
The default location for the metrics is \fB\fClocalhost:9153\fR. The metrics path is fixed to \fB\fC/metrics\fR.
The following metrics are exported:
.IP \(bu 4
\fB\fCcoredns_build_info{version, revision, goversion}\fR - info about CoreDNS itself.
.IP \(bu 4
\fB\fCcoredns_panic_count_total{}\fR - total number of panics.
.IP \(bu 4
\fB\fCcoredns_dns_request_count_total{server, zone, proto, family}\fR - total query count.
.IP \(bu 4
\fB\fCcoredns_dns_request_duration_seconds{server, zone}\fR - duration to process each query.
.IP \(bu 4
\fB\fCcoredns_dns_request_size_bytes{server, zone, proto}\fR - size of the request in bytes.
.IP \(bu 4
\fB\fCcoredns_dns_request_do_count_total{server, zone}\fR - queries that have the DO bit set
.IP \(bu 4
\fB\fCcoredns_dns_request_type_count_total{server, zone, type}\fR - counter of queries per zone and type.
.IP \(bu 4
\fB\fCcoredns_dns_response_size_bytes{server, zone, proto}\fR - response size in bytes.
.IP \(bu 4
\fB\fCcoredns_dns_response_rcode_count_total{server, zone, rcode}\fR - response per zone and rcode.
.IP \(bu 4
\fB\fCcoredns_plugin_enabled{server, zone, name}\fR - indicates whether a plugin is enabled on per server and zone basis.
.PP
Each counter has a label \fB\fCzone\fR which is the zonename used for the request/response.
.PP
Extra labels used are:
.
.IP "\(bu" 4
\fBserver\fR is identifying the server responsible for the request\. This is a string formatted as the server\'s listening address: \fB<scheme>://[<bind>]:<port>\fR\. I\.e\. for a "normal" DNS server this is \fBdns://:53\fR\. If you are using the \fIbind\fR plugin an IP address is included, e\.g\.: \fBdns://127\.0\.0\.53:53\fR\.
.
.IP "\(bu" 4
\fBproto\fR which holds the transport of the response ("udp" or "tcp")
.
.IP "\(bu" 4
The address family (\fBfamily\fR) of the transport (1 = IP (IP version 4), 2 = IP6 (IP version 6))\.
.
.IP "\(bu" 4
\fBtype\fR which holds the query type\. It holds most common types (A, AAAA, MX, SOA, CNAME, PTR, TXT, NS, SRV, DS, DNSKEY, RRSIG, NSEC, NSEC3, IXFR, AXFR and ANY) and "other" which lumps together all other types\.
.
.IP "\(bu" 4
The \fBresponse_rcode_count_total\fR has an extra label \fBrcode\fR which holds the rcode of the response\.
.
.IP "" 0
.
.P
If monitoring is enabled, queries that do not enter the plugin chain are exported under the fake name "dropped" (without a closing dot \- this is never a valid domain name)\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "SYNTAX"
.
.nf
.IP \(bu 4
\fB\fCserver\fR is identifying the server responsible for the request. This is a string formatted
as the server's listening address: \fB\fC<scheme>://[<bind>]:<port>\fR. I.e. for a "normal" DNS server
this is \fB\fCdns://:53\fR. If you are using the \fIbind\fP plugin an IP address is included, e.g.: \fB\fCdns://127.0.0.53:53\fR.
.IP \(bu 4
\fB\fCproto\fR which holds the transport of the response ("udp" or "tcp")
.IP \(bu 4
The address family (\fB\fCfamily\fR) of the transport (1 = IP (IP version 4), 2 = IP6 (IP version 6)).
.IP \(bu 4
\fB\fCtype\fR which holds the query type. It holds most common types (A, AAAA, MX, SOA, CNAME, PTR, TXT,
NS, SRV, DS, DNSKEY, RRSIG, NSEC, NSEC3, IXFR, AXFR and ANY) and "other" which lumps together all
other types.
.IP \(bu 4
The \fB\fCresponse_rcode_count_total\fR has an extra label \fB\fCrcode\fR which holds the rcode of the response.
.PP
If monitoring is enabled, queries that do not enter the plugin chain are exported under the fake
name "dropped" (without a closing dot - this is never a valid domain name).
.PP
This plugin can only be used once per Server Block.
.SH SYNTAX
.PP
.RS
.nf
prometheus [ADDRESS]
.
.fi
.
.P
For each zone that you want to see metrics for\.
.
.P
It optionally takes a bind address to which the metrics are exported; the default listens on \fBlocalhost:9153\fR\. The metrics path is fixed to \fB/metrics\fR\.
.
.SH "EXAMPLES"
Use an alternative listening address:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
For each zone that you want to see metrics for.
.PP
It optionally takes a bind address to which the metrics are exported; the default
listens on \fB\fClocalhost:9153\fR. The metrics path is fixed to \fB\fC/metrics\fR.
.SH EXAMPLES
.PP
Use an alternative listening address:
.PP
.RS
.nf
\&. {
prometheus localhost:9253
}
.
.fi
.
.IP "" 0
.
.P
Or via an environment variable (this is supported throughout the Corefile): \fBexport PORT=9253\fR, and then:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Or via an environment variable (this is supported throughout the Corefile): \fB\fCexport PORT=9253\fR, and
then:
.PP
.RS
.nf
\&. {
prometheus localhost:{$PORT}
}
.
.fi
.
.IP "" 0
.
.SH "BUGS"
When reloading, the Prometheus handler is stopped before the new server instance is started\. If that new server fails to start, then the initial server instance is still available and DNS queries still served, but Prometheus handler stays down\. Prometheus will not reply HTTP request until a successful reload or a complete restart of CoreDNS\. Only the plugins that register as Handler are visible in \fBcoredns_plugin_enabled{server, zone, name}\fR\. As of today the plugins reload and bind will not be reported\.
.RE
.SH BUGS
.PP
When reloading, the Prometheus handler is stopped before the new server instance is started.
If that new server fails to start, then the initial server instance is still available and DNS queries still served,
but Prometheus handler stays down.
Prometheus will not reply HTTP request until a successful reload or a complete restart of CoreDNS.
Only the plugins that register as Handler are visible in \fB\fCcoredns_plugin_enabled{server, zone, name}\fR. As of today the plugins reload and bind will not be reported.

114
man/coredns-nsid.7
View file

@ -1,71 +1,79 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-NSID" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fInsid\fR \- adds an identifier of this server to each reply\.
.
.SH "DESCRIPTION"
This plugin implements RFC 5001 \fIhttps://tools\.ietf\.org/html/rfc5001\fR and adds an EDNS0 OPT resource record to replies that uniquely identify the server\. This is useful in anycast setups to see which server was responsible for generating the reply and for debugging\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-NSID" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH NSID
.SH NAME
.PP
\fInsid\fP - adds an identifier of this server to each reply.
.SH DESCRIPTION
.PP
This plugin implements RFC 5001
\[la]https://tools.ietf.org/html/rfc5001\[ra] and adds an EDNS0 OPT
resource record to replies that uniquely identify the server. This is useful in anycast setups to
see which server was responsible for generating the reply and for debugging.
.PP
This plugin can only be used once per Server Block.
.SH SYNTAX
.PP
.RS
.nf
nsid [DATA]
.
.fi
.
.P
\fBDATA\fR is the string to use in the nsid record\.
.
.P
If \fBDATA\fR is not given, the host\'s name is used\.
.
.SH "EXAMPLES"
Enable nsid:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
\fBDATA\fP is the string to use in the nsid record.
.PP
If \fBDATA\fP is not given, the host's name is used.
.SH EXAMPLES
.PP
Enable nsid:
.PP
.RS
.nf
\&. {
whoami
nsid Use The Force
}
.
.fi
.
.IP "" 0
.
.P
And now a client with NSID support will see an OPT record with the NSID option:
.
.IP "" 4
.
.nf
% dig +nsid @localhost a whoami\.example\.org
.fi
.RE
.PP
And now a client with NSID support will see an OPT record with the NSID option:
.PP
.RS
.nf
% dig +nsid @localhost a whoami.example.org
;; Got answer:
;; \->>HEADER<<\- opcode: QUERY, status: NOERROR, id: 46880
;; flags: qr aa rd; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 3
\.\.\.\.
\&....
; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
; NSID: 55 73 65 20 54 68 65 20 46 6f 72 63 65 ("Use The Force")
;; QUESTION SECTION:
;whoami\.example\.org\. IN A
.
;whoami.example.org. IN A
.fi
.
.IP "" 0
.
.SH "ALSO SEE"
RFC 5001 \fIhttps://tools\.ietf\.org/html/rfc5001\fR
.RE
.SH ALSO SEE
.PP
RFC 5001
\[la]https://tools.ietf.org/html/rfc5001\[ra]

181
man/coredns-pprof.7
View file

@ -1,103 +1,116 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-PPROF" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIpprof\fR \- publishes runtime profiling data at endpoints under \fB/debug/pprof\fR\.
.
.SH "DESCRIPTION"
You can visit \fB/debug/pprof\fR on your site for an index of the available endpoints\. By default it will listen on localhost:6053\.
.
.P
This is a debugging tool\. Certain requests (such as collecting execution traces) can be slow\. If you use pprof on a live server, consider restricting access or enabling it only temporarily\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-PPROF" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH PPROF
.SH NAME
.PP
\fIpprof\fP - publishes runtime profiling data at endpoints under \fB\fC/debug/pprof\fR.
.SH DESCRIPTION
.PP
You can visit \fB\fC/debug/pprof\fR on your site for an index of the available endpoints. By default it
will listen on localhost:6053.
.PP
This is a debugging tool. Certain requests (such as collecting execution traces) can be slow. If
you use pprof on a live server, consider restricting access or enabling it only temporarily.
.PP
This plugin can only be used once per Server Block.
.SH SYNTAX
.PP
.RS
.nf
pprof [ADDRESS]
.
.fi
.
.P
Optionally pprof takes an address; the default is \fBlocalhost:6053\fR\.
.
.P
An extra option can be set with this extended syntax:
.
.IP "" 4
.
.nf
.fi
.RE
.PP
Optionally pprof takes an address; the default is \fB\fClocalhost:6053\fR.
.PP
An extra option can be set with this extended syntax:
.PP
.RS
.nf
pprof [ADDRESS] {
block [RATE]
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBblock\fR option enables block profiling, \fBRATE\fR defaults to 1\. \fBRATE\fR must be a positive value\. See Diagnostics, chapter profiling \fIhttps://golang\.org/doc/diagnostics\.html\fR and runtime\.SetBlockProfileRate \fIhttps://golang\.org/pkg/runtime/#SetBlockProfileRate\fR for what block profiling entails\.
.
.IP "" 0
.
.SH "EXAMPLES"
Enable a pprof endpoint:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.IP \(bu 4
\fB\fCblock\fR option enables block profiling, \fBRATE\fP defaults to 1. \fBRATE\fP must be a positive value.
See Diagnostics, chapter profiling
\[la]https://golang.org/doc/diagnostics.html\[ra] and
runtime.SetBlockProfileRate
\[la]https://golang.org/pkg/runtime/#SetBlockProfileRate\[ra] for what block
profiling entails.
.SH EXAMPLES
.PP
Enable a pprof endpoint:
.PP
.RS
.nf
\&. {
pprof
}
.
.fi
.
.IP "" 0
.
.P
And use the pprof tool to get statistics: \fBgo tool pprof http://localhost:6053\fR\.
.
.P
.RE
.PP
And use the pprof tool to get statistics: \fB\fCgo tool pprof http://localhost:6053\fR.
.PP
Listen on an alternate address:
.
.IP "" 4
.
.nf
\&\. {
pprof 10\.9\.8\.7:6060
.PP
.RS
.nf
\&. {
pprof 10.9.8.7:6060
}
.
.fi
.
.IP "" 0
.
.P
Listen on an all addresses on port 6060, and enable block profiling
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Listen on an all addresses on port 6060, and enable block profiling
.PP
.RS
.nf
\&. {
pprof :6060 {
block
}
}
.
.fi
.
.IP "" 0
.
.SH "ALSO SEE"
See Go\'s pprof documentation \fIhttps://golang\.org/pkg/net/http/pprof/\fR and Profiling Go Programs \fIhttps://blog\.golang\.org/profiling\-go\-programs\fR\.
.
.P
See runtime\.SetBlockProfileRate \fIhttps://golang\.org/pkg/runtime/#SetBlockProfileRate\fR for background on block profiling\.
.RE
.SH ALSO SEE
.PP
See Go's pprof documentation
\[la]https://golang.org/pkg/net/http/pprof/\[ra] and Profiling Go
Programs
\[la]https://blog.golang.org/profiling-go-programs\[ra].
.PP
See runtime.SetBlockProfileRate
\[la]https://golang.org/pkg/runtime/#SetBlockProfileRate\[ra] for
background on block profiling.

112
man/coredns-ready.7
View file

@ -1,64 +1,76 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-READY" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIready\fR \- enables a readiness check HTTP endpoint\.
.
.SH "DESCRIPTION"
By enabling \fIready\fR an HTTP endpoint on port 8181 will return 200 OK, when all plugins that are able to signal readiness have done so\. If some are not ready yet the endpoint will return a 503 with the body containing the list of plugins that are not ready\. Once a plugin has signaled it is ready it will not be queried again\.
.
.P
Each Server Block that enables the \fIready\fR plugin will have the plugins \fIin that server block\fR report readiness into the /ready endpoint that runs on the same port\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-READY" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH READY
.SH NAME
.PP
\fIready\fP - enables a readiness check HTTP endpoint.
.SH DESCRIPTION
.PP
By enabling \fIready\fP an HTTP endpoint on port 8181 will return 200 OK, when all plugins that are able
to signal readiness have done so. If some are not ready yet the endpoint will return a 503 with the
body containing the list of plugins that are not ready. Once a plugin has signaled it is ready it
will not be queried again.
.PP
Each Server Block that enables the \fIready\fP plugin will have the plugins \fIin that server block\fP
report readiness into the /ready endpoint that runs on the same port.
.SH SYNTAX
.PP
.RS
.nf
ready [ADDRESS]
.
.fi
.
.P
\fIready\fR optionally takes an address; the default is \fB:8181\fR\. The path is fixed to \fB/ready\fR\. The readiness endpoint returns a 200 response code and the word "OK" when this server is ready\. It returns a 503 otherwise\.
.
.SH "PLUGINS"
Any plugin wanting to signal readiness will need to implement the \fBready\.Readiness\fR interface by implementing a method \fBReady() bool\fR that returns true when the plugin is ready and false otherwise\.
.
.SH "EXAMPLES"
Let \fIready\fR report readiness for both the \fB\.\fR and \fBexample\.org\fR servers (assuming the \fIwhois\fR plugin also exports readiness):
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
\fIready\fP optionally takes an address; the default is \fB\fC:8181\fR. The path is fixed to \fB\fC/ready\fR. The
readiness endpoint returns a 200 response code and the word "OK" when this server is ready. It
returns a 503 otherwise.
.SH PLUGINS
.PP
Any plugin wanting to signal readiness will need to implement the \fB\fCready.Readiness\fR interface by
implementing a method \fB\fCReady() bool\fR that returns true when the plugin is ready and false otherwise.
.SH EXAMPLES
.PP
Let \fIready\fP report readiness for both the \fB\fC.\fR and \fB\fCexample.org\fR servers (assuming the \fIwhois\fP
plugin also exports readiness):
.PP
.RS
.nf
\&. {
ready
erratic
}
example\.org {
example.org {
ready
whoami
}
.
.fi
.
.IP "" 0
.
.P
Run \fIready\fR on a different port\.
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Run \fIready\fP on a different port.
.PP
.RS
.nf
\&. {
ready localhost:8091
}
.
.fi
.
.IP "" 0
.fi
.RE

236
man/coredns-reload.7
View file

@ -1,127 +1,141 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-RELOAD" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIreload\fR \- allows automatic reload of a changed Corefile\.
.
.SH "DESCRIPTION"
This plugin allows automatic reload of a changed \fICorefile\fR\. To enable automatic reloading of \fIzone file\fR changes, use the \fBauto\fR plugin\.
.
.P
This plugin periodically checks if the Corefile has changed by reading it and calculating its MD5 checksum\. If the file has changed, it reloads CoreDNS with the new Corefile\. This eliminates the need to send a SIGHUP or SIGUSR1 after changing the Corefile\.
.
.P
The reloads are graceful \- you should not see any loss of service when the reload happens\. Even if the new Corefile has an error, CoreDNS will continue to run the old config and an error message will be printed to the log\. But see the Bugs section for failure modes\.
.
.P
In some environments (for example, Kubernetes), there may be many CoreDNS instances that started very near the same time and all share a common Corefile\. To prevent these all from reloading at the same time, some jitter is added to the reload check interval\. This is jitter from the perspective of multiple CoreDNS instances; each instance still checks on a regular interval, but all of these instances will have their reloads spread out across the jitter duration\. This isn\'t strictly necessary given that the reloads are graceful, and can be disabled by setting the jitter to \fB0s\fR\.
.
.P
Jitter is re\-calculated whenever the Corefile is reloaded\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-RELOAD" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH RELOAD
.SH NAME
.PP
\fIreload\fP - allows automatic reload of a changed Corefile.
.SH DESCRIPTION
.PP
This plugin allows automatic reload of a changed \fICorefile\fP.
To enable automatic reloading of \fIzone file\fP changes, use the \fB\fCauto\fR plugin.
.PP
This plugin periodically checks if the Corefile has changed by reading
it and calculating its MD5 checksum. If the file has changed, it reloads
CoreDNS with the new Corefile. This eliminates the need to send a SIGHUP
or SIGUSR1 after changing the Corefile.
.PP
The reloads are graceful - you should not see any loss of service when the
reload happens. Even if the new Corefile has an error, CoreDNS will continue
to run the old config and an error message will be printed to the log. But see
the Bugs section for failure modes.
.PP
In some environments (for example, Kubernetes), there may be many CoreDNS
instances that started very near the same time and all share a common
Corefile. To prevent these all from reloading at the same time, some
jitter is added to the reload check interval. This is jitter from the
perspective of multiple CoreDNS instances; each instance still checks on a
regular interval, but all of these instances will have their reloads spread
out across the jitter duration. This isn't strictly necessary given that the
reloads are graceful, and can be disabled by setting the jitter to \fB\fC0s\fR.
.PP
Jitter is re-calculated whenever the Corefile is reloaded.
.PP
This plugin can only be used once per Server Block.
.SH SYNTAX
.PP
.RS
.nf
reload [INTERVAL] [JITTER]
.
.fi
.
.IP "\(bu" 4
The plugin will check for changes every \fBINTERVAL\fR, subject to +/\- the \fBJITTER\fR duration
.
.IP "\(bu" 4
\fBINTERVAL\fR and \fBJITTER\fR are Golang (durations)[https://golang\.org/pkg/time/#ParseDuration]
.
.IP "\(bu" 4
Default \fBINTERVAL\fR is 30s, default \fBJITTER\fR is 15s
.
.IP "\(bu" 4
Minimal value for \fBINTERVAL\fR is 2s, and for \fBJITTER\fR is 1s
.
.IP "\(bu" 4
If \fBJITTER\fR is more than half of \fBINTERVAL\fR, it will be set to half of \fBINTERVAL\fR
.
.IP "" 0
.
.SH "EXAMPLES"
Check with the default intervals:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.IP \(bu 4
The plugin will check for changes every \fBINTERVAL\fP, subject to +/- the \fBJITTER\fP duration
.IP \(bu 4
\fBINTERVAL\fP and \fBJITTER\fP are Golang (durations)[https://golang.org/pkg/time/#ParseDuration
\[la]https://golang.org/pkg/time/#ParseDuration\[ra]]
.IP \(bu 4
Default \fBINTERVAL\fP is 30s, default \fBJITTER\fP is 15s
.IP \(bu 4
Minimal value for \fBINTERVAL\fP is 2s, and for \fBJITTER\fP is 1s
.IP \(bu 4
If \fBJITTER\fP is more than half of \fBINTERVAL\fP, it will be set to half of \fBINTERVAL\fP
.SH EXAMPLES
.PP
Check with the default intervals:
.PP
.RS
.nf
\&. {
reload
erratic
}
.
.fi
.
.IP "" 0
.
.P
Check every 10 seconds (jitter is automatically set to 10 / 2 = 5 in this case):
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
Check every 10 seconds (jitter is automatically set to 10 / 2 = 5 in this case):
.PP
.RS
.nf
\&. {
reload 10s
erratic
}
.
.fi
.
.IP "" 0
.
.SH "BUGS"
The reload happens without data loss (i\.e\. DNS queries keep flowing), but there is a corner case where the reload fails, and you loose functionality\. Consider the following Corefile:
.
.IP "" 4
.
.nf
\&\. {
health :8080
whoami
}
.
.fi
.
.IP "" 0
.
.P
CoreDNS starts and serves health from :8080\. Now you change \fB:8080\fR to \fB:443\fR not knowing a process is already listening on that port\. The process reloads and performs the following steps:
.
.IP "1." 4
.RE
.SH BUGS
.PP
The reload happens without data loss (i.e. DNS queries keep flowing), but there is a corner case
where the reload fails, and you loose functionality. Consider the following Corefile:
.PP
.RS
.nf
\&. {
health :8080
whoami
}
.fi
.RE
.PP
CoreDNS starts and serves health from :8080. Now you change \fB\fC:8080\fR to \fB\fC:443\fR not knowing a process
is already listening on that port. The process reloads and performs the following steps:
.IP 1\. 4
close the listener on 8080
.
.IP "2." 4
.IP 2\. 4
reload and parse the config again
.
.IP "3." 4
.IP 3\. 4
fail to start a new listener on 443
.
.IP "4." 4
.IP 4\. 4
fail loading the new Corefile, abort and keep using the old process
.
.IP "" 0
.
.P
After the aborted attempt to reload we are left with the old processes running, but the listener is closed in step 1; so the health endpoint is broken\. The same can hopen in the prometheus metrics plugin\.
.
.P
In general be careful with assigning new port and expecting reload to work fully\.
.
.P
Also any \fBimport\fR statement is not discovered by this plugin\. This means if any of these imported files changes the \fIreload\fR plugin is ignorant of that fact\.
.
.SH "ALSO SEE"
See coredns\-import(7) and corefile(5)\.
.PP
After the aborted attempt to reload we are left with the old processes running, but the listener is
closed in step 1; so the health endpoint is broken. The same can hopen in the prometheus metrics plugin.
.PP
In general be careful with assigning new port and expecting reload to work fully.
.PP
Also any \fB\fCimport\fR statement is not discovered by this plugin. This means if any of these imported files
changes the \fIreload\fP plugin is ignorant of that fact.
.SH ALSO SEE
.PP
See coredns-import(7) and corefile(5).

764
man/coredns-rewrite.7
View file

@ -1,181 +1,191 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-REWRITE" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIrewrite\fR \- performs internal message rewriting\.
.
.SH "DESCRIPTION"
Rewrites are invisible to the client\. There are simple rewrites (fast) and complex rewrites (slower), but they\'re powerful enough to accommodate most dynamic back\-end applications\.
.
.SH "SYNTAX"
A simplified/easy to digest syntax for \fIrewrite\fR is\.\.\. ~~~ rewrite [continue|stop] FIELD [FROM TO|FROM TTL] ~~~
.
.IP "\(bu" 4
\fBFIELD\fR indicates what part of the request/response is being re\-written\.
.
.IP "\(bu" 4
\fBtype\fR \- the type field of the request will be rewritten\. FROM/TO must be a DNS record type (\fBA\fR, \fBMX\fR, etc); e\.g\., to rewrite ANY queries to HINFO, use \fBrewrite type ANY HINFO\fR\.
.
.IP "\(bu" 4
\fBclass\fR \- the class of the message will be rewritten\. FROM/TO must be a DNS class type (\fBIN\fR, \fBCH\fR, or \fBHS\fR) e\.g\., to rewrite CH queries to IN use \fBrewrite class CH IN\fR\.
.
.IP "\(bu" 4
\fBname\fR \- the query name in the \fIrequest\fR is rewritten; by default this is a full match of the name, e\.g\., \fBrewrite name example\.net example\.org\fR\. Other match types are supported, see the \fBName Field Rewrites\fR section below\.
.
.IP "\(bu" 4
\fBanswer name\fR \- the query name in the \fIresponse\fR is rewritten\. This option has special restrictions and requirements, in particular it must always combined with a \fBname\fR rewrite\. See below in the \fBResponse Rewrites\fR section\.
.
.IP "\(bu" 4
\fBedns0\fR \- an EDNS0 option can be appended to the request as described below in the \fBEDNS0 Options\fR section\.
.
.IP "\(bu" 4
\fBttl\fR \- the TTL value in the \fIresponse\fR is rewritten\.
.
.IP "" 0
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-REWRITE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH REWRITE
.SH NAME
.PP
\fIrewrite\fP - performs internal message rewriting.
.SH DESCRIPTION
.PP
Rewrites are invisible to the client. There are simple rewrites (fast) and complex rewrites
(slower), but they're powerful enough to accommodate most dynamic back-end applications.
.SH SYNTAX
.PP
A simplified/easy to digest syntax for \fIrewrite\fP is...
.PP
.RS
.
.IP "\(bu" 4
\fBFROM\fR is the name (exact, suffix, prefix, substring, or regex) or type to match
.
.IP "\(bu" 4
\fBTO\fR is the destination name or type to rewrite to
.
.IP "\(bu" 4
\fBTTL\fR is the number of seconds to set the TTL value to
.
.IP "" 0
.
.P
If you specify multiple rules and an incoming query matches on multiple rules, the rewrite will behave as following * \fBcontinue\fR will continue apply the next rule in the rule list\. * \fBstop\fR will consider the current rule is the last rule and will not continue\. Default behaviour for not specifying this rule processing mode is \fBstop\fR
.
.SS "NAME FIELD REWRITES"
The \fBrewrite\fR plugin offers the ability to match on the name in the question section of a DNS request\. The match could be exact, substring, or based on a prefix, suffix, or regular expression\. If the newly used name is not a legal domain name the plugin returns an error to the client\.
.
.P
The syntax for the name re\-writing is as follows:
.
.IP "" 4
.
.nf
rewrite [continue|stop] FIELD [FROM TO|FROM TTL]
.fi
.RE
.IP \(bu 4
\fBFIELD\fP indicates what part of the request/response is being re-written.
.RS
.IP \(en 4
\fB\fCtype\fR - the type field of the request will be rewritten. FROM/TO must be a DNS record type (\fB\fCA\fR, \fB\fCMX\fR, etc);
e.g., to rewrite ANY queries to HINFO, use \fB\fCrewrite type ANY HINFO\fR.
.IP \(en 4
\fB\fCclass\fR - the class of the message will be rewritten. FROM/TO must be a DNS class type (\fB\fCIN\fR, \fB\fCCH\fR, or \fB\fCHS\fR) e.g., to rewrite CH queries to IN use \fB\fCrewrite class CH IN\fR.
.IP \(en 4
\fB\fCname\fR - the query name in the \fIrequest\fP is rewritten; by default this is a full match of the
name, e.g., \fB\fCrewrite name example.net example.org\fR. Other match types are supported, see the \fBName Field Rewrites\fP section below.
.IP \(en 4
\fB\fCanswer name\fR - the query name in the \fIresponse\fP is rewritten. This option has special restrictions and requirements, in particular it must always combined with a \fB\fCname\fR rewrite. See below in the \fBResponse Rewrites\fP section.
.IP \(en 4
\fB\fCedns0\fR - an EDNS0 option can be appended to the request as described below in the \fBEDNS0 Options\fP section.
.IP \(en 4
\fB\fCttl\fR - the TTL value in the \fIresponse\fP is rewritten.
.RE
.IP \(bu 4
\fBFROM\fP is the name (exact, suffix, prefix, substring, or regex) or type to match
.IP \(bu 4
\fBTO\fP is the destination name or type to rewrite to
.IP \(bu 4
\fBTTL\fP is the number of seconds to set the TTL value to
.PP
If you specify multiple rules and an incoming query matches on multiple rules, the rewrite
will behave as following
* \fB\fCcontinue\fR will continue apply the next rule in the rule list.
* \fB\fCstop\fR will consider the current rule is the last rule and will not continue. Default behaviour
for not specifying this rule processing mode is \fB\fCstop\fR
.SS NAME FIELD REWRITES
.PP
The \fB\fCrewrite\fR plugin offers the ability to match on the name in the question section of
a DNS request. The match could be exact, substring, or based on a prefix, suffix, or regular
expression. If the newly used name is not a legal domain name the plugin returns an error to the
client.
.PP
The syntax for the name re-writing is as follows:
.PP
.RS
.nf
rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
.
.fi
.
.IP "" 0
.
.P
The match type, i\.e\. \fBexact\fR, \fBsubstring\fR, etc\., triggers re\-write:
.
.IP "\(bu" 4
\fBexact\fR (default): on exact match of the name in the question section of a request
.
.IP "\(bu" 4
\fBsubstring\fR: on a partial match of the name in the question section of a request
.
.IP "\(bu" 4
\fBprefix\fR: when the name begins with the matching string
.
.IP "\(bu" 4
\fBsuffix\fR: when the name ends with the matching string
.
.IP "\(bu" 4
\fBregex\fR: when the name in the question section of a request matches a regular expression
.
.IP "" 0
.
.P
If the match type is omitted, the \fBexact\fR match type is being assumed\.
.
.P
The following instruction allows re\-writing the name in the query that contains \fBservice\.us\-west\-1\.example\.org\fR substring\.
.
.IP "" 4
.
.nf
rewrite name substring service\.us\-west\-1\.example\.org service\.us\-west\-1\.consul
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
The match type, i.e. \fB\fCexact\fR, \fB\fCsubstring\fR, etc., triggers re-write:
.IP \(bu 4
\fBexact\fP (default): on exact match of the name in the question section of a request
.IP \(bu 4
\fBsubstring\fP: on a partial match of the name in the question section of a request
.IP \(bu 4
\fBprefix\fP: when the name begins with the matching string
.IP \(bu 4
\fBsuffix\fP: when the name ends with the matching string
.IP \(bu 4
\fBregex\fP: when the name in the question section of a request matches a regular expression
.PP
If the match type is omitted, the \fB\fCexact\fR match type is being assumed.
.PP
The following instruction allows re-writing the name in the query that
contains \fB\fCservice.us-west-1.example.org\fR substring.
.PP
.RS
.nf
rewrite name substring service.us\-west\-1.example.org service.us\-west\-1.consul
.fi
.RE
.PP
Thus:
.
.IP "\(bu" 4
Incoming Request Name: \fBftp\.service\.us\-west\-1\.example\.org\fR
.
.IP "\(bu" 4
Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
.
.IP "" 0
.
.P
The following instruction uses regular expressions\. The name in a request matching \fB(\.*)\-(us\-west\-1)\e\.example\e\.org\fR regular expression is being replaces with \fB{1}\.service\.{2}\.consul\fR, where \fB{1}\fR and \fB{2}\fR are regular expression match groups\.
.
.IP "" 4
.
.nf
rewrite name regex (\.*)\-(us\-west\-1)\e\.example\e\.org {1}\.service\.{2}\.consul
.
.IP \(bu 4
Incoming Request Name: \fB\fCftp.service.us-west-1.example.org\fR
.IP \(bu 4
Re-written Request Name: \fB\fCftp.service.us-west-1.consul\fR
.PP
The following instruction uses regular expressions. The name in a request
matching \fB\fC(.*)-(us-west-1)\.example\.org\fR regular expression is being replaces with
\fB\fC{1}.service.{2}.consul\fR, where \fB\fC{1}\fR and \fB\fC{2}\fR are regular expression match groups.
.PP
.RS
.nf
rewrite name regex (.*)\-(us\-west\-1)\\.example\\.org {1}.service.{2}.consul
.fi
.
.IP "" 0
.
.P
.RE
.PP
Thus:
.
.IP "\(bu" 4
Incoming Request Name: \fBftp\-us\-west\-1\.example\.org\fR
.
.IP "\(bu" 4
Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
.
.IP "" 0
.
.P
The following example rewrites the \fBschmoogle\.com\fR suffix to \fBgoogle\.com\fR\.
.
.IP "" 4
.
.nf
rewrite name suffix \.schmoogle\.com\. \.google\.com\.
.
.IP \(bu 4
Incoming Request Name: \fB\fCftp-us-west-1.example.org\fR
.IP \(bu 4
Re-written Request Name: \fB\fCftp.service.us-west-1.consul\fR
.PP
The following example rewrites the \fB\fCschmoogle.com\fR suffix to \fB\fCgoogle.com\fR.
.PP
.RS
.nf
rewrite name suffix .schmoogle.com. .google.com.
.fi
.
.IP "" 0
.
.SS "RESPONSE REWRITES"
When re\-writing incoming DNS requests\' names, CoreDNS re\-writes the \fBQUESTION SECTION\fR section of the requests\. It may be necessary to re\-write the \fBANSWER SECTION\fR of the requests, because some DNS resolvers would treat the mismatch between \fBQUESTION SECTION\fR and \fBANSWER SECTION\fR as a man\-in\-the\-middle attack (MITM)\.
.
.P
For example, a user tries to resolve \fBftp\-us\-west\-1\.coredns\.rocks\fR\. The CoreDNS configuration file has the following rule:
.
.IP "" 4
.
.nf
.RE
.SS RESPONSE REWRITES
.PP
When re-writing incoming DNS requests' names, CoreDNS re-writes the \fB\fCQUESTION SECTION\fR
section of the requests. It may be necessary to re-write the \fB\fCANSWER SECTION\fR of the
requests, because some DNS resolvers would treat the mismatch between \fB\fCQUESTION SECTION\fR
and \fB\fCANSWER SECTION\fR as a man-in-the-middle attack (MITM).
.PP
For example, a user tries to resolve \fB\fCftp-us-west-1.coredns.rocks\fR. The
CoreDNS configuration file has the following rule:
.PP
.RS
.nf
rewrite name regex (.*)\-(us\-west\-1)\\.coredns\\.rocks {1}.service.{2}.consul
rewrite name regex (\.*)\-(us\-west\-1)\e\.coredns\e\.rocks {1}\.service\.{2}\.consul
.
.fi
.
.IP "" 0
.
.P
CoreDNS instance re\-wrote the request to \fBftp\-us\-west\-1\.coredns\.rocks\fR with \fBftp\.service\.us\-west\-1\.consul\fR and ultimately resolved it to 3 records\. The resolved records, see \fBANSWER SECTION\fR, were not from \fBcoredns\.rocks\fR, but rather from \fBservice\.us\-west\-1\.consul\fR\.
.
.IP "" 4
.
.RE
.PP
CoreDNS instance re-wrote the request to \fB\fCftp-us-west-1.coredns.rocks\fR with
\fB\fCftp.service.us-west-1.consul\fR and ultimately resolved it to 3 records.
The resolved records, see \fB\fCANSWER SECTION\fR, were not from \fB\fCcoredns.rocks\fR, but
rather from \fB\fCservice.us-west-1.consul\fR.
.PP
.RS
.nf
$ dig @10.1.1.1 ftp\-us\-west\-1.coredns.rocks
$ dig @10\.1\.1\.1 ftp\-us\-west\-1\.coredns\.rocks
; <<>> DiG 9\.8\.3\-P1 <<>> @10\.1\.1\.1 ftp\-us\-west\-1\.coredns\.rocks
; <<>> DiG 9.8.3\-P1 <<>> @10.1.1.1 ftp\-us\-west\-1.coredns.rocks
; (1 server found)
;; global options: +cmd
;; Got answer:
@ -183,46 +193,45 @@ $ dig @10\.1\.1\.1 ftp\-us\-west\-1\.coredns\.rocks
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;ftp\-us\-west\-1\.coredns\.rocks\. IN A
;ftp\-us\-west\-1.coredns.rocks. IN A
;; ANSWER SECTION:
ftp\.service\.us\-west\-1\.consul\. 0 IN A 10\.10\.10\.10
ftp\.service\.us\-west\-1\.consul\. 0 IN A 10\.20\.20\.20
ftp\.service\.us\-west\-1\.consul\. 0 IN A 10\.30\.30\.30
.
.fi
.
.IP "" 0
.
.P
The above is the mismatch\.
.
.P
The following configuration snippet allows for the re\-writing of the \fBANSWER SECTION\fR, provided that the \fBQUESTION SECTION\fR was re\-written:
.
.IP "" 4
.
.nf
ftp.service.us\-west\-1.consul. 0 IN A 10.10.10.10
ftp.service.us\-west\-1.consul. 0 IN A 10.20.20.20
ftp.service.us\-west\-1.consul. 0 IN A 10.30.30.30
.fi
.RE
.PP
The above is the mismatch.
.PP
The following configuration snippet allows for the re-writing of the
\fB\fCANSWER SECTION\fR, provided that the \fB\fCQUESTION SECTION\fR was re-written:
.PP
.RS
.nf
rewrite stop {
name regex (\.*)\-(us\-west\-1)\e\.coredns\e\.rocks {1}\.service\.{2}\.consul
answer name (\.*)\e\.service\e\.(us\-west\-1)\e\.consul {1}\-{2}\.coredns\.rocks
name regex (.*)\-(us\-west\-1)\\.coredns\\.rocks {1}.service.{2}.consul
answer name (.*)\\.service\\.(us\-west\-1)\\.consul {1}\-{2}.coredns.rocks
}
.
.fi
.
.IP "" 0
.
.P
Now, the \fBANSWER SECTION\fR matches the \fBQUESTION SECTION\fR:
.
.IP "" 4
.
.RE
.PP
Now, the \fB\fCANSWER SECTION\fR matches the \fB\fCQUESTION SECTION\fR:
.PP
.RS
.nf
$ dig @10.1.1.1 ftp\-us\-west\-1.coredns.rocks
$ dig @10\.1\.1\.1 ftp\-us\-west\-1\.coredns\.rocks
; <<>> DiG 9\.8\.3\-P1 <<>> @10\.1\.1\.1 ftp\-us\-west\-1\.coredns\.rocks
; <<>> DiG 9.8.3\-P1 <<>> @10.1.1.1 ftp\-us\-west\-1.coredns.rocks
; (1 server found)
;; global options: +cmd
;; Got answer:
@ -230,213 +239,230 @@ $ dig @10\.1\.1\.1 ftp\-us\-west\-1\.coredns\.rocks
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;ftp\-us\-west\-1\.coredns\.rocks\. IN A
;ftp\-us\-west\-1.coredns.rocks. IN A
;; ANSWER SECTION:
ftp\-us\-west\-1\.coredns\.rocks\. 0 IN A 10\.10\.10\.10
ftp\-us\-west\-1\.coredns\.rocks\. 0 IN A 10\.20\.20\.20
ftp\-us\-west\-1\.coredns\.rocks\. 0 IN A 10\.30\.30\.30
.
.fi
.
.IP "" 0
.
.P
The syntax for the rewrite of DNS request and response is as follows:
.
.IP "" 4
.
.nf
ftp\-us\-west\-1.coredns.rocks. 0 IN A 10.10.10.10
ftp\-us\-west\-1.coredns.rocks. 0 IN A 10.20.20.20
ftp\-us\-west\-1.coredns.rocks. 0 IN A 10.30.30.30
.fi
.RE
.PP
The syntax for the rewrite of DNS request and response is as follows:
.PP
.RS
.nf
rewrite [continue|stop] {
name regex STRING STRING
answer name STRING STRING
}
.
.fi
.
.IP "" 0
.
.P
Note that the above syntax is strict\. For response rewrites only \fBname\fR rules are allowed to match the question section, and only by match type \fBregex\fR\. The answer rewrite must be after the name, as ordered in the syntax example\. There must only be two lines (a \fBname\fR followed by an \fBanswer\fR) in the brackets, additional rules are not supported\.
.
.P
An alternate syntax for the rewrite of DNS request and response is as follows:
.
.IP "" 4
.
.nf
.fi
.RE
.PP
Note that the above syntax is strict. For response rewrites only \fB\fCname\fR
rules are allowed to match the question section, and only by match type
\fB\fCregex\fR. The answer rewrite must be after the name, as ordered in the
syntax example. There must only be two lines (a \fB\fCname\fR followed by an
\fB\fCanswer\fR) in the brackets, additional rules are not supported.
.PP
An alternate syntax for the rewrite of DNS request and response is as
follows:
.PP
.RS
.nf
rewrite [continue|stop] name regex STRING STRING answer name STRING STRING
.
.fi
.
.IP "" 0
.
.P
When using \fBexact\fR name rewrite rules, answer gets re\-written automatically, and there is no need defining \fBanswer name\fR instruction\. The below rule rewrites the name in a request from \fBRED\fR to \fBBLUE\fR, and subsequently rewrites the name in a corresponding response from \fBBLUE\fR to \fBRED\fR\. The client in the request would see only \fBRED\fR and no \fBBLUE\fR\.
.
.IP "" 4
.
.nf
.fi
.RE
.PP
When using \fB\fCexact\fR name rewrite rules, answer gets re-written automatically,
and there is no need defining \fB\fCanswer name\fR instruction. The below rule
rewrites the name in a request from \fB\fCRED\fR to \fB\fCBLUE\fR, and subsequently
rewrites the name in a corresponding response from \fB\fCBLUE\fR to \fB\fCRED\fR. The
client in the request would see only \fB\fCRED\fR and no \fB\fCBLUE\fR.
.PP
.RS
.nf
rewrite [continue|stop] name exact RED BLUE
.
.fi
.
.IP "" 0
.
.SS "TTL FIELD REWRITES"
At times, the need for rewriting TTL value could arise\. For example, a DNS server may prevent caching by setting TTL as low as zero (\fB0\fR)\. An administrator may want to increase the TTL to prevent caching, e\.g\. to 15 seconds\.
.
.P
In the below example, the TTL in the answers for \fBcoredns\.rocks\fR domain are being set to \fB15\fR:
.
.IP "" 4
.
.nf
.fi
.RE
.SS TTL FIELD REWRITES
.PP
At times, the need for rewriting TTL value could arise. For example, a DNS server
may prevent caching by setting TTL as low as zero (\fB\fC0\fR). An administrator
may want to increase the TTL to prevent caching, e.g. to 15 seconds.
.PP
In the below example, the TTL in the answers for \fB\fCcoredns.rocks\fR domain are
being set to \fB\fC15\fR:
.PP
.RS
.nf
rewrite continue {
ttl regex (\.*)\e\.coredns\e\.rocks 15
ttl regex (.*)\\.coredns\\.rocks 15
}
.
.fi
.
.IP "" 0
.
.P
By the same token, an administrator may use this feature to force caching by setting TTL value really low\.
.
.P
The syntax for the TTL rewrite rule is as follows\. The meaning of \fBexact|prefix|suffix|substring|regex\fR is the same as with the name rewrite rules\.
.
.IP "" 4
.
.nf
.fi
.RE
.PP
By the same token, an administrator may use this feature to force caching by
setting TTL value really low.
.PP
The syntax for the TTL rewrite rule is as follows. The meaning of
\fB\fCexact|prefix|suffix|substring|regex\fR is the same as with the name rewrite rules.
.PP
.RS
.nf
rewrite [continue|stop] ttl [exact|prefix|suffix|substring|regex] STRING SECONDS
.
.fi
.
.IP "" 0
.
.SH "EDNS0 OPTIONS"
Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request\.
.
.IP "\(bu" 4
\fBreplace\fR will modify any "matching" option with the specified option\. The criteria for "matching" varies based on EDNS0 type\.
.
.IP "\(bu" 4
\fBappend\fR will add the option only if no matching option exists
.
.IP "\(bu" 4
\fBset\fR will modify a matching option or add one if none is found
.
.IP "" 0
.
.P
Currently supported are \fBEDNS0_LOCAL\fR, \fBEDNS0_NSID\fR and \fBEDNS0_SUBNET\fR\.
.
.SS "EDNS0_LOCAL"
This has two fields, code and data\. A match is defined as having the same code\. Data may be a string or a variable\.
.
.TP
A string data can be treated as hex if it starts with \fB0x\fR\. Example:
.RE
.SH EDNS0 OPTIONS
.PP
Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request.
.IP \(bu 4
\fB\fCreplace\fR will modify any "matching" option with the specified option. The criteria for "matching" varies based on EDNS0 type.
.IP \(bu 4
\fB\fCappend\fR will add the option only if no matching option exists
.IP \(bu 4
\fB\fCset\fR will modify a matching option or add one if none is found
.PP
Currently supported are \fB\fCEDNS0_LOCAL\fR, \fB\fCEDNS0_NSID\fR and \fB\fCEDNS0_SUBNET\fR.
.SS EDNS0_LOCAL
.PP
This has two fields, code and data. A match is defined as having the same code. Data may be a string or a variable.
.IP \(bu 4
A string data can be treated as hex if it starts with \fB\fC0x\fR. Example:
.PP
.RS
.
.IP "" 4
.
.nf
\&\. {
\&. {
rewrite edns0 local set 0xffee 0x61626364
whoami
}
.
.fi
.
.IP "" 0
.
.P
rewrites the first local option with code 0xffee, setting the data to "abcd"\. Equivalent:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
rewrites the first local option with code 0xffee, setting the data to "abcd". Equivalent:
.PP
.RS
.nf
\&. {
rewrite edns0 local set 0xffee abcd
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
A variable data is specified with a pair of curly brackets \fB{}\fR\. Following are the supported variables: {qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}\.
.
.IP "\(bu" 4
If the metadata plugin is enabled, then labels are supported as variables if they are presented within curly brackets\. the variable data will be filled with the value associated with that label\. If that label is not provided, the variable will be silently substitute by an empty string\.
.
.IP "" 0
.
.P
.RE
.IP \(bu 4
A variable data is specified with a pair of curly brackets \fB\fC{}\fR. Following are the supported variables:
{qname}, {qtype}, {client\fIip}, {client\fPport}, {protocol}, {server\fIip}, {server\fPport}.
.IP \(bu 4
If the metadata plugin is enabled, then labels are supported as variables if they are presented within curly brackets.
the variable data will be filled with the value associated with that label. If that label is not provided,
the variable will be silently substitute by an empty string.
.PP
Examples:
.
.IP "" 4
.
.nf
rewrite edns0 local set 0xffee {client_ip}
.
.PP
.RS
.nf
rewrite edns0 local set 0xffee {client\_ip}
.fi
.
.IP "" 0
.
.P
The following example uses metadata and an imaginary "some\-plugin" that would provide "some\-label" as metadata information\.
.
.IP "" 4
.
.nf
.RE
.PP
The following example uses metadata and an imaginary "some-plugin" that would provide "some-label" as metadata information.
.PP
.RS
.nf
metadata
some\-plugin
rewrite edns0 local set 0xffee {some\-plugin/some\-label}
.
.fi
.
.IP "" 0
.
.SS "EDNS0_NSID"
This has no fields; it will add an NSID option with an empty string for the NSID\. If the option already exists and the action is \fBreplace\fR or \fBset\fR, then the NSID in the option will be set to the empty string\.
.
.SS "EDNS0_SUBNET"
This has two fields, IPv4 bitmask length and IPv6 bitmask length\. The bitmask length is used to extract the client subnet from the source IP address in the query\.
.
.P
Example:
.
.IP "" 4
.
.nf
rewrite edns0 subnet set 24 56
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet\.
.
.IP "\(bu" 4
If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet\.
.
.IP "" 0
.
.SH "FULL SYNTAX"
The full plugin usage syntax is harder to digest\.\.\. ~~~ rewrite [continue|stop] {type|class|edns0|name [exact|prefix|suffix|substring|regex [FROM TO answer name]]} FROM TO ~~~
.
.P
The syntax above doesn\'t cover the multi line block option for specifying a name request+response rewrite rule described in the \fBResponse Rewrite\fR section\.
.RE
.SS EDNS0_NSID
.PP
This has no fields; it will add an NSID option with an empty string for the NSID. If the option already exists
and the action is \fB\fCreplace\fR or \fB\fCset\fR, then the NSID in the option will be set to the empty string.
.SS EDNS0_SUBNET
.PP
This has two fields, IPv4 bitmask length and IPv6 bitmask length. The bitmask
length is used to extract the client subnet from the source IP address in the query.
.PP
Example:
.PP
.RS
.nf
rewrite edns0 subnet set 24 56
.fi
.RE
.IP \(bu 4
If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet.
.IP \(bu 4
If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet.
.SH FULL SYNTAX
.PP
The full plugin usage syntax is harder to digest...
.PP
.RS
.nf
rewrite [continue|stop] {type|class|edns0|name [exact|prefix|suffix|substring|regex [FROM TO answer name]]} FROM TO
.fi
.RE
.PP
The syntax above doesn't cover the multi line block option for specifying a name request+response rewrite rule described in the \fBResponse Rewrite\fP section.

72
man/coredns-root.7
View file

@ -1,40 +1,44 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ROOT" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIroot\fR \- simply specifies the root of where to find (zone) files\.
.
.SH "DESCRIPTION"
The default root is the current working directory of CoreDNS\. The \fIroot\fR plugin allows you to change this\. A relative root path is relative to the current working directory\.
.
.P
This plugin can only be used once per Server Block\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-ROOT" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH ROOT
.SH NAME
.PP
\fIroot\fP - simply specifies the root of where to find (zone) files.
.SH DESCRIPTION
.PP
The default root is the current working directory of CoreDNS. The \fIroot\fP plugin allows you to change
this. A relative root path is relative to the current working directory.
.PP
This plugin can only be used once per Server Block.
.SH SYNTAX
.PP
.RS
.nf
root PATH
.
.fi
.
.P
\fBPATH\fR is the directory to set as CoreDNS\' root\.
.
.SH "EXAMPLES"
Serve zone data (when the \fIfile\fR plugin is used) from \fB/etc/coredns/zones\fR:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
\fBPATH\fP is the directory to set as CoreDNS' root.
.SH EXAMPLES
.PP
Serve zone data (when the \fIfile\fP plugin is used) from \fB\fC/etc/coredns/zones\fR:
.PP
.RS
.nf
\&. {
root /etc/coredns/zones
}
.
.fi
.
.IP "" 0
.fi
.RE

198
man/coredns-route53.7
View file

@ -1,119 +1,125 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ROUTE53" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIroute53\fR \- enables serving zone data from AWS route53\.
.
.SH "DESCRIPTION"
The route53 plugin is useful for serving zones from resource record sets in AWS route53\. This plugin supports all Amazon Route 53 records (\fIhttps://docs\.aws\.amazon\.com/Route53/latest/DeveloperGuide/ResourceRecordTypes\.html\fR)\. The route53 plugin can be used when coredns is deployed on AWS or elsewhere\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-ROUTE53" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
route53 [ZONE:HOSTED_ZONE_ID\.\.\.] {
[aws_access_key AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY]
.SH ROUTE53
.SH NAME
.PP
\fIroute53\fP - enables serving zone data from AWS route53.
.SH DESCRIPTION
.PP
The route53 plugin is useful for serving zones from resource record
sets in AWS route53. This plugin supports all Amazon Route 53 records
(https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ResourceRecordTypes.html
\[la]https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ResourceRecordTypes.html\[ra]).
The route53 plugin can be used when coredns is deployed on AWS or elsewhere.
.SH SYNTAX
.PP
.RS
.nf
route53 [ZONE:HOSTED\_ZONE\_ID...] {
[aws\_access\_key AWS\_ACCESS\_KEY\_ID AWS\_SECRET\_ACCESS\_KEY]
upstream
credentials PROFILE [FILENAME]
fallthrough [ZONES\.\.\.]
fallthrough [ZONES...]
}
.
.fi
.
.IP "\(bu" 4
\fBZONE\fR the name of the domain to be accessed\. When there are multiple zones with overlapping domains (private vs\. public hosted zone), CoreDNS does the lookup in the given order here\. Therefore, for a non\-existing resource record, SOA response will be from the rightmost zone\.
.
.IP "\(bu" 4
\fBHOSTED\fIZONE\fRID\fR the ID of the hosted zone that contains the resource record sets to be accessed\.
.
.IP "\(bu" 4
\fBAWS\fIACCESS\fRKEY_ID\fR and \fBAWS\fISECRET\fRACCESS_KEY\fR the AWS access key ID and secret access key to be used when query AWS (optional)\. If they are not provided, then coredns tries to access AWS credentials the same way as AWS CLI, e\.g\., environmental variables, AWS credentials file, instance profile credentials, etc\.
.
.IP "\(bu" 4
\fBupstream\fRis used for resolving services that point to external hosts (eg\. used to resolve CNAMEs)\. CoreDNS will resolve against itself\.
.
.IP "\(bu" 4
\fBcredentials\fR is used for reading the credential file and setting the profile name for a given zone\.
.
.IP "\(bu" 4
\fBPROFILE\fR AWS account profile name\. Defaults to \fBdefault\fR\.
.
.IP "\(bu" 4
\fBFILENAME\fR AWS credentials filename\. Defaults to \fB~/\.aws/credentials\fR are used\.
.
.IP "\(bu" 4
\fBfallthrough\fR If zone matches and no record can be generated, pass request to the next plugin\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.IP "\(bu" 4
\fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block
.
.IP "" 0
.
.SH "EXAMPLES"
.RE
.IP \(bu 4
\fBZONE\fP the name of the domain to be accessed. When there are multiple zones with overlapping
domains (private vs. public hosted zone), CoreDNS does the lookup in the given order here.
Therefore, for a non-existing resource record, SOA response will be from the rightmost zone.
.IP \(bu 4
\fBHOSTED\fIZONE\fPID\fP the ID of the hosted zone that contains the resource record sets to be
accessed.
.IP \(bu 4
\fBAWS\fIACCESS\fPKEY_ID\fP and \fBAWS\fISECRET\fPACCESS_KEY\fP the AWS access key ID and secret access key
to be used when query AWS (optional). If they are not provided, then coredns tries to access
AWS credentials the same way as AWS CLI, e.g., environmental variables, AWS credentials file,
instance profile credentials, etc.
.IP \(bu 4
\fB\fCupstream\fRis used for resolving services that point to external hosts (eg. used to resolve
CNAMEs). CoreDNS will resolve against itself.
.IP \(bu 4
\fB\fCcredentials\fR is used for reading the credential file and setting the profile name for a given
zone.
.IP \(bu 4
\fBPROFILE\fP AWS account profile name. Defaults to \fB\fCdefault\fR.
.IP \(bu 4
\fBFILENAME\fP AWS credentials filename. Defaults to \fB\fC~/.aws/credentials\fR are used.
.IP \(bu 4
\fB\fCfallthrough\fR If zone matches and no record can be generated, pass request to the next plugin.
If \fB[ZONES...]\fP is omitted, then fallthrough happens for all zones for which the plugin is
authoritative. If specific zones are listed (for example \fB\fCin-addr.arpa\fR and \fB\fCip6.arpa\fR), then
only queries for those zones will be subject to fallthrough.
.IP \(bu 4
\fBZONES\fP zones it should be authoritative for. If empty, the zones from the configuration block
.SH EXAMPLES
.PP
Enable route53 with implicit AWS credentials and an upstream:
.
.IP "" 4
.
.nf
\&\. {
route53 example\.org\.:Z1Z2Z3Z4DZ5Z6Z7 {
upstream 10\.0\.0\.1
}
.PP
.RS
.nf
\&. {
route53 example.org.:Z1Z2Z3Z4DZ5Z6Z7 {
upstream 10.0.0.1
}
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Enable route53 with explicit AWS credentials:
.
.IP "" 4
.
.nf
\&\. {
route53 example\.org\.:Z1Z2Z3Z4DZ5Z6Z7 {
aws_access_key AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY
.PP
.RS
.nf
\&. {
route53 example.org.:Z1Z2Z3Z4DZ5Z6Z7 {
aws\_access\_key AWS\_ACCESS\_KEY\_ID AWS\_SECRET\_ACCESS\_KEY
}
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Enable route53 with fallthrough:
.
.IP "" 4
.
.nf
\&\. {
route53 example\.org\.:Z1Z2Z3Z4DZ5Z6Z7 example\.gov\.:Z654321543245 {
fallthrough example\.gov\.
.PP
.RS
.nf
\&. {
route53 example.org.:Z1Z2Z3Z4DZ5Z6Z7 example.gov.:Z654321543245 {
fallthrough example.gov.
}
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Enable route53 with multiple hosted zones with the same domain:
.
.IP "" 4
.
.PP
.RS
.nf
\&\. {
route53 example\.org\.:Z1Z2Z3Z4DZ5Z6Z7 example\.org\.:Z93A52145678156
\&. {
route53 example.org.:Z1Z2Z3Z4DZ5Z6Z7 example.org.:Z93A52145678156
}
.
.fi
.
.IP "" 0
.fi
.RE

162
man/coredns-secondary.7
View file

@ -1,95 +1,99 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-SECONDARY" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIsecondary\fR \- enables serving a zone retrieved from a primary server\.
.
.SH "DESCRIPTION"
With \fIsecondary\fR you can transfer (via AXFR) a zone from another server\. The retrieved zone is \fInot committed\fR to disk (a violation of the RFC)\. This means restarting CoreDNS will cause it to retrieve all secondary zones\.
.
.IP "" 4
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-SECONDARY" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH SECONDARY
.SH NAME
.PP
\fIsecondary\fP - enables serving a zone retrieved from a primary server.
.SH DESCRIPTION
.PP
With \fIsecondary\fP you can transfer (via AXFR) a zone from another server. The retrieved zone is
\fInot committed\fP to disk (a violation of the RFC). This means restarting CoreDNS will cause it to
retrieve all secondary zones.
.PP
.RS
.nf
secondary [ZONES...]
secondary [ZONES\.\.\.]
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block are used\. Note that without a remote address to \fIget\fR the zone from, the above is not that useful\.
.
.IP "" 0
.
.P
A working syntax would be:
.
.IP "" 4
.
.nf
.RE
secondary [zones\.\.\.] {
.IP \(bu 4
\fBZONES\fP zones it should be authoritative for. If empty, the zones from the configuration block
are used. Note that without a remote address to \fIget\fP the zone from, the above is not that useful.
.PP
A working syntax would be:
.PP
.RS
.nf
secondary [zones...] {
transfer from ADDRESS
transfer to ADDRESS
upstream
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBtransfer from\fR specifies from which address to fetch the zone\. It can be specified multiple times; if one does not work, another will be tried\.
.
.IP "\(bu" 4
\fBtransfer to\fR can be enabled to allow this secondary zone to be transferred again\.
.
.IP "\(bu" 4
\fBupstream\fR resolve external names found (think CNAMEs) pointing to external names\. This is only really useful when CoreDNS is configured as a proxy; for normal authoritative serving you don\'t need \fIor\fR want to use this\. CoreDNS will resolve CNAMEs against itself\.
.
.IP "" 0
.
.P
When a zone is due to be refreshed (Refresh timer fires) a random jitter of 5 seconds is applied, before fetching\. In the case of retry this will be 2 seconds\. If there are any errors during the transfer the transfer fails; this will be logged\.
.
.SH "EXAMPLES"
Transfer \fBexample\.org\fR from 10\.0\.1\.1, and if that fails try 10\.1\.2\.1\.
.
.IP "" 4
.
.nf
example\.org {
.fi
.RE
.IP \(bu 4
\fB\fCtransfer from\fR specifies from which address to fetch the zone. It can be specified multiple times;
if one does not work, another will be tried.
.IP \(bu 4
\fB\fCtransfer to\fR can be enabled to allow this secondary zone to be transferred again.
.IP \(bu 4
\fB\fCupstream\fR resolve external names found (think CNAMEs) pointing to external names. This is only
really useful when CoreDNS is configured as a proxy; for normal authoritative serving you don't
need \fIor\fP want to use this. CoreDNS will resolve CNAMEs against itself.
.PP
When a zone is due to be refreshed (Refresh timer fires) a random jitter of 5 seconds is
applied, before fetching. In the case of retry this will be 2 seconds. If there are any errors
during the transfer the transfer fails; this will be logged.
.SH EXAMPLES
.PP
Transfer \fB\fCexample.org\fR from 10.0.1.1, and if that fails try 10.1.2.1.
.PP
.RS
.nf
example.org {
secondary {
transfer from 10\.0\.1\.1
transfer from 10\.1\.2\.1
transfer from 10.0.1.1
transfer from 10.1.2.1
}
}
.
.fi
.
.IP "" 0
.
.P
Or re\-export the retrieved zone to other secondaries\.
.
.IP "" 4
.
.nf
\&\. {
secondary example\.net {
transfer from 10\.1\.2\.1
.fi
.RE
.PP
Or re-export the retrieved zone to other secondaries.
.PP
.RS
.nf
\&. {
secondary example.net {
transfer from 10.1.2.1
transfer to *
}
}
.
.fi
.
.IP "" 0
.
.SH "BUGS"
Only AXFR is supported and the retrieved zone is not committed to disk\.
.RE
.SH BUGS
.PP
Only AXFR is supported and the retrieved zone is not committed to disk.

567
man/coredns-template.7
View file

@ -1,347 +1,358 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-TEMPLATE" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fItemplate\fR \- allows for dynamic responses based on the incoming query\.
.
.SH "DESCRIPTION"
The \fItemplate\fR plugin allows you to dynamically respond to queries by just writing a (Go) template\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-TEMPLATE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
template CLASS TYPE [ZONE\.\.\.] {
match REGEX\.\.\.
.SH TEMPLATE
.SH NAME
.PP
\fItemplate\fP - allows for dynamic responses based on the incoming query.
.SH DESCRIPTION
.PP
The \fItemplate\fP plugin allows you to dynamically respond to queries by just writing a (Go) template.
.SH SYNTAX
.PP
.RS
.nf
template CLASS TYPE [ZONE...] {
match REGEX...
answer RR
additional RR
authority RR
rcode CODE
upstream
fallthrough [ZONE\.\.\.]
fallthrough [ZONE...]
}
.
.fi
.
.IP "\(bu" 4
\fBCLASS\fR the query class (usually IN or ANY)\.
.
.IP "\(bu" 4
\fBTYPE\fR the query type (A, PTR, \.\.\. can be ANY to match all types)\.
.
.IP "\(bu" 4
\fBZONE\fR the zone scope(s) for this template\. Defaults to the server zones\.
.
.IP "\(bu" 4
\fBREGEX\fR Go regexp \fIhttps://golang\.org/pkg/regexp/\fR that are matched against the incoming question name\. Specifying no regex matches everything (default: \fB\.*\fR)\. First matching regex wins\.
.
.IP "\(bu" 4
\fBanswer|additional|authority\fR \fBRR\fR A RFC 1035 \fIhttps://tools\.ietf\.org/html/rfc1035#section\-5\fR style resource record fragment built by a Go template \fIhttps://golang\.org/pkg/text/template/\fR that contains the reply\.
.
.IP "\(bu" 4
\fBrcode\fR \fBCODE\fR A response code (\fBNXDOMAIN, SERVFAIL, \.\.\.\fR)\. The default is \fBSUCCESS\fR\.
.
.IP "\(bu" 4
\fBupstream\fR defines the upstream resolvers used for resolving CNAMEs\. CoreDNS will resolve CNAMEs against itself\.
.
.IP "\(bu" 4
\fBfallthrough\fR Continue with the next plugin if the zone matched but no regex matched\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.IP "" 0
.
.P
At least one \fBanswer\fR or \fBrcode\fR directive is needed (e\.g\. \fBrcode NXDOMAIN\fR)\.
.
.P
\fIAlso see\fR contains an additional reading list\.
.
.SH "TEMPLATES"
Each resource record is a full\-featured Go template \fIhttps://golang\.org/pkg/text/template/\fR with the following predefined data
.
.IP "\(bu" 4
\fB\.Zone\fR the matched zone string (e\.g\. \fBexample\.\fR)\.
.
.IP "\(bu" 4
\fB\.Name\fR the query name, as a string (lowercased)\.
.
.IP "\(bu" 4
\fB\.Class\fR the query class (usually \fBIN\fR)\.
.
.IP "\(bu" 4
\fB\.Type\fR the RR type requested (e\.g\. \fBPTR\fR)\.
.
.IP "\(bu" 4
\fB\.Match\fR an array of all matches\. \fBindex \.Match 0\fR refers to the whole match\.
.
.IP "\(bu" 4
\fB\.Group\fR a map of the named capture groups\.
.
.IP "\(bu" 4
\fB\.Message\fR the complete incoming DNS message\.
.
.IP "\(bu" 4
\fB\.Question\fR the matched question section\.
.
.IP "" 0
.
.P
The output of the template must be a RFC 1035 \fIhttps://tools\.ietf\.org/html/rfc1035\fR style resource record (commonly referred to as a "zone file")\.
.
.P
\fBWARNING\fR there is a syntactical problem with Go templates and CoreDNS config files\. Expressions like \fB{{$var}}\fR will be interpreted as a reference to an environment variable by CoreDNS (and Caddy) while \fB{{ $var }}\fR will work\. See \fIBugs\fR and corefile(5)\.
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
.
.IP "\(bu" 4
\fBcoredns_template_matches_total{server, regex}\fR the total number of matched requests by regex\.
.
.IP "\(bu" 4
\fBcoredns_template_template_failures_total{server, regex,section,template}\fR the number of times the Go templating failed\. Regex, section and template label values can be used to map the error back to the config file\.
.
.IP "\(bu" 4
\fBcoredns_template_rr_failures_total{server, regex,section,template}\fR the number of times the templated resource record was invalid and could not be parsed\. Regex, section and template label values can be used to map the error back to the config file\.
.
.IP "" 0
.
.P
Both failure cases indicate a problem with the template configuration\. The \fBserver\fR label indicates the server incrementing the metric, see the \fImetrics\fR plugin for details\.
.
.SH "EXAMPLES"
.
.SS "RESOLVE EVERYTHING TO NXDOMAIN"
The most simplistic template is
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.IP \(bu 4
\fBCLASS\fP the query class (usually IN or ANY).
.IP \(bu 4
\fBTYPE\fP the query type (A, PTR, ... can be ANY to match all types).
.IP \(bu 4
\fBZONE\fP the zone scope(s) for this template. Defaults to the server zones.
.IP \(bu 4
\fBREGEX\fP Go regexp
\[la]https://golang.org/pkg/regexp/\[ra] that are matched against the incoming question name. Specifying no regex matches everything (default: \fB\fC.*\fR). First matching regex wins.
.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
built by a Go template
\[la]https://golang.org/pkg/text/template/\[ra] that contains the reply.
.IP \(bu 4
\fB\fCrcode\fR \fBCODE\fP A response code (\fB\fCNXDOMAIN, SERVFAIL, ...\fR). The default is \fB\fCSUCCESS\fR.
.IP \(bu 4
\fB\fCupstream\fR defines the upstream resolvers used for resolving CNAMEs. CoreDNS will resolve CNAMEs against itself.
.IP \(bu 4
\fB\fCfallthrough\fR Continue with the next plugin if the zone matched but no regex matched.
If specific zones are listed (for example \fB\fCin-addr.arpa\fR and \fB\fCip6.arpa\fR), then only queries for
those zones will be subject to fallthrough.
.PP
At least one \fB\fCanswer\fR or \fB\fCrcode\fR directive is needed (e.g. \fB\fCrcode NXDOMAIN\fR).
.PP
Also see
\[la]#also-see\[ra] contains an additional reading list.
.SH TEMPLATES
.PP
Each resource record is a full-featured Go template
\[la]https://golang.org/pkg/text/template/\[ra] with the following predefined data
.IP \(bu 4
\fB\fC.Zone\fR the matched zone string (e.g. \fB\fCexample.\fR).
.IP \(bu 4
\fB\fC.Name\fR the query name, as a string (lowercased).
.IP \(bu 4
\fB\fC.Class\fR the query class (usually \fB\fCIN\fR).
.IP \(bu 4
\fB\fC.Type\fR the RR type requested (e.g. \fB\fCPTR\fR).
.IP \(bu 4
\fB\fC.Match\fR an array of all matches. \fB\fCindex .Match 0\fR refers to the whole match.
.IP \(bu 4
\fB\fC.Group\fR a map of the named capture groups.
.IP \(bu 4
\fB\fC.Message\fR the complete incoming DNS message.
.IP \(bu 4
\fB\fC.Question\fR the matched question section.
.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").
.PP
\fBWARNING\fP there is a syntactical problem with Go templates and CoreDNS config files. Expressions
like \fB\fC{{$var}}\fR will be interpreted as a reference to an environment variable by CoreDNS (and
Caddy) while \fB\fC{{ $var }}\fR will work. See Bugs
\[la]#bugs\[ra] and corefile(5).
.SH METRICS
.PP
If monitoring is enabled (via the \fIprometheus\fP directive) then the following metrics are exported:
.IP \(bu 4
\fB\fCcoredns_template_matches_total{server, regex}\fR the total number of matched requests by regex.
.IP \(bu 4
\fB\fCcoredns_template_template_failures_total{server, regex,section,template}\fR the number of times the Go templating failed. Regex, section and template label values can be used to map the error back to the config file.
.IP \(bu 4
\fB\fCcoredns_template_rr_failures_total{server, regex,section,template}\fR the number of times the templated resource record was invalid and could not be parsed. Regex, section and template label values can be used to map the error back to the config file.
.PP
Both failure cases indicate a problem with the template configuration. The \fB\fCserver\fR label indicates
the server incrementing the metric, see the \fImetrics\fP plugin for details.
.SH EXAMPLES
.SS RESOLVE EVERYTHING TO NXDOMAIN
.PP
The most simplistic template is
.PP
.RS
.nf
\&. {
template ANY ANY {
rcode NXDOMAIN
}
}
.
.fi
.
.IP "" 0
.
.IP "1." 4
This template uses the default zone (\fB\.\fR or all queries)
.
.IP "2." 4
All queries will be answered (no \fBfallthrough\fR)
.
.IP "3." 4
The answer is always NXDOMAIN
.
.IP "" 0
.
.SS "RESOLVE \.INVALID AS NXDOMAIN"
The \fB\.invalid\fR domain is a reserved TLD (see RFC 2606 Reserved Top Level DNS Names \fIhttps://tools\.ietf\.org/html/rfc2606#section\-2\fR) to indicate invalid domains\.
.
.IP "" 4
.
.nf
\&\. {
forward \. 8\.8\.8\.8
.fi
.RE
.IP 1\. 4
This template uses the default zone (\fB\fC.\fR or all queries)
.IP 2\. 4
All queries will be answered (no \fB\fCfallthrough\fR)
.IP 3\. 4
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.
.PP
.RS
.nf
\&. {
forward . 8.8.8.8
template ANY ANY invalid {
rcode NXDOMAIN
authority "invalid\. 60 {{ \.Class }} SOA ns\.invalid\. hostmaster\.invalid\. (1 60 60 60 60)"
authority "invalid. 60 {{ .Class }} SOA ns.invalid. hostmaster.invalid. (1 60 60 60 60)"
}
}
.
.fi
.
.IP "" 0
.
.IP "1." 4
A query to \.invalid will result in NXDOMAIN (rcode)
.
.IP "2." 4
.RE
.IP 1\. 4
A query to .invalid will result in NXDOMAIN (rcode)
.IP 2\. 4
A dummy SOA record is sent to hand out a TTL of 60s for caching purposes
.
.IP "3." 4
Querying \fB\.invalid\fR in the \fBCH\fR class will also cause a NXDOMAIN/SOA response
.
.IP "4." 4
The default regex is \fB\.*\fR
.
.IP "" 0
.
.SS "BLOCK INVALID SEARCH DOMAIN COMPLETIONS"
Imagine you run \fBexample\.com\fR with a datacenter \fBdc1\.example\.com\fR\. The datacenter domain is part of the DNS search domain\. However \fBsomething\.example\.com\.dc1\.example\.com\fR would indicate a fully qualified domain name (\fBsomething\.example\.com\fR) that inadvertently has the default domain or search path (\fBdc1\.example\.com\fR) added\.
.
.IP "" 4
.
.IP 3\. 4
Querying \fB\fC.invalid\fR in the \fB\fCCH\fR class will also cause a NXDOMAIN/SOA response
.IP 4\. 4
The default regex is \fB\fC.*\fR
.SS BLOCK INVALID SEARCH DOMAIN COMPLETIONS
.PP
Imagine you run \fB\fCexample.com\fR with a datacenter \fB\fCdc1.example.com\fR. The datacenter domain
is part of the DNS search domain.
However \fB\fCsomething.example.com.dc1.example.com\fR would indicate a fully qualified
domain name (\fB\fCsomething.example.com\fR) that inadvertently has the default domain or search
path (\fB\fCdc1.example.com\fR) added.
.PP
.RS
.nf
\&. {
forward . 8.8.8.8
\&\. {
forward \. 8\.8\.8\.8
template IN ANY example\.com\.dc1\.example\.com {
template IN ANY example.com.dc1.example.com {
rcode NXDOMAIN
authority "{{ \.Zone }} 60 IN SOA ns\.example\.com hostmaster\.example\.com (1 60 60 60 60)"
authority "{{ .Zone }} 60 IN SOA ns.example.com hostmaster.example.com (1 60 60 60 60)"
}
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
A more verbose regex based equivalent would be
.
.IP "" 4
.
.PP
.RS
.nf
\&. {
forward . 8.8.8.8
\&\. {
forward \. 8\.8\.8\.8
template IN ANY example\.com {
match "example\e\.com\e\.(dc1\e\.example\e\.com\e\.)$"
template IN ANY example.com {
match "example\\.com\\.(dc1\\.example\\.com\\.)$"
rcode NXDOMAIN
authority "{{ index \.Match 1 }} 60 IN SOA ns\.{{ index \.Match 1 }} hostmaster\.{{ index \.Match 1 }} (1 60 60 60 60)"
authority "{{ index .Match 1 }} 60 IN SOA ns.{{ index .Match 1 }} hostmaster.{{ index .Match 1 }} (1 60 60 60 60)"
fallthrough
}
}
.
.fi
.
.IP "" 0
.
.P
The regex\-based version can do more complex matching/templating while zone\-based templating is easier to read and use\.
.
.SS "RESOLVE A/PTR FOR \.EXAMPLE"
.
.RE
.PP
The regex-based version can do more complex matching/templating while zone-based templating is easier to read and use.
.SS RESOLVE A/PTR FOR .EXAMPLE
.PP
.RS
.nf
\&. {
forward . 8.8.8.8
\&\. {
forward \. 8\.8\.8\.8
# ip\-a\-b\-c\-d\.example A a\.b\.c\.d
# ip\-a\-b\-c\-d.example A a.b.c.d
template IN A example {
match (^|[\.])ip\-(?P<a>[0\-9]*)\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]example[\.]$
answer "{{ \.Name }} 60 IN A {{ \.Group\.a }}\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
match (^|[.])ip\-(?P<a>[0\-9]*)\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[.]example[.]$
answer "{{ .Name }} 60 IN A {{ .Group.a }}.{{ .Group.b }}.{{ .Group.c }}.{{ .Group.d }}"
fallthrough
}
# d\.c\.b\.a\.in\-addr\.arpa PTR ip\-a\-b\-c\-d\.example
# d.c.b.a.in\-addr.arpa PTR ip\-a\-b\-c\-d.example
template IN PTR in\-addr\.arpa {
match ^(?P<d>[0\-9]*)[\.](?P<c>[0\-9]*)[\.](?P<b>[0\-9]*)[\.](?P<a>[0\-9]*)[\.]in\-addr[\.]arpa[\.]$
answer "{{ \.Name }} 60 IN PTR ip\-{{ \.Group\.a }}\-{{ \.Group\.b }}\-{{ \.Group\.c }}\-{{ \.Group\.d }}\.example\."
template IN PTR in\-addr.arpa {
match ^(?P<d>[0\-9]*)[.](?P<c>[0\-9]*)[.](?P<b>[0\-9]*)[.](?P<a>[0\-9]*)[.]in\-addr[.]arpa[.]$
answer "{{ .Name }} 60 IN PTR ip\-{{ .Group.a }}\-{{ .Group.b }}\-{{ .Group.c }}\-{{ .Group.d }}.example."
}
}
.
.fi
.
.P
An IPv4 address consists of 4 bytes, \fBa\.b\.c\.d\fR\. Named groups make it less error\-prone to reverse the IP address in the PTR case\. Try to use named groups to explain what your regex and template are doing\.
.
.P
Note that the A record is actually a wildcard: any subdomain of the IP address will resolve to the IP address\.
.
.P
Having templates to map certain PTR/A pairs is a common pattern\.
.
.P
Fallthrough is needed for mixed domains where only some responses are templated\.
.
.SS "RESOLVE MULTIPLE IP PATTERNS"
.
.nf
\&\. {
forward \. 8\.8\.8\.8
.fi
.RE
.PP
An IPv4 address consists of 4 bytes, \fB\fCa.b.c.d\fR. Named groups make it less error-prone to reverse the
IP address in the PTR case. Try to use named groups to explain what your regex and template are doing.
.PP
Note that the A record is actually a wildcard: any subdomain of the IP address will resolve to the IP address.
.PP
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 MULTIPLE IP PATTERNS
.PP
.RS
.nf
\&. {
forward . 8.8.8.8
template IN A example {
match "^ip\-(?P<a>10)\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]dc[\.]example[\.]$"
match "^(?P<a>[0\-9]*)[\.](?P<b>[0\-9]*)[\.](?P<c>[0\-9]*)[\.](?P<d>[0\-9]*)[\.]ext[\.]example[\.]$"
answer "{{ \.Name }} 60 IN A {{ \.Group\.a}}\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
match "^ip\-(?P<a>10)\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[.]dc[.]example[.]$"
match "^(?P<a>[0\-9]*)[.](?P<b>[0\-9]*)[.](?P<c>[0\-9]*)[.](?P<d>[0\-9]*)[.]ext[.]example[.]$"
answer "{{ .Name }} 60 IN A {{ .Group.a}}.{{ .Group.b }}.{{ .Group.c }}.{{ .Group.d }}"
fallthrough
}
}
.
.fi
.
.P
Named capture groups can be used to template one response for multiple patterns\.
.
.SS "RESOLVE A AND MX RECORDS FOR IP TEMPLATES IN \.EXAMPLE"
.
.nf
\&\. {
forward \. 8\.8\.8\.8
.fi
.RE
.PP
Named capture groups can be used to template one response for multiple patterns.
.SS RESOLVE A AND MX RECORDS FOR IP TEMPLATES IN .EXAMPLE
.PP
.RS
.nf
\&. {
forward . 8.8.8.8
template IN A example {
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]example[\.]$
answer "{{ \.Name }} 60 IN A 10\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[.]example[.]$
answer "{{ .Name }} 60 IN A 10.{{ .Group.b }}.{{ .Group.c }}.{{ .Group.d }}"
fallthrough
}
template IN MX example {
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]example[\.]$
answer "{{ \.Name }} 60 IN MX 10 {{ \.Name }}"
additional "{{ \.Name }} 60 IN A 10\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[.]example[.]$
answer "{{ .Name }} 60 IN MX 10 {{ .Name }}"
additional "{{ .Name }} 60 IN A 10.{{ .Group.b }}.{{ .Group.c }}.{{ .Group.d }}"
fallthrough
}
}
.
.fi
.
.SS "ADDING AUTHORITATIVE NAMESERVERS TO THE RESPONSE"
.
.nf
\&\. {
forward \. 8\.8\.8\.8
.fi
.RE
.SS ADDING AUTHORITATIVE NAMESERVERS TO THE RESPONSE
.PP
.RS
.nf
\&. {
forward . 8.8.8.8
template IN A example {
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]example[\.]$
answer "{{ \.Name }} 60 IN A 10\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
authority "example\. 60 IN NS ns0\.example\."
authority "example\. 60 IN NS ns1\.example\."
additional "ns0\.example\. 60 IN A 203\.0\.113\.8"
additional "ns1\.example\. 60 IN A 198\.51\.100\.8"
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[.]example[.]$
answer "{{ .Name }} 60 IN A 10.{{ .Group.b }}.{{ .Group.c }}.{{ .Group.d }}"
authority "example. 60 IN NS ns0.example."
authority "example. 60 IN NS ns1.example."
additional "ns0.example. 60 IN A 203.0.113.8"
additional "ns1.example. 60 IN A 198.51.100.8"
fallthrough
}
template IN MX example {
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]example[\.]$
answer "{{ \.Name }} 60 IN MX 10 {{ \.Name }}"
additional "{{ \.Name }} 60 IN A 10\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
authority "example\. 60 IN NS ns0\.example\."
authority "example\. 60 IN NS ns1\.example\."
additional "ns0\.example\. 60 IN A 203\.0\.113\.8"
additional "ns1\.example\. 60 IN A 198\.51\.100\.8"
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[.]example[.]$
answer "{{ .Name }} 60 IN MX 10 {{ .Name }}"
additional "{{ .Name }} 60 IN A 10.{{ .Group.b }}.{{ .Group.c }}.{{ .Group.d }}"
authority "example. 60 IN NS ns0.example."
authority "example. 60 IN NS ns1.example."
additional "ns0.example. 60 IN A 203.0.113.8"
additional "ns1.example. 60 IN A 198.51.100.8"
fallthrough
}
}
.
.fi
.
.SH "ALSO SEE"
.
.IP "\(bu" 4
Go regexp \fIhttps://golang\.org/pkg/regexp/\fR for details about the regex implementation
.
.IP "\(bu" 4
RE2 syntax reference \fIhttps://github\.com/google/re2/wiki/Syntax\fR for details about the regex syntax
.
.IP "\(bu" 4
RFC 1034 \fIhttps://tools\.ietf\.org/html/rfc1034#section\-3\.6\.1\fR and RFC 1035 \fIhttps://tools\.ietf\.org/html/rfc1035#section\-5\fR for the resource record format
.
.IP "\(bu" 4
Go template \fIhttps://golang\.org/pkg/text/template/\fR for the template language reference
.
.IP "" 0
.
.SH "BUGS"
CoreDNS supports caddyfile environment variables \fIhttps://caddyserver\.com/docs/caddyfile#env\fR with notion of \fB{$ENV_VAR}\fR\. This parser feature will break Go template variables \fIhttps://golang\.org/pkg/text/template/#hdr\-Variables\fR notations like\fB{{$variable}}\fR\. The equivalent notation \fB{{ $variable }}\fR will work\. Try to avoid Go template variables in the context of this plugin\.
.RE
.SH ALSO SEE
.IP \(bu 4
Go regexp
\[la]https://golang.org/pkg/regexp/\[ra] for details about the regex implementation
.IP \(bu 4
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
.IP \(bu 4
Go template
\[la]https://golang.org/pkg/text/template/\[ra] for the template language reference
.SH BUGS
.PP
CoreDNS supports caddyfile environment variables
\[la]https://caddyserver.com/docs/caddyfile#env\[ra]
with notion of \fB\fC{$ENV_VAR}\fR. This parser feature will break Go template variables
\[la]https://golang.org/pkg/text/template/#hdr-Variables\[ra] notations like\fB\fC{{$variable}}\fR.
The equivalent notation \fB\fC{{ $variable }}\fR will work.
Try to avoid Go template variables in the context of this plugin.

129
man/coredns-tls.7
View file

@ -1,65 +1,78 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-TLS" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fItls\fR \- allows you to configure the server certificates for the TLS and gRPC servers\.
.
.SH "DESCRIPTION"
CoreDNS supports queries that are encrypted using TLS (DNS over Transport Layer Security, RFC 7858) or are using gRPC (https://grpc\.io/, not an IETF standard)\. Normally DNS traffic isn\'t encrypted at all (DNSSEC only signs resource records)\.
.
.P
The \fItls\fR "plugin" allows you to configure the cryptographic keys that are needed for both DNS\-over\-TLS and DNS\-over\-gRPC\. If the \fBtls\fR directive is omitted, then no encryption takes place\.
.
.P
The gRPC protobuffer is defined in \fBpb/dns\.proto\fR\. It defines the proto as a simple wrapper for the wire data of a DNS message\.
.
.SH "SYNTAX"
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-TLS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH TLS
.SH NAME
.PP
\fItls\fP - allows you to configure the server certificates for the TLS and gRPC servers.
.SH DESCRIPTION
.PP
CoreDNS supports queries that are encrypted using TLS (DNS over Transport Layer Security, RFC 7858)
or are using gRPC (https://grpc.io/
\[la]https://grpc.io/\[ra], not an IETF standard). Normally DNS traffic isn't encrypted at
all (DNSSEC only signs resource records).
.PP
The \fItls\fP "plugin" allows you to configure the cryptographic keys that are needed for both
DNS-over-TLS and DNS-over-gRPC. If the \fB\fCtls\fR directive is omitted, then no encryption takes place.
.PP
The gRPC protobuffer is defined in \fB\fCpb/dns.proto\fR. It defines the proto as a simple wrapper for the
wire data of a DNS message.
.SH SYNTAX
.PP
.RS
.nf
tls CERT KEY [CA]
.
.fi
.
.P
Parameter CA is optional\. If not set, system CAs can be used to verify the client certificate
.
.SH "EXAMPLES"
Start a DNS\-over\-TLS server that picks up incoming DNS\-over\-TLS queries on port 5553 and uses the nameservers defined in \fB/etc/resolv\.conf\fR to resolve the query\. This proxy path uses plain old DNS\.
.
.IP "" 4
.
.nf
tls://\.:5553 {
tls cert\.pem key\.pem ca\.pem
forward \. /etc/resolv\.conf
}
.
.fi
.
.IP "" 0
.
.P
Start a DNS\-over\-gRPC server that is similar to the previous example, but using DNS\-over\-gRPC for incoming queries\.
.
.IP "" 4
.
.nf
.RE
grpc://\. {
tls cert\.pem key\.pem ca\.pem
forward \. /etc/resolv\.conf
.PP
Parameter CA is optional. If not set, system CAs can be used to verify the client certificate
.SH EXAMPLES
.PP
Start a DNS-over-TLS server that picks up incoming DNS-over-TLS queries on port 5553 and uses the
nameservers defined in \fB\fC/etc/resolv.conf\fR to resolve the query. This proxy path uses plain old DNS.
.PP
.RS
.nf
tls://.:5553 {
tls cert.pem key.pem ca.pem
forward . /etc/resolv.conf
}
.
.fi
.
.IP "" 0
.
.P
Only Knot DNS\' \fBkdig\fR supports DNS\-over\-TLS queries, no command line client supports gRPC making debugging these transports harder than it should be\.
.
.SH "ALSO SEE"
RFC 7858 and https://grpc\.io\.
.RE
.PP
Start a DNS-over-gRPC server that is similar to the previous example, but using DNS-over-gRPC for
incoming queries.
.PP
.RS
.nf
grpc://. {
tls cert.pem key.pem ca.pem
forward . /etc/resolv.conf
}
.fi
.RE
.PP
Only Knot DNS' \fB\fCkdig\fR supports DNS-over-TLS queries, no command line client supports gRPC making
debugging these transports harder than it should be.
.SH ALSO SEE
.PP
RFC 7858 and https://grpc.io
\[la]https://grpc.io\[ra].

228
man/coredns-trace.7
View file

@ -1,147 +1,143 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-TRACE" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fItrace\fR \- enables OpenTracing\-based tracing of DNS requests as they go through the plugin chain\.
.
.SH "DESCRIPTION"
With \fItrace\fR you enable OpenTracing of how a request flows through CoreDNS\.
.
.SH "SYNTAX"
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-TRACE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH TRACE
.SH NAME
.PP
\fItrace\fP - enables OpenTracing-based tracing of DNS requests as they go through the plugin chain.
.SH DESCRIPTION
.PP
With \fItrace\fP you enable OpenTracing of how a request flows through CoreDNS.
.SH SYNTAX
.PP
The simplest form is just:
.
.IP "" 4
.
.nf
.PP
.RS
.nf
trace [ENDPOINT\-TYPE] [ENDPOINT]
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBENDPOINT\-TYPE\fR is the type of tracing destination\. Currently only \fBzipkin\fR and \fBdatadog\fR are supported\. Defaults to \fBzipkin\fR\.
.
.IP "\(bu" 4
\fBENDPOINT\fR is the tracing destination, and defaults to \fBlocalhost:9411\fR\. For Zipkin, if ENDPOINT does not begin with \fBhttp\fR, then it will be transformed to \fBhttp://ENDPOINT/api/v1/spans\fR\.
.
.IP "" 0
.
.P
With this form, all queries will be traced\.
.
.P
.RE
.IP \(bu 4
\fBENDPOINT-TYPE\fP is the type of tracing destination. Currently only \fB\fCzipkin\fR and \fB\fCdatadog\fR are supported.
Defaults to \fB\fCzipkin\fR.
.IP \(bu 4
\fBENDPOINT\fP is the tracing destination, and defaults to \fB\fClocalhost:9411\fR. For Zipkin, if
ENDPOINT does not begin with \fB\fChttp\fR, then it will be transformed to \fB\fChttp://ENDPOINT/api/v1/spans\fR.
.PP
With this form, all queries will be traced.
.PP
Additional features can be enabled with this syntax:
.
.IP "" 4
.
.nf
.PP
.RS
.nf
trace [ENDPOINT\-TYPE] [ENDPOINT] {
every AMOUNT
service NAME
client_server
every AMOUNT
service NAME
client\_server
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBevery\fR \fBAMOUNT\fR will only trace one query of each AMOUNT queries\. For example, to trace 1 in every 100 queries, use AMOUNT of 100\. The default is 1\.
.
.IP "\(bu" 4
\fBservice\fR \fBNAME\fR allows you to specify the service name reported to the tracing server\. Default is \fBcoredns\fR\.
.
.IP "\(bu" 4
\fBclient_server\fR will enable the \fBClientServerSameSpan\fR OpenTracing feature\.
.
.IP "" 0
.
.SH "ZIPKIN"
.RE
.IP \(bu 4
\fB\fCevery\fR \fBAMOUNT\fP will only trace one query of each AMOUNT queries. For example, to trace 1 in every
100 queries, use AMOUNT of 100. The default is 1.
.IP \(bu 4
\fB\fCservice\fR \fBNAME\fP allows you to specify the service name reported to the tracing server.
Default is \fB\fCcoredns\fR.
.IP \(bu 4
\fB\fCclient_server\fR will enable the \fB\fCClientServerSameSpan\fR OpenTracing feature.
.SH ZIPKIN
.PP
You can run Zipkin on a Docker host like this:
.
.IP "" 4
.
.nf
.PP
.RS
.nf
docker run \-d \-p 9411:9411 openzipkin/zipkin
.
.fi
.
.IP "" 0
.
.SH "EXAMPLES"
.RE
.SH EXAMPLES
.PP
Use an alternative Zipkin address:
.
.IP "" 4
.
.nf
.PP
.RS
.nf
trace tracinghost:9253
.
.fi
.
.IP "" 0
.
.P
or
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
or
.PP
.RS
.nf
\&. {
trace zipkin tracinghost:9253
}
.
.fi
.
.IP "" 0
.
.P
If for some reason you are using an API reverse proxy or something and need to remap the standard Zipkin URL you can do something like:
.
.IP "" 4
.
.nf
.fi
.RE
.PP
If for some reason you are using an API reverse proxy or something and need to remap
the standard Zipkin URL you can do something like:
.PP
.RS
.nf
trace http://tracinghost:9411/zipkin/api/v1/spans
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Using DataDog:
.
.IP "" 4
.
.nf
.PP
.RS
.nf
trace datadog localhost:8125
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Trace one query every 10000 queries, rename the service, and enable same span:
.
.IP "" 4
.
.PP
.RS
.nf
trace tracinghost:9411 {
every 10000
service dnsproxy
client_server
every 10000
service dnsproxy
client\_server
}
.
.fi
.
.IP "" 0
.fi
.RE

132
man/coredns-whoami.7
View file

@ -1,73 +1,83 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-WHOAMI" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIwhoami\fR \- returns your resolver\'s local IP address, port and transport\.
.
.SH "DESCRIPTION"
The \fIwhoami\fR plugin is not really that useful, but can be used for having a simple (fast) endpoint to test clients against\. When \fIwhoami\fR returns a response it will have your client\'s IP address in the additional section as either an A or AAAA record\.
.
.P
The reply always has an empty answer section\. The port and transport are included in the additional section as a SRV record, transport can be "tcp" or "udp"\.
.
.IP "" 4
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-WHOAMI" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.SH WHOAMI
.SH NAME
.PP
\fIwhoami\fP - returns your resolver's local IP address, port and transport.
.SH DESCRIPTION
.PP
The \fIwhoami\fP plugin is not really that useful, but can be used for having a simple (fast) endpoint
to test clients against. When \fIwhoami\fP returns a response it will have your client's IP address in
the additional section as either an A or AAAA record.
.PP
The reply always has an empty answer section. The port and transport are included in the additional
section as a SRV record, transport can be "tcp" or "udp".
.PP
.RS
.nf
\&.\_<transport>.qname. 0 IN SRV 0 0 <port> .
\&\._<transport>\.qname\. 0 IN SRV 0 0 <port> \.
.
.fi
.
.IP "" 0
.
.P
The \fIwhoami\fR plugin will respond to every A or AAAA query, regardless of the query name\.
.
.P
If CoreDNS can\'t find a Corefile on startup this is the \fIdefault\fR plugin that gets loaded\. As such it can be used to check that CoreDNS is responding to queries\. Other than that this plugin is of limited use in production\.
.
.SH "SYNTAX"
.
.nf
.RE
.PP
The \fIwhoami\fP plugin will respond to every A or AAAA query, regardless of the query name.
.PP
If CoreDNS can't find a Corefile on startup this is the \fIdefault\fP plugin that gets loaded. As such
it can be used to check that CoreDNS is responding to queries. Other than that this plugin is of
limited use in production.
.SH SYNTAX
.PP
.RS
.nf
whoami
.
.fi
.
.SH "EXAMPLES"
Start a server on the default port and load the \fIwhoami\fR plugin\.
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.SH EXAMPLES
.PP
Start a server on the default port and load the \fIwhoami\fP plugin.
.PP
.RS
.nf
\&. {
whoami
}
.
.fi
.
.IP "" 0
.
.P
When queried for "example\.org A", CoreDNS will respond with:
.
.IP "" 4
.
.nf
.fi
.RE
.PP
When queried for "example.org A", CoreDNS will respond with:
.PP
.RS
.nf
;; QUESTION SECTION:
;example\.org\. IN A
;example.org. IN A
;; ADDITIONAL SECTION:
example\.org\. 0 IN A 10\.240\.0\.1
_udp\.example\.org\. 0 IN SRV 0 0 40212
.
example.org. 0 IN A 10.240.0.1
\_udp.example.org. 0 IN SRV 0 0 40212
.fi
.
.IP "" 0
.
.SH "SEE ALSO"
Read the blog post \fIhttps://coredns\.io/2017/03/01/how\-to\-add\-plugins\-to\-coredns/\fR on how this plugin is built, or explore the source code \fIhttps://github\.com/coredns/coredns/blob/master/plugin/whoami/\fR\.
.RE
.SH SEE ALSO
.PP
Read the blog post
\[la]https://coredns.io/2017/03/01/how-to-add-plugins-to-coredns/\[ra] on how this plugin is built, or explore the source code
\[la]https://github.com/coredns/coredns/blob/master/plugin/whoami/\[ra].

109
man/coredns.1
View file

@ -1,59 +1,66 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS" "1" "March 2019" "CoreDNS" "CoreDNS"
.
.SH "NAME"
\fBcoredns\fR
.
.SH "NAME"
\fIcoredns\fR \- plugable DNS nameserver optimized for service discovery and flexibility\.
.
.SH "SYNOPSIS"
\fIcoredns\fR \fI[OPTION]\fR\.\.\.
.
.SH "DESCRIPTION"
CoreDNS is a DNS server that chains plugins\. Each plugin handles a DNS feature, like rewriting queries, kubernetes service discovery or just exporting metrics\. There are many other plugins, each described on \fIhttps://coredns\.io/plugins\fR and there respective manual pages\. Plugins not bundled in CoreDNS are listed on \fIhttps://coredns\.io/explugins\fR\.
.
.P
When started with no options CoreDNS will looks for a file names \fBCorefile\fR in the current directory, if found it will parse its contents and start up accordingly\. If no \fBCorefile\fR is found it will start with the \fIwhoami\fR plugin (coredns\-whoami(7)) and start listening on port 53 (unless overridden with \fB\-dns\.port\fR)\.
.
.P
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS" "1" "April 2019" "CoreDNS" "CoreDNS"
.SH NAME
.PP
\fIcoredns\fP - plugable DNS nameserver optimized for service discovery and flexibility.
.SH SYNOPSIS
.PP
\fIcoredns\fP \fI[OPTION]\fP...
.SH DESCRIPTION
.PP
CoreDNS is a DNS server that chains plugins. Each plugin handles a DNS feature, like rewriting
queries, kubernetes service discovery or just exporting metrics. There are many other plugins,
each described on https://coredns.io/plugins
\[la]https://coredns.io/plugins\[ra] and there respective manual pages. Plugins not
bundled in CoreDNS are listed on https://coredns.io/explugins
\[la]https://coredns.io/explugins\[ra].
.PP
When started with no options CoreDNS will looks for a file names \fB\fCCorefile\fR in the current
directory, if found it will parse its contents and start up accordingly. If no \fB\fCCorefile\fR is found
it will start with the \fIwhoami\fP plugin (coredns-whoami(7)) and start listening on port 53 (unless
overridden with \fB\fC-dns.port\fR).
.PP
Available options:
.
.RS
.TP
\fB\-conf\fR \fBFILE\fR
specify Corefile to load\.
.
\fB-conf\fP \fBFILE\fP
specify Corefile to load.
.TP
\fB\-cpu\fR \fBCAP\fR
specify maximum CPU capacity in percent\.
.
\fB-cpu\fP \fBCAP\fP
specify maximum CPU capacity in percent.
.TP
\fB\-dns\.port\fR \fBPORT\fR
override default port (53) to listen on\.
.
\fB-dns.port\fP \fBPORT\fP
override default port (53) to listen on.
.TP
\fB\-pidfile\fR \fBFILE\fR
write PID to \fBFILE\fR\.
.
\fB-pidfile\fP \fBFILE\fP
write PID to \fBFILE\fP.
.TP
\fB\-plugins\fR
list all plugins and quit\.
.
\fB-plugins\fP
list all plugins and quit.
.TP
\fB\-quiet\fR
don\'t print any version and port information on startup\.
.
\fB-quiet\fP
don't print any version and port information on startup.
.TP
\fB\-version\fR
show version and quit\.
.
.SH "AUTHORS"
CoreDNS Authors\.
.
.SH "COPYRIGHT"
Apache License 2\.0
.
.SH "SEE ALSO"
Corefile(5) coredns\-k8s_external(7) coredns\-erratic(7) coredns\-nsid(7) coredns\-hosts(7) coredns\-dnssec(7) coredns\-health(7) coredns\-grpc(7) coredns\-ready(7) coredns\-file(7) coredns\-root(7) coredns\-autopath(7) coredns\-auto(7) coredns\-dnstap(7) coredns\-pprof(7) coredns\-tls(7) coredns\-loadbalance(7) coredns\-cache(7) coredns\-whoami(7) coredns\-bind(7) coredns\-loop(7) coredns\-import(7) coredns\-chaos(7) coredns\-template(7) coredns\-log(7) coredns\-kubernetes(7) coredns\-forward(7) coredns\-debug(7) coredns\-secondary(7) coredns\-route53(7) coredns\-errors(7) coredns\-metrics(7) coredns\-reload(7) coredns\-rewrite(7) coredns\-metadata(7) coredns\-federation(7) coredns\-etcd(7) coredns\-cancel(7) coredns\-trace(7)\.
\fB-version\fP
show version and quit.
.RE
.SH AUTHORS
.PP
CoreDNS Authors.
.SH COPYRIGHT
.PP
Apache License 2.0
.SH SEE ALSO
.PP
Corefile(5) coredns-k8s_external(7) coredns-erratic(7) coredns-nsid(7) coredns-hosts(7) coredns-dnssec(7) coredns-health(7) coredns-grpc(7) coredns-ready(7) coredns-file(7) coredns-root(7) coredns-autopath(7) coredns-auto(7) coredns-dnstap(7) coredns-pprof(7) coredns-tls(7) coredns-loadbalance(7) coredns-cache(7) coredns-whoami(7) coredns-bind(7) coredns-loop(7) coredns-import(7) coredns-chaos(7) coredns-template(7) coredns-log(7) coredns-kubernetes(7) coredns-forward(7) coredns-debug(7) coredns-secondary(7) coredns-route53(7) coredns-errors(7) coredns-metrics(7) coredns-reload(7) coredns-rewrite(7) coredns-metadata(7) coredns-federation(7) coredns-etcd(7) coredns-cancel(7) coredns-trace(7).

310
man/corefile.5
View file

@ -1,192 +1,204 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREFILE" "5" "March 2019" "CoreDNS" "CoreDNS"
.
.SH "NAME"
\fBcorefile\fR
.
.SH "NAME"
\fIcorefile\fR \- configuration file for CoreDNS
.
.SH "DESCRIPTION"
A \fIcorefile\fR specifies the (internal) servers CoreDNS should run and what plugins each of these should chain\. The syntax is as follows:
.
.IP "" 4
.
.nf
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREFILE" "5" "April 2019" "CoreDNS" "CoreDNS"
[SCHEME://]ZONE [[SCHEME://]ZONE]\.\.\.[:PORT] {
[PLUGIN]\.\.\.
.SH NAME
.PP
\fIcorefile\fP - configuration file for CoreDNS
.SH DESCRIPTION
.PP
A \fIcorefile\fP specifies the (internal) servers CoreDNS should run and what plugins each of these
should chain. The syntax is as follows:
.PP
.RS
.nf
[SCHEME://]ZONE [[SCHEME://]ZONE]...[:PORT] {
[PLUGIN]...
}
.
.fi
.
.IP "" 0
.
.P
The \fBZONE\fR defines for which name this server should be called, multiple zones are allowed and should be \fIwhite space\fR separated\. You can use a "reverse" syntax to specify a reverse zone (i\.e\. ip6\.arpa and in\-addr\.arpa), by using an IP address in the CIDR notation\.
.
.P
The optional \fBSCHEME\fR defaults to \fBdns://\fR, but can also be \fBtls://\fR (DNS over TLS), \fBgrpc://\fR (DNS over gRPC) or \fBhttps://\fR (DNS over HTTP/2)\.
.
.P
The optional \fBPORT\fR controls on which port the server will bind, this default to 53\. If you use a port number here, you \fIcan\'t\fR override it with \fB\-dns\.port\fR (coredns(1))\.
.
.P
Specifying a \fBZONE\fR \fIand\fR \fBPORT\fR combination multiple times for \fIdifferent\fR servers will lead to an error on startup\.
.
.P
When a query comes in, it is matched again all zones for all servers, the server with the longest match on the query name will receive the query\.
.
.P
\fBPLUGIN\fR defines the plugin(s) we want to load into this server\. This is optional as well, but as server with no plugins will just return SERVFAIL for all queries\. Each plugin can have a number of properties than can have arguments, see the documentation for each plugin\.
.
.P
Comments are allowed and begin with an unquoted hash \fB#\fR and continue to the end of the line\. Comments may be started anywhere on a line\.
.
.P
Environment variables are supported and either the Unix or Windows form may be used: \fB{$ENV_VAR_1}\fR or \fB{%ENV_VAR_2%}\fR\.
.
.P
You can use the \fBimport\fR "plugin" to include parts of other files\.
.
.P
If CoreDNS can’t find a Corefile to load it loads the following builtin one:
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.PP
The \fBZONE\fP defines for which name this server should be called, multiple zones are allowed and
should be \fIwhite space\fP separated. You can use a "reverse" syntax to specify a reverse zone (i.e.
ip6.arpa and in-addr.arpa), by using an IP address in the CIDR notation.
.PP
The optional \fBSCHEME\fP defaults to \fB\fCdns://\fR, but can also be \fB\fCtls://\fR (DNS over TLS), \fB\fCgrpc://\fR
(DNS over gRPC) or \fB\fChttps://\fR (DNS over HTTP/2).
.PP
The optional \fBPORT\fP controls on which port the server will bind, this default to 53. If you use
a port number here, you \fIcan't\fP override it with \fB\fC-dns.port\fR (coredns(1)).
.PP
Specifying a \fBZONE\fP \fIand\fP \fBPORT\fP combination multiple times for \fIdifferent\fP servers will lead to
an error on startup.
.PP
When a query comes in, it is matched again all zones for all servers, the server with the longest
match on the query name will receive the query.
.PP
\fBPLUGIN\fP defines the plugin(s) we want to load into this server. This is optional as well, but as
server with no plugins will just return SERVFAIL for all queries. Each plugin can have a number of
properties than can have arguments, see the documentation for each plugin.
.PP
Comments are allowed and begin with an unquoted hash \fB\fC#\fR and continue to the end of the line.
Comments may be started anywhere on a line.
.PP
Environment variables are supported and either the Unix or Windows form may be used: \fB\fC{$ENV_VAR_1}\fR
or \fB\fC{%ENV_VAR_2%}\fR.
.PP
You can use the \fB\fCimport\fR "plugin" to include parts of other files.
.PP
If CoreDNS can’t find a Corefile to load it loads the following builtin one:
.PP
.RS
.nf
\&. {
whoami
}
.
.fi
.
.IP "" 0
.
.SH "IMPORT"
You can use the \fBimport\fR "plugin" to include parts of other files, see \fIhttps://coredns\.io/plugins/import\fR\.
.
.SH "SNIPPETS"
If you want to reuse a snippet you can define one with and then use it with \fIimport\fR\.
.
.IP "" 4
.
.nf
.fi
.RE
.SH IMPORT
.PP
You can use the \fB\fCimport\fR "plugin" to include parts of other files, see https://coredns.io/plugins/import
\[la]https://coredns.io/plugins/import\[ra].
.SH SNIPPETS
.PP
If you want to reuse a snippet you can define one with and then use it with \fIimport\fP.
.PP
.RS
.nf
(mysnippet) {
log
whoami
}
\. {
\&. {
import mysnippet
}
.
.fi
.
.IP "" 0
.
.SH "EXAMPLES"
The \fBZONE\fR is root zone \fB\.\fR, the \fBPLUGIN\fR is chaos\. The chaos plugin takes an argument: \fBCoreDNS\-001\fR\. This text is returned on a CH class query: \fBdig CH txt version\.bind @localhost\fR\.
.
.IP "" 4
.
.nf
\&\. {
.fi
.RE
.SH EXAMPLES
.PP
The \fBZONE\fP is root zone \fB\fC.\fR, the \fBPLUGIN\fP is chaos. The chaos plugin takes an argument:
\fB\fCCoreDNS-001\fR. This text is returned on a CH class query: \fB\fCdig CH txt version.bind @localhost\fR.
.PP
.RS
.nf
\&. {
chaos CoreDNS\-001
}
.
.fi
.
.IP "" 0
.
.P
When defining a new zone, you either create a new server, or add it to an existing one\. Here we define one server that handles two zones; that potentially chain different plugins:
.
.IP "" 4
.
.nf
example\.org {
.fi
.RE
.PP
When defining a new zone, you either create a new server, or add it to an existing one. Here we
define one server that handles two zones; that potentially chain different plugins:
.PP
.RS
.nf
example.org {
whoami
}
org {
whoami
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Is identical to:
.
.IP "" 4
.
.nf
example\.org org {
.PP
.RS
.nf
example.org org {
whoami
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
Reverse zones can be specified as domain names:
.
.IP "" 4
.
.nf
0\.0\.10\.in\-addr\.arpa {
.PP
.RS
.nf
0.0.10.in\-addr.arpa {
whoami
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
or by just using the CIDR notation:
.
.IP "" 4
.
.nf
10\.0\.0\.0/24 {
.PP
.RS
.nf
10.0.0.0/24 {
whoami
}
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
This also works on a non octet boundary:
.
.IP "" 4
.
.nf
10\.0\.0\.0/27 {
.PP
.RS
.nf
10.0.0.0/27 {
whoami
}
.
.fi
.
.IP "" 0
.
.SH "AUTHORS"
CoreDNS Authors\.
.
.SH "COPYRIGHT"
Apache License 2\.0
.
.SH "SEE ALSO"
The manual page for CoreDNS: coredns(1) and more documentation on \fIhttps://coredns\.io\fR\. Also see the \fIimport\fR \fIhttps://coredns\.io/plugins/import\fR\'s documentation\.
.RE
.SH AUTHORS
.PP
CoreDNS Authors.
.SH COPYRIGHT
.PP
Apache License 2.0
.SH SEE ALSO
.PP
The manual page for CoreDNS: coredns(1) and more documentation on https://coredns.io
\[la]https://coredns.io\[ra].
Also see the \fIimport\fP
\[la]https://coredns.io/plugins/import\[ra]'s documentation.