COREDNS-FORWARD(7)

📦

version 1.15.0 · 3 versions

1.15.0 · opensuse-leap 16.0 (latest)
1.11.3 · opensuse-leap 16.0
1.14.7 · nixpkgs unstable

🦋 COREDNS-FORWARD(7) 🦋

okay bestie, welcome to the coredns-forward glow-up 💅 this is the manual page for the forward plugin, and it's genuinely one of the most iconic little pieces of CoreDNS. grab a strawberry drink 🍓 and let's get into it.

✨ NAME ✨

forward — literally facilitates proxying DNS messages to upstream resolvers. that's it, that's the whole job, and it does it so well 🫶

🌸 DESCRIPTION 🌸

so the forward plugin re-uses already opened sockets to the upstreams. no cap — it's not out here opening a fresh socket for every single query like some kind of amateur. it reuses what it's got, which is main character energy 👑

it supports UDP, TCP, DNS-over-TLS, and DNS-over-HTTPS, and it uses in band health checking. yes bestie, all of those. slay 🌈

💖 the health check situation 💖

okay so here's the tea ☕ when forward detects an error, a health check is performed. and this check runs in a loop — performing each check at a 0.5s interval for as long as the upstream reports unhealthy. like it is not going to stop checking on that upstream, it's committed 😭

once the upstream is healthy again, we stop health checking — until the next error shows up. you know the vibe: it's chill until it's not 🙈

the health checks use a recursive DNS query (. IN NS) to get upstream health. and here's the important bit — any response that is not a network error (REFUSED, NOTIMPL, SERVFAIL, etc) is taken as a healthy upstream. so don't come for it just because the answer was spicy, as long as it's not a network error we're calling that healthy ✨

the health check uses the same protocol as specified in TO. that part matters, bestie, iykyk 🔥

and if max_fails is set to 0, no checking is performed and upstreams will always be considered healthy. literally zero vibes checks. it's just trusting everyone, fr fr 💀

🎀 when everything is down 🎀

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. ngl that's the "well, we tried everything, roll the dice" moment 🎲😭

✨ SYNTAX ✨

Okay so the simplest possible forwarder setup? Literally just this:

forward FROM TO...

FROM is the base domain that gets matched before a request gets forwarded. One tiny catch though: domains using CIDR notation that expand into multiple reverse zones aren't fully supported — only the first expanded zone gets used. 💅
TO... are the destination endpoints you're forwarding to. The TO syntax lets you specify a protocol — tls://9.9.9.9, quic://94.140.14.14, https://9.9.9.9 (heads up, DoH defaults to the /dns-query path) or dns:// (or literally no protocol at all) for plain DNS. The number of upstreams is capped at 15. Besides IP addresses and files (like /etc/resolv.conf), TO can also be a hostname (e.g., my-dns.svc.cluster.local). Hostnames get resolved to IP addresses at startup and are treated as absolute DNS names even without a trailing dot — resolver search domains are not applied. Peep the resolver option below for that. 🫶

Multiple upstreams get randomized (see policy) on first use. And when a healthy proxy returns an error during the exchange, the next upstream in the list gets tried. Slay.

🎀 Extra knobs (the expanded syntax) 🎀

There's a whole expanded syntax if you want more control, bestie:

forward FROM TO... {
    except IGNORED_NAMES...
    force_tcp
    prefer_udp
    expire DURATION
    max_age DURATION
    max_idle_conns INTEGER
    read_timeout DURATION
    max_fails INTEGER
    max_connect_attempts INTEGER
    doh_method GET|POST
    tls CERT KEY CA
    tls_servername NAME
    policy random|round_robin|sequential
    health_check DURATION [no_rec] [domain FQDN]
    max_concurrent MAX
    next RCODE_1 [RCODE_2] [RCODE_3...]
    failfast_all_unhealthy_upstreams
    failover RCODE_1 [RCODE_2] [RCODE_3...]
    source_address IP
    resolver IP[:PORT] [IP[:PORT]...]
}

