kea

README

example

Name

kea - supports Kea lease hostname lookups

Description

This plugin offers two methods to load hostname/IP data from Kea.

Supports	Reservations	Leases
Control agent [^1]	⚠️ [^2]	✅
Configuration file	✅	❌

[^1]: The Kea Control Agent has been deprecated in Kea 3.0 in favour of directly contacting the dhcp4 and dhcp6 agents. This plugin doesn't yet support those connections.

[^2]: The Kea Control Agent supports reservation information if it is built with the host control hook. This was a paid add-on before Kea 2.7.7/Kea 3.0.

Authentication note

OPNsense doesn't support configuring authentication on its Kea control agent, so neither does this plugin at this time.

Compilation

This package will always be compiled as part of CoreDNS and not in a standalone way. It will require you to use go get or as a dependency on plugin.cfg.

The manual will have more information about how to configure and extend the server with external plugins.

A simple way to consume this plugin, is by adding the following on plugin.cfg, and recompile it as detailed on coredns.io.

kea:github.com/ionothanus/coredns-kea

You can compile coredns by:

go generate
go build

Or you can instead use make:

make

Syntax

kea {
  # One of the following must be configured.
  control_agent http://localhost:8000
  dhcp4_conf /etc/kea/kea-dhcp4.conf
  dhcp6_conf /etc/kea/kea-dhcp6.conf

  # Filter IP responses to include only ones in the specified CIDRs.
  # If unspecified, filtering will be disabled.
	networks 10.0.0.0/16 10.10.0.0/16

  # Set to "false" if you have an HTTPS proxy for your control agent
  # and you want to enforce a secure connection. "false" by default.
	insecure false
  
  # Use extract_hostname to send only the hostname of a domain name query to Kea.
  # For example, if the request will look up test.example.com, "true" here
  # would send "test" as the hostname to Kea. "false" by default.
	extract_hostname true

  # You can disable one or the other, but at least one of lease and reservation lookups 
  # must be enabled when the control agent is enabled.
  # Both are enabled by default.
	control_agent_leases true
	control_agent_reservations false

  # You can disable one or the other, but at least one of IPv4 and IPv6 support must be enabled.
  # Both are enabled by default with the control agent. 
  # They are automatically enabled as appropriate when dhcp[4,6]_conf are set.
	use_ipv4 true
	use_ipv6 true
}

Metrics

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

• coredns_kea_request_count_total{server} - query count to the kea plugin.

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

Ready

This plugin reports readiness to the ready plugin. It will be immediately ready.

Also See

See the manual. This plugin was derived from coredns-proxmox.

Documentation

Index

• Constants
• func CompareCIDRs(subnet1 string, subnet2 string) bool
• func FilterIPsInCIDRs(ips []net.IP, cidrs []string) (filteredIps []net.IP, err error)
• type Kea
  • func (k Kea) ControlAgentGetIPsForLease(deviceName string) (ips []net.IP, err error)
  • func (k Kea) ControlAgentGetIPsForReservation(deviceName string) (ips []net.IP, err error)
  • func (k Kea) GetIPsForHostname(deviceName string) (ips []net.IP, err error)
  • func (k Kea) MakeControlAgentRequest(requestBody string) (responseBody []byte, err error)
  • func (k Kea) Name() string
  • func (e Kea) Ready() bool
  • func (k Kea) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
• type KeaDHCP4Conf
• type KeaDHCP6Conf
• type KeaLeaseRecords
• type KeaReservationRecords
• type KeaResultCode

Constants

const KEA_IPV4_SERVICE_NAME = "dhcp4"

const KEA_IPV6_SERVICE_NAME = "dhcp6"

const KEA_LIST_LEASES_BY_HOSTNAME_TEMPLATE = `{
  "command": "lease4-get-by-hostname",
  "arguments": {
    "hostname": "%s"
  },
  "service": [
    %s
  ]
}`

const KEA_LIST_RESERVATIONS_BY_HOSTNAME_TEMPLATE = `{
  "command": "reservation-get-by-hostname",
  "arguments": {
    "hostname": "%s"
  },
  "service": [
    %s
  ]
}`

Functions

func CompareCIDRs

func CompareCIDRs(subnet1 string, subnet2 string) bool

func FilterIPsInCIDRs

func FilterIPsInCIDRs(ips []net.IP, cidrs []string) (filteredIps []net.IP, err error)

Types

type Kea

type Kea struct {
	ControlAgent             string
	Networks                 []string
	ExtractHostname          string
	ControlAgentLeases       string
	ControlAgentReservations string
	Insecure                 string
	Next                     plugin.Handler
	UseIPv4                  string
	UseIPv6                  string
	DHCP4ConfPath            string
	DHCP6ConfPath            string
	DHCP4Conf                KeaDHCP4Conf
	DHCP6Conf                KeaDHCP6Conf
}

func (Kea) ControlAgentGetIPsForLease

func (k Kea) ControlAgentGetIPsForLease(deviceName string) (ips []net.IP, err error)

func (Kea) ControlAgentGetIPsForReservation

func (k Kea) ControlAgentGetIPsForReservation(deviceName string) (ips []net.IP, err error)

func (Kea) GetIPsForHostname

func (k Kea) GetIPsForHostname(deviceName string) (ips []net.IP, err error)

func (Kea) MakeControlAgentRequest

func (k Kea) MakeControlAgentRequest(requestBody string) (responseBody []byte, err error)

func (Kea) Name

func (k Kea) Name() string

func (Kea) Ready

func (e Kea) Ready() bool

Ready implements the ready.Readiness interface, once this flips to true CoreDNS assumes this plugin is ready for queries; it is not checked again.

func (Kea) ServeDNS

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

type KeaDHCP4Conf

type KeaDHCP4Conf struct {
	Dhcp4 struct {
		Subnet4 []struct {
			Subnet       string `json:"subnet"`
			Reservations []struct {
				IpAddress string `json:"ip-address"`
				HwAddress string `json:"hw-address"`
				Hostname  string `json:"hostname,omitempty"`
			} `json:"reservations,omitempty"`
		} `json:"subnet4"`
	} `json:"Dhcp4"`
}

type KeaDHCP6Conf

type KeaDHCP6Conf struct {
	Dhcp6 struct {
		Subnet6 []struct {
			Subnet       string `json:"subnet"`
			Reservations []struct {
				IpAddresses []string `json:"ip-addresses"`
				HwAddress   string   `json:"hw-address"`
				Hostname    string   `json:"hostname,omitempty"`
			} `json:"reservations,omitempty"`
		} `json:"subnet6"`
	} `json:"Dhcp6"`
}

type KeaLeaseRecords

type KeaLeaseRecords []struct {
	Arguments struct {
		Leases []struct {
			Cltt      int    `json:"cltt"`
			FqdnFwd   bool   `json:"fqdn-fwd"`
			FqdnRev   bool   `json:"fqdn-rev"`
			Hostname  string `json:"hostname"`
			HwAddress string `json:"hw-address"`
			IPAddress string `json:"ip-address"`
			State     int    `json:"state"`
			SubnetID  int    `json:"subnet-id"`
			ValidLft  int    `json:"valid-lft"`
		} `json:"leases"`
	} `json:"arguments,omitempty"`
	Result KeaResultCode `json:"result"`
	Text   string        `json:"text"`
}

type KeaReservationRecords

type KeaReservationRecords []struct {
	Arguments struct {
		Hosts []struct {
			Hostname    string   `json:"hostname"`
			HwAddress   string   `json:"hw-address"`
			IPAddress   string   `json:"ip-address,omitempty"`
			IPAddresses []string `json:"ip-addresses,omitempty"`
			SubnetID    int      `json:"subnet-id"`
		} `json:"hosts"`
	} `json:"arguments,omitempty"`
	Result KeaResultCode `json:"result"`
	Text   string        `json:"text"`
}

type KeaResultCode

type KeaResultCode int

const (
	Success KeaResultCode = iota
	Error
	Unsupported
	NoContent
)