aggregate

README

aggregate

Name

aggregate - parallel proxying DNS messages to upstream resolvers.

Description

Each incoming DNS query that hits the CoreDNS aggregate plugin will be replicated in parallel to each listed IP (i.e. the DNS servers). The first non-negative response from any of the queried DNS Servers will be forwarded as a response to the application's DNS request.

Syntax

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

• worker-count is the number of parallel queries per request. By default equals to count of IP list. Use this only for reducing parallel queries per request.

• network is a specific network protocol. Could be tcp, udp, tcp-tls.

• except is a list is a space-separated list of domains to exclude from proxying.

• except-file is the path to file with line-separated list of domains to exclude from proxying.

• attempt-count is the number of attempts to connect to upstream servers that are needed before considering an upstream to be down. If 0, the upstream will never be marked as down and request will be finished by timeout. Default is 3.

• timeout is the timeout of request. After this period, attempts to receive a response from the upstream servers will be stopped. Default is 30s.

Metrics

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

• coredns_aggregate_request_duration_seconds{to} - duration per upstream interaction.
• coredns_aggregate_request_count_total{to} - query count per upstream.
• coredns_aggregate_response_rcode_count_total{to, rcode} - count of RCODEs per upstream.
• coredns_aggregate_healthcheck_failure_count_total{to} - number of failed health checks per upstream.
• coredns_aggregate_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.

Where to is one of the upstream servers (TO from the config), rcode is the returned RCODE from the upstream.

Examples

Proxy all requests within example.org. to a nameservers running on a different ports. The first positive response from a proxy will be provided as the result.

example.org {
    aggregate . 127.0.0.1:9005 127.0.0.1:9006 127.0.0.1:9007 127.0.0.1:9008
}

Sends parallel requests between three resolvers, one of which has a IPv6 address via TCP. The first response from proxy will be provided as the result.

. {
    aggregate . 10.0.0.10:53 10.0.0.11:1053 [2003::1]:53 {
        network TCP
    }
}

Proxying everything except requests to example.org

. {
    aggregate . 10.0.0.10:1234 {
        except example.org
    }
}

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

. {
    aggregate . /etc/resolv.conf {
        except example.org
    }
}

Proxy all requests to 9.9.9.9 using the DNS-over-TLS protocol. Note the tls-server is mandatory if you want a working setup, as 9.9.9.9 can't be used in the TLS negotiation.

. {
    aggregate . tls://9.9.9.9 {
       tls-server dns.quad9.net
    }
}

Sends parallel requests between five resolvers via UDP uses two workers and without attempting to reconnect. The first positive response from a proxy will be provided as the result.

. {
    aggregate . 10.0.0.10:53 10.0.0.11:53 10.0.0.12:53 10.0.0.13:1053 10.0.0.14:1053 {
        worker-count 2
    }
}

Documentation

Overview

Package aggregate - parallel proxying DNS messages to upstream resolvers.

Index

• Variables
• type Aggregate
  • func New() *Aggregate
  • func (f *Aggregate) Name() string
  • func (f *Aggregate) OnShutdown() error
  • func (f *Aggregate) OnStartup() (err error)
  • func (f *Aggregate) ServeDNS(ctx context.Context, w dns.ResponseWriter, m *dns.Msg) (int, error)
• type Client
  • func NewClient(addr, net string) Client
• type Domain
  • func NewDomain() Domain
• type Transport
  • func NewTransport(addr string) Transport

Variables

var (
	RequestCount = promauto.NewCounterVec(prometheus.CounterOpts{
		Namespace: plugin.Namespace,
		Subsystem: "aggregate",
		Name:      "request_count_total",
		Help:      "Counter of requests made per upstream.",
	}, []string{"to"})
	RcodeCount = promauto.NewCounterVec(prometheus.CounterOpts{
		Namespace: plugin.Namespace,
		Subsystem: "aggregate",
		Name:      "response_rcode_count_total",
		Help:      "Counter of requests made per upstream.",
	}, []string{"rcode", "to"})
	RequestDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
		Namespace: plugin.Namespace,
		Subsystem: "aggregate",
		Name:      "request_duration_seconds",
		Buckets:   plugin.TimeBuckets,
		Help:      "Histogram of the time each request took.",
	}, []string{"to"})
	HealthcheckFailureCount = promauto.NewCounterVec(prometheus.CounterOpts{
		Namespace: plugin.Namespace,
		Subsystem: "aggregate",
		Name:      "healthcheck_failure_count_total",
		Help:      "Counter of the number of failed healthchecks.",
	}, []string{"to"})
	HealthcheckBrokenCount = promauto.NewCounter(prometheus.CounterOpts{
		Namespace: plugin.Namespace,
		Subsystem: "aggregate",
		Name:      "healthcheck_broken_count_total",
		Help:      "Counter of the number of complete failures of the healthchecks.",
	})
)

Variables declared for monitoring.

Types

type Aggregate

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

Aggregate represents a plugin instance that can aggregate responses from a list of DNS servers.

func New

func New() *Aggregate

New returns reference to new Aggregate plugin instance with default configs.

func (*Aggregate) Name

func (f *Aggregate) Name() string

Name implements plugin.Handler.

func (*Aggregate) OnShutdown

func (f *Aggregate) OnShutdown() error

OnShutdown stops all configured clients.

func (*Aggregate) OnStartup

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

OnStartup starts a goroutines for all clients.

func (*Aggregate) ServeDNS

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

ServeDNS implements plugin.Handler.

type Client

type Client interface {
	Request(context.Context, *request.Request) (*dns.Msg, error)
	Endpoint() string
	SetTLSConfig(*tls.Config)
}

Client represents the proxy for remote DNS server

func NewClient

func NewClient(addr, net string) Client

NewClient creates new client with specific addr and network

type Domain

type Domain interface {
	Get(string) Domain
	AddString(string)
	Add(string, Domain)
	Contains(string) bool
	IsFinal() bool
	Finish()
}

Domain represents DNS domain name

func NewDomain

func NewDomain() Domain

NewDomain creates new domain instance

type Transport

type Transport interface {
	Dial(ctx context.Context, net string) (*dns.Conn, error)
	SetTLSConfig(*tls.Config)
}

Transport represent a solution to connect to remote DNS endpoint with specific network

func NewTransport

func NewTransport(addr string) Transport

NewTransport creates new transport with address