FROM and TO... — same as above, no notes. 💖
IGNORED_NAMES in except is a space-separated list of domains to exclude from forwarding. Anything that doesn't match one of these names just gets passed through.
force_tcp — use TCP even when the request comes in over UDP.
prefer_udp — try UDP first even when the request comes in over TCP. If the response is truncated (TC flag set in the response) then it does another attempt over TCP. And if you somehow specify both force_tcp and prefer_udp, force_tcp takes precedence, periodt. Also important: neither of these options changes an explicitly configured DoT, DoQ, or DoH upstream transport. ✨
max_fails is the number of subsequent failed health checks needed before an upstream is considered down. If it's 0, the upstream will never be marked as down (and won't be health checked at all). Default is 2.
max_connect_attempts caps the total number of upstream connect attempts performed for a single incoming DNS request. The default cap is twice the number of configured upstreams, which lets you do two complete passes when all upstreams are healthy. Set it to 0 to disable the per-request cap.
expire DURATION — expire (cached) connections after this time. Default is 10s.
max_age DURATION — stop reusing and replace connections after this total lifetime. The default is 0, which disables maximum connection age. A non-zero value must not be less than expire. 🚨
doh_method GET|POST — whether to use the GET or POST HTTP method for DoH requests (defaults to POST).
max_idle_conns INTEGER — maximum number of idle connections to cache per upstream for reuse. Default is 0, which means unlimited. Also fyi, DoQ multiplexes streams over one cached connection per upstream.
read_timeout DURATION — the per-query read timeout applied to each upstream while waiting for a response. Default is 2s. Bump this up if your upstreams legitimately take longer than 2s to answer (like slow recursive resolutions that would otherwise show up as SERVFAIL/timeouts). Ngl though, this timeout applies to each upstream individually, so big values reduce the time available to retry other upstreams within a single query. 🙈
tls CERT KEY CA — define the TLS properties for the TLS connection. You can provide from 0 to 3 arguments, with these meanings:
- 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.

CoreDNS sets the minimum TLS version to TLS 1.2 for DoT and DoH. DoQ uses TLS 1.3 as required by QUIC. The maximum TLS version, TLS 1.2 cipher suites, and key exchange mechanisms all use the Go crypto/tls defaults. 💜

tls_servername NAME lets you set a server name in the TLS configuration — for instance 9.9.9.9 needs this set to dns.quad9.net. It is strongly recommended when using DoT, DoQ, or DoH with an IP address whose certificate identifies a DNS name instead of that IP address. 👑

Per destination endpoint TLS server name indication is possible in the form of tls://9.9.9.9%dns.quad9.net or quic://9.9.9.9%dns.quad9.net. tls_servername must not be specified when using per destination endpoint TLS server name indication, because it would introduce a clash between server name indication specifications. If a destination endpoint is to be reached via a port other than 853, then the port must be appended to the end of the destination endpoint specifier. In the case of port 10853, the above string would be: tls://9.9.9.9%dns.quad9.net:10853. 🦋

policy specifies the policy used for selecting upstream servers. Default is random.
- random — a policy that implements random upstream selection.
- round_robin — a policy that selects hosts based on round robin ordering.
- sequential — a policy that selects hosts based on sequential ordering.
health_check configures the behaviour of health checking for 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 true by default.
- domain FQDN — set the domain name used for health checks to FQDN. If not configured, the domain name used for health checks is .. 🍓
max_concurrent MAX will limit the number of concurrent queries to MAX. Any new query that would push the number of concurrent queries above MAX gets a REFUSED response. That response does not count as a health failure. When picking a value for MAX, choose a number at least greater than the expected upstream query rate × latency of the upstream servers. And as an upper bound, keep in mind each concurrent query uses about 2kb of memory. 🧠
next — if the RCODE (i.e. NXDOMAIN) is returned by the remote, then execute the next plugin. If no next plugin is defined, or the next plugin isn't a forward plugin, this setting is ignored.
next_on_nodata — if NOERROR is returned by the remote but an empty answer section (NODATA) was provided, execute the next forward plugin, if configured.
failfast_all_unhealthy_upstreams — determines how requests are handled when all upstream servers are unhealthy and unresponsive to health checks. Enabling this option immediately returns SERVFAIL responses for all requests. By default, requests are sent to a random upstream.
failover — by default, when a DNS lookup fails to return a DNS response (e.g. timeout), forward will attempt a lookup on the next upstream server. The failover option makes forward do the same for any response with a response code matching an RCODE (e.g. SERVFAIL、REFUSED). NOERROR cannot be used. If all upstreams have been tried, the response from the last attempt is returned. 💀
source_address IP — set the address to use for all outgoing requests as the source address (health check query included). This works reliably when upstream servers are reachable from that address. But if upstream servers belong to different networks, be careful — the selected source address may not be valid for all upstreams, and responses may fail if return routing isn't properly configured. In those cases, make sure the upstream servers have a route back to the configured source address. 🌈
resolver IP[:PORT] [IP[:PORT]...] — specifies one or more DNS resolver addresses used to resolve hostname-based TO endpoints at startup. If not specified, the system resolver (/etc/resolv.conf) is used. Each address is either a bare IP (IPv4 or IPv6, port 53 assumed) or IP:port. You can list multiple addresses for redundancy. ⭐

