Skip to content

kea: allow hostname-only DHCP reservations#10423

Draft
tkreagan wants to merge 1 commit into
opnsense:masterfrom
tkreagan:feat/kea-hostname-only-reservations
Draft

kea: allow hostname-only DHCP reservations#10423
tkreagan wants to merge 1 commit into
opnsense:masterfrom
tkreagan:feat/kea-hostname-only-reservations

Conversation

@tkreagan

@tkreagan tkreagan commented Jun 15, 2026

Copy link
Copy Markdown

Important notices

Before you submit a pull request, we ask you kindly to acknowledge the following:

[x] I have read the contributing guidelines at https://github.com/opnsense/core/blob/master/CONTRIBUTING.md
[x]vI opened an issue first for non-trivial changes and linked it below.
[x] AI tools were used to create at least part of the code submitted herewith.

This PR offers a fix for #10208

Kea's reservation model supports hostname-only reservations — a MAC address (or
client ID / DUID) matched against a hostname, with no fixed IP address. When a
matching client requests a lease, Kea assigns a dynamic address from the pool
and substitutes the reserved hostname in the lease record. If DDNS is configured,
that hostname is used for the DNS update. Cooperative clients may also adopt the
hostname from the DHCP response, though this is client-dependent and not
guaranteed.

This is particularly useful on networks with embedded devices — IoT sensors,
thermostats, access points, printers — that do not support direct hostname
configuration and would otherwise negotiate generic or vendor-default names.
A hostname-only reservation pins a meaningful, collision-free name to the device
by MAC address in the lease database, without also locking it to a specific IP
address.

OPNsense currently requires an IP address on every reservation. The only blocker
is a missing null-guard in performValidation(): isIPInCIDR("", ...) returns
false unconditionally, so saving with an empty IP address always fails. The conf
emitter (getConfigSubnets()) already omits the ip-address field when empty
and produces valid Kea JSON.

Changes:

  • KeaDhcpv4.php: guard the CIDR check with a non-empty test before calling
    isIPInCIDR; require a hostname when no IP address is given.
  • KeaDhcpv6.php: same null-guard; accept hostname as a valid third alternative
    to ip_address / prefix in the "at least one must be set" check.
  • dialogReservation4.xml, dialogReservation6.xml: update IP address and
    hostname field help text to describe the hostname-only behaviour.

Kea supports hostname-only reservations — a client matched by MAC/DUID
(or client-id for DHCPv4) with a hostname but no fixed address. Kea
assigns a dynamic address from the pool and stamps the reserved hostname
on the lease record. If DDNS is configured that hostname propagates to
DNS; cooperative clients may also adopt it via option 12/39, though this
is client-dependent.

This is useful for embedded devices (IoT sensors, APs, printers) that
cannot be configured with a hostname directly. A hostname-only reservation
pins a meaningful, collision-free name to the device by hardware address
without locking it to a specific IP.

OPNsense currently rejects any reservation without an IP address. The only
code blocker is a missing null-guard in performValidation(): isIPInCIDR("")
returns false unconditionally, so saving always fails. The conf emitter
(getConfigSubnets()) already omits ip-address when empty and produces valid
Kea JSON — no template changes are needed.

Changes:
- KeaDhcpv4.php: guard CIDR check with non-empty test; require hostname
  when IP address is omitted
- KeaDhcpv6.php: same null-guard; add hostname as a valid third alternative
  to ip_address / prefix in the "at least one must be set" check
- dialogReservation4.xml, dialogReservation6.xml: update IP address and
  hostname field help text to describe the hostname-only behaviour

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Monviech

Copy link
Copy Markdown
Member

Same discussion as in this PR applies here:
#10401

I'm not a fan to weaken the current reservation model.

@tkreagan

tkreagan commented Jun 15, 2026

Copy link
Copy Markdown
Author

Yes, I added comments to the upstream Issue request - #10208 - as well. I just created this PR as the simplest possible implementation of that Issue, #10401 has a couple of things in there.

@Monviech

Monviech commented Jun 15, 2026

Copy link
Copy Markdown
Member

It's not an argument about code or how simple it is to change it.

It's about the current identity of a reservation object inside the current KEA model.

The current model is strong because it constrains the possible states in a way that can be nicely supported, maintained and understood by the majority of users.

I also worked on the dnsmasq reservation model where the contract is far weaker, and there are lots of validations and edge cases implemented. I certainly don't want that repeated for KEA.

@tkreagan

Copy link
Copy Markdown
Author

Sorry, would it be better to discuss in the pull request or the original issue - #10208?

@Monviech

Copy link
Copy Markdown
Member

I don't have anything more to discuss here. It's up to the other maintainers if it peaks their interest.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants