README
¶
forward
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, every 0.5s, 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.
How does forward relate to proxy? This plugin is the "new" version of proxy and is faster because it re-uses connections to the upstreams. It also does in-band health checks - using DNS instead of HTTP. Since it is newer it has a little less (production) mileage on it.
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
ordns://
(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
}
-
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 bothforce_tcp
andprefer_udp
options specified theforce_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 belowtls
- no client authentication is used, and the system CAs are used to verify the server certificatetls
CA - no client authentication is used, and the file CA is used to verify the server certificatetls
CERT KEY - client authentication is used with the specified cert/key pair. The server certificate is verified with the system CAstls
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 todns.quad9.net
. Multiple upstreams are still allowed in this scenario, but they have to use the sametls_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 israndom
. -
health_check
, use a different DURATION for health checking, the default duration is 0.5s.
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 of the communication are set by default and automatically tuned depending early results.
- dialTimeout by default is 30 sec, and can decrease automatically down to 100ms
- readTimeout by default is 2 sec, and can decrease automatically down to 200ms
Metrics
If monitoring is enabled (via the prometheus directive) then the following metric are exported:
coredns_forward_request_duration_seconds{to}
- duration per upstream interaction.coredns_forward_request_count_total{to}
- query count per upstream.coredns_forward_response_rcode_total{to, rcode}
- count of RCODEs per upstream.coredns_forward_healthcheck_failure_count_total{to}
- number of failed health checks per upstream.coredns_forward_healthcheck_broken_count_total{}
- counter of when all upstreams are unhealthy, and we are randomly (this always uses therandom
policy) spraying to an upstream.coredns_forward_socket_count_total{to}
- number of cached sockets per upstream.
Where to
is one of the upstream servers (TO from the config), proto
is the protocol used by
the incoming query ("tcp" or "udp"), and family the transport family ("1" for IPv4, and "2" for
IPv6).
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 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
}
Bugs
The TLS config is global for the whole forwarding proxy if you need a different tls_servername
for
different upstreams you're out of luck.
Also See
RFC 7858 for DNS over TLS.
Documentation
¶
Overview ¶
Package forward implements a forwarding proxy. It caches an upstream net.Conn for some time, so if the same client returns the upstream's Conn will be precached. Depending on how you benchmark this looks to be 50% faster than just opening a new connection for every client. It works with UDP and TCP and uses inband healthchecking.
Package forward implements a forwarding proxy. It caches an upstream net.Conn for some time, so if the same client returns the upstream's Conn will be precached. Depending on how you benchmark this looks to be 50% faster than just opening a new connection for every client. It works with UDP and TCP and uses inband healthchecking.
Index ¶
- Variables
- type Forward
- func (f *Forward) Close()
- func (f *Forward) ForceTCP() bool
- func (f *Forward) Len() int
- func (f *Forward) List() []*Proxy
- func (f *Forward) Name() string
- func (f *Forward) OnShutdown() error
- func (f *Forward) OnStartup() (err error)
- func (f *Forward) PreferUDP() bool
- func (f *Forward) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
- func (f *Forward) SetProxy(p *Proxy)
- type HealthChecker
- type Policy
- type Proxy
- type Transport
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoHealthy means no healthy proxies left. ErrNoHealthy = errors.New("no healthy proxies") // ErrNoForward means no forwarder defined. ErrNoForward = errors.New("no forwarder defined") // ErrCachedClosed means cached connection was closed by peer. ErrCachedClosed = errors.New("cached connection was closed by peer") )
var ( RequestCount = prometheus.NewCounterVec(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "forward", Name: "request_count_total", Help: "Counter of requests made per upstream.", }, []string{"to"}) RcodeCount = prometheus.NewCounterVec(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "forward", Name: "response_rcode_count_total", Help: "Counter of requests made per upstream.", }, []string{"rcode", "to"}) RequestDuration = prometheus.NewHistogramVec(prometheus.HistogramOpts{ Namespace: plugin.Namespace, Subsystem: "forward", Name: "request_duration_seconds", Buckets: plugin.TimeBuckets, Help: "Histogram of the time each request took.", }, []string{"to"}) HealthcheckFailureCount = prometheus.NewCounterVec(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "forward", Name: "healthcheck_failure_count_total", Help: "Counter of the number of failed healtchecks.", }, []string{"to"}) HealthcheckBrokenCount = prometheus.NewCounter(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "forward", Name: "healthcheck_broken_count_total", Help: "Counter of the number of complete failures of the healtchecks.", }) SocketGauge = prometheus.NewGaugeVec(prometheus.GaugeOpts{ Namespace: plugin.Namespace, Subsystem: "forward", Name: "sockets_open", Help: "Gauge of open sockets per upstream.", }, []string{"to"}) )
Variables declared for monitoring.
Functions ¶
This section is empty.
Types ¶
type Forward ¶
Forward represents a plugin instance that can proxy requests to another (DNS) server. It has a list of proxies each representing one upstream proxy.
func ParseForwardStanza ¶ added in v1.2.1
ParseForwardStanza parses one forward stanza
func (*Forward) ForceTCP ¶ added in v1.1.3
ForceTCP returns if TCP is forced to be used even when the request comes in over UDP.
func (*Forward) List ¶ added in v1.1.3
List returns a set of proxies to be used for this client depending on the policy in f.
func (*Forward) OnShutdown ¶
OnShutdown stops all configured proxies.
func (*Forward) PreferUDP ¶ added in v1.2.0
PreferUDP returns if UDP is preferred to be used even when the request comes in over TCP.
type HealthChecker ¶ added in v1.2.0
HealthChecker checks the upstream health.
func NewHealthChecker ¶ added in v1.2.0
func NewHealthChecker(trans string) HealthChecker
NewHealthChecker returns a new HealthChecker based on transport.
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
Proxy defines an upstream host.
func (*Proxy) Connect ¶ added in v1.1.3
Connect selects an upstream, sends the request and waits for a response.
func (*Proxy) Healthcheck ¶
func (p *Proxy) Healthcheck()
Healthcheck kicks of a round of health checks for this proxy.
func (*Proxy) SetTLSConfig ¶
SetTLSConfig sets the TLS config in the lower p.transport and in the healthchecking client.
type Transport ¶ added in v1.2.3
type Transport struct {
// contains filtered or unexported fields
}
Transport hold the persistent cache.
func (*Transport) Dial ¶ added in v1.2.3
Dial dials the address configured in transport, potentially reusing a connection or creating a new one.
func (*Transport) SetExpire ¶ added in v1.2.3
SetExpire sets the connection expire time in transport.
func (*Transport) SetTLSConfig ¶ added in v1.2.3
SetTLSConfig sets the TLS config in transport.
func (*Transport) Start ¶ added in v1.2.3
func (t *Transport) Start()
Start starts the transport's connection manager.