coredns
/
coredns.io
mirror of https://github.com/coredns/coredns.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

sync plugin docs and notes to 1.9.2 (#262) 

Signed-off-by: Chris O'Haver <cohaver@infoblox.com>
This commit is contained in:
Chris O'Haver 2022-05-12 09:32:36 -04:00 committed by GitHub
parent de832a6b99
commit 430b7eeedb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 136 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
content/blog/coredns-1.9.2.md Normal file
View File

@ -0,0 +1,46 @@
+++
title = "CoreDNS-1.9.2 Release"
description = "CoreDNS-1.9.2 Release Notes."
tags = ["Release", "1.9.2", "Notes"]
release = "1.9.2"
date = "2022-05-13T00:00:00+00:00"
author = "coredns"
+++
This is a release with many added features and security and bug fixes. The most notable one is the
release of 3rd party security audit from Trail of Bits. Security issues discovered by this audit
have all been fixed or covered.
## Brought to You By
Antoine Tollenaere,
Balazs Nagy,
Chris O'Haver,
dilyevsky,
hansedong,
Lorenz Brun,
Marius Kimmina,
nathannaveen,
Ondřej Benkovský,
Patrick W. Healy,
Qasim Sarfraz,
xuweiwei,
Yong Tang
## Noteworthy Changes
* core: add Trail of Bits to list of 3rd party security auditors (https://github.com/coredns/coredns/pull/5356)
* core: avoid usage of pseudo-random number (https://github.com/coredns/coredns/pull/5228)
* plugin/bufsize: don't add OPT RR to non-EDNS0 queries (https://github.com/coredns/coredns/pull/5368)
* plugin/cache: add refresh mode setting to serve_stale (https://github.com/coredns/coredns/pull/5131)
* plugin/cache: fix cache poisoning exploit (https://github.com/coredns/coredns/pull/5174)
* plugin/etcd: fix multi record TXT lookups (https://github.com/coredns/coredns/pull/5293)
* plugin/forward: configurable domain support for healthcheck (https://github.com/coredns/coredns/pull/5281)
* plugin/geoip: read source IP from EDNS0 subnet if provided (https://github.com/coredns/coredns/pull/5183)
* plugin/health: rework overloaded goroutine to support graceful shutdown (https://github.com/coredns/coredns/pull/5244)
* plugin/k8s_external: persist tc bit from lookup to client response (https://github.com/coredns/coredns/pull/4716)
* plugin/k8s_external: set authoritative bit in responses (https://github.com/coredns/coredns/pull/5284)
* plugin/kubernetes: fix k8s start up timeout ticker (https://github.com/coredns/coredns/pull/5361)
* plugin/route53: deprecate plaintext secret in Corefile for route53 plugin (https://github.com/coredns/coredns/pull/5228)
* plugin/route53: expand AWS config/credentials setup. (https://github.com/coredns/coredns/pull/5370)
* plugin/template: fix rcode option documentation (https://github.com/coredns/coredns/pull/5328)

10
content/plugins/acl.md
View File

@ -4,12 +4,18 @@ description = "*acl* enforces access control policies on source ip and prevents
weight = 1
tags = ["plugin", "acl"]
categories = ["plugin"]
date = "2021-02-01T14:59:19.8771982"
date = "2022-05-10T17:23:06.877685"
+++
## Description
With `acl` enabled, users are able to block or filter suspicious DNS queries by configuring IP filter rule sets, i.e. allowing authorized queries to recurse or blocking unauthorized queries.
With `acl` enabled, users are able to block or filter suspicious DNS queries by configuring IP filter rule sets, i.e. allowing authorized queries or blocking unauthorized queries.
When evaluating the rule sets, _acl_ uses the source IP of the TCP/UDP headers of the DNS query received by CoreDNS.
This source IP will be different than the IP of the client originating the request in cases where the source IP of the request is changed in transit. For example:
* if the request passes though an intermediate forwarding DNS server or recursive DNS server before reaching CoreDNS
* if the request traverses a Source NAT before reaching CoreDNS
This plugin can be used multiple times per Server Block.

17
content/plugins/bind.md
View File

@ -4,7 +4,7 @@ description = "*bind* overrides the host to which the server should bind."
weight = 6
tags = ["plugin", "bind"]
categories = ["plugin"]
date = "2022-01-24T14:51:48.8774881"
date = "2022-05-10T17:23:06.877685"
+++
## Description
@ -87,10 +87,17 @@ You can exclude some addresses by their IP or interface name (The following will
## Bugs
When defining more than one server block, take care not to bind more than one server to the same
address and port. Doing so will result in unpredictable behavior (requests may be randomly
served by either server). Keep in mind that *without* the *bind* plugin, a server will bind to all
interfaces, and this will collide with another server if it's using *bind* to listen to an interface
### Avoiding Listener Contention
TL;DR, When adding the _bind_ plugin to a server block, it must also be added to all other server blocks that listen on the same port.
When more than one server block is configured to listen to a common port, those server blocks must either
all use the _bind_ plugin, or all use default binding (no _bind_ plugin). Note that "port" here refers the TCP/UDP port that
a server block is configured to serve (default 53) - not a network interface. For two server blocks listening on the same port,
if one uses the bind plugin and the other does not, two separate listeners will be created that will contend for serving
packets destined to the same address. Doing so will result in unpredictable behavior (requests may be randomly
served by either server). This happens because *without* the *bind* plugin, a server will bind to all
interfaces, and this will collide with another server if it's using *bind* to listen to an address
on the same port. For example, the following creates two servers that both listen on 127.0.0.1:53,
which would result in unpredictable behavior for queries in `a.bad.example.com`:

4
content/plugins/bufsize.md
View File

@ -4,12 +4,13 @@ description = "*bufsize* sizes EDNS0 buffer size to prevent IP fragmentation."
weight = 7
tags = ["plugin", "bufsize"]
categories = ["plugin"]
date = "2020-05-04T14:06:34.8773485"
date = "2022-05-10T17:23:57.8775785"
+++
## Description
*bufsize* limits a requester's UDP payload size.
It prevents IP fragmentation, mitigating certain DNS vulnerabilities.
This will only affect queries that have an OPT RR.
## Syntax
```txt
@ -41,4 +42,3 @@ Enable limiting the buffer size as an authoritative nameserver:
## Considerations
- Setting 1232 bytes to bufsize may avoid fragmentation on the majority of networks in use today, but it depends on the MTU of the physical network links.
- For now, if a client does not use EDNS, this plugin adds OPT RR.

11
content/plugins/cache.md
View File

@ -4,7 +4,7 @@ description = "*cache* enables a frontend cache."
weight = 8
tags = ["plugin", "cache"]
categories = ["plugin"]
date = "2022-04-06T19:05:17.8771784"
date = "2022-05-10T17:23:06.877685"
+++
## Description
@ -40,7 +40,7 @@ cache [TTL] [ZONES...] {
success CAPACITY [TTL] [MINTTL]
denial CAPACITY [TTL] [MINTTL]
prefetch AMOUNT [[DURATION] [PERCENTAGE%]]
serve_stale [DURATION]
serve_stale [DURATION] [REFRESH_MODE]
}
~~~
@ -60,7 +60,12 @@ cache [TTL] [ZONES...] {
* `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.
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
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
from ever being served if an updated response can be retrieved from the source.
## Capacity and Eviction

18
content/plugins/forward.md
View File

@ -4,7 +4,7 @@ description = "*forward* facilitates proxying DNS messages to upstream resolvers
weight = 20
tags = ["plugin", "forward"]
categories = ["plugin"]
date = "2022-01-24T14:51:48.8774881"
date = "2022-05-10T17:23:06.877685"
+++
## Description
@ -53,7 +53,7 @@ forward FROM TO... {
tls CERT KEY CA
tls_servername NAME
policy random|round_robin|sequential
health_check DURATION [no_rec]
health_check DURATION [no_rec] [domain DOMAIN]
max_concurrent MAX
}
~~~
@ -93,6 +93,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.
* `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
@ -185,6 +187,18 @@ service with health checks.
}
~~~
Or configure other domain name for health check requests
~~~ corefile
. {
forward . tls://9.9.9.9 {
tls_servername dns.quad9.net
health_check 5s domain example.org
}
cache 30
}
~~~
Or with multiple upstreams from the same provider
~~~ corefile

36
content/plugins/geoip.md
View File

@ -4,10 +4,11 @@ description = "*geoip* Lookup maxmind geoip2 databases using the client IP, then
weight = 21
tags = ["plugin", "geoip"]
categories = ["plugin"]
date = "2022-01-24T14:51:48.8774881"
date = "2022-05-10T17:23:06.877685"
+++
## Description
The *geoip* plugin add geo location data associated with the client IP, it allows you to configure a [geoIP2 maxmind database](https://dev.maxmind.com/geoip/docs/databases) to add the geo location data associated with the IP address.
The data is added leveraging the *metadata* plugin, values can then be retrieved using it as well, for example:
@ -20,8 +21,8 @@ import (
// ...
if getLongitude := metadata.ValueFunc(ctx, "geoip/longitude"); getLongitude != nil {
if longitude, err := strconv.ParseFloat(getLongitude(), 64); err == nil {
// Do something useful with longitude.
}
// Do something useful with longitude.
}
} else {
// The metadata label geoip/longitude for some reason, was not set.
}
@ -29,26 +30,47 @@ if getLongitude := metadata.ValueFunc(ctx, "geoip/longitude"); getLongitude != n
```
## Databases
The supported databases use city schema such as `City` and `Enterprise`. Other databases types with different schemas are not supported yet.
You can download a [free and public City database](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data).
## Syntax
```txt
```text
geoip [DBFILE]
```
* **DBFILE** the mmdb database file path.
or
```text
geoip [DBFILE] {
[edns-subnet]
}
```
* **DBFILE** the mmdb database file path. We recommend updating your mmdb database periodically for more accurate results.
* `edns-subnet`: Optional. Use [EDNS0 subnet](https://en.wikipedia.org/wiki/EDNS_Client_Subnet) (if present) for Geo IP instead of the source IP of the DNS request. This helps identifying the closest source IP address through intermediary DNS resolvers, and it also makes GeoIP testing easy: `dig +subnet=1.2.3.4 @dns-server.example.com www.geo-aware.com`.
**NOTE:** due to security reasons, recursive DNS resolvers may mask a few bits off of the clients' IP address, which can cause inaccuracies in GeoIP resolution.
There is no defined mask size in the standards, but there are examples: [RFC 7871's example](https://datatracker.ietf.org/doc/html/rfc7871#section-13) conceals the last 72 bits of an IPv6 source address, and NS1 Help Center [mentions](https://help.ns1.com/hc/en-us/articles/360020256573-About-the-EDNS-Client-Subnet-ECS-DNS-extension) that ECS-enabled DNS resolvers send only the first three octets (eg. /24) of the source IPv4 address.
## Examples
The following configuration configures the `City` database.
The following configuration configures the `City` database, and looks up geolocation based on EDNS0 subnet if present.
```txt
. {
geoip /opt/geoip2/db/GeoLite2-City.mmdb
geoip /opt/geoip2/db/GeoLite2-City.mmdb {
edns-subnet
}
metadata # Note that metadata plugin must be enabled as well.
}
```
## Metadata Labels
A limited set of fields will be exported as labels, all values are stored using strings **regardless of their underlying value type**, and therefore you may have to convert it back to its original type, note that numeric values are always represented in base 10.
| Label | Type | Example | Description

19
content/plugins/route53.md
View File

@ -4,7 +4,7 @@ description = "*route53* enables serving zone data from AWS route53."
weight = 42
tags = ["plugin", "route53"]
categories = ["plugin"]
date = "2022-04-06T19:05:17.8771784"
date = "2022-05-10T17:23:57.8775785"
+++
## Description
@ -12,7 +12,7 @@ date = "2022-04-06T19:05:17.8771784"
The route53 plugin is useful for serving zones from resource record
sets in AWS route53. This plugin supports all Amazon Route 53 records
([https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ResourceRecordTypes.html](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ResourceRecordTypes.html)).
The route53 plugin can be used when coredns is deployed on AWS or elsewhere.
The route53 plugin can be used when CoreDNS is deployed on AWS or elsewhere.
## Syntax
@ -34,9 +34,9 @@ route53 [ZONE:HOSTED_ZONE_ID...] {
accessed.
* **AWS\_ACCESS\_KEY\_ID** and **AWS\_SECRET\_ACCESS\_KEY** 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.
to be used when querying AWS (optional). If they are not provided, CoreDNS tries to access
AWS credentials the same way as AWS CLI - environment variables, shared credential file (and optionally
shared config file if `AWS_SDK_LOAD_CONFIG` env is set), and lastly EC2 Instance Roles.
Note the usage of `aws_access_key` has been deprecated and may be removed in future versions. Instead,
user can use other methods to pass crentials, e.g., with environmental variable `AWS_ACCESS_KEY_ID` and
`AWS_SECRET_ACCESS_KEY`, respectively.
@ -44,9 +44,12 @@ route53 [ZONE:HOSTED_ZONE_ID...] {
* `aws_endpoint` can be used to control the endpoint to use when querying AWS (optional). **ENDPOINT** is the
URL of the endpoint to use. If this is not provided the default AWS endpoint resolution will occur.
* `credentials` is used for reading the credential **FILENAME** and setting the **PROFILE** name for a given
zone. **PROFILE** is the AWS account profile name. Defaults to `default`. **FILENAME** is the
AWS credentials filename, defaults to `~/.aws/credentials`.
* `credentials` is used for overriding the shared credentials **FILENAME** and the **PROFILE** name for a
given zone. **PROFILE** is the AWS account profile name. Defaults to `default`. **FILENAME** is the
AWS shared credentials filename, defaults to `~/.aws/credentials`. CoreDNS will only load shared credentials
file and not shared config file (`~/.aws/config`) by default. Set `AWS_SDK_LOAD_CONFIG` env variable to
a truthy value to enable also loading of `~/.aws/config` (e.g. if you want to provide assumed IAM role
configuration). Will be ignored if static keys are set via `aws_access_key`.
* `fallthrough` If zone matches and no record can be generated, pass request to the next plugin.
If **ZONES** is omitted, then fallthrough happens for all zones for which the plugin is

7
content/plugins/template.md
View File

@ -1,10 +1,10 @@
+++
title = "template"
description = "*template* allows for dynamic responses based on the incoming query."
weight = 41
weight = 45
tags = ["plugin", "template"]
categories = ["plugin"]
date = "2020-08-10T08:43:00.877088"
date = "2022-05-10T17:23:06.877685"
+++
## Description
@ -30,7 +30,8 @@ template CLASS TYPE [ZONE...] {
* **REGEX** [Go regexp](https://golang.org/pkg/regexp/) that are matched against the incoming question name. Specifying no regex matches everything (default: `.*`). First matching regex wins.
* `answer|additional|authority` **RR** A [RFC 1035](https://tools.ietf.org/html/rfc1035#section-5) style resource record fragment
built by a [Go template](https://golang.org/pkg/text/template/) that contains the reply.
* `rcode` **CODE** A response code (`NXDOMAIN, SERVFAIL, ...`). The default is `SUCCESS`.
* `rcode` **CODE** A response code (`NXDOMAIN, SERVFAIL, ...`). The default is `NOERROR`. Valid response code values are
per the `RcodeToString` map defined by the `miekg/dns` package in `msg.go`.
* `fallthrough` Continue with the next plugin if the zone matched but no regex matched.
If specific zones are listed (for example `in-addr.arpa` and `ip6.arpa`), then only queries for
those zones will be subject to fallthrough.