ipref

package module
v0.0.0-...-8503a67 Latest Latest
Warning

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

 Go to latest Published: Jun 12, 2021 License: Apache-2.0 Imports: 19 Imported by: 0

README

ipref

Name

ipref - perform recursive queries that can resolve IPREF addresses

Description

Via ipref you can perform recursive queries that resolve IPREF addresses in addition to standard IPv4 and IPv6 addresses. Ipref plugin is based on unboud plugin which uses libunbound library. Unbound uses DNSSEC by default when resolving and it returns those records (DNSKEY, RRSIG, NSEC and NSEC3) back to the clients. The ipref 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.

This code includes technology covered by patent US 10,749,840 B2.

Syntax

ipref [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:

ipref [FROM] {
    except IGNORED_NAMES...
    option NAME VALUE
}
  • 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.

Metrics

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

  • coredns_ipref_request_duration_seconds{server} - duration per query.
  • coredns_ipref_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:

. {
    ipref
}

Resolve all queries within example.org.

. {
    ipref example.org
}

or

example.org {
    ipref
}

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

. {
    ipref {
        except example.org
    }
}

Enable DNS Query Name Minimisation by setting the option:

. {
    ipref {
        option qname-minimisation yes
    }
}

Bugs

IPREF needs new DNS resource record type. The plan is to register AA records with IANA. For now, as a workaround to allow development, the unavailable AA records are emulated by embedding them in TXT records. This is invisible to hosts requesting name resolution.

The ipref 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 configurating a trust anchor.

See Also

See https://github.com/ipref/dns for information on IPREF addressing.
See https://github.com/coredns/unbound for information on the unboud plugin.
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

Constants

View Source 
const (
	// v1 constants
	V1_SIG      = 0x11 // v1 signature
	V1_HDR_LEN  = 8
	V1_AREC_LEN = 4 + 4 + 4 + 8 + 8 // ea + ip + gw + ref.h + ref.l
	// v1 header offsets
	V1_VER      = 0
	V1_CMD      = 1
	V1_PKTID    = 2
	V1_RESERVED = 4
	V1_PKTLEN   = 6
	// v1 arec offsets
	V1_AREC_EA   = 0
	V1_AREC_IP   = 4
	V1_AREC_GW   = 8
	V1_AREC_REFH = 12
	V1_AREC_REFL = 20
	// v1 commands
	V1_MC_GET_EA = 7
	// v1 tlv types
	V1_TYPE_STRING = 4
	// v1 command mode, top two bits
	V1_DATA = 0x00
	V1_REQ  = 0x40
	V1_ACK  = 0x80
	V1_NACK = 0xC0
)
View Source 
const (
	MSGMAX = ((V1_HDR_LEN + V1_AREC_LEN + 2 + 255 + 16) / 16) * 16 // round up to 16 byte boundary (304)
)

Variables

View Source 
var (
	RequestDuration = prometheus.NewHistogramVec(prometheus.HistogramOpts{
		Namespace: plugin.Namespace,
		Subsystem: "ipref",
		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: "ipref",
		Name:      "response_rcode_count_total",
		Help:      "Counter of rcodes made per request.",
	}, []string{"server", "rcode"})
)

Metrics exported by the ipref plugin.

Functions

This section is empty.

Types

type Ipref 

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

Ipref is a plugin that resolves requests using libunbound.

func New 

func New() *Ipref

New returns a pointer to an initialzed Ipref.

func (*Ipref) Name 

func (ipr *Ipref) Name() string

Name implements the Handler interface.

func (*Ipref) ServeDNS 

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

ServeDNS implements the plugin.Handler interface.

func (*Ipref) Stop 

func (ipr *Ipref) Stop() error

Stop stops unbound and cleans up the memory used.

type MapperClient 

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

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.