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

Build manual docs (#1721)

Browse source 
Slight tweak in the forward readme, as sublist don't work well to
generate these.
This commit is contained in:
Miek Gieben 2018-04-23 12:47:32 +01:00 • committed by GitHub
parent 12b2ff9740
commit eb7c3ad137
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
19 changed files with 72 additions and 26 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" "February 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-AUTO" "7" "April 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\.

2
man/coredns-bind.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-BIND" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-BIND" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIbind\fR \- overrides the host to which the server should bind\.

2
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" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-DNSSEC" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIdnssec\fR \- enable on\-the\-fly DNSSEC signing of served data\.

2
man/coredns-dnstap.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-DNSTAP" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-DNSTAP" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIdnstap\fR \- enable logging to dnstap

2
man/coredns-erratic.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ERRATIC" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-ERRATIC" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIerratic\fR \- a plugin useful for testing client behavior\.

2
man/coredns-errors.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ERRORS" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-ERRORS" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIerrors\fR \- enable error logging\.

2
man/coredns-etcd.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ETCD" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-ETCD" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIetcd\fR \- enables reading zone data from an etcd instance\.

2
man/coredns-file.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-FILE" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-FILE" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIfile\fR \- enables serving zone data from an RFC 1035\-style master file\.

1
man/coredns-forward.7
View file

@ -80,6 +80,7 @@ forward FROM TO\.\.\. {
\fBexpire\fR \fBDURATION\fR, expire (cached) connections after this time, the default is 10s\.
.
.IP "\(bu" 4
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCA\fR define the TLS properties for TLS connection\. From 0 to 3 arguments can be provided with the meaning as described below
.
.IP "\(bu" 4
\fBtls\fR \- no client authentication is used, and the system CAs are used to verify the server certificate

9
man/coredns-health.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-HEALTH" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-HEALTH" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIhealth\fR \- enables a health check endpoint\.
@ -18,7 +18,7 @@ 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 CoreDNS is healthy\. It returns a 503\. \fIhealth\fR periodically (1s) polls plugin that exports health information\. If any of the plugin signals that it is unhealthy, the server will go unhealthy too\. Each plugin that supports health checks has a section "Health" in their README\.
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\. It returns a 503\. \fIhealth\fR periodically (1s) polls plugins that exports health information\. If any of the plugins signals that it is unhealthy, the server will go unhealthy too\. Each plugin that supports health checks has a section "Health" in their README\.
.
.P
More options can be set with this extended syntax:
@ -41,7 +41,7 @@ Where \fBlameduck\fR will make the process unhealthy then \fIwait\fR for \fBDURA
.IP "" 0
.
.P
If you have multiple Server Block and need to export health for each of the plugins, you must run health endpoints on different ports:
If you have multiple Server Blocks and need to export health for each of the plugins, you must run health endpoints on different ports:
.
.IP "" 4
.
@ -72,6 +72,9 @@ If monitoring is enabled (via the \fIprometheus\fR directive) then the following
.
.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\.
.

18
man/coredns-kubernetes.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-KUBERNETES" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-KUBERNETES" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIkubernetes\fR \- enables the reading zone data from a Kubernetes cluster\.
@ -225,19 +225,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
\fIservice\fR in an \fBA\fR record request: \fIservice\fR\.namespace\.svc\.zone, e\.g\. \fB*\.ns\.svc\.myzone\.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
\fInamespace\fR in an \fBA\fR record request: service\.\fInamespace\fR\.svc\.zone, e\.g\. \fBnginx\.*\.svc\.myzone\.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
\fIport and/or protocol\fR in an \fBSRV\fR request: \fBport_\.\fRprotocol_\.service\.namespace\.svc\.zone\., e\.g\. \fB_http\.*\.service\.ns\.svc\.\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
.
.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
.
.IP "\(bu" 4
Wildcard can be used also to resolve PODs IPs as \fBA\fR records in a Service with ClusterIP\. e\.g\.: \fB*\.service\.ns\.svc\.myzone\.local\fR will return the PODs IPs as the following: \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
.
.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

2
man/coredns-nsid.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-NSID" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-NSID" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fInsid\fR \- adds an identifier of this server to each reply\.

2
man/coredns-pprof.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-PPROF" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-PPROF" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIpprof\fR \- publishes runtime profiling data at endpoints under \fB/debug/pprof\fR\.

40
man/coredns-reload.7
View file

@ -10,7 +10,7 @@
This plugin periodically checks if the Corefile has changed by reading it and calculating its MD5 checksum\. If the file has changed, it reloads CoreDNS with the new Corefile\. This eliminates the need to send a SIGHUP or SIGUSR1 after changing the Corefile\.
.
.P
The reloads are graceful \- you should not see any loss of service when the reload happens\. Even if the new Corefile has an error, CoreDNS will continue to run the old config and an error message will be printed to the log\.
The reloads are graceful \- you should not see any loss of service when the reload happens\. Even if the new Corefile has an error, CoreDNS will continue to run the old config and an error message will be printed to the log\. But see the Bugs section for failure modes\.
.
.P
In some environments (for example, Kubernetes), there may be many CoreDNS instances that started very near the same time and all share a common Corefile\. To prevent these all from reloading at the same time, some jitter is added to the reload check interval\. This is jitter from the perspective of multiple CoreDNS instances; each instance still checks on a regular interval, but all of these instances will have their reloads spread out across the jitter duration\. This isn\'t strictly necessary given that the reloads are graceful, and can be disabled by setting the jitter to \fB0s\fR\.
@ -77,4 +77,42 @@ Check every 10 seconds (jitter is automatically set to 10 / 2 = 5 in this case):
.fi
.
.IP "" 0
.
.SH "BUGS"
The reload happens without data loss (i\.e\. DNS queries keep flowing), but there is a corner case where the reload fails, and you loose functionality\. Consider the following Corefile:
.
.IP "" 4
.
.nf
\&\. {
health :8080
whoami
}
.
.fi
.
.IP "" 0
.
.P
CoreDNS starts and serves health from :8080\. Now you change \fB:8080\fR to \fB:443\fR not knowing a process is already listening on that port\. The process reloads and performs the following steps:
.
.IP "1." 4
close the listener on 8080
.
.IP "2." 4
reload and parse the config again
.
.IP "3." 4
fail to start a new listener on 443
.
.IP "4." 4
fail loading the new Corefile, abort and keep using the old process
.
.IP "" 0
.
.P
After the aborted attempt to reload we are left with the old proceses running, but the listener is closed in step 1; so the health endpoint is broken\. The same can hopen in the prometheus metrics plugin\.
.
.P
In general be careful with assigning new port and expecting reload to work fully\.

2
man/coredns-root.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ROOT" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-ROOT" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIroot\fR \- simply specifies the root of where to find (zone) files\.

2
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" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-ROUTE53" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIroute53\fR \- enables serving zone data from AWS route53\.

2
man/coredns-secondary.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-SECONDARY" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-SECONDARY" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIsecondary\fR \- enables serving a zone retrieved from a primary server\.

2
man/coredns-template.7
View file

@ -1,7 +1,7 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-TEMPLATE" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
.TH "COREDNS\-TEMPLATE" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fItemplate\fR \- allows for dynamic responses based on the incoming query\.

2
plugin/forward/README.md
View file

@ -62,12 +62,14 @@ forward FROM TO... {
* `expire` **DURATION**, expire (cached) connections after this time, the default is 10s.
* `tls` **CERT** **KEY** **CA** define the TLS properties for TLS connection. From 0 to 3 arguments can be
provided with the meaning as described below
* `tls` - no client authentication is used, and the system CAs are used to verify the server certificate
* `tls` **CA** - no client authentication is used, and the file CA is used to verify the server certificate
* `tls` **CERT** **KEY** - client authentication is used with the specified cert/key pair.
The server certificate is verified with the system CAs
* `tls` **CERT** **KEY** **CA** - client authentication is used with the specified cert/key pair.
The server certificate is verified using the specified CA file
* `tls_servername` **NAME** allows you to set a server name in the TLS configuration; for instance 9.9.9.9
needs this to be set to `dns.quad9.net`.
* `policy` specifies the policy to use for selecting upstream servers. The default is `random`.