FreeBSD Kea DHCP Server Operations: Pools, Leases, and Safe Rollouts

Kea is ISC’s DHCP server for IPv4 and IPv6. On FreeBSD it is available through the Ports Collection and package repositories as third-party software. The server’s job is to receive client requests on selected interfaces, choose an address from a configured subnet and pool, persist lease state, and return options such as routers and DNS servers.

A DHCP configuration can disrupt an entire VLAN if its interface scope, address pool, or gateway option is wrong. Build and test the configuration on an isolated network before enabling the service on a production segment. Do not treat a successful daemon start as proof that clients will receive a safe address or that an existing DHCP server has been retired.

Install and inspect the FreeBSD service integration

Install the port package and inventory its installed files before enabling it:

pkg install kea
pkg info -l kea | grep -E 'etc/kea|rc.d/kea'

The FreeBSD port installs a kea rc script that controls keactrl and ships sample configurations under /usr/local/etc/kea. The rc variable is kea_enable, and its default is disabled. Confirm the exact package files and release version on the host instead of assuming sample paths from another platform.

Copy the sample configuration to a managed file, preserve its ownership and mode, and record the package version:

install -m 0640 /usr/local/etc/kea/kea-dhcp4.conf.sample \
  /usr/local/etc/kea/kea-dhcp4.conf
pkg info kea

Kea’s FreeBSD rc integration also expects keactrl.conf. Review which server daemons it will start and their configuration paths. Do not enable DHCPv6, Dynamic DNS, or a control agent merely because sample files exist. Enable only the service components required by the design.

Define a deliberately bounded subnet

This example uses documentation-only addresses and is intended for an isolated test VLAN. Replace the interface and subnet with a network you administer. Ensure that static infrastructure addresses are excluded from the dynamic pool and that no other DHCP server can answer on the segment.

{
  "Dhcp4": {
    "interfaces-config": {
      "interfaces": [ "em0" ]
    },
    "lease-database": {
      "type": "memfile",
      "persist": true,
      "name": "kea-leases4.csv"
    },
    "valid-lifetime": 3600,
    "subnet4": [
      {
        "id": 1,
        "subnet": "192.0.2.0/24",
        "pools": [
          { "pool": "192.0.2.100 - 192.0.2.199" }
        ],
        "option-data": [
          { "name": "routers", "data": "192.0.2.1" },
          { "name": "domain-name-servers", "data": "192.0.2.53" }
        ]
      }
    ]
  }
}

The sample has one subnet, one dynamic range, one interface, a persistent memfile lease database, and a finite lease lifetime. The router and DNS addresses are examples; they must be reachable and appropriate for the real VLAN. RFC 5737 addresses are reserved for documentation and should not be treated as routable production assignments.

Lease persistence matters. Kea’s documentation explains that disabling memfile persistence can cause a restarted server to forget assigned addresses and offer an address that is already in use. Keep persistence enabled for normal service. Select lease file location and retention with the FreeBSD package’s data-directory behavior in mind; use a simple filename in the documented data directory unless the installed Kea version explicitly supports another path.

Validate configuration before enabling service

Kea’s DHCPv4 server supports a configuration test mode that loads and checks a file, reports errors, and exits without serving normal DHCP requests:

kea-dhcp4 -t /usr/local/etc/kea/kea-dhcp4.conf

The test cannot prove every runtime dependency or network behavior. Review the exact exit status and diagnostics, then test on an isolated interface with a client you control. Confirm the interface exists and is up, the server has the intended address on that subnet, and the upstream switch or relay will direct only the intended requests to this server.

Before enabling the rc service, inspect keactrl.conf and verify the intended daemon configuration paths. Enable and start the service only in a maintenance window with rollback:

sysrc kea_enable="YES"
service kea start
service kea status

If the configuration lives elsewhere or the installed service uses different behavior, follow its local rc script and package documentation. Keep the previous known-good configuration until the new server has passed client and lease-state tests.

Verify the DHCP exchange end to end

On the server, inspect the configured address, route, service status, and UDP packet exchange:

ifconfig em0
netstat -rn
service kea status
tcpdump -ni em0 'udp port 67 or udp port 68'

Replace em0 with the interface configured in Kea. A packet capture can show Discover, Offer, Request, and Acknowledgment traffic, but it does not prove that a client installed the lease or can reach its gateway. From a test client, verify its address, prefix, default route, DNS servers, lease expiry, and renewal behavior.

Observe the lease file through Kea’s supported tools or read-only inspection while the service is stopped or according to its documented concurrency rules. Do not edit lease records manually. For a memfile backend, periodic cleanup may compact historical records; schedule and monitor this using the documented settings rather than deleting the live database to “reset” clients.

If clients are on another subnet, an authorized DHCP relay must forward requests to the server. A packet capture on the server can distinguish no request from a request with an unmatched subnet or pool. Validate relay address and giaddr behavior with the network team before expanding scope.

Plan renewals, reservations, and migration

Set lease lifetimes based on address scarcity, expected client churn, and outage behavior. Short leases increase renewal traffic and server/database activity; long leases retain allocations after a client disappears. A lease lifetime does not guarantee that an address is continuously available, nor does a static reservation remove the need to consider pool overlap.

Keep host reservations and dynamic ranges non-overlapping by design. Use a documented client identifier policy and verify how the target Kea version matches hardware addresses and DHCP client identifiers. A client can present a different identifier after an OS reinstall or interface change. Test reservation behavior using the actual client type instead of assuming that a MAC address is always the only key.

For migration from another DHCP server, export and review leases, reservations, options, and vendor-specific behavior. Prevent both servers from allocating from the same pool during cutover. Use a test VLAN, staged clients, and a rollback plan that includes the old server’s lease database. A new daemon serving the right options but with no record of active leases can create duplicate-address incidents.

Kea’s configuration, lease backend, and optional high-availability components are separate design choices. A second server is not automatically a failover pair; shared or replicated state and coordination must be configured according to Kea’s supported model. Do not put two independent servers with the same pool on a segment and call that high availability.

Diagnose common failure modes

If kea-dhcp4 -t fails, fix JSON syntax, duplicate keys, missing interfaces, invalid options, or invalid backend paths before starting the service. If the service exits at startup, inspect rc status and the Kea logs; the rc script may orchestrate more than one daemon. A successful start does not prove it bound the intended interface.

If no requests appear, inspect the client VLAN, switch port, relay, and server capture point. If Discover appears but Offer does not, compare the request’s subnet, interface, pool availability, and server logs. If the client receives an address but cannot use it, validate router, DNS, prefix, and duplicate addresses independently.

If a restart causes duplicate assignments, verify that the lease database persists and the server is reading the expected file. Do not erase or replace a live lease file to solve an unexplained conflict. Save the current file, logs, and capture; restore service using the known-good state and reconcile allocations with the network’s authoritative inventory.

Acceptance criteria

Promote a Kea deployment only after configuration tests pass, the service binds to intended interfaces, an isolated client completes the full DORA exchange, options and renewal behavior match the design, persistent lease state survives a controlled restart, and rollback to the prior server has been tested.

Kea automates DHCP allocation; it does not validate address-plan ownership, eliminate duplicate servers, or guarantee client connectivity. Treat network scope and lease state as production data with explicit owners and recoverable change procedures.

Related:

Sources: