Skip to content

C
Coredns
Commit f8aa208c authored by Miek Gieben's avatar Miek Gieben Committed by GitHub
Browse files
Options

docs: Regenerate all manpages using mmark (#2762) 

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: default avatarMiek Gieben <miek@miek.nl>
parent 663271a7
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 4657 additions and 4186 deletions
Makefile.doc
View file @ f8aa208c
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:
......
corefile.5.md
View file @ f8aa208c
......@@ -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
}
......
man/coredns-auto.7
View file @ f8aa208c
.\" 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"
.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
auto [ZONES\.\.\.] {
directory DIR [REGEXP ORIGIN_TEMPLATE [TIMEOUT]]
.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
.RE
\&\. {
auto example\.org {
.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
.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
.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
.RE
man/coredns-autopath.7
View file @ f8aa208c
.\" 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"
.
.\" 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"
.
.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.
man/coredns-bind.7
View file @ f8aa208c
.\" 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"
.
.\" 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
.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):
\&\. {
bind 127\.0\.0\.1
.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
.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
\&\. {
bind 127\.0\.0\.1
.nf
\&. {
bind 127.0.0.1
bind ::1
}
.
.fi
.
.IP "" 0
.RE
man/coredns-cache.7
View file @ f8aa208c
.\" 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"
.
.\" 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
.RE
.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:
.
.IP "" 4
.
.nf
cache [TTL] [ZONES\.\.\.] {
.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"
.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:
.
.IP "" 4
.
.nf
\&\. {
.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
.RE
\&\. {
forward \. 8\.8\.8\.8:53
cache example\.org
.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
.RE
.PP
Enable caching for all zones, keep a positive cache size of 5000 and a negative cache size of 2500:
.
.IP "" 4
.
.nf
\. {
.PP
.RS
.nf
. {
cache {
success 5000
denial 2500
}
}
.
.fi
.
.IP "" 0
.RE
man/coredns-cancel.7
View file @ f8aa208c
.\" 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
.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
.RE
.PP
Or with a custom timeout:
.
.IP "" 4
.
.nf
\&\. {
.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.
man/coredns-chaos.7
View file @ f8aa208c
.\" 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"
.
.\" 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
.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.
version\.bind version\.server authors\.bind hostname\.bind id\.server {
chaos CoreDNS\-001 info@coredns\.io
.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
.RE
.PP
Or just default to \fB\fC.\fR:
\&\. {
chaos CoreDNS\-001 info@coredns\.io
.PP
.RS
.nf
\&. {
chaos CoreDNS\-001 info@coredns.io
}
.
.fi
.
.IP "" 0
.
.P
And test with \fBdig\fR:
.
.IP "" 4
.
.nf
.RE
.PP
And test with \fB\fCdig\fR:
.PP
.RS
% dig @localhost CH TXT version\.bind
\.\.\.
.nf
% dig @localhost CH TXT version.bind
\&...
;; ANSWER SECTION:
version\.bind\. 0 CH TXT "CoreDNS\-001"
\.\.\.
.
version.bind. 0 CH TXT "CoreDNS\-001"
\&...
.fi
.
.IP "" 0
.RE
man/coredns-debug.7
View file @ f8aa208c
.\" 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
.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"
.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:
.
.IP "" 4
.
.nf
\&\. {
.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].
man/coredns-dnssec.7
View file @ f8aa208c
.\" 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"
.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.
dnssec [ZONES\.\.\. ] {
key file KEY\.\.\.
cache_capacity CAPACITY
.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
.
.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
.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.
example\.org {
.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
.nf
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
.RE
.PP
Sign responses for a kubernetes zone with the key "Kcluster.local+013+45129.key".
cluster\.local {
.PP
.RS
.nf
cluster.local {
kubernetes
dnssec {
key file Kcluster\.local+013+45129
key file Kcluster.local+013+45129
}
}
.
.fi
.
.IP "" 0
.RE
man/coredns-dnstap.7
View file @ f8aa208c
.\" 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
.
.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 /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
.
.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 unix:///tmp/dnstap\.sock full
.
.fi
.
.IP "" 0
.
.P
Log to a remote endpoint\.
.
.IP "" 4
.
.RE
.PP
Log to a remote endpoint.
.PP
.RS
.nf
dnstap tcp://127.0.0.1:6000 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
.
.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
.
.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
.
.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 \-u /tmp/dnstap\.sock \-w /tmp/test\.dnstap
.
.fi
.
.IP "" 0
.
.P
Listen for dnstap messages on port 6000\.
.
.IP "" 4
.
.RE
.PP
Listen for dnstap messages on port 6000.
.PP
.RS
.nf
$ dnstap \-l 127.0.0.1:6000
$ dnstap \-l 127\.0\.0\.1:6000
.
.fi
.
.IP "" 0
.
.SH "USING DNSTAP IN YOUR PLUGIN"
.
.nf
.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].
man/coredns-erratic.7
View file @ f8aa208c
.\" 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
.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
.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
.RE
.PP
Delay 1 in 3 queries for 50ms
.
.IP "" 4
.
.nf
\&\. {
.PP
.RS
.nf
\&. {
erratic {
delay 3 50ms
}
}
.
.fi
.
.IP "" 0
.
.P
Delay 1 in 3 and truncate 1 in 5\.
.
.IP "" 4
.
.nf
.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
.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].
man/coredns-errors.7
View file @ f8aa208c
.\" 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
.
.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
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
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
.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 ".
\&\. {
forward \. 8\.8\.8\.8
.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
.RE
man/coredns-etcd.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-federation.7
View file @ f8aa208c
.\" 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"
.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
federation [ZONES\.\.\.] {
.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
.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.
\&\. {
kubernetes cluster\.local
federation cluster\.local {
prod prod\.feddomain\.com
staging staging\.feddomain\.com
.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
.RE
.PP
Or slightly shorter:
.
.IP "" 4
.
.nf
cluster\.local {
.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
.RE
man/coredns-file.7
View file @ f8aa208c
.\" 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"
.
.\" 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
.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.
file DBFILE [ZONES\.\.\. ] {
transfer to ADDRESS\.\.\.
.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
.RE
example\.org {
file example\.org\.signed {
.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
.RE
man/coredns-forward.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-grpc.7
View file @ f8aa208c
.\" 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
.
.PP
.RS
.nf
grpc FROM TO...
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
.
.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
.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:
example\.org {
grpc \. 127\.0\.0\.1:9005
.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
.nf
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
.RE
.PP
Load balance all requests between three resolvers, one of which has a IPv6 address.
\&\. {
grpc \. 10\.0\.0\.10:53 10\.0\.0\.11:1053 [2003::1]:53
.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
.RE
.PP
Forward everything except requests to \fB\fCexample.org\fR
\&\. {
grpc \. 10\.0\.0\.10:1234 {
except example\.org
.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
.RE
\&\. {
grpc \. /etc/resolv\.conf {
except example\.org
.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
.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
\&\. {
grpc \. 9\.9\.9\.9 {
tls_servername dns\.quad9\.net
.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.
man/coredns-health.7
View file @ f8aa208c
.\" 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
.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:
.
.IP "" 4
.
.nf
.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
.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
.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
.RE
.PP
Set a lameduck duration of 1 second:
.
.IP "" 4
.
.nf
\&\. {
.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.
man/coredns-hosts.7
View file @ f8aa208c
.\" 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
.
.nf
# THE FOLLOWING LINES ARE DESIRABLE FOR IPV4 CAPABLE HOSTS
127\.0\.0\.1 localhost
192\.168\.1\.10 example\.com example
.PP
.RS
# THE FOLLOWING LINES ARE DESIRABLE FOR IPV6 CAPABLE HOSTS
.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 IPv6 capable hosts
::1 localhost ip6\-localhost ip6\-loopback
fdfc:a744:27b5:3b0e::1 example\.com example
.
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
.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
hosts [FILE [ZONES\.\.\.]] {
.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
.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
.RE
.PP
Load \fB\fCexample.hosts\fR file in the current directory.
.PP
.RS
\&\. {
hosts example\.hosts
.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
.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
\&\. {
hosts example\.hosts example\.org example\.net {
.nf
\&. {
hosts example.hosts example.org example.net {
fallthrough
}
}
.
.fi
.
.IP "" 0
.
.P
Load hosts file inlined in Corefile\.
.
.IP "" 4
.
.nf
.RE
.PP
Load hosts file inlined in Corefile.
.PP
.RS
\&\. {
hosts example\.hosts example\.org {
10\.0\.0\.1 example\.org
.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].
man/coredns-import.7
View file @ f8aa208c
.\" 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
.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
.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
.RE
.PP
Where \fB\fCconfig/common.conf\fR contains:
.PP
.RS
.nf
prometheus
errors
log
.
.fi
.
.IP "" 0
.
.P
.RE
.PP
This imports files found in the zones directory:
.
.IP "" 4
.
.PP
.RS
.nf
import ../zones/*
import \.\./zones/*
.
.fi
.
.IP "" 0
.
.SH "ALSO SEE"
See corefile(5)\.
.RE
.SH ALSO SEE
.PP
See corefile(5).
man/coredns-k8s_external.7
View file @ f8aa208c
.\" 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.
ns1.dns.example.org. 5 IN A ....
ns1.dns.example.org. 5 IN AAAA ....
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 \.\.\.\.
.
.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"
.
.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
.IP \(bu 4
\fBZONES\fP zones \fIk8s_external\fP should be authoritative for.
k8s_external [ZONE\.\.\.] {
.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
.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).
\&\. {
kubernetes cluster\.local
k8s_external example\.org
.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
.
.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
.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.
man/coredns-kubernetes.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-loadbalance.7
View file @ f8aa208c
.\" 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
.
.nf
\&\. {
loadbalance round_robin
forward \. 8\.8\.8\.8 8\.8\.4\.4
.PP
.RS
.nf
\&. {
loadbalance round\_robin
forward . 8.8.8.8 8.8.4.4
}
.
.fi
.
.IP "" 0
.RE
man/coredns-log.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-loop.7
View file @ f8aa208c
.\" 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
.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
.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 \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
.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 \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
.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.
man/coredns-metadata.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-metrics.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-nsid.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-pprof.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-ready.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-reload.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-rewrite.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-root.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-route53.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-secondary.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-template.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-tls.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-trace.7
View file @ f8aa208c
This diff is collapsed.
man/coredns-whoami.7
View file @ f8aa208c
This diff is collapsed.
man/coredns.1
View file @ f8aa208c
This diff is collapsed.
man/corefile.5
View file @ f8aa208c
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment