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

mechanical: make -f Makefile.doc (#2390)

Browse source 
update the manpages by running make -f Makefile.doc

No other changes.

Signed-off-by: Miek Gieben <miek@miek.nl>
This commit is contained in:
Miek Gieben 2018-12-11 20:46:02 +00:00 • committed by GitHub
parent d0adf6f3a6
commit d9880681c3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 196 additions and 77 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
man/coredns-auto.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-AUTO" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-AUTO" "7" "December 2018" "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\.

5
man/coredns-autopath.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-AUTOPATH" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-AUTOPATH" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIautopath\fR \- allows for server\-side search path completion\.
@ -62,3 +62,6 @@ autopath @kubernetes
.
.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\.

10
man/coredns-cache.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-CACHE" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-CACHE" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIcache\fR \- enables a frontend cache\.
@ -29,7 +29,7 @@ cache [TTL] [ZONES\.\.\.]
.IP "" 0
.
.P
Each element in the cache is cached according to its TTL (with \fBTTL\fR as the max)\. For the negative cache, the SOA\'s MinTTL value is used\. A TTL of zero is not allowed\. A cache is divided into 256 shards, each holding up to 512 items by default \- for a total size of 256 * 512 = 131,072 items\.
Each element in the cache is cached according to its TTL (with \fBTTL\fR as the max)\. A cache is divided into 256 shards, each holding up to 39 items by default \- for a total size of 256 * 39 = 9984 items\.
.
.P
If you want more control:
@ -52,10 +52,10 @@ cache [TTL] [ZONES\.\.\.] {
\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 0), which can be useful to limit queries to the backend\.
\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 0), which can be useful to limit queries to the backend\. There is a third category (\fBerror\fR) but those responses are never cached\.
\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\.
@ -63,7 +63,7 @@ cache [TTL] [ZONES\.\.\.] {
.IP "" 0
.
.SH "CAPACITY AND EVICTION"
If \fBCAPACITY\fR is not specified, the default cache size is 10,000 per cache\. The minimum allowed cache size is 1024\.
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\.

7
man/coredns-dnssec.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-DNSSEC" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-DNSSEC" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIdnssec\fR \- enable on\-the\-fly DNSSEC signing of served data\.
@ -24,7 +24,10 @@ dnssec [ZONES\.\.\. ] {
.fi
.
.P
The specified key is used for all signing operations\. The DNSSEC signing will treat this key 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\.
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)\.

62
man/coredns-errors.7
View file

@ -1,18 +1,21 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ERRORS" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-ERRORS" "7" "December 2018" "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\.
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"
The basic syntax is:
.
.IP "" 4
.
.nf
@ -20,6 +23,42 @@ errors
.
.fi
.
.IP "" 0
.
.P
Extra knobs are available with an expanded syntax:
.
.IP "" 4
.
.nf
errors {
consolidate DURATION REGEXP
}
.
.fi
.
.IP "" 0
.
.P
Option \fBconsolidate\fR allows collecting several error messages matching the regular expression \fBREGEXP\fR during \fBDURATION\fR\. After the \fBDURATION\fR since receiving the first such message, the consolidated message will be printed to standard output, e\.g\.
.
.IP "" 4
.
.nf
2 errors like \'^read udp \.* i/o timeout$\' occurred in last 30s
.
.fi
.
.IP "" 0
.
.P
Multiple \fBconsolidate\fR options with different \fBDURATION\fR and \fBREGEXP\fR are allowed\. In case if some error message corresponds to several defined regular expressions the message will be associated with the first appropriate \fBREGEXP\fR\.
.
.P
For better performance, it\'s recommended to use the \fB^\fR or \fB$\fR metacharacters in regular expression when filtering error messages by prefix or suffix, e\.g\. \fB^failed to \.*\fR, or \fB\.* timeout$\fR\.
.
.SH "EXAMPLES"
Use the \fIwhoami\fR to respond to queries and Log errors to standard output\.
.
@ -35,4 +74,23 @@ Use the \fIwhoami\fR to respond to queries and Log errors to standard output\.
.fi
.
.IP "" 0
.
.P
Use the \fIforward\fR to resolve queries via 8\.8\.8\.8 and print consolidated error messages for errors with suffix " i/o timeout" or with prefix "Failed to "\.
.
.IP "" 4
.
.nf
\&\. {
forward \. 8\.8\.8\.8
errors {
consolidate 5m "\.* i/o timeout$"
consolidate 30s "^Failed to \.+"
}
}
.
.fi
.
.IP "" 0

14
man/coredns-file.7
View file

@ -1,13 +1,13 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-FILE" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-FILE" "7" "December 2018" "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, i\.e\. DNSSEC) correct DNSSEC answers are returned\. Only NSEC is supported! If you use this setup \fIyou\fR are responsible for resigning the zonefile\.
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"
.
@ -18,7 +18,7 @@ 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\.
\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\.
@ -26,7 +26,7 @@ file DBFILE [ZONES\.\.\.]
.IP "" 0
.
.P
If you want to round robin A and AAAA responses look at the \fIloadbalance\fR plugin\.
If you want to round\-robin A and AAAA responses look at the \fIloadbalance\fR plugin\.
.
.IP "" 4
.
@ -44,16 +44,16 @@ file DBFILE [ZONES\.\.\. ] {
.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 (127\.0\.0\.1/32 etc\.) 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\.
\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 reload of zone if SOA version changes\. 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\.
\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 defines upstream resolvers to be used 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\. \fBADDRESS\fR can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\. If no \fBADDRESS\fR is given, CoreDNS will resolve CNAMEs against itself\.
\fBupstream\fR defines upstream resolvers to be used 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\. \fBADDRESS\fR can be an IP address, an IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\. If no \fBADDRESS\fR is given, CoreDNS will resolve CNAMEs against itself\.
.
.IP "" 0
.

23
man/coredns-forward.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-FORWARD" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-FORWARD" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIforward\fR \- facilitates proxying DNS messages to upstream resolvers\.
@ -105,7 +105,7 @@ forward FROM TO\.\.\. {
.
.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\.
\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\.
@ -238,6 +238,25 @@ Proxy all requests to 9\.9\.9\.9 using the DNS\-over\-TLS protocol, and cache ev
.
.IP "" 0
.
.P
Or with multiple upstreams from the same provider
.
.IP "" 4
.
.nf
\&\. {
forward \. tls://1\.1\.1\.1 tls://1\.0\.0\.1 {
tls_servername loudflare\-dns\.com
health_check 5s
}
cache 30
}
.
.fi
.
.IP "" 0
.
.SH "BUGS"
The TLS config is global for the whole forwarding proxy if you need a different \fBtls_servername\fR for different upstreams you\'re out of luck\.
.

4
man/coredns-health.7
View file

@ -1,13 +1,13 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-HEALTH" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-HEALTH" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIhealth\fR \- enables a health check endpoint\.
.
.SH "DESCRIPTION"
By enabling \fIhealth\fR any plugin that implements healt\.Healther interface \fIhttps://godoc\.org/github\.com/coredns/coredns/plugin/health#Healther\fR will be queried for it\'s health\. The combined health is exported, by default, on port 8080/health \.
By enabling \fIhealth\fR any plugin that implements health\.Healther interface \fIhttps://godoc\.org/github\.com/coredns/coredns/plugin/health#Healther\fR will be queried for it\'s health\. The combined health is exported, by default, on port 8080/health \.
.
.SH "SYNTAX"
.

43
man/coredns-kubernetes.7
View file

@ -1,16 +1,16 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-KUBERNETES" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-KUBERNETES" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIkubernetes\fR \- enables the reading zone data from a Kubernetes cluster\.
.
.SH "DESCRIPTION"
It implements the Kubernetes DNS\-Based Service Discovery Specification \fIhttps://github\.com/kubernetes/dns/blob/master/docs/specification\.md\fR\.
This plugin implements the Kubernetes DNS\-Based Service Discovery Specification \fIhttps://github\.com/kubernetes/dns/blob/master/docs/specification\.md\fR\.
.
.P
CoreDNS running the kubernetes plugin can be used as a replacement of kube\-dns in a kubernetes cluster\. See the deployment \fIhttps://github\.com/coredns/deployment\fR repository for details on how to deploy CoreDNS in Kubernetes \fIhttps://github\.com/coredns/deployment/tree/master/kubernetes\fR\.
CoreDNS running the kubernetes plugin can be used as a replacement for kube\-dns in a kubernetes cluster\. See the deployment \fIhttps://github\.com/coredns/deployment\fR repository for details on how to deploy CoreDNS in Kubernetes \fIhttps://github\.com/coredns/deployment/tree/master/kubernetes\fR\.
.
.P
stubDomains and upstreamNameservers \fIhttp://blog\.kubernetes\.io/2017/04/configuring\-private\-dns\-zones\-upstream\-nameservers\-kubernetes\.html\fR are implemented via the \fIproxy\fR plugin and kubernetes \fIupstream\fR\. See example below\.
@ -27,7 +27,7 @@ kubernetes [ZONES\.\.\.]
.fi
.
.P
With only the directive specified, the \fIkubernetes\fR plugin will default to the zone specified in the server\'s block\. It will handle all queries in that zone and connect to Kubernetes in\-cluster\. It will not provide PTR records for services, or A records for pods\. If \fBZONES\fR is used it specifies all the zones the plugin should be authoritative for\.
With only the directive specified, the \fIkubernetes\fR plugin will default to the zone specified in the server\'s block\. It will handle all queries in that zone and connect to Kubernetes in\-cluster\. It will not provide PTR records for services or A records for pods\. If \fBZONES\fR is used it specifies all the zones the plugin should be authoritative for\.
.
.IP "" 4
.
@ -37,14 +37,17 @@ kubernetes [ZONES\.\.\.] {
resyncperiod DURATION
endpoint URL [URL\.\.\.]
tls CERT KEY CACERT
kubeconfig KUBECONFIG CONTEXT
namespaces NAMESPACE\.\.\.
labels EXPRESSION
pods POD\-MODE
endpoint_pod_names
upstream [ADDRESS\.\.\.]
ttl TTL
noendpoints
transfer to ADDRESS\.\.\.
fallthrough [ZONES\.\.\.]
ignore empty_service
}
.
.fi
@ -61,10 +64,10 @@ kubernetes [ZONES\.\.\.] {
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCACERT\fR are the TLS cert, key and the CA cert file names for remote k8s connection\. This option is ignored if connecting in\-cluster (i\.e\. endpoint is not specified)\.
.
.IP "\(bu" 4
\fBkubeconfig\fR \fBKUBECONFIG\fR \fBCONTEXT\fR authenticates the connection to a remote k8s cluster using a kubeconfig file\. It supports TLS, username and password, or token\-based authentication\. This option is ignored if connecting in\-cluster (i\.e\. endpoint is not specified)\.
\fBkubeconfig\fR \fBKUBECONFIG\fR \fBCONTEXT\fR authenticates the connection to a remote k8s cluster using a kubeconfig file\. It supports TLS, username and password, or token\-based authentication\. This option is ignored if connecting in\-cluster (i\.e\., the endpoint is not specified)\.
.
.IP "\(bu" 4
\fBnamespaces\fR \fBNAMESPACE [NAMESPACE\.\.\.]\fR, only exposes the k8s namespaces listed\. If this option is omitted all namespaces are exposed
\fBnamespaces\fR \fBNAMESPACE [NAMESPACE\.\.\.]\fR only exposes the k8s namespaces listed\. If this option is omitted all namespaces are exposed
.
.IP "\(bu" 4
\fBlabels\fR \fBEXPRESSION\fR only exposes the records for Kubernetes objects that match this label selector\. The label selector syntax is described in the Kubernetes User Guide \- Labels \fIhttp://kubernetes\.io/docs/user\-guide/labels/\fR\. An example that only exposes objects labeled as "application=nginx" in the "staging" or "qa" environments, would use: \fBlabels environment in (staging, qa),application=nginx\fR\.
@ -85,25 +88,25 @@ kubernetes [ZONES\.\.\.] {
.
.IP "\(bu" 4
\fBendpoint_pod_names\fR uses the pod name of the pod targeted by the endpoint as the endpoint name in A records, e\.g\. \fBendpoint\-name\.my\-service\.namespace\.svc\.cluster\.local\. in A 1\.2\.3\.4\fR By default, the endpoint\-name name selection is as follows: Use the hostname of the endpoint, or if hostname is not set, use the dashed form of the endpoint IP address (e\.g\. \fB1\-2\-3\-4\.my\-service\.namespace\.svc\.cluster\.local\.\fR) If this directive is included, then name selection for endpoints changes as follows: Use the hostname of the endpoint, or if hostname is not set, use the pod name of the pod targeted by the endpoint\. If there is no pod targeted by the endpoint, use the dashed IP address form\.
\fBendpoint_pod_names\fR uses the pod name of the pod targeted by the endpoint as the endpoint name in A records, e\.g\., \fBendpoint\-name\.my\-service\.namespace\.svc\.cluster\.local\. in A 1\.2\.3\.4\fR By default, the endpoint\-name name selection is as follows: Use the hostname of the endpoint, or if hostname is not set, use the dashed form of the endpoint IP address (e\.g\., \fB1\-2\-3\-4\.my\-service\.namespace\.svc\.cluster\.local\.\fR) If this directive is included, then name selection for endpoints changes as follows: Use the hostname of the endpoint, or if hostname is not set, use the pod name of the pod targeted by the endpoint\. If there is no pod targeted by the endpoint, use the dashed IP address form\.
.
.IP "\(bu" 4
\fBupstream\fR [\fBADDRESS\fR\.\.\.] defines the upstream resolvers used for resolving services that point to external hosts (aka External Services aka CNAMEs)\. If no \fBADDRESS\fR is given, CoreDNS will resolve External Services against itself\. \fBADDRESS\fR can be an IP, an IP:port, or a path to a file structured like resolv\.conf\.
\fBupstream\fR [\fBADDRESS\fR\.\.\.] defines the upstream resolvers used for resolving services that point to external hosts (aka External Services, aka CNAMEs)\. If no \fBADDRESS\fR is given, CoreDNS will resolve External Services against itself\. \fBADDRESS\fR can be an IP, an IP:port, or a path to a file structured like resolv\.conf\.
.
.IP "\(bu" 4
\fBttl\fR allows you to set a custom TTL for responses\. The default (and allowed minimum) is to use 5 seconds, the maximum is capped at 3600 seconds\.
\fBttl\fR allows you to set a custom TTL for responses\. The default (and minimum allowed) is 0 seconds, while the maximum is capped at 3600 seconds\. Setting TTL to 0 will prevent records from being cached\.
.
.IP "\(bu" 4
\fBnoendpoints\fR will turn off the serving of endpoint records by disabling the watch on endpoints\. All endpoint queries and headless service queries will result in an NXDOMAIN\.
.
.IP "\(bu" 4
\fBtransfer\fR enables zone transfers\. It may be specified multiples times\. \fBTo\fR signals the direction (only \fBto\fR is allow)\. \fBADDRESS\fR must be denoted in CIDR notation (127\.0\.0\.1/32 etc\.) or just as plain addresses\. The special wildcard \fB*\fR means: the entire internet\. Sending DNS notifies is not supported\. Deprecated \fIhttps://github\.com/kubernetes/dns/blob/master/docs/specification\.md#26\-\-\-deprecated\-records\fR pod records in the sub domain \fBpod\.cluster\.local\fR are not transferred\.
\fBtransfer\fR enables zone transfers\. It may be specified multiples times\. \fBTo\fR signals the direction (only \fBto\fR is allow)\. \fBADDRESS\fR must be denoted in CIDR notation (127\.0\.0\.1/32 etc\.) or just as plain addresses\. The special wildcard \fB*\fR means: the entire internet\. Sending DNS notifies is not supported\. Deprecated \fIhttps://github\.com/kubernetes/dns/blob/master/docs/specification\.md#26\-\-\-deprecated\-records\fR pod records in the subdomain \fBpod\.cluster\.local\fR are not transferred\.
.
.IP "\(bu" 4
\fBfallthrough\fR \fB[ZONES\.\.\.]\fR If a query for a record in the zones for which the plugin is authoritative results in NXDOMAIN, normally that is what the response will be\. However, if you specify this option, the query will instead be passed on down the plugin chain, which can include another plugin to handle the query\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.IP "\(bu" 4
\fBignore empty_service\fR return NXDOMAIN for services without any ready endpoint addresses (e\.g\. ready pods)\. This allows the querying pod to continue searching for the service in the search path\. The search path could, for example, include another kubernetes cluster\.
\fBignore empty_service\fR return NXDOMAIN for services without any ready endpoint addresses (e\.g\., ready pods)\. This allows the querying pod to continue searching for the service in the search path\. The search path could, for example, include another Kubernetes cluster\.
.
.IP "" 0
.
@ -163,7 +166,7 @@ kubernetes cluster\.local {
.IP "" 0
.
.SH "STUBDOMAINS AND UPSTREAMNAMESERVERS"
Here we use the \fIproxy\fR plugin to implement a stubDomain that forwards \fBexample\.local\fR to the nameserver \fB10\.100\.0\.10:53\fR\. The \fIupstream\fR option in kubernetes means that ExternalName services (CNAMEs) will be resolved using the respective proxy\. Also configured is an upstreamNameserver \fB8\.8\.8\.8:53\fR that will be used for resolving names that do not fall in \fBcluster\.local\fR or \fBexample\.local\fR\.
Here we use the \fIproxy\fR plugin to implement a stubDomain that forwards \fBexample\.local\fR to the nameserver \fB10\.100\.0\.10:53\fR\. The \fIupstream\fR option in the \fIkubernetes\fR plugin means that ExternalName services (CNAMEs) will be resolved using the respective proxy\. Also configured is an upstreamNameserver \fB8\.8\.8\.8:53\fR that will be used for resolving names that do not fall in \fBcluster\.local\fR or \fBexample\.local\fR\.
.
.IP "" 4
.
@ -198,7 +201,7 @@ The configuration above represents the following Kube\-DNS stubDomains and upstr
.IP "" 0
.
.SH "AUTOPATH"
The \fIkubernetes\fR plugin can be used in conjunction with the \fIautopath\fR plugin\. Using this feature enables server\-side domain search path completion in kubernetes clusters\. Note: \fBpods\fR must be set to \fBverified\fR for this to function properly\.
The \fIkubernetes\fR plugin can be used in conjunction with the \fIautopath\fR plugin\. Using this feature enables server\-side domain search path completion in Kubernetes clusters\. Note: \fBpods\fR must be set to \fBverified\fR for this to function properly\.
.
.IP "" 4
.
@ -216,7 +219,7 @@ cluster\.local {
.IP "" 0
.
.SH "FEDERATION"
The \fIkubernetes\fR plugin can be used in conjunction with the \fIfederation\fR plugin\. Using this feature enables serving federated domains from the kubernetes clusters\.
The \fIkubernetes\fR plugin can be used in conjunction with the \fIfederation\fR plugin\. Using this feature enables serving federated domains from the Kubernetes clusters\.
.
.IP "" 4
.
@ -238,21 +241,21 @@ cluster\.local {
Some query labels accept a wildcard value to match any value\. If a label is a valid wildcard (*, or the word "any"), then that label will match all values\. The labels that accept wildcards are:
.
.IP "\(bu" 4
\fIendpoint\fR in an \fBA\fR record request: \fIendpoint\fR\.service\.namespace\.svc\.zone, e\.g\. \fB*\.nginx\.ns\.svc\.cluster\.local\fR
\fIendpoint\fR in an \fBA\fR record request: \fIendpoint\fR\.service\.namespace\.svc\.zone, e\.g\., \fB*\.nginx\.ns\.svc\.cluster\.local\fR
.
.IP "\(bu" 4
\fIservice\fR in an \fBA\fR record request: \fIservice\fR\.namespace\.svc\.zone, e\.g\. \fB*\.ns\.svc\.cluster\.local\fR
\fIservice\fR in an \fBA\fR record request: \fIservice\fR\.namespace\.svc\.zone, e\.g\., \fB*\.ns\.svc\.cluster\.local\fR
.
.IP "\(bu" 4
\fInamespace\fR in an \fBA\fR record request: service\.\fInamespace\fR\.svc\.zone, e\.g\. \fBnginx\.*\.svc\.cluster\.local\fR
\fInamespace\fR in an \fBA\fR record request: service\.\fInamespace\fR\.svc\.zone, e\.g\., \fBnginx\.*\.svc\.cluster\.local\fR
.
.IP "\(bu" 4
\fIport and/or protocol\fR in an \fBSRV\fR request: \fBport_\.\fRprotocol_\.service\.namespace\.svc\.zone\., e\.g\. \fB_http\.*\.service\.ns\.svc\.cluster\.local\fR
\fIport and/or protocol\fR in an \fBSRV\fR request: \fBport_\.\fRprotocol_\.service\.namespace\.svc\.zone\., e\.g\., \fB_http\.*\.service\.ns\.svc\.cluster\.local\fR
.
.IP "\(bu" 4
multiple wild cards are allowed in a single query, e\.g\. \fBA\fR Request \fB*\.*\.svc\.zone\.\fR or \fBSRV\fR request \fB*\.*\.*\.*\.svc\.zone\.\fR
multiple wild cards are allowed in a single query, e\.g\., \fBA\fR Request \fB*\.*\.svc\.zone\.\fR or \fBSRV\fR request \fB*\.*\.*\.*\.svc\.zone\.\fR
.
.IP "" 0
.
.P
For example, Wildcards can be used to resolve all Endpoints for a Service as \fBA\fR records\. e\.g\.: \fB*\.service\.ns\.svc\.myzone\.local\fR will return the Endpoint IPs in the Service \fBservice\fR in namespace \fBdefault\fR: \fB*\.service\.default\.svc\.cluster\.local\. 5 IN A 192\.168\.10\.10 *\.service\.default\.svc\.cluster\.local\. 5 IN A 192\.168\.25\.15\fR This response can be randomized using the \fBloadbalance\fR plugin
For example, wildcards can be used to resolve all Endpoints for a Service as \fBA\fR records\. e\.g\.: \fB*\.service\.ns\.svc\.myzone\.local\fR will return the Endpoint IPs in the Service \fBservice\fR in namespace \fBdefault\fR: \fB*\.service\.default\.svc\.cluster\.local\. 5 IN A 192\.168\.10\.10 *\.service\.default\.svc\.cluster\.local\. 5 IN A 192\.168\.25\.15\fR This response can be randomized using the \fBloadbalance\fR plugin

32
man/coredns-log.7
View file

@ -1,16 +1,16 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-LOG" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-LOG" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIlog\fR \- enables query logging to standard output\.
.
.SH "DESCRIPTION"
By just using \fIlog\fR you dump all queries (and parts for the reply) on standard output\. Options exist to tweak the output a little\.
By just using \fIlog\fR you dump all queries (and parts for the reply) on standard output\. Options exist to tweak the output a little\. The date/time prefix on log lines is RFC3339 formatted with milliseconds\.
.
.P
Note that for busy servers this will incur a performance hit\.
Note that for busy servers logging will incur a performance hit\.
.
.SH "SYNTAX"
.
@ -105,10 +105,10 @@ The following place holders are supported:
\fB{proto}\fR: protocol used (tcp or udp)
.
.IP "\(bu" 4
\fB{when}\fR: time of the query
\fB{remote}\fR: client\'s IP address, for IPv6 addresses these are enclosed in brackets: \fB[::1]\fR
.
.IP "\(bu" 4
\fB{remote}\fR: client\'s IP address, for IPv6 addresses these are enclosed in brackets: \fB[::1]\fR
\fB{local}\fR: server\'s IP address, for IPv6 addresses these are enclosed in brackets: \fB[::1]\fR
.
.IP "\(bu" 4
\fB{size}\fR: request size in bytes
@ -123,10 +123,10 @@ The following place holders are supported:
\fB{rcode}\fR: response RCODE
.
.IP "\(bu" 4
\fB{rsize}\fR: response size
\fB{rsize}\fR: raw (uncompressed), response size (a client may receive a smaller response)
.
.IP "\(bu" 4
\fB{>rflags}\fR: response flags, each set flag will be displayed, e\.g\. "aa, tc"\. This includes the qr bit as well\.
\fB{>rflags}\fR: response flags, each set flag will be displayed, e\.g\. "aa, tc"\. This includes the qr bit as well
.
.IP "\(bu" 4
\fB{>bufsize}\fR: the EDNS0 buffer size advertised in the query
@ -140,6 +140,9 @@ The following place holders are supported:
.IP "\(bu" 4
\fB{>opcode}\fR: query OPCODE
.
.IP "\(bu" 4
\fB{/[LABEL]}\fR: any metadata label is accepted as a place holder if it is enclosed between \fB{/\fR and \fB}\fR\. the place holder will be replaced by the corresponding metadata value or the default value \fB\-\fR if label is not defined\.
.
.IP "" 0
.
.P
@ -149,7 +152,20 @@ The default Common Log Format is:
.
.nf
`{remote}:{port} \- [{when}] {>id} "{type} {class} {name} {proto} {size} {>do} {>bufsize}" {rcode} {>rflags} {rsize} {duration}`
`{remote}:{port} \- {>id} "{type} {class} {name} {proto} {size} {>do} {>bufsize}" {rcode} {>rflags} {rsize} {duration}`
.
.fi
.
.IP "" 0
.
.P
Each of these logs will be outputted with \fBlog\.Infof\fR, so a typical example looks like this:
.
.IP "" 4
.
.nf
2018\-10\-30T19:10:07\.547Z [INFO] [::1]:50759 \- 29008 "A IN example\.org\. udp 41 false 4096" NOERROR qr,rd,ra,ad 68 0\.037990251s
.
.fi
.

28
man/coredns-loop.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-LOOP" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-LOOP" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIloop\fR \- detect simple forwarding loops and halt the server\.
@ -67,7 +67,15 @@ the loop must occur for at least the \fBHINFO\fR query type\.
When CoreDNS logs contain the message \fBForwarding loop detected \.\.\.\fR, this means that the \fBloop\fR detection plugin has detected an infinite forwarding loop in one of the upstream DNS servers\. This is a fatal error because operating with an infinite loop will consume memory and CPU until eventual out of memory death by the host\.
.
.P
A forwarding loop is usually caused by: * Most commonly, CoreDNS forwarding requests directly to itself\. e\.g\. to \fB127\.0\.0\.1\fR or \fB127\.0\.0\.53\fR * Less commonly, CoreDNS forwarding to an upstream server that in turn, forwards requests back to CoreDNS\.
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 \fBproxy\fR or \fBforward\fR 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 \fBproxy\fR or \fBforward\fR are using a file (e\.g\. \fB/etc/resolv\.conf\fR), make sure that file does not contain local addresses\.
@ -76,7 +84,19 @@ To troubleshoot this problem, look in your Corefile for any \fBproxy\fR or \fBfo
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 \fBsystemd\-resolved\fR on the host node\. \fBsystemd\-resolved\fR will, in certain configurations, put \fB127\.0\.0\.53\fR as an upstream into \fB/etc/resolv\.conf\fR\. Kubernetes (\fBkubelet\fR) by default will pass this \fB/etc/resolv/conf\fR file to all Pods using the \fBdefault\fR dnsPolicy (this includes CoreDNS Pods)\. CoreDNS then uses this \fB/etc/resolv\.conf\fR as a list of upstreams to proxy/forward requests to\. Since it contains a local address, CoreDNS ends up forwarding requests to itself\.
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 proxy/forward requests to\. Since it contains a loopback address, CoreDNS ends up forwarding requests to itself\.
.
.P
There are many ways to work around this issue, some are listed here: * Add the following to \fBkubelet\fR: \fB\-\-resolv\-conf /run/systemd/resolve/resolv\.conf\fR\. This flag tells \fBkubelet\fR to pass an alternate \fBresolv\.conf\fR to Pods\. For \fBsystemd\-resolved\fR, \fB/run/systemd/resolve/resolv\.conf\fR is typically the location of the "original" \fB/etc/resolv\.conf\fR\. * Disable \fBsystemd\-resolved\fR on host nodes, and restore \fB/etc/resolv\.conf\fR to the original\. * A quick and dirty fix is to edit your Corefile, replacing \fBproxy \. /etc/resolv\.conf\fR with the ip address of your upstream DNS, for example \fBproxy \. 8\.8\.8\.8\fR\.
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 \fBproxy \. /etc/resolv\.conf\fR with the ip address of your upstream DNS, for example \fBproxy \. 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

2
man/coredns-metadata.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-METADATA" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-METADATA" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fImetadata\fR \- enable a meta data collector\.

15
man/coredns-rewrite.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-REWRITE" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-REWRITE" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIrewrite\fR \- performs internal message rewriting\.
@ -273,6 +273,19 @@ rewrite [continue|stop] name regex STRING STRING answer name STRING STRING
.
.IP "" 0
.
.P
When using \fBexact\fR name rewrite rules, answer gets re\-written automatically, and there is no need defining \fBanswer name\fR instruction\. The below rule rewrites the name in a request from \fBRED\fR to \fBBLUE\fR, and subsequently rewrites the name in a corresponding response from \fBBLUE\fR to \fBRED\fR\. The client in the request would see only \fBRED\fR and no \fBBLUE\fR\.
.
.IP "" 4
.
.nf
rewrite [continue|stop] name exact RED BLUE
.
.fi
.
.IP "" 0
.
.SS "TTL FIELD REWRITES"
At times, the need for rewriting TTL value could arise\. For example, a DNS server may prevent caching by setting TTL as low as zero (\fB0\fR)\. An administrator may want to increase the TTL to prevent caching, e\.g\. to 15 seconds\.
.

26
man/coredns-route53.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ROUTE53" "7" "October 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-ROUTE53" "7" "December 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIroute53\fR \- enables serving zone data from AWS route53\.
@ -32,7 +32,7 @@ route53 [ZONE:HOSTED_ZONE_ID\.\.\.] {
\fBAWS_ACCESS_KEY_ID\fR and \fBAWS_SECRET_ACCESS_KEY\fR the AWS access key ID and secret access key to be used when query AWS (optional)\. If they are not provided, then coredns tries to access AWS credentials the same way as AWS CLI, e\.g\., environmental variables, AWS credentials file, instance profile credentials, etc\.
.
.IP "\(bu" 4
\fBupstream\fR [\fBADDRESS\fR\.\.\.] specifies upstream resolver(s) used for resolving services that point to external hosts (eg\. used to resolve CNAMEs)\. If no \fBADDRESS\fR is given, CoreDNS will resolve against itself\. \fBADDRESS\fR can be an IP, an IP:port or a path to a file structured like resolv\.conf (\fBNB\fR: Currently a bug (#2099) is preventing the use of self\-resolver)\.
\fBupstream\fR [\fBADDRESS\fR\.\.\.] specifies upstream resolver(s) used for resolving services that point to external hosts (eg\. used to resolve CNAMEs)\. If no \fBADDRESS\fR is given, CoreDNS will resolve against itself\. \fBADDRESS\fR can be an IP, an IP:port or a path to a file structured like resolv\.conf\.
.
.IP "\(bu" 4
\fBcredentials\fR used for reading the credential file and setting the profile name for a given zone\.
@ -59,8 +59,9 @@ Enable route53 with implicit AWS credentials and an upstream:
.nf
\&\. {
route53 example\.org\.:Z1Z2Z3Z4DZ5Z6Z7
upstream 10\.0\.0\.1
route53 example\.org\.:Z1Z2Z3Z4DZ5Z6Z7 {
upstream 10\.0\.0\.1
}
}
.
.fi
@ -102,23 +103,6 @@ Enable route53 with fallthrough:
.IP "" 0
.
.P
Enable route53 with AWS credentials file:
.
.IP "" 4
.
.nf
\&\. {
route53 example\.org\.:Z1Z2Z3Z4DZ5Z6Z7 {
credentials_file some\-user
}
}
.
.fi
.
.IP "" 0
.
.P
Enable route53 with multiple hosted zones with the same domain:
.
.IP "" 4