cmus-tutorial

package: cmus

title: cmus-tutorial(7)

summary: C* Music Player tutorial

text:
# cmus-tutorial(7)

## NAME
cmus - C* Music Player tutorial

## CONTENTS
Step 1: Starting Cmus

Step 2: Adding Music

Step 3: Playing Tracks From The Library

Step 4: Managing The Queue

Step 5: The Playlists

Step 6: Find that track

Step 7: Customization

Step 8: Quit

Step 9: Further Reading

## Step 1: Starting Cmus
When you first launch cmus (just type cmus in a terminal and press Enter) it will open to the album/artist view, which looks something like this:

```
+---------------------------------------------------------------------+
| Artist / Album             Track                            Library |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                                                                     |
| . 00:00 - 00:00 vol: 100                     all from library | C   |
|                                                                     |
+---------------------------------------------------------------------+
```

This is the view where your artists and albums will be displayed.

## Step 2: Adding Music
Press 5 to switch to the file-browser view so we can add some music. You should see something like this:

```
+---------------------------------------------------------------------+
| Browser - /home/jasonwoof                                           |
| ../                                                                 |
| Desktop/                                                            |
| MySqueak/                                                           |
| audio-projects/                                                     |
| audio/                                                              |
| bin/                                                                |
| config/                                                             |
|                                                                     |
| . 00:00 - 00:00 vol: 100                     all from library | C   |
|                                                                     |
+---------------------------------------------------------------------+
```

Now, use the arrow keys, Enter and Backspace to navigate to where you have audio files stored. To add music to your cmus library, use the arrow keys to highlight a file or folder, and press a. When you press a cmus will move you to the next line down (so that it is easy to add a bunch of files/folders in a row) and start adding the file/folder you pressed a on to your library. This can take a while if you added a folder with a lot in it. As files are added, you will see the second time in the bottom right go up. This is the total duration of all the music in the cmus library.

Note: cmus does not move, duplicate or change your files. It just remembers where they are and caches the metadata (duration, artist, etc.)

Just to be on the safe side, lets save. Type :save and press Enter.

Note: Cmus automatically saves your settings and library and everything when you quit, so you probably won't use the save command much.

## Step 3: Playing Tracks From The Library
Press 2 to go to the simple library view. You should see something like this:

```
+---------------------------------------------------------------------+
| Library ~/.config/cmus/lib.pl - 31 tracks sorted by artist album di |
| Flying Lizards         . Money (That's What I Want)           02:31 |
| Jason Woofenden        . VoR Theme                       2009 01:20 |
| Keali'i Reichel      06. Wanting Memories                1994 04:28 |
| Molly Lewis            . Tom Cruise Crazy                     03:13 |
| NonMemory              . pista1                          2009 03:18 |
| NonMemory            01. pista1                    2009-04-21 04:13 |
| Ray Charles          06. Halleluja I Love Her So              02:33 |
|                                                                     |
| . 00:00 - 2:16:25 vol: 100                   all from library | C   |
|                                                                     |
+---------------------------------------------------------------------+
```

Use the up and down arrow keys to select a track you'd like to hear, and press Enter to play it. Here are some keys to control playback:

Press c to pause/unpause Press right/left to seek by 10 seconds Press </> seek by one minute Press z to play the previous track and b to play the next track

cmus has some great options to control what plays next (if anything) when the track ends. The state of these settings are shown in the bottom right corner. The first of these shows what collection of tracks (currently "all from library") we are playing. Press m to cycle through the different options for this setting. To the right of that (past the "|") cmus shows the state of four toggles. Only toggles which are "on" are shown, so now we only see the C. Here are the toggles:

[C]ontinue

If this is off, cmus will always stop at the end of the track. You can toggle this setting by pressing shift-C.

[R]epeat

If this is on (and continue is on), when cmus reaches the end of the group of tracks you're playing (selected with the m key) it will start again from the beginning. Press r to toggle this setting.

[S]huffle

If this is on, cmus will choose a random order to play all the tracks once. Press s to toggle this option.

[F]ollow

If this is on, cmus will select the currently playing track on track change. Press f to toggle this option.

## Step 4: Managing The Queue
Lets say you're listening to a song, and you want to select which song will play next, without interrupting the currently playing song. No problem! Just go to the song you want to hear next (in any of the views) and press e. The queue is FIFO, meaning if you queue up another track, it will play after the one you already had queued up.

Note: The queue is not affected by the "shuffle" option described above.

Press 4 to view/edit the queue. This view works and looks a lot like the simple library view. The main difference is that you can change the order of the tracks with the p and P keys. You can press shift-D to remove a track from the queue.

