sync 1.9.4 (#273)

Signed-off-by: Chris O'Haver <cohaver@infoblox.com>
2024-04-21 12:32:00 +00:00 · 2022-09-12 10:35:28 -04:00
parent a5bac5e411
commit 4332dc5f4a
11 changed files with 388 additions and 44 deletions
@@ -0,0 +1,59 @@
+++
+title = "CoreDNS-1.9.3 Release"
+description = "CoreDNS-1.9.4 Release Notes."
+tags = ["Release", "1.9.4", "Notes"]
+release = "1.9.4"
+date = "2022-09-07T00:00:00+00:00"
+author = "coredns"
+++
+
+This is a release with many new features. The most notable addition is a new plugin tsig for validating
+TSIG requests and signing responses. In header plugin a selector of `query` or `response` (default) is added for
+applying the actions. This release also adds lots of enhancements and bug fixes.
+
+## Brought to You By
+
+Abirdcfly
+Alex
+AndreasHuber-CH
+Andy Lindeman
+Chris O'Haver
+Christoph Heer
+Konstantin Demin
+Marius Kimmina
+Md Sahil
+Ondřej Benkovský
+Shane Xie
+TomasKohout
+Vancl
+Yong Tang
+
+
+## Noteworthy Changes
+
+* core: add log listeners for k8s_event plugin (https://github.com/coredns/coredns/pull/5451)
+* core: log DoH HTTP server error logs in CoreDNS format (https://github.com/coredns/coredns/pull/5457)
+* core: warn when domain names are not in RFC1035 preferred syntax (https://github.com/coredns/coredns/pull/5414)
+* plugin/acl: add support for extended DNS errors (https://github.com/coredns/coredns/pull/5532)
+* plugin/cache: add cache disable option (https://github.com/coredns/coredns/pull/5540)
+* plugin/cache: add metadata for wildcard record responses (https://github.com/coredns/coredns/pull/5308)
+* plugin/cache: add option to adjust SERVFAIL response cache TTL (https://github.com/coredns/coredns/pull/5320)
+* plugin/cache: correct responses to Authenticated Data requests (https://github.com/coredns/coredns/pull/5191)
+* plugin/file: add metadata for wildcard record responses (https://github.com/coredns/coredns/pull/5308)
+* plugin/forward: enable multiple forward declarations (https://github.com/coredns/coredns/pull/5127)
+* plugin/forward: health_check needs to normalize a specified domain name (https://github.com/coredns/coredns/pull/5543)
+* plugin/forward: remove unused coredns_forward_sockets_open metric (https://github.com/coredns/coredns/pull/5431)
+* plugin/header: add support for query modification (https://github.com/coredns/coredns/pull/5556)
+* plugin/health: bypass proxy in self health check (https://github.com/coredns/coredns/pull/5401)
+* plugin/health: don't go lameduck when reloading (https://github.com/coredns/coredns/pull/5472)
+* plugin/k8s_external: add support for PTR requests (https://github.com/coredns/coredns/pull/5435)
+* plugin/k8s_external: resolve headless services (https://github.com/coredns/coredns/pull/5505)
+* plugin/kubernetes: make kubernetes client log in CoreDNS format (https://github.com/coredns/coredns/pull/5461)
+* plugin/ready: reset list of readiness plugins on startup (https://github.com/coredns/coredns/pull/5492)
+* plugin/rewrite: add PTR records to supported types (https://github.com/coredns/coredns/pull/5565)
+* plugin/rewrite: fix a crash in rewrite plugin when rule type is missing (https://github.com/coredns/coredns/pull/5459)
+* plugin/rewrite: fix out-of-index issue in rewrite plugin (https://github.com/coredns/coredns/pull/5462)
+* plugin/rewrite: support min and max TTL values (https://github.com/coredns/coredns/pull/5508)
+* plugin/trace : make zipkin HTTP reporter more configurable using Corefile (https://github.com/coredns/coredns/pull/5460)
+* plugin/trace: read trace context info from headers for DOH (https://github.com/coredns/coredns/pull/5439)
+* plugin/tsig: add new plugin TSIG for validating TSIG requests and signing responses (https://github.com/coredns/coredns/pull/4957)
@@ -4,7 +4,7 @@ description = "*cache* enables a frontend cache."
 weight = 8
 tags = ["plugin", "cache"]
 categories = ["plugin"]
-date = "2022-06-09T08:39:42.8774286"
+date = "2022-09-08T18:42:54.8775489"
 +++

 ## Description
@@ -41,6 +41,8 @@ cache [TTL] [ZONES...] {
    denial CAPACITY [TTL] [MINTTL]
    prefetch AMOUNT [[DURATION] [PERCENTAGE%]]
    serve_stale [DURATION] [REFRESH_MODE]
+    servfail DURATION
+    disable success|denial [ZONES...]
 }
 ~~~

@@ -57,15 +59,20 @@ cache [TTL] [ZONES...] {
  **DURATION** defaults to 1m. Prefetching will happen when the TTL drops below **PERCENTAGE**,
  which defaults to `10%`, or latest 1 second before TTL expiration. Values should be in the range `[10%, 90%]`.
  Note the percent sign is mandatory. **PERCENTAGE** is treated as an `int`.
-* `serve_stale`, when serve\_stale is set, cache always will serve an expired entry to a client if there is one
-  available.  When this happens, cache will attempt to refresh the cache entry after sending the expired cache
-  entry to the client. The responses have a TTL of 0. **DURATION** is how far back to consider
-  stale responses as fresh. The default duration is 1h. **REFRESH_MODE** controls when the attempt to refresh
-  the cache happens. `verified` will first verify that an entry is still unavailable from the source before sending
-  the stale response to the client. `immediate` will immediately send the expired response to the client before
+* `serve_stale`, when serve\_stale is set, cache will always serve an expired entry to a client if there is one
+  available as long as it has not been expired for longer than **DURATION** (default 1 hour). By default, the _cache_ plugin will
+  attempt to refresh the cache entry after sending the expired cache entry to the client. The
+  responses have a TTL of 0. **REFRESH_MODE** controls the timing of the expired cache entry refresh.
+  `verify` will first verify that an entry is still unavailable from the source before sending the expired entry to the client.
+  `immediate` will immediately send the expired entry to the client before
  checking to see if the entry is available from the source. **REFRESH_MODE** defaults to `immediate`. Setting this
-  value to `verified` can lead to increased latency when serving stale responses, but will prevent stale entries
+  value to `verify` can lead to increased latency when serving stale responses, but will prevent stale entries
  from ever being served if an updated response can be retrieved from the source.
+* `servfail` cache SERVFAIL responses for **DURATION**.  Setting **DURATION** to 0 will disable caching of SERVFAIL
+  responses.  If this option is not set, SERVFAIL responses will be cached for 5 seconds.  **DURATION** may not be
+  greater than 5 minutes.
+* `disable`  disable the success or denial cache for the listed **ZONES**.  If no **ZONES** are given, the specified
+  cache will be disabled for all zones.

 ## Capacity and Eviction

@@ -123,3 +130,13 @@ example.org {
    }
 }
 ~~~
+
+Enable caching for `example.org`, but do not cache denials in `sub.example.org`:
+
+~~~ corefile
+example.org {
+    cache {
+        disable denial sub.example.org
+    }
+}
+~~~
@@ -4,7 +4,7 @@ description = "*dnstap* enables logging to dnstap."
 weight = 15
 tags = ["plugin", "dnstap"]
 categories = ["plugin"]
-date = "2022-06-09T07:57:48.8774886"
+date = "2022-09-08T18:42:54.8775489"
 +++

 ## Description
@@ -18,11 +18,16 @@ Every message is sent to the socket as soon as it comes in, the *dnstap* plugin
 ## Syntax

 ~~~ txt
-dnstap SOCKET [full]
+dnstap SOCKET [full] {
+  [identity IDENTITY]
+  [version VERSION]
+}
 ~~~

 * **SOCKET** is the socket (path) supplied to the dnstap command line tool.
 * `full` to include the wire-format DNS message.
+* **IDENTITY** to override the identity of the server. Defaults to the hostname.
+* **VERSION** to override the version field. Defaults to the CoreDNS version.

 ## Examples

@@ -50,6 +55,15 @@ Log to a remote endpoint by FQDN.
 dnstap tcp://example.com:6000 full
 ~~~

+Log to a socket, overriding the default identity and version.
+
+~~~ txt
+dnstap /tmp/dnstap.sock {
+  identity my-dns-server1
+  version MyDNSServer-1.2.3
+}
+~~~
+
 ## Command Line Tool

 Dnstap has a command line tool that can be used to inspect the logging. The tool can be found
@@ -4,7 +4,7 @@ description = "*forward* facilitates proxying DNS messages to upstream resolvers
 weight = 20
 tags = ["plugin", "forward"]
 categories = ["plugin"]
-date = "2022-06-09T07:57:48.8774886"
+date = "2022-09-08T18:42:54.8775489"
 +++

 ## Description
@@ -22,8 +22,6 @@ is taken as a healthy upstream. The health check uses the same protocol as speci
 When *all* upstreams are down it assumes health checking as a mechanism has failed and will try to
 connect to a random upstream (which may or may not work).

-This plugin can only be used once per Server Block.
-
 ## Syntax

 In its most basic form, a simple forwarder uses this syntax:
@@ -53,7 +51,7 @@ forward FROM TO... {
    tls CERT KEY CA
    tls_servername NAME
    policy random|round_robin|sequential
-    health_check DURATION [no_rec] [domain DOMAIN]
+    health_check DURATION [no_rec] [domain FQDN]
    max_concurrent MAX
 }
 ~~~
@@ -93,8 +91,8 @@ forward FROM TO... {
  * `<duration>` - use a different duration for health checking, the default duration is 0.5s.
  * `no_rec` - optional argument that sets the RecursionDesired-flag of the dns-query used in health checking to `false`.
    The flag is default `true`.
-  * `domain DOMAIN` - optional arguments that sets the domain of the dns-query used in health checking.
-    If not configured, the requested domain name is `.`. `DOMAIN` is used to configure the domain name.
+  * `domain FQDN` - set the domain name used for health checks to **FQDN**.
+    If not configured, the domain name used for health checks is `.`.
 * `max_concurrent` **MAX** will limit the number of concurrent queries to **MAX**.  Any new query that would
  raise the number of concurrent queries above the **MAX** will result in a REFUSED response. This
  response does not count as a health failure. When choosing a value for **MAX**, pick a number
@@ -144,6 +142,40 @@ example.org {
 }
 ~~~

+Send all requests within `lab.example.local.` to `10.20.0.1`, all requests within `example.local.` (and not in
+`lab.example.local.`) to `10.0.0.1`, all others requests to the servers defined in `/etc/resolv.conf`, and
+caches results. Note that a CoreDNS server configured with multiple _forward_ plugins in a server block will evaluate those
+forward plugins in the order they are listed when serving a request.  Therefore, subdomains should be
+placed before parent domains otherwise subdomain requests will be forwarded to the parent domain's upstream.
+Accordingly, in this example `lab.example.local` is before `example.local`, and `example.local` is before `.`.
+
+~~~ corefile
+. {
+    cache
+    forward lab.example.local 10.20.0.1
+    forward example.local 10.0.0.1
+    forward . /etc/resolv.conf
+}
+~~~
+
+The example above is almost equivalent to the following example, except that example below defines three separate plugin
+chains (and thus 3 separate instances of _cache_).
+
+~~~ corefile
+lab.example.local {
+    cache
+    forward . 10.20.0.1
+}
+example.local {
+    cache
+    forward . 10.0.0.1
+}
+. {
+    cache
+    forward . /etc/resolv.conf
+}
+~~~
+
 Load balance all requests between three resolvers, one of which has a IPv6 address.

 ~~~ corefile
@@ -1,26 +1,28 @@
 +++
 title = "header"
-description = "*header* modifies the header for responses."
+description = "*header* modifies the header for queries and responses."
 weight = 23
 tags = ["plugin", "header"]
 categories = ["plugin"]
-date = "2021-09-21T15:01:04.877489"
+date = "2022-09-08T18:42:54.8775489"
 +++

 ## Description

-*header* ensures that the flags are in the desired state for responses. The modifications are made transparently for
-the client.
+*header* ensures that the flags are in the desired state for queries and responses.
+The modifications are made transparently for the client and subsequent plugins.

 ## Syntax

 ~~~
 header {
-    ACTION FLAGS...
-    ACTION FLAGS...
+    [SELECTOR] ACTION FLAGS...
+    [SELECTOR] ACTION FLAGS...
 }
 ~~~

+* **SELECTOR** defines if the action should be applied on `query` or `response`. In future CoreDNS version the selector will be mandatory. For backwards compatibility the action will be applied on `response` if the selector is undefined.
+
 * **ACTION** defines the state for DNS message header flags. Actions are evaluated in the order they are defined so last one has the
  most precedence. Allowed values are:
    * `set`
@@ -37,7 +39,7 @@ Make sure recursive available `ra` flag is set in all the responses:
 ~~~ corefile
 . {
    header {
-        set ra
+        response set ra
    }
 }
 ~~~
@@ -47,8 +49,18 @@ Make sure "recursion available" `ra` and "authoritative answer" `aa` flags are s
 ~~~ corefile
 . {
    header {
-        set ra aa
-        clear rd
+        response set ra aa
+        response clear rd
+    }
+}
+~~~
+
+Make sure "recursion desired" `rd` is set for all subsequent plugins::
+
+~~~ corefile
+. {
+    header {
+        query set rd
    }
 }
 ~~~
@@ -4,7 +4,7 @@ description = "*health* enables a health check endpoint."
 weight = 24
 tags = ["plugin", "health"]
 categories = ["plugin"]
-date = "2021-09-21T15:01:04.877489"
+date = "2022-09-08T18:42:54.8775489"
 +++

 ## Description
@@ -51,13 +51,13 @@ Doing this is supported but both endpoints ":8080" and ":8081" will export the e

 ## Metrics

-If monitoring is enabled (via the *prometheus* plugin) then the following metric is exported:
+If monitoring is enabled (via the *prometheus* plugin) then the following metrics are exported:

- * `coredns_health_request_duration_seconds{}` - duration to process a HTTP query to the local
-    `/health` endpoint. As this a local operation it should be fast. A (large) increase in this
+ * `coredns_health_request_duration_seconds{}` - The *health* plugin performs a self health check
+    once per second on the `/health` endpoint. This metric is the duration to process that request.
+    As this is a local operation it should be fast. A (large) increase in this
    duration indicates the CoreDNS process is having trouble keeping up with its query load.
- * `coredns_health_request_failures_total{}` - The number of times the internal health check loop
-    failed to query `/health`.
+ * `coredns_health_request_failures_total{}` - The number of times the self health check failed.

 Note that these metrics *do not* have a `server` label, because being overloaded is a symptom of
 the running process, *not* a specific server.
@@ -1,19 +1,19 @@
 +++
 title = "k8s_external"
-description = "*k8s_external* resolves load balancer and external IPs from outside Kubernetes clusters."
+description = "*k8s_external* resolves load balancer, external IPs from outside Kubernetes clusters and if enabled headless services."
 weight = 27
 tags = ["plugin", "k8s_external"]
 categories = ["plugin"]
-date = "2022-04-06T19:05:17.8771784"
+date = "2022-09-08T18:42:54.8775489"
 +++

 ## 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 *kubernetes* plugin is also loaded.
+service and headless services. This plugin is only useful if the *kubernetes* plugin is also loaded.

 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
+AAAA, SRV, and PTR 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.

 By default the apex of the zone will look like the following (assuming the zone used is `example.org`):
@@ -60,6 +60,16 @@ k8s_external [ZONE...] {
 * **APEX** is the name (DNS label) to use for the apex records; it defaults to `dns`.
 * `ttl` allows you to set a custom **TTL** for responses. The default is 5 (seconds).

+If you want to enable headless service resolution, you can do so by adding `headless` option.
+
+~~~
+k8s_external [ZONE...] {
+    headless
+}
+~~~
+
+* if there is a headless service with external IPs set, external IPs will be resolved
+
 ## Examples

 Enable names under `example.org` to be resolved to in-cluster DNS addresses.
@@ -104,6 +114,3 @@ zone transfers.  Notifies are not supported.
 For some background see [resolve external IP address](https://github.com/kubernetes/dns/issues/242).
 And [A records for services with Load Balancer IP](https://github.com/coredns/coredns/issues/1851).

-# Bugs
-
-PTR queries for the reverse zone is not supported.
@@ -1,10 +1,10 @@
 +++
 title = "rewrite"
 description = "*rewrite* performs internal message rewriting."
-weight = 38
+weight = 40
 tags = ["plugin", "rewrite"]
 categories = ["plugin"]
-date = "2021-05-04T08:30:20.8772085"
+date = "2022-09-08T18:42:54.8775489"
 +++

 ## Description
@@ -208,7 +208,7 @@ regular expression and a rewrite name as parameters and works in the same way as

 Note that names in the `AUTHORITY SECTION` and `ADDITIONAL SECTION` will also be
 rewritten following the specified rules. The names returned by the following
-record types: `CNAME`, `DNAME`, `SOA`, `SRV`, `MX`, `NAPTR`, `NS` will be rewritten
+record types: `CNAME`, `DNAME`, `SOA`, `SRV`, `MX`, `NAPTR`, `NS`, `PTR` will be rewritten
 if the `answer value` rule is specified.

 The syntax for the rewrite of DNS request and response is as follows:
@@ -225,6 +225,44 @@ Note that the above syntax is strict.  For response rewrites, only `name`
 rules are allowed to match the question section. The answer rewrite must be
 after the name, as in the syntax example.

+##### Example: PTR Response Value Rewrite
+
+The original response contains the domain `service.consul.` in the `VALUE` part
+of the `ANSWER SECTION`
+
+```
+$ dig @10.1.1.1 30.30.30.10.in-addr.arpa PTR
+
+;; QUESTION SECTION:
+;30.30.30.10.in-addr.arpa. IN PTR
+
+;; ANSWER SECTION:
+30.30.30.10.in-addr.arpa. 60    IN PTR    ftp-us-west-1.service.consul.
+```
+
+The following configuration snippet allows for rewriting of the value
+in the `ANSWER SECTION`:
+
+```
+    rewrite stop {
+        name suffix .arpa .arpa
+        answer name auto
+        answer value (.*)\.service\.consul\. {1}.coredns.rocks.
+    }
+```
+
+Now, the `VALUE` in the `ANSWER SECTION` has been overwritten in the domain part:
+
+```
+$ dig @10.1.1.1 30.30.30.10.in-addr.arpa PTR
+
+;; QUESTION SECTION:
+;30.30.30.10.in-addr.arpa. IN PTR
+
+;; ANSWER SECTION:
+30.30.30.10.in-addr.arpa. 60    IN PTR    ftp-us-west-1.coredns.rocks.
+```
+
 #### Multiple Response Rewrites

 `name` and `value` rewrites can be chained by appending multiple answer rewrite
@@ -276,7 +314,27 @@ The syntax for the TTL rewrite rule is as follows. The meaning of
 An omitted type is defaulted to `exact`.

 ```
-rewrite [continue|stop] ttl [exact|prefix|suffix|substring|regex] STRING SECONDS
+rewrite [continue|stop] ttl [exact|prefix|suffix|substring|regex] STRING [SECONDS|MIN-MAX]
+```
+
+It is possible to supply a range of TTL values in the `SECONDS` parameters instead of a single value.
+If a range is supplied, the TTL value is set to `MIN` if it is below, or set to `MAX` if it is above.
+The TTL value is left unchanged if it is already inside the provided range.
+The ranges can be unbounded on either side.
+
+TTL examples with ranges:
+```
+# rewrite TTL to be between 30s and 300s
+rewrite ttl example.com. 30-300
+
+# cap TTL at 30s
+rewrite ttl example.com. -30 # equivalent to rewrite ttl example.com. 0-30
+
+# increase TTL to a minimum of 30s
+rewrite ttl example.com. 30-
+
+# set TTL to 30s
+rewrite ttl example.com. 30 # equivalent to rewrite ttl example.com. 30-30
 ```

 ## EDNS0 Options
@@ -4,7 +4,7 @@ description = "*template* allows for dynamic responses based on the incoming que
 weight = 45
 tags = ["plugin", "template"]
 categories = ["plugin"]
-date = "2022-06-09T07:57:48.8774886"
+date = "2022-09-08T18:42:54.8775489"
 +++

 ## Description
@@ -245,6 +245,22 @@ Named capture groups can be used to template one response for multiple patterns.
 }
 ~~~

+### Fabricate a CNAME
+
+This example responds with a CNAME to `google.com` for any DNS query made exactly for `foogle.com`.
+The answer will also contain a record for `google.com` if the upstream nameserver can return a record for it of the
+requested type.
+
+~~~ corefile
+. {
+  template IN ANY foogle.com {
+    match "^foogle\.com\.$"
+    answer "foogle.com 60 IN CNAME google.com"
+  }
+  forward . 8.8.8.8
+}
+~~~
+
 ## Also see

 * [Go regexp](https://golang.org/pkg/regexp/) for details about the regex implementation
@@ -4,7 +4,7 @@ description = "*trace* enables OpenTracing-based tracing of DNS requests as they
 weight = 47
 tags = ["plugin", "trace"]
 categories = ["plugin"]
-date = "2021-09-21T15:01:04.877489"
+date = "2022-09-08T18:42:54.8775489"
 +++

 ## Description
@@ -35,6 +35,9 @@ trace [ENDPOINT-TYPE] [ENDPOINT] {
    service NAME
    client_server
    datadog_analytics_rate RATE
+    zipkin_max_backlog_size SIZE
+    zipkin_max_batch_size SIZE
+    zipkin_max_batch_interval DURATION
 }
 ~~~

@@ -46,6 +49,11 @@ trace [ENDPOINT-TYPE] [ENDPOINT] {
 * `datadog_analytics_rate` **RATE** will enable [trace analytics](https://docs.datadoghq.com/tracing/app_analytics) on the traces sent
  from *0* to *1*, *1* being every trace sent will be analyzed. This is a datadog only feature
  (**ENDPOINT-TYPE** needs to be `datadog`)
+* `zipkin_max_backlog_size` configures the maximum backlog size for Zipkin HTTP reporter. When batch size reaches this threshold,
+   spans from the beginning of the batch will be disposed. Default is 1000 backlog size.
+* `zipkin_max_batch_size` configures the maximum batch size for Zipkin HTTP reporter, after which a collect will be triggered. The default batch size is 100 traces.
+* `zipkin_max_batch_interval` configures the maximum duration we will buffer traces before emitting them to the collector using Zipkin HTTP reporter.
+   The default batch interval is 1 second.

 ## Zipkin

@@ -0,0 +1,121 @@
+++
+title = "tsig"
+description = "*tsig* define TSIG keys, validate incoming TSIG signed requests and sign responses."
+weight = 49
+tags = ["plugin", "tsig"]
+categories = ["plugin"]
+date = "2022-09-08T18:42:54.8775489"
+++
+
+## Description
+
+With *tsig*, you can define CoreDNS's TSIG secret keys. Using those keys, *tsig* validates incoming TSIG requests and signs
+responses to those requests. It does not itself sign requests outgoing from CoreDNS; it is up to the
+respective plugins sending those requests to sign them using the keys defined by *tsig*.
+
+The *tsig* plugin can also require that incoming requests be signed for certain query types, refusing requests that do not comply.
+
+## Syntax
+
+~~~
+tsig [ZONE...] {
+  secret NAME KEY
+  secrets FILE
+  require [QTYPE...]
+}
+~~~
+
+   * **ZONE** - the zones *tsig* will TSIG.  By default, the zones from the server block are used.
+
+   * `secret` **NAME** **KEY** - specifies a TSIG secret for **NAME** with **KEY**. Use this option more than once
+   to define multiple secrets. Secrets are global to the server instance, not just for the enclosing **ZONE**.
+
+   * `secrets` **FILE** - same as `secret`, but load the secrets from a file. The file may define any number
+     of unique keys, each in the following `named.conf` format:
+     ```cgo
+     key "example." {
+         secret "X28hl0BOfAL5G0jsmJWSacrwn7YRm2f6U5brnzwWEus=";
+     };
+     ```
+     Each key may also specify an `algorithm` e.g. `algorithm hmac-sha256;`, but this is currently ignored by the plugin.
+
+     * `require` **QTYPE...** - the query types that must be TSIG'd. Requests of the specified types
+   will be `REFUSED` if they are not signed.`require all` will require requests of all types to be
+   signed. `require none` will not require requests any types to be signed. Default behavior is to not require.
+
+## Examples
+
+Require TSIG signed transactions for transfer requests to `example.zone`.
+
+```
+example.zone {
+  tsig {
+    secret example.zone.key. NoTCJU+DMqFWywaPyxSijrDEA/eC3nK0xi3AMEZuPVk=
+    require AXFR IXFR
+  }
+  transfer {
+    to *
+  }
+}
+```
+
+Require TSIG signed transactions for all requests to `auth.zone`.
+
+```
+auth.zone {
+  tsig {
+    secret auth.zone.key. NoTCJU+DMqFWywaPyxSijrDEA/eC3nK0xi3AMEZuPVk=
+    require all
+  }
+  forward . 10.1.0.2
+}
+```
+
+## Bugs
+
+### Secondary
+
+TSIG transfers are not yet implemented for the *secondary* plugin.  The *secondary* plugin will not sign its zone transfer requests.
+
+### Zone Transfer Notifies
+
+With the *transfer* plugin, zone transfer notifications from CoreDNS are not TSIG signed.
+
+### Special Considerations for Forwarding Servers (RFC 8945 5.5)
+
+https://datatracker.ietf.org/doc/html/rfc8945#section-5.5
+
+CoreDNS does not implement this section as follows ...
+
+* RFC requirement:
+  > If the name on the TSIG is not
+of a secret that the server shares with the originator, the server
+MUST forward the message unchanged including the TSIG.
+
+  CoreDNS behavior:
+If ths zone of the request matches the _tsig_ plugin zones, then the TSIG record
+is always stripped. But even when the _tsig_ plugin is not involved, the _forward_ plugin
+may alter the message with compression, which would cause validation failure
+at the destination.
+
+
+* RFC requirement:
+  > If the TSIG passes all checks, the forwarding
+server MUST, if possible, include a TSIG of its own to the
+destination or the next forwarder.
+
+  CoreDNS behavior:
+If ths zone of the request matches the _tsig_ plugin zones, _forward_ plugin will
+proxy the request upstream without TSIG.
+
+
+* RFC requirement:
+  > If no transaction security is
+available to the destination and the message is a query, and if the
+corresponding response has the AD flag (see RFC4035) set, the
+forwarder MUST clear the AD flag before adding the TSIG to the
+response and returning the result to the system from which it
+received the query.
+
+  CoreDNS behavior:
+The AD flag is not cleared.