forward

package
v1.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 22, 2018 License: Apache-2.0 Imports: 22 Imported by: 0

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

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
    expire DURATION
    max_fails INTEGER
    tls CERT KEY CA
    tls_servername NAME
    policy random|round_robin
    health_checks 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.
  • 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; if you leave this out the system's configuration will be used.
  • 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.
  • policy specifies the policy to use for selecting upstream servers. The default is random.
  • health_checks, 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.

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

Bugs

The TLS config is global for the whole forwarding proxy if you need a different tls_serveraame 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 openening 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 openening 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 openening a new connection for every client. It works with UDP and TCP and uses inband healthchecking.

Index

Constants

View Source 
const (
	DNS = iota + 1
	TLS
)

Supported protocols.

Variables

View Source 
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:      "socket_count_total",
		Help:      "Guage of open sockets per upstream.",
	}, []string{"to"})
)

Variables declared for monitoring.

Functions

This section is empty.

Types

type Forward 

type Forward struct {
	Next plugin.Handler
	// contains filtered or unexported fields
}

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 New 

func New() *Forward

New returns a new Forward.

func NewLookup 

func NewLookup(addr []string) *Forward

NewLookup returns a Forward that can be used for plugin that need an upstream to resolve external names. Note that the caller must run Close on the forward to stop the health checking goroutines.

func (*Forward) Close 

func (f *Forward) Close()

Close is a synonym for OnShutdown().

func (*Forward) Forward 

func (f *Forward) Forward(state request.Request) (*dns.Msg, error)

Forward forward the request in state as-is. Unlike Lookup that adds EDNS0 suffix to the message. Forward may be called with a nil f, an error is returned in that case.

func (*Forward) Len 

func (f *Forward) Len() int

Len returns the number of configured proxies.

func (*Forward) Lookup 

func (f *Forward) Lookup(state request.Request, name string, typ uint16) (*dns.Msg, error)

Lookup will use name and type to forge a new message and will send that upstream. It will set any EDNS0 options correctly so that downstream will be able to process the reply. Lookup may be called with a nil f, an error is returned in that case.

func (*Forward) Name 

func (f *Forward) Name() string

Name implements plugin.Handler.

func (*Forward) OnShutdown 

func (f *Forward) OnShutdown() error

OnShutdown stops all configured proxies.

func (*Forward) OnStartup 

func (f *Forward) OnStartup() (err error)

OnStartup starts a goroutines for all proxies.

func (*Forward) ServeDNS 

func (f *Forward) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

ServeDNS implements plugin.Handler.

func (*Forward) SetProxy 

func (f *Forward) SetProxy(p *Proxy)

SetProxy appends p to the proxy list and starts healthchecking.

type Policy 

type Policy interface {
	List([]*Proxy) []*Proxy
	String() string
}

Policy defines a policy we use for selecting upstreams.

type Proxy 

type Proxy struct {
	// contains filtered or unexported fields
}

Proxy defines an upstream host.

func NewProxy 

func NewProxy(addr string, tlsConfig *tls.Config) *Proxy

NewProxy returns a new proxy.

func (*Proxy) Check 

func (p *Proxy) Check() error

Check is used as the up.Func in the up.Probe.

func (*Proxy) Dial 

func (p *Proxy) Dial(proto string) (*dns.Conn, error)

Dial connects to the host in p with the configured transport.

func (*Proxy) Down 

func (p *Proxy) Down(maxfails uint32) bool

Down returns true if this proxy is down, i.e. has *more* fails than maxfails.

func (*Proxy) Healthcheck 

func (p *Proxy) Healthcheck()

Healthcheck kicks of a round of health checks for this proxy.

func (*Proxy) SetExpire 

func (p *Proxy) SetExpire(expire time.Duration)

SetExpire sets the expire duration in the lower p.transport.

func (*Proxy) SetTLSConfig 

func (p *Proxy) SetTLSConfig(cfg *tls.Config)

SetTLSConfig sets the TLS config in the lower p.transport.

func (*Proxy) Yield 

func (p *Proxy) Yield(c *dns.Conn)

Yield returns the connection to the pool.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.