When cmus is ready to play another track (it's reached the end of a track and the "continue" setting is on) it will remove the top entry from the queue and start playing it.

## Step 5: The Playlists
The playlists work like another set of libraries (like view 2) except that (like the queue) you manually set the order of the tracks. This can be quite useful if you want to create a mixes of specific tracks or if you want to listen to an audio book without having the chapters play when you're playing "all from library".

The playlists are on view 3. But before we go there, lets add some tracks. Press 2 to go to the simple library view, go to a track you want and press y to add it to a playlist. The only visual feedback you'll get that anything happened is that the highlight will move down one row. Add a few more so you have something to work with.

Now press 3 to go to the playlist. You should see something like this:

```
+---------------------------------------------------------------------+
| Playlist                   Track                              11:32 |
| * default                | Flying Lizards     . Money (Th...  02:31 |
|                          | Jason Woofenden    . VoR T... 2009 01:20 |
|                          | Keali'i Reichel  06. Wanti... 1994 04:28 |
|                          | Molly Lewis        . Tom Cruis...  03:13 |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                                                                     |
| . 00:00 - 00:00 vol: 100                     all from library | C   |
|                                                                     |
+---------------------------------------------------------------------+
```

Just like the queue, you can use the p, P and D keys to move and delete tracks from the playlist.

Note: Changing the view (e.g. by pressing 3) does not affect what cmus will play next. To put cmus into "play from the playlist" mode, press Enter on one of the tracks in the playlist. To switch modes without interrupting the currently-playing song, you can press shift-M.

## Step 6: Find that track
This step shows various ways you can find track(s) you're looking for.

Search: Press 2 to be sure you're on the simple library view, then press / to start a search. Type a word or two from the track you're looking for. cmus will search for tracks that have all those words in them. Press enter to get the keyboard out of the search command, and n to find the next match.

Tree View: Press 1 to select the tree view. Scroll to the artist, press space to show their albums, scroll to the album you want, then press tab so the keyboard controls the right column. Press tab again to get back to the left column.

Filters: See the reference manual (see Further Reading below) for a detailed description on how to quickly (and temporarily) hide most of your music.

## Step 7: Customization
Cmus has some very cool settings you can tweak, like changing the way tracks are displayed (e.g. to display disk numbers), enabling replaygain support or changing the keybindings.

Press 7 for a quick overview of the current keybindings and settings.

To change a setting or keybind, just select it (up/down keys) and press enter. This will put the command for the current setting in the command now (bottom left of your screen), which you can edit to put in a new value/key.

Please see the reference manual (see Further Reading below) for a detailed description of all the commands and settings available.

## Step 8: Quit
When you're done, type :q and press Enter to quit. This will save your settings, library, playlist and queue.

## Step 9: Further Reading
Cmus comes with a great reference manual. Now that you've got the basics down it should be intelligible. Try man cmus in a terminal. If that's not installed, try opening up cmus.txt from the Doc directory, or read the latest version online:

https://github.com/cmus/cmus/blob/master/Doc/cmus.txt

There are more commands and features not covered here like loading and saving playlists, controlling cmus remotely with cmus-remote, etc.


coredns-acl

package: coredns

title: coredns-acl(7)

text:
# coredns-acl(7)

## NAME
acl - enforces access control policies on source ip and prevents unauthorized access to DNS servers.

## 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.

This plugin can be used multiple times per Server Block.

## SYNTAX

```
acl [ZONES...] {

    ACTION [type QTYPE...] [net SOURCE...]
}
```

- ZONES zones it should be authoritative for. If empty, the zones from the configuration block are used.

- ACTION (allow, block, or filter) defines the way to deal with DNS queries matched by this rule. The default action is allow, which means a DNS query not matched by any rules will be allowed to recurse. The difference between block and filter is that block returns status code of REFUSED while filter returns an empty set NOERROR

- QTYPE is the query type to match for the requests to be allowed or blocked. Common resource record types are supported. * stands for all record types. The default behavior for an omitted type QTYPE... is to match all kinds of DNS queries (same as type *).

- SOURCE is the source IP address to match for the requests to be allowed or blocked. Typical CIDR notation and single IP address are supported. * stands for all possible source IP addresses.

## EXAMPLES
To demonstrate the usage of plugin acl, here we provide some typical examples.

Block all DNS queries with record type A from 192.168.0.0/16：

```
. {

    acl {

        block type A net 192.168.0.0/16

    }
}
```

Filter all DNS queries with record type A from 192.168.0.0/16：

```
. {

    acl {

        filter type A net 192.168.0.0/16

    }
}
```

Block all DNS queries from 192.168.0.0/16 except for 192.168.1.0/24:

```
. {

    acl {

        allow net 192.168.1.0/24

        block net 192.168.0.0/16

    }
}
```

Allow only DNS queries from 192.168.0.0/24 and 192.168.1.0/24:

```
. {

    acl {

        allow net 192.168.0.0/24 192.168.1.0/24

        block

    }
}
```

Block all DNS queries from 192.168.1.0/24 towards a.example.org:

```
example.org {

    acl a.example.org {

        block net 192.168.1.0/24

    }
}
```

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metrics are exported:

- coredns_acl_blocked_requests_total{server, zone} - counter of DNS requests being blocked.

- coredns_acl_allowed_requests_total{server} - counter of DNS requests being allowed.

The server and zone labels are explained in the metrics plugin documentation.


coredns-any

title: coredns-any(7)

text:
# coredns-any(7)

## NAME
any - gives a minimal response to ANY queries.

## DESCRIPTION
any basically blocks ANY queries by responding to them with a short HINFO reply. See RFC 8482 ⟨https://tools.ietf.org/html/rfc8482⟩ for details.

## SYNTAX

```
any
```

## EXAMPLES

```
example.org {

    whoami

    any
}
```

A dig +nocmd ANY example.org +noall +answer now returns:

```
example.org.  8482    IN    HINFO    "ANY obsoleted" "See RFC 8482"
```

## SEE ALSO
RFC 8482 ⟨https://tools.ietf.org/html/rfc8482⟩.


coredns-auto

title: coredns-auto(7)

text:
# coredns-auto(7)

## 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. using DNSSEC) correct DNSSEC answers are returned. Only NSEC is supported! If you use this setup you are responsible for re-signing the zonefile. New or changed zones are automatically picked up from disk only when SOA's serial changes. If the zones are not updated via a zone transfer, the serial must be manually changed.

## SYNTAX

```
auto [ZONES...] {

    directory DIR [REGEXP ORIGIN_TEMPLATE]

    reload DURATION
}
```

ZONES zones it should be authoritative for. If empty, the zones from the configuration block are used.

- directory loads zones from the specified DIR. If a file name matches REGEXP it will be used to extract the origin. ORIGIN_TEMPLATE will be used as a template for the origin. Strings like {<number>} are replaced with the respective matches in the file name, e.g. {1} is the first match, {2} is the second. The default is: db.(.*) {1} i.e. from a file with the name db.example.com, the extracted origin will be example.com.

- reload interval to perform reloads of zones if SOA version changes and zonefiles. It specifies how often CoreDNS should scan the directory to watch for file removal and addition. Default is one minute. Value of 0 means to not scan for changes and reload. eg. 30s checks zonefile every 30 seconds and reloads zone when serial changes.

For enabling zone transfers look at the transfer plugin.

All directives from the file plugin are supported. Note that auto will load all zones found, even though the directive might only receive queries for a specific zone. I.e:

```
. {

    auto example.org {

        directory /etc/coredns/zones

    }
}
```

Will happily pick up a zone for example.COM, except it will never be queried, because the auto directive only is authoritative for example.ORG.

## EXAMPLES
Load org domains from /etc/coredns/zones/org and allow transfers to the internet, but send notifies to 10.240.1.1

```
org {

    auto {

        directory /etc/coredns/zones/org

    }

    transfer {

        to *

        to 10.240.1.1

    }
}
```

Load org domains from /etc/coredns/zones/org and looks for file names as www.db.example.org, where example.org is the origin. Scan every 45 seconds.

```
org {

    auto {

        directory /etc/coredns/zones/org www\.db\.(.*) {1}

        reload 45s

    }
}
```

## ALSO
Use the root plugin to help you specify the location of the zone files. See the transfer plugin to enable outgoing zone transfers.


coredns-autopath

title: coredns-autopath(7)

text:
# coredns-autopath(7)

## NAME
autopath - allows for server-side search path completion.

## DESCRIPTION
If the autopath plugin sees a query that matches the first element of the configured search path, it will follow the chain of search path elements and return the first reply that is not NXDOMAIN. On any failures, the original reply is returned. Because autopath returns a reply for a name that wasn't the original question, it will add a CNAME that points from the original name (with the search path element in it) to the name of this answer.

Note: There are several known issues, see the "Bugs" section below.

## SYNTAX

```
autopath [ZONE...] RESOLV-CONF
```

- ZONES zones autopath should be authoritative for.

- RESOLV-CONF points to a resolv.conf like file or uses a special syntax to point to another plugin. For instance @kubernetes, will call out to the kubernetes plugin (for each query) to retrieve the search list it should use.

If a plugin implements the AutoPather interface then it can be used by autopath.

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metric is exported:

•

coredns_autopath_success_total{server} - counter of successfully autopath-ed queries.

The server label is explained in the metrics plugin documentation.

## EXAMPLES

```
autopath my-resolv.conf
```

Use my-resolv.conf as the file to get the search path from. This file only needs to have one line: search domain1 domain2 ...

```
autopath @kubernetes
```

Use the search path dynamically retrieved from the kubernetes plugin.

## BUGS
In Kubernetes, autopath can derive the wrong namespace of a client Pod (and therefore wrong search path) in the following case. To properly build the search path of a client autopath needs to know the namespace of the a Pod making a DNS request. To do this, it relies on the kubernetes plugin's Pod cache to resolve the client's IP address to a Pod. The Pod cache is maintained by an API watch on Pods. When Pod IP assignments change, the Kubernetes API notifies CoreDNS via the API watch. However, that notification is not instantaneous. In the case that a Pod is deleted, and it's IP is immediately provisioned to a Pod in another namespace, and that new Pod make a DNS lookup before the API watch can notify CoreDNS of the change, autopath will resolve the IP to the previous Pod's namespace.

In Kubernetes, autopath is not compatible with Pods running from Windows nodes.

If the server side search ultimately results in a negative answer (e.g. NXDOMAIN), then the client will fruitlessly search all paths manually, thus negating the autopath optimization.


coredns-azure

title: coredns-azure(7)

text:
# coredns-azure(7)

## NAME
azure - enables serving zone data from Microsoft Azure DNS service.

## DESCRIPTION
The azure plugin is useful for serving zones from Microsoft Azure DNS. The azure plugin supports all the DNS records supported by Azure, viz. A, AAAA, CNAME, MX, NS, PTR, SOA, SRV, and TXT record types. NS record type is not supported by azure private DNS.

## SYNTAX

```
azure RESOURCE_GROUP:ZONE... {

    tenant TENANT_ID

    client CLIENT_ID

    secret CLIENT_SECRET

    subscription SUBSCRIPTION_ID

    environment ENVIRONMENT

    fallthrough [ZONES...]

    access private
}
```

- RESOURCE_GROUP:ZONE is the resource group to which the hosted zones belongs on Azure, and ZONE the zone that contains data.

- CLIENT_ID and CLIENT_SECRET are the credentials for Azure, and tenant specifies the TENANT_ID to be used. SUBSCRIPTION_ID is the subscription ID. All of these are needed to access the data in Azure.

- environment specifies the Azure ENVIRONMENT.

- 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 authoritative.

- access specifies if the zone is public or private. Default is public.

## EXAMPLES
Enable the azure plugin with Azure credentials for private zones example.org, example.private:

```
example.org {

    azure resource_group_foo:example.org resource_group_foo:example.private {

      tenant 123abc-123abc-123abc-123abc

      client 123abc-123abc-123abc-234xyz

      subscription 123abc-123abc-123abc-563abc

      secret mysecret

      access private

    }
}
```

## SEE ALSO
The Azure DNS Overview ⟨https://docs.microsoft.com/en-us/azure/dns/dns-overview⟩.


coredns-bind

title: coredns-bind(7)

text:
# coredns-bind(7)

## NAME
bind - overrides the host to which the server should bind.

## DESCRIPTION
Normally, the listener binds to the wildcard host. However, you may want the listener to bind to another IP instead.

If several addresses are provided, a listener will be open on each of the IP provided.

Each address has to be an IP or name of one of the interfaces of the host. Bind by interface name, binds to the IPs on that interface at the time of startup or reload (reload will happen with a SIGHUP or if the config file changes).

If the given argument is an interface name, and that interface has serveral IP addresses, CoreDNS will listen on all of the interface IP addresses (including IPv4 and IPv6).

## SYNTAX

```
bind ADDRESS  ...
```

ADDRESS is an IP address to bind to. When several addresses are provided a listener will be opened on each of the addresses.

## EXAMPLES
To make your socket accessible only to that machine, bind to IP 127.0.0.1 (localhost):

```
. {

    bind 127.0.0.1
}
```

To allow processing DNS requests only local host on both IPv4 and IPv6 stacks, use the syntax:

```
. {

    bind 127.0.0.1 ::1
}
```

If the configuration comes up with several bind plugins, all addresses are consolidated together: The following sample is equivalent to the preceding:

```
. {

    bind 127.0.0.1

    bind ::1
}
```

The following server block, binds on localhost with its interface name (both "127.0.0.1" and "::1"):

```
. {

    bind lo
}
```

## 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 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:

```
a.bad.example.com {

    bind 127.0.0.1

    forward . 1.2.3.4
}
bad.example.com {

    forward . 5.6.7.8
}
```


coredns-bufsize

title: coredns-bufsize(7)

text:
# coredns-bufsize(7)

## NAME
bufsize - sizes EDNS0 buffer size to prevent IP fragmentation.

## DESCRIPTION
bufsize limits a requester's UDP payload size. It prevents IP fragmentation, mitigating certain DNS vulnerabilities.

## SYNTAX

```
bufsize [SIZE]
```

[SIZE] is an int value for setting the buffer size. The default value is 512, and the value must be within 512 - 4096. Only one argument is acceptable, and it covers both IPv4 and IPv6.

## EXAMPLES
Enable limiting the buffer size of outgoing query to the resolver (172.31.0.10):

```
. {

    bufsize 512

    forward . 172.31.0.10

    log
}
```

Enable limiting the buffer size as an authoritative nameserver:

```
. {

    bufsize 512

    file db.example.org

    log
}
```

## 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.


coredns-cache

title: coredns-cache(7)

text:
# coredns-cache(7)

## 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.

Cache will change the query to enable DNSSEC (DNSSEC OK; DO) if it passes through the plugin. If the client didn't request any DNSSEC (records), these are filtered out when replying.

This plugin can only be used once per Server Block.

## SYNTAX

```
cache [TTL] [ZONES...]
```

- TTL max TTL in seconds. If not specified, the maximum TTL will be used, which is 3600 for NOERROR responses and 1800 for denial of existence ones. Setting a TTL of 300: cache 300 would cache records up to 300 seconds.

- ZONES zones it should cache for. If empty, the zones from the configuration block are used.

Each element in the cache is cached according to its TTL (with TTL 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.

If you want more control:

```
cache [TTL] [ZONES...] {

    success CAPACITY [TTL] [MINTTL]

    denial CAPACITY [TTL] [MINTTL]

    prefetch AMOUNT [[DURATION] [PERCENTAGE%]]

    serve_stale [DURATION]
}
```

- TTL and ZONES as above.

- success, override the settings for caching successful responses. CAPACITY indicates the maximum number of packets we cache before we start evicting (randomly). TTL overrides the cache maximum TTL. MINTTL overrides the cache minimum TTL (default 5), which can be useful to limit queries to the backend.

- denial, override the settings for caching denial of existence responses. CAPACITY indicates the maximum number of packets we cache before we start evicting (LRU). TTL overrides the cache maximum TTL. MINTTL overrides the cache minimum TTL (default 5), which can be useful to limit queries to the backend. There is a third category (error) but those responses are never cached.

- prefetch will prefetch popular items when they are about to be expunged from the cache. Popular means AMOUNT queries have been seen with no gaps of DURATION or more between them. 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.

## CAPACITY AND EVICTION
If CAPACITY is not specified, the default cache size is 9984 per cache. The minimum allowed cache size is 1024. If CAPACITY is specified, the actual cache size used will be rounded down to the nearest number divisible by 256 (so all shards are equal in size).

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.

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metrics are exported:

- coredns_cache_entries{server, type} - Total elements in the cache by cache type.

- coredns_cache_hits_total{server, type} - Counter of cache hits by cache type.

- coredns_cache_misses_total{server} - Counter of cache misses.

- coredns_cache_prefetch_total{server} - Counter of times the cache has prefetched a cached item.

- coredns_cache_drops_total{server} - Counter of responses excluded from the cache due to request/response question name mismatch.

- coredns_cache_served_stale_total{server} - Counter of requests served from stale cache entries.

Cache types are either "denial" or "success". Server is the server handling the request, see the prometheus plugin for documentation.

## EXAMPLES
Enable caching for all zones, but cap everything to a TTL of 10 seconds:

```
. {

    cache 10

    whoami
}
```

Proxy to Google Public DNS and only cache responses for example.org (or below).

```
. {

    forward . 8.8.8.8:53

    cache example.org
}
```

Enable caching for example.org, keep a positive cache size of 5000 and a negative cache size of 2500:

```
example.org {

    cache {

        success 5000

        denial 2500

    }
}
```


coredns-cancel

title: coredns-cancel(7)

text:
# coredns-cancel(7)

## NAME
cancel - cancels a request's context after 5001 milliseconds.

## DESCRIPTION
The cancel plugin creates a canceling context for each request. It adds a timeout that gets triggered after 5001 milliseconds.

The 5001 number was chosen because the default timeout for DNS clients is 5 seconds, after that they give up.

A plugin interested in the cancellation status should call plugin.Done() on the context. If the context was canceled due to a timeout the plugin should not write anything back to the client and return a value indicating CoreDNS should not either; a zero return value should suffice for that.

## SYNTAX

```
cancel [TIMEOUT]
```

•

TIMEOUT allows setting a custom timeout. The default timeout is 5001 milliseconds (5001 ms)

## EXAMPLES

```
example.org {

    cancel

    whoami
}
```

Or with a custom timeout:

```
example.org {

    cancel 1s

    whoami
}
```

## SEE ALSO
The Go documentation for the context package.


coredns-chaos

title: coredns-chaos(7)

text:
# coredns-chaos(7)

## NAME
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 domain name in the CH class.

## SYNTAX

```
chaos [VERSION] [AUTHORS...]
```

- VERSION is the version to return. Defaults to CoreDNS-<version>, if not set.

- AUTHORS is what authors to return. This defaults to all GitHub handles in the OWNERS files.

Note that you have to make sure that this plugin will get actual queries for the following zones: version.bind, version.server, authors.bind, hostname.bind and id.server.

## EXAMPLES
Specify all the zones in full.

```
version.bind version.server authors.bind hostname.bind id.server {

    chaos CoreDNS-001 info@coredns.io
}
```

Or just default to .:

```
.  {

    chaos CoreDNS-001 info@coredns.io
}
```

And test with dig:

```
% dig @localhost CH TXT version.bind
...
;; ANSWER SECTION:
version.bind.        0    CH    TXT    "CoreDNS-001"
...
```


coredns-clouddns

title: coredns-clouddns(7)

text:
# coredns-clouddns(7)

## NAME
clouddns - enables serving zone data from GCP Cloud DNS.

## DESCRIPTION
The clouddns plugin is useful for serving zones from resource record sets in GCP Cloud DNS. This plugin supports all Google Cloud DNS records ⟨https://cloud.google.com/dns/docs/overview#supported_dns_record_types⟩. This plugin can be used when CoreDNS is deployed on GCP or elsewhere. Note that this plugin accesses the resource records through the Google Cloud API. For records in a privately hosted zone, it is not necessary to place CoreDNS and this plugin in the associated VPC network. In fact the private hosted zone could be created without any associated VPC and this plugin could still access the resource records under the hosted zone.

## SYNTAX

```
clouddns [ZONE:PROJECT_ID:HOSTED_ZONE_NAME...] {

    credentials [FILENAME]

    fallthrough [ZONES...]
}
```

- ZONE the name of the domain to be accessed. When there are multiple zones with overlapping domains (private vs. public hosted zone), CoreDNS does the lookup in the given order here. Therefore, for a non-existing resource record, SOA response will be from the rightmost zone.

- PROJECT_ID the project ID of the Google Cloud project.

- HOSTED_ZONE_NAME the name of the hosted zone that contains the resource record sets to be accessed.

- credentials is used for reading the credential file from FILENAME (normally a .json file).

- 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 authoritative. If specific zones are listed (for example in-addr.arpa and ip6.arpa), then only queries for those zones will be subject to fallthrough.

## EXAMPLES
Enable clouddns with implicit GCP credentials and resolve CNAMEs via 10.0.0.1:

```
example.org {

    clouddns example.org.:gcp-example-project:example-zone

    forward . 10.0.0.1
}
```

Enable clouddns with fallthrough:

```
example.org {

    clouddns example.org.:gcp-example-project:example-zone example.com.:gcp-example-project:example-zone-2 {

        fallthrough example.gov.

    }
}
```

Enable clouddns with multiple hosted zones with the same domain:

```
. {

    clouddns example.org.:gcp-example-project:example-zone example.com.:gcp-example-project:other-example-zone
}
```


coredns-debug

title: coredns-debug(7)

text:
# coredns-debug(7)

## NAME
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 in testing. A side effect of using debug is that log.Debug and log.Debugf messages will be printed to standard output.

Note that the errors plugin (if loaded) will also set a recover, negating this setting.

Enabling this plugin is process-wide: enabling debug in at least one server block enables debug mode globally.

## SYNTAX

```
debug
```

Some plugins will send debug log DNS messages. This is done in the following format:

```
debug: 000000 00 0a 01 00 00 01 00 00 00 00 00 01 07 65 78 61
debug: 000010 6d 70 6c 65 05 6c 6f 63 61 6c 00 00 01 00 01 00
debug: 000020 00 29 10 00 00 00 80 00 00 00
debug: 00002a
```

Using text2pcap (part of Wireshark), this can be converted back to binary, with the following command line: text2pcap -i 17 -u 53,53, where 17 is the protocol (UDP) and 53 are the ports. These ports allow Wireshark to detect these packets as DNS messages.

Each plugin can decide whether to dump messages to aid in debugging.

## EXAMPLES
Disable the ability to recover from crashes and show debug logging:

```
. {

    debug
}
```

## SEE ALSO
https://www.wireshark.org/docs/man-pages/text2pcap.html ⟨https://www.wireshark.org/docs/man-pages/text2pcap.html⟩.


title: coredns-dns64(7)

text:
# coredns-dns64(7)

## NAME
dns64 - enables DNS64 IPv6 transition mechanism.

## DESCRIPTION
The dns64 plugin will when asked for a domain's AAAA records, but only finds A records, synthesizes the AAAA records from the A records.

The synthesis is only performed if the query came in via IPv6.

This translation is for IPv6-only networks that have NAT64 ⟨https://en.wikipedia.org/wiki/NAT64⟩.

## SYNTAX

```
dns64 [PREFIX]
```

•

PREFIX defines a custom prefix instead of the default 64:ff9b::/96.

Or use this slightly longer form with more options:

```
dns64 [PREFIX] {

    [translate_all]

    prefix PREFIX
}
```

- prefix specifies any local IPv6 prefix to use, instead of the well known prefix (64:ff9b::/96)

- translate_all translates all queries, including responses that have AAAA results.

## EXAMPLES
Translate with the default well known prefix. Applies to all queries (if they came in over IPv6).

```
. {

    dns64
}
```

Use a custom prefix.

```
. {

    dns64 64:1337::/96
}
```

Or

```
. {

    dns64 {

        prefix 64:1337::/96

    }
}
```

Enable translation even if an existing AAAA record is present.

```
. {

    dns64 {

        translate_all

    }
}
```

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metrics are exported:

•

coredns_dns64_requests_translated_total{server} - counter of DNS requests translated

The server label is explained in the prometheus plugin documentation.

## BUGS
Not all features required by DNS64 are implemented, only basic AAAA synthesis.

- Support "mapping of separate IPv4 ranges to separate IPv6 prefixes"

- Resolve PTR records

- Make resolver DNSSEC aware. See: RFC 6147 Section 3 ⟨https://tools.ietf.org/html/rfc6147#section-3⟩

## SEE ALSO
See RFC 6147 ⟨https://tools.ietf.org/html/rfc6147⟩ for more information on the DNS64 mechanism.


coredns-dnssec

title: coredns-dnssec(7)

text:
# coredns-dnssec(7)

## NAME
dnssec - enables 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.

This plugin can only be used once per Server Block.

## SYNTAX

```
dnssec [ZONES... ] {

    key file KEY...

    cache_capacity CAPACITY
}
```

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.

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 not supported.

If multiple dnssec plugins are specified in the same zone, the last one specified will be used (See bugs ⟨#bugs⟩).

- ZONES zones that should be signed. If empty, the zones from the configuration block are used.

- key file indicates that KEY file(s) should be read from disk. When multiple keys are specified, RRsets will be signed with all keys. Generating a key can be done with dnssec-keygen: dnssec-keygen -a ECDSAP256SHA256 <zonename>. A key created for zone A can be safely used for zone B. The name of the key file can be specified in one of the following formats

–

basename of the generated key Kexample.org+013+45330

–

generated public key Kexample.org+013+45330.key

–

generated private key Kexample.org+013+45330.private

•

cache_capacity indicates the capacity of the cache. The dnssec plugin uses a cache to store RRSIGs. The default for CAPACITY is 10000.

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metrics are exported:

- coredns_dnssec_cache_entries{server, type} - total elements in the cache, type is "signature".

- coredns_dnssec_cache_hits_total{server} - Counter of cache hits.

- coredns_dnssec_cache_misses_total{server} - Counter of cache misses.

The label server indicated the server handling the request, see the metrics plugin for details.

## EXAMPLES
Sign responses for example.org with the key "Kexample.org.+013+45330.key".

```
example.org {

    dnssec {

        key file Kexample.org.+013+45330

    }

    whoami
}
```

Sign responses for a kubernetes zone with the key "Kcluster.local+013+45129.key".

```
cluster.local {

    kubernetes

    dnssec {

      key file Kcluster.local+013+45129

    }
}
```


coredns-dnstap

title: coredns-dnstap(7)

text:
# coredns-dnstap(7)

## NAME
dnstap - enables logging to dnstap.

## DESCRIPTION
dnstap is a flexible, structured binary log format for DNS software; see https://dnstap.info ⟨https://dnstap.info⟩. With this plugin you make CoreDNS output dnstap logging.

Every message is sent to the socket as soon as it comes in, the dnstap plugin has a buffer of 10000 messages, above that number dnstap messages will be dropped (this is logged).

## SYNTAX

```
dnstap SOCKET [full]
```

- SOCKET is the socket (path) supplied to the dnstap command line tool.

- full to include the wire-format DNS message.

## EXAMPLES
Log information about client requests and responses to /tmp/dnstap.sock.

```
dnstap /tmp/dnstap.sock
```

Log information including the wire-format DNS message about client requests and responses to /tmp/dnstap.sock.

```
dnstap unix:///tmp/dnstap.sock full
```

Log to a remote endpoint.

```
dnstap tcp://127.0.0.1:6000 full
```

## COMMAND LINE TOOL
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 ⟨https://github.com/dnstap/golang-dnstap⟩. It's written in Go.

The following command listens on the given socket and decodes messages to stdout.

```
$ dnstap -u /tmp/dnstap.sock
```

The following command listens on the given socket and saves message payloads to a binary dnstap-format log file.

```
$ dnstap -u /tmp/dnstap.sock -w /tmp/test.dnstap
```

Listen for dnstap messages on port 6000.

```
$ dnstap -l 127.0.0.1:6000
```

## USING DNSTAP IN YOUR PLUGIN
In your setup function, check to see if the dnstap plugin is loaded:

```
c.OnStartup(func() error {

    if taph := dnsserver.GetConfig(c).Handler("dnstap"); taph != nil {

        if tapPlugin, ok := taph.(dnstap.Dnstap); ok {

            f.tapPlugin = tapPlugin

        }

    }

    return nil
})
```

And then in your plugin:

```
func (x RandomPlugin) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error) {

    if tapPlugin != nil {

        q := new(msg.Msg)

        msg.SetQueryTime(q, time.Now())

        msg.SetQueryAddress(q, w.RemoteAddr())

        if tapPlugin.IncludeRawMessage {

            buf, _ := r.Pack() // r has been seen packed/unpacked before, this should not fail

            q.QueryMessage = buf

        }

        msg.SetType(q, tap.Message_CLIENT_QUERY)

        tapPlugin.TapMessage(q)

    }

    // ...
}
```

## SEE ALSO
The website dnstap.info ⟨https://dnstap.info⟩ has info on the dnstap protocol. The forward plugin's dnstap.go uses dnstap to tap messages sent to an upstream.


coredns-erratic

title: coredns-erratic(7)

text:
# coredns-erratic(7)

## NAME
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 (except AXFR). The reply for A will return 192.0.2.53 (RFC 5737 ⟨https://tools.ietf.org/html/rfc5737⟩), for AAAA it returns 2001:DB8::53 (RFC 3849 ⟨https://tools.ietf.org/html/rfc3849⟩). For an AXFR request it will respond with a small zone transfer.

## SYNTAX

```
erratic {

    drop [AMOUNT]

    truncate [AMOUNT]

    delay [AMOUNT [DURATION]]
}
```

- drop: drop 1 per AMOUNT of queries, the default is 2.

- truncate: truncate 1 per AMOUNT of queries, the default is 2.

- delay: delay 1 per AMOUNT of queries for DURATION, the default for AMOUNT is 2 and the default for DURATION is 100ms.

In case of a zone transfer and truncate the final SOA record isn't added to the response.

## READY
This plugin reports readiness to the ready plugin.

## EXAMPLES

```
example.org {

    erratic {

        drop 3

    }
}
```

Or even shorter if the defaults suit you. Note this only drops queries, it does not delay them.

```
example.org {

    erratic
}
```

Delay 1 in 3 queries for 50ms

```
example.org {

    erratic {

        delay 3 50ms

    }
}
```

Delay 1 in 3 and truncate 1 in 5.

```
example.org {

    erratic {

        delay 3 5ms

        truncate 5

    }
}
```

Drop every second query.

```
example.org {

    erratic {

        drop 2

        truncate 2

    }
}
```

## SEE ALSO
RFC 3849 ⟨https://tools.ietf.org/html/rfc3849⟩ and RFC 5737 ⟨https://tools.ietf.org/html/rfc5737⟩.


coredns-errors

title: coredns-errors(7)

text:
# coredns-errors(7)

## NAME
errors - enables error logging.

## DESCRIPTION
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.

This plugin can only be used once per Server Block.

## SYNTAX
The basic syntax is:

```
errors
```

Extra knobs are available with an expanded syntax:

```
errors {

    consolidate DURATION REGEXP
}
```

Option consolidate allows collecting several error messages matching the regular expression REGEXP during DURATION. After the DURATION since receiving the first such message, the consolidated message will be printed to standard output, e.g.

```
2 errors like '^read udp .* i/o timeout$' occurred in last 30s
```

Multiple consolidate options with different DURATION and REGEXP are allowed. In case if some error message corresponds to several defined regular expressions the message will be associated with the first appropriate REGEXP.

For better performance, it's recommended to use the ^ or $ metacharacters in regular expression when filtering error messages by prefix or suffix, e.g. ^failed to .*, or .* timeout$.

## EXAMPLES
Use the whoami to respond to queries in the example.org domain and Log errors to standard output.

```
example.org {

    whoami

    errors
}
```

Use the forward 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 ".

```
. {

    forward . 8.8.8.8

    errors {

        consolidate 5m ".* i/o timeout$"

        consolidate 30s "^Failed to .+"

    }
}
```


coredns-etcd

title: coredns-etcd(7)

text:
# coredns-etcd(7)

## NAME
etcd - enables SkyDNS service discovery from etcd.

## DESCRIPTION
The etcd plugin implements the (older) SkyDNS service discovery service. It is not suitable as a generic DNS zone data plugin. Only a subset of DNS record types are implemented, and subdomains and delegations are not handled at all. The plugin will also recursively descend the tree and return all records found, see "Special Behavior" below for details.

The data in the etcd instance 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 works just like SkyDNS.

The etcd plugin makes extensive use of the forward plugin to forward and query other servers in the network - if that plugin has been enabled as well.

## SYNTAX

```
etcd [ZONES...]
```

•

ZONES zones etcd should be authoritative for.

The path will default to /skydns the local etcd3 proxy (http://localhost:2379 ⟨http://localhost:2379⟩). If no zones are specified the block's zone will be used as the zone.

```
etcd [ZONES...] {

    fallthrough [ZONES...]

    path PATH

    endpoint ENDPOINT...

    credentials USERNAME PASSWORD

    tls CERT KEY CACERT
}
```

- fallthrough If zone matches but 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 authoritative. If specific zones are listed (for example in-addr.arpa and ip6.arpa), then only queries for those zones will be subject to fallthrough.

- PATH the path inside etcd. Defaults to "/skydns".

- ENDPOINT the etcd endpoints. Defaults to "http://localhost:2379" ⟨http://localhost:2379"⟩.

- credentials is used to set the USERNAME and PASSWORD for accessing the etcd cluster.

- 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.

## SPECIAL BEHAVIOUR
The etcd plugin leverages directory structure to look for related entries. For example an entry /skydns/test/skydns/mx would have entries like /skydns/test/skydns/mx/a, /skydns/test/skydns/mx/b and so on. Similarly a directory /skydns/test/skydns/mx1 will have all mx1 entries. Note this plugin will search through the entire (sub)tree for records. In case of the first example, a query for mx.skydns.text will return both the contents of the a and b records. If the directory extends deeper those records are returned as well.

With etcd3, support for hierarchical keys are dropped ⟨https://coreos.com/etcd/docs/latest/learning/api.html⟩. This means there are no directories but only flat keys with prefixes in etcd3. To accommodate lookups, the etcd plugin now does a lookup on prefix /skydns/test/skydns/mx/ to search for entries like /skydns/test/skydns/mx/a etc, and if there is nothing found on /skydns/test/skydns/mx/, it looks for /skydns/test/skydns/mx to find entries like /skydns/test/skydns/mx1.

This causes two lookups from CoreDNS to etcd in certain cases.

## EXAMPLES
This is the default SkyDNS setup, with everything specified in full:

```
skydns.local {

    etcd {

        path /skydns

        endpoint http://localhost:2379

    }

    prometheus

    cache

    loadbalance
}
. {

    forward . 8.8.8.8:53 8.8.4.4:53

    cache
}
```

Or a setup where we use /etc/resolv.conf as the basis for the proxy and the upstream when resolving external pointing CNAMEs.

```
skydns.local {

    etcd {

        path /skydns

    }

    cache
}
. {

    forward . /etc/resolv.conf

    cache
}
```

Multiple endpoints are supported as well.

```
etcd skydns.local {

    endpoint http://localhost:2379 http://localhost:4001
...
```

Before getting started with these examples, please setup etcdctl (with etcdv3 API) as explained here ⟨https://coreos.com/etcd/docs/latest/dev-guide/interacting_v3.html⟩. This will help you to put sample keys in your etcd server.

If you prefer, you can use curl to populate the etcd server, but with curl the endpoint URL depends on the version of etcd. For instance, etcd v3.2 or before uses only [CLIENT-URL]/v3alpha/* while etcd v3.5 or later uses [CLIENT-URL]/v3/* . Also, Key and Value must be base64 encoded in the JSON payload. With etcdctl these details are automatically taken care of. You can check this document ⟨https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/api_grpc_gateway.md#notes⟩ for details.

### REVERSE ZONES
Reverse zones are supported. You need to make CoreDNS aware of the fact that you are also authoritative for the reverse. For instance if you want to add the reverse for 10.0.0.0/24, you'll need to add the zone 0.0.10.in-addr.arpa to the list of zones. Showing a snippet of a Corefile:

```
etcd skydns.local 10.0.0.0/24 {
...
```

Next you'll need to populate the zone with reverse records, here we add a reverse for 10.0.0.127 pointing to reverse.skydns.local.

```
% etcdctl put /skydns/arpa/in-addr/10/0/0/127 '{"host":"reverse.skydns.local."}'
```

Querying with dig:

```
% dig @localhost -x 10.0.0.127 +short
reverse.skydns.local.
```

### ZONE NAME AS A RECORD
The zone name itself can be used as an A record. This behavior can be achieved by writing special entries to the ETCD path of your zone. If your zone is named skydns.local for example, you can create an A record for this zone as follows:

```
% etcdctl put /skydns/local/skydns/ '{"host":"1.1.1.1","ttl":60}'
```

If you query the zone name itself, you will receive the created A record:

```
% dig +short skydns.local @localhost
1.1.1.1
```

If you would like to use DNS RR for the zone name, you can set the following:

```
% etcdctl put /skydns/local/skydns/x1 '{"host":"1.1.1.1","ttl":60}'
% etcdctl put /skydns/local/skydns/x2 '{"host":"1.1.1.2","ttl":60}'
```

If you query the zone name now, you will get the following response:

```
% dig +short skydns.local @localhost
1.1.1.1
1.1.1.2
```

### ZONE NAME AS AAAA RECORD
If you would like to use AAAA records for the zone name too, you can set the following:

```
% etcdctl put /skydns/local/skydns/x3 '{"host":"2003::8:1","ttl":60}'
% etcdctl put /skydns/local/skydns/x4 '{"host":"2003::8:2","ttl":60}'
```

If you query the zone name for AAAA now, you will get the following response:

```
% dig +short skydns.local AAAA @localhost
2003::8:1
2003::8:2
```

### SRV RECORD
If you would like to use SRV records, you can set the following:

```
% etcdctl put /skydns/local/skydns/x5 '{"host":"skydns-local.server","ttl":60,"priority":10,"port":8080}'
```

Please notice that the key host is the target in SRV, so it should be a domain name.

If you query the zone name for SRV now, you will get the following response:

```
% dig +short skydns.local SRV @localhost
10 100 8080 skydns-local.server.
```

### TXT RECORD
If you would like to use TXT records, you can set the following:

```
% etcdctl put /skydns/local/skydns/x6 '{"ttl":60,"text":"this is a random text message."}'
```

If you query the zone name for TXT now, you will get the following response:

```
% dig +short skydns.local TXT @localhost
"this is a random text message."
```

## SEE ALSO
If you want to round robin A and AAAA responses look at the loadbalance plugin.


coredns-file

title: coredns-file(7)

text:
# coredns-file(7)

## 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 contained RFC 1035 styled data. 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 you are responsible for re-signing the zonefile.

## SYNTAX

```
file DBFILE [ZONES...]
```

- DBFILE the database file to read and parse. If the path is relative, the path from the root plugin will be prepended to it.

- ZONES zones it should be authoritative for. If empty, the zones from the configuration block are used.

If you want to round-robin A and AAAA responses look at the loadbalance plugin.

```
file DBFILE [ZONES... ] {

    reload DURATION
}
```

•

reload interval to perform a reload of the zone if the SOA version changes. Default is one minute. Value of 0 means to not scan for changes and reload. For example, 30s checks the zonefile every 30 seconds and reloads the zone when serial changes.

If you need outgoing zone transfers, take a look at the transfer plugin.

## EXAMPLES
Load the example.org zone from db.example.org and allow transfers to the internet, but send notifies to 10.240.1.1

```
example.org {

    file db.example.org

    transfer {

        to * 10.240.1.1

    }
}
```

Where db.example.org would contain RRSets (https://tools.ietf.org/html/rfc7719#section-4 ⟨https://tools.ietf.org/html/rfc7719#section-4⟩) in the (text) presentation format from RFC 1035:

```
$ORIGIN example.org.
@    3600 IN    SOA sns.dns.icann.org. noc.dns.icann.org. 2017042745 7200 3600 1209600 3600

    3600 IN NS a.iana-servers.net.

    3600 IN NS b.iana-servers.net.
www     IN A     127.0.0.1

        IN AAAA  ::1
```

Or use a single zone file for multiple zones:

```
. {

    file example.org.signed example.org example.net

    transfer example.org example.net {

        to * 10.240.1.1

    }
}
```

Note that if you have a configuration like the following you may run into a problem of the origin not being correctly recognized:

```
. {

    file db.example.org
}
```

We omit the origin for the file db.example.org, so this references the zone in the server block, which, in this case, is the root zone. Any contents of db.example.org will then read with that origin set; this may or may not do what you want. It's better to be explicit here and specify the correct origin. This can be done in two ways:

```
. {

    file db.example.org example.org
}
```

Or

```
example.org {

    file db.example.org
}
```

## SEE ALSO
See the loadbalance plugin if you need simple record shuffling. And the transfer plugin for zone transfers. Lastly the root plugin can help you specify the location of the zone files.

See RFC 1035 ⟨https://www.rfc-editor.org/rfc/rfc1035.txt⟩ for more info on how to structure zone files.


coredns-forward

title: coredns-forward(7)

text:
# coredns-forward(7)

## NAME
forward - facilitates proxying DNS messages to upstream resolvers.

## DESCRIPTION
The forward plugin re-uses already opened sockets to the upstreams. It supports UDP, TCP and DNS-over-TLS and uses in band health checking.

When it detects an error a health check is performed. This checks runs in a loop, performing each check at a 0.5s interval for as long as the upstream reports unhealthy. Once healthy we stop health checking (until the next error). The health checks use a recursive DNS query (. IN NS) to get upstream health. Any response that is not a network error (REFUSED, NOTIMPL, SERVFAIL, etc) is taken as a healthy upstream. The health check uses the same protocol as specified in TO. If max_fails is set to 0, no checking is performed and upstreams will always be considered healthy.

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:

```
forward FROM TO...
```

- FROM is the base domain to match for the request to be forwarded.

- TO... are the destination endpoints to forward to. The TO syntax allows you to specify a protocol, tls://9.9.9.9 or dns:// (or no protocol) for plain DNS. The number of upstreams is limited to 15.

Multiple upstreams are randomized (see policy) on first use. When a healthy proxy returns an error during the exchange the next upstream in the list is tried.

Extra knobs are available with an expanded syntax:

```
forward FROM TO... {

    except IGNORED_NAMES...

    force_tcp

    prefer_udp

    expire DURATION

    max_fails INTEGER

    tls CERT KEY CA

    tls_servername NAME

    policy random|round_robin|sequential

    health_check DURATION [no_rec]

    max_concurrent MAX
}
```

- FROM and TO... as above.

- IGNORED_NAMES in except is a space-separated list of domains to exclude from forwarding. Requests that match none of these names will be passed through.

- force_tcp, use TCP even when the request comes in over UDP.

- prefer_udp, try first using UDP even when the request comes in over TCP. If response is truncated (TC flag set in response) then do another attempt over TCP. In case if both force_tcp and prefer_udp options specified the force_tcp takes precedence.

- max_fails is the number of subsequent failed health checks that are needed before considering an upstream to be down. If 0, the upstream will never be marked as down (nor health checked). Default is 2.

- 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. Multiple upstreams are still allowed in this scenario, but they have to use the same tls_servername. E.g. mixing 9.9.9.9 (QuadDNS) with 1.1.1.1 (Cloudflare) will not work.

- policy specifies the policy to use for selecting upstream servers. The default is random.

–

random is a policy that implements random upstream selection.

–

round_robin is a policy that selects hosts based on round robin ordering.

–

sequential is a policy that selects hosts based on sequential ordering.

•

health_check configure the behaviour of health checking of the upstream servers

–

<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.

•

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 at least greater than the expected upstream query rate * latency of the upstream servers. As an upper bound for MAX, consider that each concurrent query will use about 2kb of memory.

Also note the TLS config is "global" for the whole forwarding proxy if you need a different tls-name for different upstreams you're out of luck.

On each endpoint, the timeouts for communication are set as follows:

- The dial timeout by default is 30s, and can decrease automatically down to 100ms based on early results.

- The read timeout is static at 2s.

## METADATA
The forward plugin will publish the following metadata, if the metadata plugin is also enabled:

•

forward/upstream: the upstream used to forward the request

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metric are exported:

- coredns_forward_requests_total{to} - query count per upstream.

- coredns_forward_responses_total{to} - Counter of responses received per upstream.

- coredns_forward_request_duration_seconds{to, rcode, type} - duration per upstream, RCODE, type

- coredns_forward_responses_total{to, rcode} - count of RCODEs per upstream.

- coredns_forward_healthcheck_failures_total{to} - number of failed health checks per upstream.

- coredns_forward_healthcheck_broken_total{} - counter of when all upstreams are unhealthy, and we are randomly (this always uses the random policy) spraying to an upstream.

- coredns_forward_max_concurrent_rejects_total{} - counter of the number of queries rejected because the number of concurrent queries were at maximum.

- coredns_forward_conn_cache_hits_total{to, proto} - counter of connection cache hits per upstream and protocol.

- coredns_forward_conn_cache_misses_total{to, proto} - counter of connection cache misses per upstream and protocol. Where to is one of the upstream servers (TO from the config), rcode is the returned RCODE from the upstream, proto is the transport protocol like udp, tcp, tcp-tls.

## EXAMPLES
Proxy all requests within example.org. to a nameserver running on a different port:

```
example.org {

    forward . 127.0.0.1:9005
}
```

Load balance all requests between three resolvers, one of which has a IPv6 address.

```
. {

    forward . 10.0.0.10:53 10.0.0.11:1053 [2003::1]:53
}
```

Forward everything except requests to example.org

```
. {

    forward . 10.0.0.10:1234 {

        except example.org

    }
}
```

Proxy everything except example.org using the host's resolv.conf's nameservers:

```
. {

    forward . /etc/resolv.conf {

        except example.org

    }
}
```

Proxy all requests to 9.9.9.9 using the DNS-over-TLS (DoT) protocol, and cache every answer for up to 30 seconds. Note the tls_servername is mandatory if you want a working setup, as 9.9.9.9 can't be used in the TLS negotiation. Also set the health check duration to 5s to not completely swamp the service with health checks.

```
. {

    forward . tls://9.9.9.9 {

       tls_servername dns.quad9.net

       health_check 5s

    }

    cache 30
}
```

Or with multiple upstreams from the same provider

```
. {

    forward . tls://1.1.1.1 tls://1.0.0.1 {

       tls_servername cloudflare-dns.com

       health_check 5s

    }

    cache 30
}
```

Or when you have multiple DoT upstreams with different tls_servernames, you can do the following:

```
. {

    forward . 127.0.0.1:5301 127.0.0.1:5302
}
.:5301 {

    forward . 8.8.8.8 8.8.4.4 {

        tls_servername dns.google

    }
}
.:5302 {

    forward . 1.1.1.1 1.0.0.1 {

        tls_servername cloudflare-dns.com

    }
}
```

## SEE ALSO
RFC 7858 ⟨https://tools.ietf.org/html/rfc7858⟩ for DNS over TLS.


coredns-geoip

title: coredns-geoip(7)

text:
# coredns-geoip(7)

## NAME
geoip - Lookup maxmind geoip2 databases using the client IP, then add associated geoip data to the context request.

## 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:

```
import (

    "strconv"

    "github.com/coredns/coredns/plugin/metadata"
)
// ...
if getLongitude := metadata.ValueFunc(ctx, "geoip/longitude"); getLongitude != nil {

    if longitude, err := strconv.ParseFloat(getLongitude(), 64); err == nil {

        // Do something useful with longitude.

    }
} else {

    // The metadata label geoip/longitude for some reason, was not set.
}
// ...
```

## 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

```
geoip [DBFILE]
```

•

DBFILE the mmdb database file path.

## EXAMPLES
The following configuration configures the City database.

```
. {

    geoip /opt/geoip2/db/GeoLite2-City.mmdb

    metadata # Note that metadata plugin must be enabled as well.
}
```

## METADATADA 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

geoip/city/name

string

Cambridge

Then city name in English language.

geoip/country/code

string

GB

Country ISO 3166-1

⟨https://en.wikipedia.org/wiki/ISO_3166-1⟩ code.

geoip/country/name

string

United Kingdom

The country name in English language.

geoip/country/is_in_european_union

bool

false

Either true or false.

geoip/continent/code

string

EU

See Continent codes

⟨#ContinentCodes⟩.

geoip/continent/name

string

Europe

The continent name in English language.

geoip/latitude

float64

52.2242

Base 10, max available precision.

geoip/longitude

float64

0.1315

Base 10, max available precision.

geoip/timezone

string

Europe/London

The timezone.

geoip/postalcode

string

CB4

The postal code.

## CONTINENT CODES
Value

Continent (EN)

AF

Africa

AN

Antarctica

AS

Asia

EU

Europe

NA

North America

OC

Oceania

SA

South America


coredns-grpc

title: coredns-grpc(7)

text:
# coredns-grpc(7)

## NAME
grpc - facilitates proxying DNS messages to upstream resolvers via gRPC protocol.

## DESCRIPTION
The grpc plugin supports gRPC and TLS.

This plugin can only be used once per Server Block.

## SYNTAX
In its most basic form:

```
grpc FROM TO...
```

- FROM is the base domain to match for the request to be proxied.

- TO... are the destination endpoints to proxy to. The number of upstreams is limited to 15.

Multiple upstreams are randomized (see policy) on first use. When a proxy returns an error the next upstream in the list is tried.

Extra knobs are available with an expanded syntax:

```
grpc FROM TO... {

    except IGNORED_NAMES...

    tls CERT KEY CA

    tls_servername NAME

    policy random|round_robin|sequential
}
```

- FROM and TO... as above.

- IGNORED_NAMES in except is a space-separated list of domains to exclude from proxying. Requests that match none of these names will be passed through.

- 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. Multiple upstreams are still allowed in this scenario, but they have to use the same tls_servername. E.g. mixing 9.9.9.9 (QuadDNS) with 1.1.1.1 (Cloudflare) will not work.

- policy specifies the policy to use for selecting upstream servers. The default is random.

Also note the TLS config is "global" for the whole grpc proxy if you need a different tls-name for different upstreams you're out of luck.

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metric are exported:

- coredns_grpc_request_duration_seconds{to} - duration per upstream interaction.

- coredns_grpc_requests_total{to} - query count per upstream.

- coredns_grpc_responses_total{to, rcode} - count of RCODEs per upstream. and we are randomly (this always uses the random policy) spraying to an upstream.

## EXAMPLES
Proxy all requests within example.org. to a nameserver running on a different port:

```
example.org {

    grpc . 127.0.0.1:9005
}
```

Load balance all requests between three resolvers, one of which has a IPv6 address.

```
. {

    grpc . 10.0.0.10:53 10.0.0.11:1053 [2003::1]:53
}
```

Forward everything except requests to example.org

```
. {

    grpc . 10.0.0.10:1234 {

        except example.org

    }
}
```

Proxy everything except example.org using the host's resolv.conf's nameservers:

```
. {

    grpc . /etc/resolv.conf {

        except example.org

    }
}
```

Proxy all requests to 9.9.9.9 using the TLS protocol, and cache every answer for up to 30 seconds. Note the tls_servername is mandatory if you want a working setup, as 9.9.9.9 can't be used in the TLS negotiation.

```
. {

    grpc . 9.9.9.9 {

       tls_servername dns.quad9.net

    }

    cache 30
}
```

Or with multiple upstreams from the same provider

```
. {

    grpc . 1.1.1.1 1.0.0.1 {

       tls_servername cloudflare-dns.com

    }

    cache 30
}
```

## BUGS
The TLS config is global for the whole grpc proxy if you need a different tls_servername for different upstreams you're out of luck.


coredns-header

title: coredns-header(7)

text:
# coredns-header(7)

## NAME
header - modifies the header for responses.

## DESCRIPTION
header ensures that the flags are in the desired state for responses. The modifications are made transparently for the client.

## SYNTAX

```
header {

    ACTION FLAGS...

    ACTION FLAGS...
}
```

•

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

–

clear

•

FLAGS are the DNS header flags that will be modified. Current supported flags include:

–

aa - Authoritative(Answer)

–

ra - RecursionAvailable

–

rd - RecursionDesired

## EXAMPLES
Make sure recursive available ra flag is set in all the responses:

```
. {

    header {

        set ra

    }
}
```

Make sure "recursion available" ra and "authoritative answer" aa flags are set and "recursion desired" is cleared in all responses:

```
. {

    header {

        set ra aa

        clear rd

    }
}
```


coredns-health

title: coredns-health(7)

text:
# coredns-health(7)

## NAME
health - enables a health check endpoint.

## DESCRIPTION
Enabled process wide health endpoint. When CoreDNS is up and running this returns a 200 OK HTTP status code. The health is exported, by default, on port 8080/health.

## SYNTAX

```
health [ADDRESS]
```

Optionally takes an address; the default is :8080. The health path is fixed to /health. The health endpoint returns a 200 response code and the word "OK" when this server is healthy.

An extra option can be set with this extended syntax:

```
health [ADDRESS] {

    lameduck DURATION
}
```

•

Where lameduck will delay shutdown for DURATION. /health will still answer 200 OK. Note: The ready plugin will not answer OK while CoreDNS is in lameduck mode prior to shutdown.

If you have multiple Server Blocks, health can only be enabled in one of them (as it is process wide). If you really need multiple endpoints, you must run health endpoints on different ports:

```
com {

    whoami

    health :8080
}
net {

    erratic

    health :8081
}
```

Doing this is supported but both endpoints ":8080" and ":8081" will export the exact same health.

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metric is 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 duration indicates the CoreDNS process is having trouble keeping up with its query load.

Note that this metric does not have a server label, because being overloaded is a symptom of the running process, not a specific server.

## EXAMPLES
Run another health endpoint on http://localhost:8091 ⟨http://localhost:8091⟩.

```
. {

    health localhost:8091
}
```

Set a lameduck duration of 1 second:

```
. {

    health localhost:8092 {

        lameduck 1s

    }
}
```


coredns-hosts

title: coredns-hosts(7)

text:
# coredns-hosts(7)

## 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 plugin only supports A, AAAA, and PTR records. The hosts plugin can be used with readily available hosts files that block access to advertising servers.

The plugin reloads the content of the hosts file every 5 seconds. Upon reload, CoreDNS will use the new definitions. Should the file be deleted, any inlined content will continue to be served. When the file is restored, it will then again be used.

If you want to pass the request to the rest of the plugin chain if there is no match in the hosts plugin, you must specify the fallthrough option.

This plugin can only be used once per Server Block.

## THE HOSTS FILE
Commonly the entries are of the form IP_address canonical_hostname [aliases...] as explained by the hosts(5) man page.

Examples:

```
127.0.0.1       localhost
192.168.1.10    example.com            example
::1                     localhost ip6-localhost ip6-loopback
fdfc:a744:27b5:3b0e::1  example.com example
```

### PTR RECORDS
PTR records for reverse lookups are generated automatically by CoreDNS (based on the hosts file entries) and cannot be created manually.

## SYNTAX

```
hosts [FILE [ZONES...]] {

    [INLINE]

    ttl SECONDS

    no_reverse

    reload DURATION

    fallthrough [ZONES...]
}
```

- FILE the hosts file to read and parse. If the path is relative the path from the root plugin will be prepended to it. Defaults to /etc/hosts if omitted. We scan the file for changes every 5 seconds.

- ZONES zones it should be authoritative for. If empty, the zones from the configuration block are used.

- INLINE the hosts file contents inlined in Corefile. If there are any lines before fallthrough then all of them will be treated as the additional content for hosts file. The specified hosts file path will still be read but entries will be overridden.

- ttl change the DNS TTL of the records generated (forward and reverse). The default is 3600 seconds (1 hour).

- reload change the period between each hostsfile reload. A time of zero seconds disables the feature. Examples of valid durations: "300ms", "1.5h" or "2h45m". See Go's time ⟨https://godoc.org/time⟩. package.

- no_reverse disable the automatic generation of the in-addr.arpa or ip6.arpa entries for the hosts

- 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 authoritative. If specific zones are listed (for example in-addr.arpa and ip6.arpa), then only queries for those zones will be subject to fallthrough.

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metrics are exported:

- coredns_hosts_entries{} - The combined number of entries in hosts and Corefile.

- coredns_hosts_reload_timestamp_seconds{} - The timestamp of the last reload of hosts file.

## EXAMPLES
Load /etc/hosts file.

```
. {

    hosts
}
```

Load example.hosts file in the current directory.

```
. {

    hosts example.hosts
}
```

Load example.hosts file and only serve example.org and example.net from it and fall through to the next plugin if query doesn't match.

```
. {

    hosts example.hosts example.org example.net {

        fallthrough

    }
}
```

Load hosts file inlined in Corefile.

```
example.hosts example.org {

    hosts {

        10.0.0.1 example.org

        fallthrough

    }

    whoami
}
```

## SEE ALSO
The form of the entries in the /etc/hosts file are based on IETF RFC 952 ⟨https://tools.ietf.org/html/rfc952⟩ which was updated by IETF RFC 1123 ⟨https://tools.ietf.org/html/rfc1123⟩.


coredns-import

title: coredns-import(7)

text:
# coredns-import(7)

## NAME
import - includes files or references snippets from a Corefile.

## DESCRIPTION
The import plugin can be used to include files into the main configuration. Another use is to reference predefined snippets. Both can help to avoid some duplication.

This is a unique plugin in that import can appear outside of a server block. In other words, it can appear at the top of a Corefile where an address would normally be.

## SYNTAX

```
import PATTERN
```

•

PATTERN is the file, glob pattern (*) or snippet to include. Its contents will replace this line, as if that file's contents appeared here to begin with.

## FILES
You can use import to include a file or files. This file's location is relative to the Corefile's location. It is an error if a specific file cannot be found, but an empty glob pattern is not an error.

## SNIPPETS
You can define snippets to be reused later in your Corefile by defining a block with a single-token label surrounded by parentheses:

```
(mysnippet) {

    ...
}
```

Then you can invoke the snippet with import:

```
import mysnippet
```

## EXAMPLES
Import a shared configuration:

```
. {

   import config/common.conf
}
```

Where config/common.conf contains:

```
prometheus
errors
log
```

This imports files found in the zones directory:

```
import ../zones/*
```

## SEE ALSO
See corefile(5).


title: coredns-k8s_external(7)

text:
# coredns-k8s_external(7)

## NAME
k8s_external - resolves load balancer and external IPs from outside Kubernetes clusters.

## 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.

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 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):

```
example.org.    5 IN    SOA ns1.dns.example.org. hostmaster.example.org. (

                12345      ; serial

                14400      ; refresh (4 hours)

                3600       ; retry (1 hour)

                604800     ; expire (1 week)

                5          ; minimum (4 hours)

                )
example.org        5 IN    NS ns1.dns.example.org.
ns1.dns.example.org.  5 IN  A    ....
ns1.dns.example.org.  5 IN  AAAA ....
```

Note that we use the dns subdomain for the records DNS needs (see the apex directive). Also note the SOA's serial number is static. The IP addresses of the nameserver records are those of the CoreDNS service.

The k8s_external plugin handles the subdomain dns and the apex of the zone itself; all other queries are resolved to addresses in the cluster.

## SYNTAX

```
k8s_external [ZONE...]
```

•

ZONES zones k8s_external should be authoritative for.

If you want to change the apex domain or use a different TTL for the returned records you can use this extended syntax.

```
k8s_external [ZONE...] {

    apex APEX

    ttl TTL
}
```

- 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).

## EXAMPLES
Enable names under example.org to be resolved to in-cluster DNS addresses.

```
. {

   kubernetes cluster.local

   k8s_external example.org
}
```

With the Corefile above, the following Service will get an A record for test.default.example.org with the IP address 192.168.200.123.

```
apiVersion: v1
kind: Service
metadata:

 name: test

 namespace: default
spec:

 clusterIP: None

 externalIPs:

 - 192.168.200.123

 type: ClusterIP
```

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⟩.

PTR queries for the reverse zone is not supported.


coredns-kubernetes

title: coredns-kubernetes(7)

text:
# coredns-kubernetes(7)

## NAME
kubernetes - enables reading zone data from a Kubernetes cluster.

## DESCRIPTION
This plugin implements the Kubernetes DNS-Based Service Discovery Specification ⟨https://github.com/kubernetes/dns/blob/master/docs/specification.md⟩.

CoreDNS running the kubernetes plugin can be used as a replacement for kube-dns in a kubernetes cluster. See the deployment ⟨https://github.com/coredns/deployment⟩ repository for details on how to deploy CoreDNS in Kubernetes ⟨https://github.com/coredns/deployment/tree/master/kubernetes⟩.

stubDomains and upstreamNameservers ⟨https://kubernetes.io/blog/2017/04/configuring-private-dns-zones-upstream-nameservers-kubernetes/⟩ are implemented via the forward plugin. See the examples below.

This plugin can only be used once per Server Block.

## SYNTAX

```
kubernetes [ZONES...]
```

With only the plugin specified, the kubernetes 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 ZONES is used it specifies all the zones the plugin should be authoritative for.

```
kubernetes [ZONES...] {

    endpoint URL

    tls CERT KEY CACERT

    kubeconfig KUBECONFIG [CONTEXT]

    namespaces NAMESPACE...

    labels EXPRESSION

    pods POD-MODE

    endpoint_pod_names

    ttl TTL

    noendpoints

    fallthrough [ZONES...]

    ignore empty_service
}
```

- endpoint specifies the URL for a remote k8s API endpoint. If omitted, it will connect to k8s in-cluster using the cluster service account.

- tls CERT KEY CACERT 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).

- kubeconfig KUBECONFIG [CONTEXT] authenticates the connection to a remote k8s cluster using a kubeconfig file. [CONTEXT] is optional, if not set, then the current context specified in kubeconfig will be used. 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).

- namespaces NAMESPACE [NAMESPACE...] only exposes the k8s namespaces listed. If this option is omitted all namespaces are exposed

- namespace_labels EXPRESSION only expose the records for Kubernetes namespaces that match this label selector. The label selector syntax is described in the Kubernetes User Guide - Labels ⟨https://kubernetes.io/docs/user-guide/labels/⟩. An example that only exposes namespaces labeled as "istio-injection=enabled", would use: labels istio-injection=enabled.

- labels EXPRESSION only exposes the records for Kubernetes objects that match this label selector. The label selector syntax is described in the Kubernetes User Guide - Labels ⟨https://kubernetes.io/docs/user-guide/labels/⟩. An example that only exposes objects labeled as "application=nginx" in the "staging" or "qa" environments, would use: labels environment in (staging, qa),application=nginx.

- pods POD-MODE sets the mode for handling IP-based pod A records, e.g. 1-2-3-4.ns.pod.cluster.local. in A 1.2.3.4. This option is provided to facilitate use of SSL certs when connecting directly to pods. Valid values for POD-MODE:

–

disabled: Default. Do not process pod requests, always returning NXDOMAIN

–

insecure: Always return an A record with IP from request (without checking k8s). This option is vulnerable to abuse if used maliciously in conjunction with wildcard SSL certs. This option is provided for backward compatibility with kube-dns.

–

verified: Return an A record if there exists a pod in same namespace with matching IP. This 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 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 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 the endpoint, use the dashed IP address form.

- ttl allows you to set a custom TTL for responses. The default is 5 seconds. The minimum TTL allowed is 0 seconds, and the maximum is capped at 3600 seconds. Setting TTL to 0 will prevent records from being cached.

- noendpoints 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.

- fallthrough [ZONES...] 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 [ZONES...] is omitted, then fallthrough happens for all zones for which the plugin is authoritative. If specific zones are listed (for example in-addr.arpa and ip6.arpa), then only queries for those zones will be subject to fallthrough.

- ignore empty_service returns 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.

Enabling zone transfer is done by using the transfer plugin.

## READY
This plugin reports readiness to the ready plugin. This will happen after it has synced to the Kubernetes API.

## EXAMPLES
Handle all queries in the cluster.local zone. Connect to Kubernetes in-cluster. Also handle all in-addr.arpa PTR requests for 10.0.0.0/17 . Verify the existence of pods when answering pod requests.

```
10.0.0.0/17 cluster.local {

    kubernetes {

        pods verified

    }
}
```

Or you can selectively expose some namespaces:

```
kubernetes cluster.local {

    namespaces test staging
}
```

Connect to Kubernetes with CoreDNS running outside the cluster:

```
kubernetes cluster.local {

    endpoint https://k8s-endpoint:8443

    tls cert key cacert
}
```

## STUBDOMAINS AND UPSTREAMNAMESERVERS
Here we use the forward plugin to implement a stubDomain that forwards example.local to the nameserver 10.100.0.10:53. Also configured is an upstreamNameserver 8.8.8.8:53 that will be used for resolving names that do not fall in cluster.local or example.local.

```
cluster.local:53 {

    kubernetes cluster.local
}
example.local {

    forward . 10.100.0.10:53
}
. {

    forward . 8.8.8.8:53
}
```

The configuration above represents the following Kube-DNS stubDomains and upstreamNameservers configuration.

```
stubDomains: |

   {“example.local”: [“10.100.0.10:53”]}
upstreamNameservers: |

   [“8.8.8.8:53”]
```

## AUTOPATH
The kubernetes plugin can be used in conjunction with the autopath plugin. Using this feature enables server-side domain search path completion in Kubernetes clusters. Note: pods must be set to verified for this to function properly. Furthermore, the remote IP address in the DNS packet received by CoreDNS must be the IP address of the Pod that sent the request.

```
cluster.local {

    autopath @kubernetes

    kubernetes {

        pods verified

    }
}
```

## WILDCARDS
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:

- endpoint in an A record request: endpoint.service.namespace.svc.zone, e.g., *.nginx.ns.svc.cluster.local

- service in an A record request: service.namespace.svc.zone, e.g., *.ns.svc.cluster.local

- namespace in an A record request: service.namespace.svc.zone, e.g., nginx.*.svc.cluster.local

- port and/or protocol in an SRV request: port_.protocol_.service.namespace.svc.zone., e.g., _http.*.service.ns.svc.cluster.local

- multiple wildcards are allowed in a single query, e.g., A Request *.*.svc.zone. or SRV request *.*.*.*.svc.zone.

For example, wildcards can be used to resolve all Endpoints for a Service as A records. e.g.: *.service.ns.svc.myzone.local will return the Endpoint IPs in the Service service in namespace default:

```
*.service.default.svc.cluster.local. 5    IN A    192.168.10.10
*.service.default.svc.cluster.local. 5    IN A    192.168.25.15
```

## METADATA
The kubernetes plugin will publish the following metadata, if the metadata plugin is also enabled:

- kubernetes/endpoint: the endpoint name in the query

- kubernetes/kind: the resource kind (pod or svc) in the query

- kubernetes/namespace: the namespace in the query

- kubernetes/port-name: the port name in an SRV query

- kubernetes/protocol: the protocol in an SRV query

- kubernetes/service: the service name in the query

- kubernetes/client-namespace: the client pod's namespace (see requirements below)

- kubernetes/client-pod-name: the client pod's name (see requirements below)

The kubernetes/client-namespace and kubernetes/client-pod-name metadata work by reconciling the client IP address in the DNS request packet to a known pod IP address. Therefore the following is required:

* pods verified mode must be enabled

* the remote IP address in the DNS packet received by CoreDNS must be the IP address

of the Pod that sent the request.

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metrics are exported:

•

coredns_kubernetes_dns_programming_duration_seconds{service_kind} - Exports the DNS programming latency SLI ⟨https://github.com/kubernetes/community/blob/master/sig-scalability/slos/dns_programming_latency.md⟩. The metrics has the service_kind label that identifies the kind of the kubernetes service ⟨https://kubernetes.io/docs/concepts/services-networking/service⟩. It may take one of the three values:

–

cluster_ip

–

headless_with_selector

–

headless_without_selector

## BUGS
The duration metric only supports the "headless_with_selector" service currently.

## SEE ALSO
See the autopath plugin to enable search path optimizations. And use the transfer plugin to enable outgoing zone transfers.


coredns-loadbalance

title: coredns-loadbalance(7)

text:
# coredns-loadbalance(7)

## NAME
loadbalance - randomizes the order of A, AAAA and MX records.

## DESCRIPTION
The loadbalance will act as a round-robin DNS load balancer by randomizing the order of A, AAAA, and MX records in the answer.

See Wikipedia ⟨https://en.wikipedia.org/wiki/Round-robin_DNS⟩ about the pros and cons of this setup. It will take care to sort any CNAMEs before any address records, because some stub resolver implementations (like glibc) are particular about that.

## SYNTAX

```
loadbalance [POLICY]
```

•

POLICY is how to balance. The default, and only option, is "round_robin".

## EXAMPLES
Load balance replies coming back from Google Public DNS:

```
. {

    loadbalance round_robin

    forward . 8.8.8.8 8.8.4.4
}
```


coredns-local

title: coredns-local(7)

text:
# coredns-local(7)

## NAME
local - respond to local names.

## DESCRIPTION
local will respond with a basic reply to a "local request". Local request are defined to be names in the following zones: localhost, 0.in-addr.arpa, 127.in-addr.arpa and 255.in-addr.arpa and any query asking for localhost.<domain>. When seeing the latter a metric counter is increased and if debug is enabled a debug log is emitted.

With local enabled any query falling under these zones will get a reply. The prevents the query from "escaping" to the internet and putting strain on external infrastructure.

The zones are mostly empty, only localhost. address records (A and AAAA) are defined and a 1.0.0.127.in-addr.arpa. reverse (PTR) record.

## SYNTAX

```
local
```

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metric is exported:

•

coredns_local_localhost_requests_total{} - a counter of the number of localhost.<domain> requests CoreDNS has seen. Note this does not count localhost. queries.

Note that this metric does not have a server label, because it's more interesting to find the client(s) performing these queries than to see which server handled it. You'll need to inspect the debug log to get the client IP address.

## EXAMPLES

```
. {

    local
}
```

## BUGS
Only the in-addr.arpa. reverse zone is implemented, ip6.arpa. queries are not intercepted.

## SEE ALSO
BIND9's configuration in Debian comes with these zones preconfigured. See the debug plugin for enabling debug logging.