The client certificate, key, and CA configuration is global for one forward stanza. For DoT and DoQ, use the %servername endpoint form when upstreams in the same stanza require different TLS server names. 🎀

On each endpoint, the timeouts for communication are set like this:

The DNS and DoT dial timeout defaults to 30s and can decrease automatically down to 1s based on early results. The DoQ handshake timeout is 5s.
DoT connection setup (TCP dial plus TLS handshake) is additionally bounded by the remaining 5s forwarding retry window, or an earlier request deadline. When retries are enabled, each setup attempt is limited to half of the window available at the start of forwarding (at most 2.5s), so a stalled handshake leaves time to try a fresh connection. With max_connect_attempts set to 1, setup may use the full remaining window. Failed handshakes close the connection; successful connections remain reusable. These setup limits do not change the DNS exchange read timeout. 😭
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 📊

Okay so if monitoring is enabled (via the prometheus plugin) then these metrics get exported, and honestly? They're giving observability icon. Let's go through them one by one:

coredns_forward_healthcheck_broken_total{} — counts every time all the upstreams are unhealthy, and we're just randomly (this always uses the random policy, no cap) spraying queries at an upstream. Chaos mode, but make it measured.
coredns_forward_max_concurrent_rejects_total{} — count of queries that got rejected because the number of concurrent queries was at maximum. Shut down, respectfully.
coredns_proxy_request_duration_seconds{proxy_name="forward", to, rcode} — histogram per upstream, RCODE.
coredns_proxy_healthcheck_failures_total{proxy_name="forward", to, rcode} — count of failed health checks per upstream.
coredns_proxy_conn_cache_hits_total{proxy_name="forward", to, proto} — count of connection cache hits per upstream and protocol.
coredns_proxy_conn_cache_misses_total{proxy_name="forward", to, proto} — count of connection cache misses per upstream and protocol.

So real quick, what are those labels? to is one of the upstream servers (that's the TO from the config, bestie), rcode is the returned RCODE from the upstream, and proto is the transport protocol like udp, tcp, tcp-tls, quic, https.

🥀 the deprecated ones (a moment of silence)

The following metrics have recently been deprecated, and here's the glow-up for each:

coredns_forward_healthcheck_failures_total{to, rcode}
- Can be replaced with coredns_proxy_healthcheck_failures_total{proxy_name="forward", to, rcode}
coredns_forward_requests_total{to}
- Can be replaced with sum(coredns_proxy_request_duration_seconds_count{proxy_name="forward", to})
coredns_forward_responses_total{to, rcode}
- Can be replaced with coredns_proxy_request_duration_seconds_count{proxy_name="forward", to, rcode}
coredns_forward_request_duration_seconds{to, rcode}
- Can be replaced with coredns_proxy_request_duration_seconds{proxy_name="forward", to, rcode}

💖 EXAMPLES 💖

This is the part where it gets fun. Buckle up.

the classic: proxy everything for a zone to a different port

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

example.org {
    forward . 127.0.0.1:9005
}

subdomain routing, and the whole "order matters" thing (iykyk)

Send all requests within lab.example.local. to 10.20.0.1, all requests within example.local. (and not in lab.example.local.) to 10.0.0.1, all others requests to the servers defined in /etc/resolv.conf, and caches results. Note that a CoreDNS server configured with multiple forward plugins in a server block will evaluate those forward plugins in the order they are listed when serving a request. Therefore, subdomains should be placed before parent domains — otherwise subdomain requests will be forwarded to the parent domain's upstream. Accordingly, in this example lab.example.local is before example.local, and example.local is before ..

. {
    cache
    forward lab.example.local 10.20.0.1
    forward example.local 10.0.0.1
    forward . /etc/resolv.conf
}

The example above is almost equivalent to the following example, except that the example below defines three separate plugin chains (and thus 3 separate instances of cache):

lab.example.local {
    cache
    forward . 10.20.0.1
}
example.local {
    cache
    forward . 10.0.0.1
}
. {
    cache
    forward . /etc/resolv.conf
}

load balancing, but make it multilingual (IPv6 says hi)

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
}

