diff options
author | 2018-01-04 12:53:07 +0000 | |
---|---|---|
committer | 2018-01-04 12:53:07 +0000 | |
commit | 58221f55db5675c6107d19679c46a216ed072aca (patch) | |
tree | f4f86c8ecd35538da492524dec549566daf40809 /plugin | |
parent | 0600f8c058f39c7afec9f915657e06f158d21c47 (diff) | |
download | coredns-58221f55db5675c6107d19679c46a216ed072aca.tar.gz coredns-58221f55db5675c6107d19679c46a216ed072aca.tar.zst coredns-58221f55db5675c6107d19679c46a216ed072aca.zip |
Manual pages (#1346)
* Add manual pages
Generate manual pages from the README and extend README with Name and
Description sections.
The generation requires 'ronn' which may not be available. Just check in
all generated manual pages.
Diffstat (limited to 'plugin')
29 files changed, 257 insertions, 97 deletions
diff --git a/plugin/auto/README.md b/plugin/auto/README.md index 9902ffe8c..500f9ad4f 100644 --- a/plugin/auto/README.md +++ b/plugin/auto/README.md @@ -1,7 +1,10 @@ # auto -*auto* enables serving zone data from an RFC 1035-style master file which is automatically picked -up from disk. +## Name + +*auto* - enables serving zone data from an RFC 1035-style master file which is automatically picked up from disk. + +## Description The *auto* 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 diff --git a/plugin/autopath/README.md b/plugin/autopath/README.md index 64ca853f5..a70b29ab8 100644 --- a/plugin/autopath/README.md +++ b/plugin/autopath/README.md @@ -1,6 +1,10 @@ # autopath -*autopath* allows for server side search path completion. +## Name + +*autopath* - allows for server side search path completion. + +## Description If it sees a query that matches the first element of the configured search path, *autopath* will follow the chain of search path elements and returns the first reply that is not NXDOMAIN. On any diff --git a/plugin/bind/README.md b/plugin/bind/README.md index 7b9ad6af6..989a65b28 100644 --- a/plugin/bind/README.md +++ b/plugin/bind/README.md @@ -1,6 +1,10 @@ # bind -*bind* overrides the host to which the server should bind. +## Name + +*bind* - overrides the host to which the server should bind. + +## Description Normally, the listener binds to the wildcard host. However, you may force the listener to bind to another IP instead. This directive accepts only an address, not a port. diff --git a/plugin/cache/README.md b/plugin/cache/README.md index 9adb4582f..edbc6f8fc 100644 --- a/plugin/cache/README.md +++ b/plugin/cache/README.md @@ -1,6 +1,14 @@ # cache -*cache* enables a frontend cache. It will cache all records except zone transfers and metadata records. +## Name + +*cache* - enables a frontend cache. + +## Description + +With *cache* 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. ## Syntax diff --git a/plugin/chaos/README.md b/plugin/chaos/README.md index 8af6f492a..8ddb2b0c7 100644 --- a/plugin/chaos/README.md +++ b/plugin/chaos/README.md @@ -1,8 +1,13 @@ # chaos -*chaos* allows for responding to TXT queries in the CH class. +## Name -This is useful for retrieving version or author information from the server. +*chaos* - allows for responding to TXT queries in the CH class. + +## 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. ## Syntax diff --git a/plugin/debug/README.md b/plugin/debug/README.md index 5990bf6bb..d6fd1b22c 100644 --- a/plugin/debug/README.md +++ b/plugin/debug/README.md @@ -1,9 +1,15 @@ # debug -*debug* disables the automatic recovery upon a crash so that you'll get a nice stack trace. +## Name -Note that the *errors* plugin (if loaded) will also set a `recover` negating this setting. The main -use of *debug* is to help testing. +*debug* - disables the automatic recovery upon a crash so that you'll get a nice stack trace. + +## Description + +Normally CoreDNS will recover from panics, using *debug* inhibits this. The main use of *debug* is +to help testing. + +Note that the *errors* plugin (if loaded) will also set a `recover` negating this setting. ## Syntax diff --git a/plugin/dnssec/README.md b/plugin/dnssec/README.md index 419823dbf..904fb9269 100644 --- a/plugin/dnssec/README.md +++ b/plugin/dnssec/README.md @@ -1,6 +1,14 @@ # dnssec -*dnssec* enables on-the-fly DNSSEC signing of served data. +## Name + +*dnssec* - enable on-the-fly DNSSEC signing of served data. + +## Description + +With *dnssec* 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 *not* supported. ## Syntax diff --git a/plugin/dnstap/README.md b/plugin/dnstap/README.md index 15c2b4f38..b38f7323d 100644 --- a/plugin/dnstap/README.md +++ b/plugin/dnstap/README.md @@ -1,8 +1,16 @@ # dnstap -*dnstap* enables logging to dnstap, a flexible, structured binary log format for DNS software: http://dnstap.info. +## Name -There is a buffer, expect at least 13 requests before the server sends its dnstap messages to the socket. +*dnstap* - enable logging to dnstap + +## Description + +dnstap is a flexible, structured binary log format for DNS software: http://dnstap.info. With this +plugin you make CoreDNS output dnstap logging. + +Note that there is an internal buffer, so expect at least 13 requests before the server sends its +dnstap messages to the socket. ## Syntax @@ -33,14 +41,10 @@ Log to a remote endpoint. dnstap tcp://127.0.0.1:6000 full ~~~ -## Dnstap command line tool +## Command Line Tool -~~~ sh -% go get github.com/dnstap/golang-dnstap -% cd $GOPATH/src/github.com/dnstap/golang-dnstap/dnstap -% go build -% ./dnstap -~~~ +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>. It's written in Go. The following command listens on the given socket and decodes messages to stdout. @@ -59,3 +63,7 @@ Listen for dnstap messages on port 6000. ~~~ sh % dnstap -l 127.0.0.1:6000 ~~~ + +# See Also + +[dnstap.info](http://dnstap.info). diff --git a/plugin/erratic/README.md b/plugin/erratic/README.md index 3f3f75d3d..045224dc5 100644 --- a/plugin/erratic/README.md +++ b/plugin/erratic/README.md @@ -1,8 +1,12 @@ # erratic -*erratic* is a plugin useful for testing client behavior. +## Name -It returns a static response to all queries, but the responses can be delayed, dropped or truncated. +*erratic* - a plugin useful for testing client behavior. + +## Description + +*erratic* returns a static response to all queries, but the responses can be delayed, dropped or truncated. The *erratic* 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), for AAAA it returns 2001:DB8::53 (see RFC 3849). diff --git a/plugin/errors/README.md b/plugin/errors/README.md index 21b8f4848..db16eaea8 100644 --- a/plugin/errors/README.md +++ b/plugin/errors/README.md @@ -1,6 +1,10 @@ # errors -*errors* enables error logging. +## Name + +*errors* - enable error logging. + +## Description Any errors encountered during the query processing will be printed to standard output. diff --git a/plugin/etcd/README.md b/plugin/etcd/README.md index 7cc396f53..6073a008a 100644 --- a/plugin/etcd/README.md +++ b/plugin/etcd/README.md @@ -1,6 +1,12 @@ # etcd -*etcd* enables reading zone data from an etcd instance. The data in etcd has to be encoded as +## Name + +*etcd* - enables reading zone data from an etcd instance. + +## Description + +The data in etcd has to be encoded as a [message](https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26) like [SkyDNS](https://github.com/skynetservices/skydns). It should also work just like SkyDNS. @@ -41,10 +47,13 @@ etcd [ZONES...] { the proxy plugin. **ADDRESS** can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv.conf. * `tls` followed by: - * no arguments, if the server certificate is signed by a system-installed CA and no client cert is needed - * a single argument that is the CA PEM file, if the server cert is not signed by a system CA and no client cert is needed - * two arguments - path to cert PEM file, the path to private key PEM file - if the server certificate is signed by a system-installed CA and a client certificate is needed - * three arguments - path to cert PEM file, path to client private key PEM file, path to CA PEM file - if the server certificate is not signed by a system-installed CA and client certificate is needed + + * no arguments, if the server certificate is signed by a system-installed CA and no client cert is needed + * a single argument that is the CA PEM file, if the server cert is not signed by a system CA and no client cert is needed + * two arguments - path to cert PEM file, the path to private key PEM file - if the server certificate is signed by a system-installed CA and a client certificate is needed + * three arguments - path to cert PEM file, path to client private key PEM file, path to CA PEM + file - if the server certificate is not signed by a system-installed CA and client certificate + is needed. ## Examples @@ -114,3 +123,7 @@ Querying with dig: % dig @localhost -x 10.0.0.127 +short reverse.skydns.local. ~~~ + +# Bugs + +Only the etcdv2 protocol is supported. diff --git a/plugin/federation/README.md b/plugin/federation/README.md index 54aa3f824..021921cb2 100644 --- a/plugin/federation/README.md +++ b/plugin/federation/README.md @@ -1,7 +1,13 @@ # federation -*federation* enables -[federated](https://kubernetes.io/docs/tasks/federation/federation-service-discovery/) queries to be +## Name + +*federation* - enables federated queries to be resolved via the kubernetes plugin. + +## Description + +Enabling this plugin allows +[Federated](https://kubernetes.io/docs/tasks/federation/federation-service-discovery/) queries to be resolved via the kubernetes plugin. Enabling *federation* without also having *kubernetes* is a noop. @@ -11,6 +17,7 @@ Enabling *federation* without also having *kubernetes* is a noop. ~~~ federation [ZONES...] { NAME DOMAIN +} ~~~ * Each **NAME** and **DOMAIN** defines federation membership. One entry for each. A duplicate diff --git a/plugin/file/README.md b/plugin/file/README.md index 50912ca9c..e3b1bb99d 100644 --- a/plugin/file/README.md +++ b/plugin/file/README.md @@ -1,6 +1,10 @@ # file -*file* enables serving zone data from an RFC 1035-style master file. +## Name + +*file* - enables serving zone data from an RFC 1035-style master file. + +## 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 diff --git a/plugin/health/README.md b/plugin/health/README.md index 69f2ffe49..f423e7088 100644 --- a/plugin/health/README.md +++ b/plugin/health/README.md @@ -1,8 +1,13 @@ # health -*health* enables a simple health check endpoint. +## Name -By default, it listens on port 8080. +*health* - enables a health check endpoint. + +## Description + +By enabling *health* any plugin that implements it will be queried for it's health. The combined +health is exported, by default, on port 8080/health . ## Syntax diff --git a/plugin/hosts/README.md b/plugin/hosts/README.md index 0476e63bb..0b7bef38b 100644 --- a/plugin/hosts/README.md +++ b/plugin/hosts/README.md @@ -1,6 +1,10 @@ # hosts -*hosts* enables serving zone data from a `/etc/hosts` style file. +## Name + +*hosts* - enables serving zone data from a `/etc/hosts` style file. + +## Description The hosts plugin is useful for serving zones from a /etc/hosts file. It serves from a preloaded file that exists on disk. It checks the file for changes and updates the zones accordingly. This diff --git a/plugin/kubernetes/README.md b/plugin/kubernetes/README.md index 097f0e65e..5c3e8e92f 100644 --- a/plugin/kubernetes/README.md +++ b/plugin/kubernetes/README.md @@ -1,6 +1,10 @@ # kubernetes -The *kubernetes* plugin enables the reading zone data from a Kubernetes cluster. +## Name + +*kubernetes* - enables the reading zone data from a Kubernetes cluster. + +## Description It implements the [Kubernetes DNS-Based Service Discovery Specification](https://github.com/kubernetes/dns/blob/master/docs/specification.md). @@ -66,15 +70,15 @@ kubernetes [ZONES...] { option requires substantially more memory than in insecure mode, since it will maintain a watch on all pods. -* `endpoint_pod_names` uses the pod name of the pod targeted by the endpoint as +* `endpoint_pod_names` uses the pod name of the pod targeted by the endpoint as the endpoint name in A records, e.g. `endpoint-name.my-service.namespace.svc.cluster.local. in A 1.2.3.4` - By default, the endpoint-name name selection is as follows: Use the hostname + 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. `1-2-3-4.my-service.namespace.svc.cluster.local.`) 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 + pod name of the pod targeted by the endpoint. If there is no pod targeted by the endpoint, use the dashed IP address form. * `upstream` **ADDRESS [ADDRESS...]** defines the upstream resolvers used for resolving services that point to external hosts (External Services). **ADDRESS** can be an IP, an IP:port, or a path @@ -174,11 +178,8 @@ feature enables serving federated domains from the kubernetes clusters. 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: - * _service_ in an `A` record request: _service_.namespace.svc.zone. - * e.g. `*.ns.svc.myzone.local` - * _namespace_ in an `A` record request: service._namespace_.svc.zone. - * e.g. `nginx.*.svc.myzone.local` - * _port and/or protocol_ in an `SRV` request: __port_.__protocol_.service.namespace.svc.zone. - * e.g. `_http.*.service.ns.svc.` - * multiple wild cards are allowed in a single query. - * e.g. `A` Request `*.*.svc.zone.` or `SRV` request `*.*.*.*.svc.zone.` + * _service_ in an `A` record request: _service_.namespace.svc.zone, e.g. `*.ns.svc.myzone.local` + * _namespace_ in an `A` record request: service._namespace_.svc.zone, e.g. `nginx.*.svc.myzone.local` + * _port and/or protocol_ in an `SRV` request: __port_.__protocol_.service.namespace.svc.zone., + e.g. `_http.*.service.ns.svc.` + * multiple wild cards are allowed in a single query, e.g. `A` Request `*.*.svc.zone.` or `SRV` request `*.*.*.*.svc.zone.` diff --git a/plugin/loadbalance/README.md b/plugin/loadbalance/README.md index 35a0a396c..58a7956e0 100644 --- a/plugin/loadbalance/README.md +++ b/plugin/loadbalance/README.md @@ -1,7 +1,11 @@ # loadbalance -*loadbalance* acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records +## Name + +*loadbalance* - acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records in the answer. + +## Description See [Wikipedia](https://en.wikipedia.org/wiki/Round-robin_DNS) about the pros and cons on this setup. It will take care to sort any CNAMEs before any address records, because some stub resolver diff --git a/plugin/log/README.md b/plugin/log/README.md index 33e3d998e..75e938e1a 100644 --- a/plugin/log/README.md +++ b/plugin/log/README.md @@ -1,6 +1,15 @@ # log -*log* enables query logging to standard output. +## Name + +*log* - enables query logging to standard output. + +## Description + +By just using *log* you dump all queries (and parts for the reply) on standard output. Options exist +to tweak the output a little. + +Note that for busy servers this will incur a performance hit. ## Syntax diff --git a/plugin/metrics/README.md b/plugin/metrics/README.md index 2c80e2ad3..7dfb13676 100644 --- a/plugin/metrics/README.md +++ b/plugin/metrics/README.md @@ -1,7 +1,12 @@ # prometheus -*prometheus* enables [Prometheus](https://prometheus.io/) metrics. +## Name +*prometheus* - enables [Prometheus](https://prometheus.io/) metrics. + +## Description + +With *prometheus* you export metrics from CoreDNS and any plugin that has them. The default location for the metrics is `localhost:9153`. The metrics path is fixed to `/metrics`. The following metrics are exported: diff --git a/plugin/nsid/README.md b/plugin/nsid/README.md index 7ba381280..10c60523f 100644 --- a/plugin/nsid/README.md +++ b/plugin/nsid/README.md @@ -1,6 +1,10 @@ # nsid -*nsid* adds an identifier of this server to each reply. +## Name + +*nsid* - adds an identifier of this server to each reply. + +## Description This plugin implements RFC 5001 and adds an EDNS0 OPT resource record to replies that uniquely identify the server. This is useful in anycast setups to see which server was responsible for diff --git a/plugin/pprof/README.md b/plugin/pprof/README.md index 8e57d25d0..82ece3464 100644 --- a/plugin/pprof/README.md +++ b/plugin/pprof/README.md @@ -1,6 +1,10 @@ # pprof -*pprof* publishes runtime profiling data at endpoints under `/debug/pprof`. +## Name + +*pprof* - publishes runtime profiling data at endpoints under `/debug/pprof`. + +## Description You can visit `/debug/pprof` on your site for an index of the available endpoints. By default it will listen on localhost:6053. @@ -45,3 +49,8 @@ Listen on an all addresses on port 6060: pprof :6060 } ~~~ + +# Also See + +See [Go's pprof documentation](https://golang.org/pkg/net/http/pprof/) and [Profiling Go +Programs](https://blog.golang.org/profiling-go-programs). diff --git a/plugin/proxy/README.md b/plugin/proxy/README.md index 04a9826e2..c5356ea37 100644 --- a/plugin/proxy/README.md +++ b/plugin/proxy/README.md @@ -1,6 +1,10 @@ # proxy -*proxy* facilitates both a basic reverse proxy and a robust load balancer. +## Name + +*proxy* - facilitates both a basic reverse proxy and a robust load balancer. + +## Description The proxy has support for multiple backends. The load balancing features include multiple policies, health checks, and failovers. If all hosts fail their health check the proxy plugin will fail @@ -72,28 +76,30 @@ Currently `protocol` supports `dns` (i.e., standard DNS over UDP/TCP) and `https payload over HTTPS). Note that with `https_google` the entire transport is encrypted. Only *you* and *Google* can see your DNS activity. -* `dns`: uses the standard DNS exchange. You can pass `force_tcp` to make sure that the proxied connection is performed - over TCP, regardless of the inbound request's protocol. -* `https_google`: bootstrap **ADDRESS...** is used to (re-)resolve `dns.google.com` to an address to - connect to. This happens every 300s. If not specified the default is used: 8.8.8.8:53/8.8.4.4:53. - Note that **TO** is *ignored* when `https_google` is used, as its upstream is defined as - `dns.google.com`. - - Debug queries are enabled by default and currently there is no way to turn them off. When CoreDNS - receives a debug query (i.e. the name is prefixed with `o-o.debug.`) a TXT record with Comment - from `dns.google.com` is added. Note this is not always set. -* `grpc`: options are used to control how the TLS connection is made to the gRPC server. +`dns` +: uses the standard DNS exchange. You can pass `force_tcp` to make sure that the proxied connection is performed + over TCP, regardless of the inbound request's protocol. + +`grpc` +: extra options are used to control how the TLS connection is made to the gRPC server. + * None - No client authentication is used, and the system CAs are used to verify the server certificate. * `insecure` - TLS is not used, the connection is made in plaintext (not good in production). * **CACERT** - No client authentication is used, and the file **CACERT** is used to verify the server certificate. * **KEY** **CERT** - Client authentication is used with the specified key/cert pair. The server - certificate is verified with the system CAs. + certificate is verified with the system CAs. * **KEY** **CERT** **CACERT** - Client authentication is used with the specified key/cert pair. The - server certificate is verified using the **CACERT** file. - + server certificate is verified using the **CACERT** file. An out-of-tree plugin that implements the server side of this can be found at [here](https://github.com/infobloxopen/coredns-grpc). +`https_google` +: bootstrap **ADDRESS...** is used to (re-)resolve `dns.google.com`. + + This happens every 300s. If not specified the default is used: 8.8.8.8:53/8.8.4.4:53. + Note that **TO** is *ignored* when `https_google` is used, as its upstream is defined as `dns.google.com`. + + ## Metrics If monitoring is enabled (via the *prometheus* directive) then the following metric is exported: diff --git a/plugin/reverse/README.md b/plugin/reverse/README.md index 97a098def..c0da8676a 100644 --- a/plugin/reverse/README.md +++ b/plugin/reverse/README.md @@ -1,6 +1,13 @@ # reverse -*reverse* allows for dynamic responses to PTR and the related A/AAAA requests. +## Name + +*reverse* - allows for dynamic responses to PTR and the related A/AAAA requests. + +## Description + +If a request matches a regular expression (see Template Syntax below) this plugin will generate a +response. This is only done for "address" records (PTR, A and AAAA). ## Syntax diff --git a/plugin/rewrite/README.md b/plugin/rewrite/README.md index 199d8a5ec..65e0e5905 100644 --- a/plugin/rewrite/README.md +++ b/plugin/rewrite/README.md @@ -1,6 +1,10 @@ # rewrite -*rewrite* performs internal message rewriting. +## Name + +*rewrite* - performs internal message rewriting. + +## Description Rewrites are invisible to the client. There are simple rewrites (fast) and complex rewrites (slower), but they're powerful enough to accommodate most dynamic back-end applications. @@ -28,7 +32,7 @@ When the FIELD is `edns0` an EDNS0 option can be appended to the request as desc If you specify multiple rules and an incoming query matches on multiple rules, the rewrite will behave as following -* `continue` will continue apply the next rule in the rule list. +* `continue` will continue apply the next rule in the rule list. * `stop` will consider the current rule is the last rule and will not continue. Default behaviour for not specifying this rule processing mode is `stop` @@ -42,9 +46,9 @@ Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the Currently supported are `EDNS0_LOCAL`, `EDNS0_NSID` and `EDNS0_SUBNET`. -### `EDNS0_LOCAL` +### EDNS0_LOCAL -This has two fields, code and data. A match is defined as having the same code. Data may be a string or a variable. +This has two fields, code and data. A match is defined as having the same code. Data may be a string or a variable. * A string data can be treated as hex if it starts with `0x`. Example: @@ -64,13 +68,7 @@ rewrites the first local option with code 0xffee, setting the data to "abcd". Eq ~~~ * A variable data is specified with a pair of curly brackets `{}`. Following are the supported variables: - * {qname} - * {qtype} - * {client_ip} - * {client_port} - * {protocol} - * {server_ip} - * {server_port} + {qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}. Example: @@ -78,15 +76,15 @@ Example: rewrite edns0 local set 0xffee {client_ip} ~~~ -### `EDNS0_NSID` +### EDNS0_NSID This has no fields; it will add an NSID option with an empty string for the NSID. If the option already exists and the action is `replace` or `set`, then the NSID in the option will be set to the empty string. -### `EDNS0_SUBNET` +### EDNS0_SUBNET This has two fields, IPv4 bitmask length and IPv6 bitmask length. The bitmask -length is used to extract the client subnet from the source IP address in the query. +length is used to extract the client subnet from the source IP address in the query. Example: @@ -109,7 +107,7 @@ The syntax for the name re-writing is as follows: rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING ``` -The match type, i.e. `exact`, `substring`, etc., triggers re-write: +The match type, i.e. `exact`, `substring`, etc., triggers re-write: * **exact** (default): on exact match of the name in the question section of a request * **substring**: on a partial match of the name in the question section of a request @@ -127,6 +125,7 @@ rewrite name substring service.us-west-1.example.org service.us-west-1.consul ``` Thus: + * Incoming Request Name: `ftp.service.us-west-1.example.org` * Re-written Request Name: `ftp.service.us-west-1.consul` @@ -139,5 +138,6 @@ rewrite name regex (.*)-(us-west-1)\.example\.org {1}.service.{2}.consul ``` Thus: + * Incoming Request Name: `ftp-us-west-1.example.org` * Re-written Request Name: `ftp.service.us-west-1.consul` diff --git a/plugin/root/README.md b/plugin/root/README.md index 41b40e4d3..2cc3df258 100644 --- a/plugin/root/README.md +++ b/plugin/root/README.md @@ -1,9 +1,13 @@ # root -*root* simply specifies the root of where to find (zone) files. +## Name -The default root is the current working directory of CoreDNS. A relative root path is relative to -the current working directory. +*root* - simply specifies the root of where to find (zone) files. + +## Description + +The default root is the current working directory of CoreDNS. The *root* plugin allows you to change +this. A relative root path is relative to the current working directory. ## Syntax diff --git a/plugin/secondary/README.md b/plugin/secondary/README.md index d6cbe465a..bf557973f 100644 --- a/plugin/secondary/README.md +++ b/plugin/secondary/README.md @@ -1,8 +1,14 @@ # secondary -*secondary* enables serving a zone retrieved from a primary server. +## Name -## Syntax +*secondary* - enables serving a zone retrieved from a primary server. + +## Description + +With *secondary* you can transfer (via AXFR) a zone from another server. The retrieved zone is +*not committed* to disk (a violation of the RFC). This means restarting CoreDNS will cause it to + retrieve all secondary zones. ~~~ secondary [ZONES...] @@ -52,3 +58,7 @@ Or re-export the retrieved zone to other secondaries. } } ~~~ + +# Bugs + +Only AXFR is supported and the retrieved zone is not committed to disk. diff --git a/plugin/tls/README.md b/plugin/tls/README.md index d2a56f793..305c7772e 100644 --- a/plugin/tls/README.md +++ b/plugin/tls/README.md @@ -1,7 +1,10 @@ # tls -*tls* allows you to configure the server certificates for the TLS and gRPC servers. -For other types of servers it is ignored. +## Name + +*tls* - allows you to configure the server certificates for the TLS and gRPC servers. + +## Description CoreDNS supports queries that are encrypted using TLS (DNS over Transport Layer Security, RFC 7858) or are using gRPC (https://grpc.io/, not an IETF standard). Normally DNS traffic isn't encrypted at diff --git a/plugin/trace/README.md b/plugin/trace/README.md index 4383423e5..a6d3bf82c 100644 --- a/plugin/trace/README.md +++ b/plugin/trace/README.md @@ -1,6 +1,12 @@ # trace -*trace* enables OpenTracing-based tracing of DNS requests as they go through the plugin chain. +## Name + +*trace* - enables OpenTracing-based tracing of DNS requests as they go through the plugin chain. + +## Description + +With *trace* you enable OpenTracing of how a request flows through CoreDNS. ## Syntax diff --git a/plugin/whoami/README.md b/plugin/whoami/README.md index 6d7024895..044e53790 100644 --- a/plugin/whoami/README.md +++ b/plugin/whoami/README.md @@ -1,9 +1,14 @@ # whoami -*whoami* returns your resolver's local IP address, port and transport. Your IP address is returned - in the additional section as either an A or AAAA record. +## Name -When CoreDNS can not find a Corefile to load, this is the default plugin it loads. +*whoami* - returns your resolver's local IP address, port and transport. + +## Description + +The *whoami* plugin is not really that useful, but can be used for having a simple (fast) endpoint +to test clients against. When *whoami* returns a response it will have your client's IP address the +additional section as either an A or AAAA record. The reply always has an empty answer section. The port and transport are included in the additional section as a SRV record, transport can be "tcp" or "udp". @@ -12,12 +17,12 @@ section as a SRV record, transport can be "tcp" or "udp". ._<transport>.qname. 0 IN SRV 0 0 <port> . ~~~ -If CoreDNS can't find a Corefile on startup this is the *default* plugin that gets loaded. As -such it can be used to check that CoreDNS is responding to queries. Other than that this plugin -is of limited use in production. - The *whoami* plugin will respond to every A or AAAA query, regardless of the query name. +If CoreDNS can't find a Corefile on startup this is the _default_ plugin that gets loaded. As such +it can be used to check that CoreDNS is responding to queries. Other than that this plugin is of +limited use in production. + ## Syntax ~~~ txt |