unbound

README

unbound

Name

unbound - perform recursive queries using libunbound.

Description

Via unbound you can perform recursive queries. Unbound uses DNSSEC by default when resolving and it returns those records (DNSKEY, RRSIG, NSEC and NSEC3) back to the clients. The unbound plugin will remove those records when a client didn't ask for it. The internal (RR) answer cache of Unbound is disabled, so you may want to use the cache plugin.

Libunbound can be configured via (a subset of) options, currently the following are set, by default:

• msg-cache-size, set to 0
• rrset-cache-size, set to 0

This plugin can only be used once per Server Block.

Syntax

unbound [FROM]

• FROM is the base domain to match for the request to be resolved. If not specified the zones from the server block are used.

More features utilized with an expanded syntax:

unbound [FROM] {
    except IGNORED_NAMES...
    option NAME VALUE
    config FILENAME
}

• FROM as above.
• IGNORED_NAMES in except is a space-separated list of domains to exclude from resolving.
• option allows setting some unbound options (see unbound.conf(5)), this can be specified multiple times.
• config allows one to supply an unbound.conf file to configure unbound. Note: The unbound configuration file still needs to be populated inside a docker container.

Metrics

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

• coredns_unbound_request_duration_seconds{server} - duration per query.
• coredns_unbound_response_rcode_count_total{server, rcode} - count of RCODEs.

The server label indicates which server handled the request, see the metrics plugin for details.

Examples

Resolve queries for all domains:

. {
    unbound
}

Resolve all queries within example.org.

. {
    unbound example.org
}

or

example.org {
    unbound
}

Resolve everything except queries for example.org (or below):

. {
    unbound {
        except example.org
    }
}

Enable DNS Query Name Minimisation by setting the option:

. {
    unbound {
        option qname-minimisation yes
    }
}

Compiling into CoreDNS

To compile this with CoreDNS you can follow the normal procedure for external plugins, except that you need to compile it with cgo. This means setting CGO_ENABLED=1 when running go build.

Bugs

The unbound plugin depends on libunbound(3) which is C library, to compile this you have a dependency on C and cgo. You can't compile CoreDNS completely static. For compilation you also need the libunbound source code installed (libunbound-dev on Debian).

DNSSEC validation is not supported (yet). There is also no (documented) way of configuration a trust anchor.

See Also

See https://unbound.net for information on Unbound and unbound.conf(5). See https://github.com/miekg/unbound for the (cgo) Go wrapper for libunbound.

Documentation

Index

• Variables
• type Unbound
  • func New() *Unbound
  • func (u *Unbound) Name() string
  • func (u *Unbound) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
  • func (u *Unbound) Stop() error

Variables

var (
	RequestDuration = prometheus.NewHistogramVec(prometheus.HistogramOpts{
		Namespace: plugin.Namespace,
		Subsystem: "unbound",
		Name:      "request_duration_seconds",
		Buckets:   plugin.TimeBuckets,
		Help:      "Histogram of the time each request took.",
	}, []string{"server"})

	RcodeCount = prometheus.NewCounterVec(prometheus.CounterOpts{
		Namespace: plugin.Namespace,
		Subsystem: "unbound",
		Name:      "response_rcode_count_total",
		Help:      "Counter of rcodes made per request.",
	}, []string{"server", "rcode"})
)

Metrics exported by the unbound plugin.

Types

type Unbound

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

Unbound is a plugin that resolves requests using libunbound.

func New

func New() *Unbound

New returns a pointer to an initialzed Unbound.

func (*Unbound) Name

func (u *Unbound) Name() string

Name implements the Handler interface.

func (*Unbound) ServeDNS

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

ServeDNS implements the plugin.Handler interface.

func (*Unbound) Stop

func (u *Unbound) Stop() error

Stop stops unbound and cleans up the memory used.