everything except that one zone

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

DoT girl summer 🦋

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
}

DoQ era ✨

The following example uses DNS-over-QUIC (DoQ). DoQ uses UDP port 853 by default and multiplexes concurrent queries over separate streams on one QUIC connection. The forward plugin's single-message exchange path does not support AXFR or IXFR over DoQ; those requests return NOTIMP.

. {
    forward . quic://94.140.14.14 {
       tls_servername dns.adguard-dns.com
       health_check 5s
    }
    cache 30
}

DoH, same energy 🌸

The same configuration but using DNS-over-HTTPS (DoH) protocol. Note that the implementation uses the default /dns-query path (custom paths are not supported).

. {
    forward . https://9.9.9.9 {
       tls_servername dns.quad9.net
       health_check 5s
    }
    cache 30
}

or configure another domain name for health check requests

. {
    forward . tls://9.9.9.9 {
       tls_servername dns.quad9.net
       health_check 5s domain example.org
    }
    cache 30
}

multiple upstreams, same provider, one servername

. {
    forward . tls://1.1.1.1 tls://1.0.0.1 {
       tls_servername cloudflare-dns.com
       health_check 5s
    }
    cache 30
}

multiple DoT upstreams with different `tls_servername`s

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 . tls://8.8.8.8 tls://8.8.4.4 {
        tls_servername dns.google
    }
}

.:5302 {
    forward . tls://1.1.1.1 tls://1.0.0.1 {
        tls_servername cloudflare-dns.com
    }
}

chaining with `next` (the try-again era)

The following would try 1.2.3.4 first. If the response is NXDOMAIN, try 5.6.7.8. If the response from 5.6.7.8 is NXDOMAIN, try 9.0.1.2.

. {
  forward . 1.2.3.4 {
    next NXDOMAIN
  }
  forward . 5.6.7.8 {
    next NXDOMAIN
  }
  forward . 9.0.1.2 {
  }
}

In the following example, if the response from 1.2.3.4 is SERVFAIL or REFUSED, it will try 5.6.7.8. If the response from 5.6.7.8 is SERVFAIL or REFUSED, it will try 9.0.1.2.

. {
  forward . 1.2.3.4 5.6.7.8 9.0.1.2 {
     policy sequential
     failover SERVFAIL REFUSED
  }
}

hostname upstream + a specific resolver to look it up 👑

Forward to an upstream identified by hostname, using a specific resolver to look it up:

. {
    forward . dns.example.local {
        resolver 10.0.0.1
    }
}

👀 SEE ALSO 👀

Go read the RFCs, they're literally the receipts:

RFC 7858 ⟨https://www.rfc-editor.org/info/rfc7858/⟩ for DNS over TLS.
RFC 8484 ⟨https://www.rfc-editor.org/info/rfc8484/⟩ for DNS over HTTPS.
RFC 9250 ⟨https://www.rfc-editor.org/info/rfc9250/⟩ for DNS over QUIC.

and that's the whole page, bestie 🫶 This one's from CoreDNS, dated October 2026, and the page itself is COREDNS-FORWARD(7) — go forth and forward responsibly, mwah 💅💖

📦 where this page comes from

opensuse-leap 16.0: coredns-extras 1.15.0-bp160.1.1 · Apache-2.0 AND MPL-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms