KEA DHCP

Index

• KEA DHCP

  • Control Agent

  • DDNS Agent

  • Kea DHCPv4/v6

  • Configuration examples

    • DHCPv4 for medium/large HA setups

    • DHCP Options

    • Dynamic DNS (RFC2136)

    • Prefix Delegation (IA_PD)

  • Leases DHCPv4/v6

Kea is the next generation of DHCP software, developed by Internet Systems Consortium (ISC).

It is considered the replacement for ISC-DHCP in larger HA enabled setups and synergizes well with radvd for HA enabled router advertisements.

Currently it is not possible to register hostnames dynamically between KEA and Unbound, only static reservations will be synchronized on an Unbound service restart.

Control Agent

The Kea Control Agent (CA) is a daemon which exposes a RESTful control interface for managing Kea servers. When building a high available dhcp setup, the control agent is a requirement for these kind of setups.

Option	Description
Enabled	Enable control agent
Bind address	Address on which the RESTful interface should be available, usually this is localhost (127.0.0.1)
Bind port	Choose an unused port for communication here.

Note

Although the control agent is required to use high availability peers, it does not have to listen on a non loopback address. The peer configuration by default uses the so called “Multi-Threaded Configuration (HA+MT)”, in which case it starts a separate listener for the HA communication.

DDNS Agent

The Kea DHCP DDNS (D2) server is a middleware between the DHCP servers, and authoritative DNS servers. Enabling it is a requirement if dynamic DNS updates (RFC2136) should be sent when clients are assigned an IP address in configured subnets.

Option	Description
Enabled	Enable DDNS server. To send updates to an authoritative nameserver, configure Dynamic DNS inside the DHCPv4 and DHCPv6 subnets.
Bind address	Address on which the DHCP DDNS server interface should be available; usually this is localhost (127.0.0.1).
Bind port	Portnumber to use for the DHCP DDNS server interface; default is 53001.

Kea DHCPv4/v6

This is the DHCPv4/v6 service available in KEA, which offers the following tab sheets with their corresponding settings:

Settings (DHCPv4/v6)Subnets (DHCPv4/v6)PD Pools (DHCPv6)Reservations (DHCPv4/v6)Options (DHCPv4/v6)HA Peers (DHCPv4/DHCPv6)

Option	Description
Service
Enabled	Enable DHCPv4/v6 server.
Manual config	Disable configuration file generation and manage the file (/usr/local/etc/kea/kea-dhcp4.conf) or (/usr/local/etc/kea/kea-dhcp6.conf) manually.
General settings
Interfaces	Select interfaces to listen on.
Valid lifetime	Defines how long the addresses (leases) given out by the server are valid (in seconds)
Firewall rules	Automatically add a basic set of firewall rules to allow dhcp traffic, more fine grained controls can be offered manually when disabling this option.
Socket type** (DHCPv4 only)	Socket type used for DHCP communication.
High Availability
Enabled	Enable High availability hook, requires the Control Agent to be enabled as well.
This server name	The name of this server, should match with one of the entries in the HA peers. Leave empty to use this machines hostname
Max Unacked clients	This specifies the number of clients which send messages to the partner but appear to not receive any response. A higher value needs a busier environment in order to consider a member down, when set to 0, any network disruption will cause a failover to happen.

Configuration examples

DHCPv4 for medium/large HA setups

KEA DHCPs main strength is the ability to synchronize leases between multiple servers, which makes it ideal for medium to large HA setups (more than 1000 unique clients) where you cannot use Dnsmasq DHCP.

As example we configure a network with two KEA DHCP instances on a master and backup OPNsense.

To configure KEA with a minimal HA setup for LAN using the 192.168.1.0/24 network follow these steps:

LAN Network:

• CARP IPv4 address: 192.168.1.1/24

• Master IPv4 address: 192.168.1.2/24

• Backup IPv4 address: 192.168.1.3/24

Attention

All configuration must be done on the master, and afterwards synchronized to the backup via System: ‣ High Availability ‣ Status

• Go to Services ‣ KEA DHCP ‣ Control Agent:

Option	Value
Enabled	X
Bind address	127.0.0.1
Bind port	8000

• Press Apply then go to Services ‣ KEA DHCP ‣ KEA DHCPv4 and follow through these tabs:

SettingsSubnetsHA Peers

Option	Value
Service
Enabled	X
General settings
Interfaces	LAN
Firewall rules**	X
High Availability
Enabled	X
This server name	(It is highly recommended to use the offered default value)

• Press Apply and go to Subnets

Now the initial configuration is finished, and we synchronize it with the backup server. Both servers will always share the exact same configuration.

Go to System: ‣ High Availability ‣ Settings and ensure that KEA is selected in Services to synchronize.

Then go to System: ‣ High Availability ‣ Status and press Synchronize and reconfigure all.

Immediately afterwards, KEA will be active on both master and backup, and a bidirectional lease synchronization will be configured.

DHCP Options

Each subnet and reservation has an DHCP option data list available. If Auto collect option data is enabled, some DHCP options like router, DNS server and system domain are added automatically. Additional fields can be filled out with other common options.

In cases where more advanced DHCP options need to be sent, you can use the Options tab found in Services ‣ KEA DHCP ‣ KEA DHCPv4 and Services ‣ KEA DHCP ‣ KEA DHCPv6.

When adding a new option, you can enter matching and setting parameters:

• When matching a DHCP option, a client class with a test is created. The set option will only be sent to clients that pass the test.

• When setting a DHCP option, the payload will be sent unconditionally if no match exists in the same input mask.

To send a created option, attach it to a reservation or subnet in their respective tabs with the available Options dropdown menu.

Combining both set and match enables you to create multiple options with the same code, but different payloads. A common example is matching based on client architecture and sending a specific boot file as payload:

• Go to Services ‣ KEA DHCP ‣ KEA DHCPv4 and follow through these tabs:

OptionSubnets

Create an option for BIOS boot:

Option	Description
Description	option-bios-bootfile
Match DHCP option
Match Code	client-system [93]
Match Encoding	uint16
Match Data	0
Set DHCP option
Set Code	bootfile-name [67]
Set Encoding	string
Set Data	undionly.kpxe

Create an option for EFI boot:

Option	Description
Description	option-efi-bootfile
Match DHCP option
Match Code	client-system [93]
Match Encoding	uint16
Match Data	7
Set DHCP option
Set Code	bootfile-name [67]
Set Encoding	string
Set Data	snponly.efi

• Press Save and go to Subnets

With this configuration, any client that sends client-system [93] containing the value 0 will be provided with bootfile-name [67] and undionly.kpxe. The same logic applies to the efi bootfile.

Note

Matching is optional, leave it empty to send the option out to any client in the subnet it is attached to.

Tip

Any option can be sent as user defined hex. This helps for structured and encapsulated options that may have multiple types or are binary blobs. A common example is vendor specific [43], which is used for vendor specific information. Just as with the bootfiles example, if you match client specific option codes, you can send out different vendor specific option codes in the same subnet.

Dynamic DNS (RFC2136)

KEA allows registering client FQDNs via dynamic DNS (RFC2136) to an authoritative DNS server.

Such an authoritative DNS server will be ISC BIND or an alternative like PowerDNS. Recursive DNS servers like Dnsmasq or Unbound are not able to fulfill this role.

When clients register their IP address, the DHCP server will receive a Client FQDN (DHCP option 81) that either contains a client hostname or an FQDN. In cases where clients only send a hostname, using the DNS qualifying suffix will construct an FQDN and force an update anyway.

Attention

The client is responsible to send the Dynamic DNS update request via DHCP option 81. Only with this payload, the hostname will be registered in a forward zone. Clients that do not send any hostname cannot be registered, the administrator must ensure all of their devices have unique hostnames configured.

As an example setup, we have configured a zone like this in ISC BIND. The example taken from the KEA DDNS documentation:

:
key "key.four.example.com." {
    algorithm hmac-sha224;
    secret "bZEG7Ow8OgAUPfLWV3aAUQ==";
};
:

To configure the forward zone for a DHCPv4 range, go to Services ‣ KEA DHCP ‣ KEA DHCPv4 and select a subnet:

Option	Value
Subnet	192.168.1.0/24
Pools	192.168.1.100 - 192.168.1.199
DHCP option data
Auto collect option data	(This must be unchecked)
Routers (gateway)	192.168.1.1
DNS servers	192.168.1.1
Domain name	four.example.com
Dynamic DNS
DNS forward zone	four.example.com.
DNS qualifying suffix	four.example.com. (optional, use if your clients do not send an FQDN via DHCP option 81)
DNS server	203.0.113.1
TSIG key name	key.four.example.com.
TSIG key secret	bZEG7Ow8OgAUPfLWV3aAUQ==
TSIG key algorithm	hmac-sha224

Next, enable the KEA DDNS Agent. Go to Services ‣ KEA DHCP ‣ DDNS Agent:

Option	Value
Enabled	X
Bind address	127.0.0.1
Bind port	53001

After applying the configuration, the DHCP servers construct DDNS update requests, known as NameChangeRequests (NCRs), based on DHCP lease change events and then post them to the DDNS Agent. The DDNS Agent attempts to match each request to the appropriate DNS server and carries out the necessary conversation with those servers to update the DNS data.

Note

The TSIG key name must be unique per DNS forward zone. If you configure multiple subnets with an identical DNS forward zone, but different TSIG key names and TSIG key secrets, only the first one will be taken into account. Best practice would be creating one unique DNS forward zone per subnet, each with a unique TSIG key name.

Attention

Only subnets that have a DNS server configured will send DDNS updates.

Prefix Delegation (IA_PD)

Kea supports prefix delegation with static prefixes.

Attention

Dynamic prefixes common with most residential ISPs are not supported.

As an example setup, we will use unique local addresses (ULA) to lease an IA_NA address (/128 IPv6 address) and a IA_PD prefix (/56 IPv6 prefix) to a requesting client.

Prefix: fd80::/48

• Go to Services ‣ KEA DHCP ‣ KEA DHCPv6 and follow through these tabs:

SettingsSubnetsPD Pools

Option	Value
Service
Enabled	X
General settings
Interfaces	LAN
Firewall rules	X

After applying the configuration, clients will receive a IA_NA address (e.g. fd80::100/128, fd80::101/128) and a IA_PD prefix (e.g. fd80:0:0:1000::/56, fd80:0:0:1010::/56).

Whenever a IA_PD lease is acknowledged, a route targeting the link local address (LLA) of the requesting DHCPv6 client will be automatically installed.

Since lease files are synchronized in high availability mode, the routes will also be installed and cleaned up on both peers.

Leases DHCPv4/v6

This page offers an overview of the (non static) leases being offered by KEA DHCPv4/v6.

Tip

There are action buttons to quickly register and find reservations.