Services: Kea DHCPv6: Dynamic prefix delegation

[Monviech]

Important notices

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

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

If AI was used, please disclose:

• Model used: ChatGPT 5.4
• Extent of AI involvement: Brainstorming about this, rubberducking, help with IPv6 splitting functions and stuff like that that handles prefix calculations

---

Describe the problem

Fixes: #9941

---

Describe the proposed solution

The scope is intentionally limited. Validations prevent interactions we do not want. Things that can make KEA crash are auto generated. The user cannot decide much to protect from hard to troubleshoot issues.

The design revolves around two steps:

1. Create a fully functional KEA config, prevent the user from having too much freedom by constraining every input possible (this can be relaxed later). Keep the GUI as lean as possible, no dynamic hints, dynamic grid values etc.
   To allow KEA to always start, even without any valid prefixes on interfaces, placeholder prefixes are emitted to the subnet, and a client-classes test prevents clients from getting leases from such subnets.
2. A hook script that will take care of prefix changes and subnet lease whipe by using user-context keys from the running KEA config and writing them to the KEA socket. (Read write). We do not need a post apply action this way.
   The hook script is indempodent and very cheap to execute. A failure or a wrong configuration file cannot crash the running KEA daemon.

A concept for 1 is in POC phase and finished
A concept for 2 is in POC phase and finished

---

Generated Configuration file example
Placeholder prefix:

        "subnet6": [
            {
                "id": 1,
                "subnet": "dead:beef::\/58",
                "option-data": [],
                "pools": [
                    {
                        "pool": "dead:beef::\/64"
                    }
                ],
                "pd-pools": [
                    {
                        "prefix": "dead:beef:0:20::",
                        "prefix-len": 59,
                        "delegated-len": 64,
                        "user-context": {
                            "uuid": "c6dabbe0-a0b2-4688-b198-a8402b9b2723"
                        }
                    }
                ],
                "reservations": [],
                "interface": "hn2",
                "user-context": {
                    "uuid": "ab5bdee9-6381-487e-966c-a1cee1bd0a39",
                    "dynamic_prefix": true,
                    "prefix_valid": false,
                    "prefix_source": "wan"
                },
                "require-client-classes": [
                    "NO_LEASES_PLEASE"
                ],
            },
            {
                "id": 2,
                "subnet": "dead:beef:0:68::\/61",
                "option-data": [],
                "pools": [
                    {
                        "pool": "dead:beef:0:68::\/64"
                    }
                ],
                "pd-pools": [
                    {
                        "prefix": "dead:beef:0:6c::",
                        "prefix-len": 62,
                        "delegated-len": 64,
                        "user-context": {
                            "uuid": "fa0a7323-dad8-47ea-92cc-b43bd6e61d37"
                        }
                    }
                ],
                "reservations": [],
                "interface": "hn3",
                "user-context": {
                    "uuid": "057de7ee-bc6e-4677-b6df-8b0ccdedf084",
                    "dynamic_prefix": true,
                    "prefix_valid": false,
                    "prefix_source": "wan"
                },
                "require-client-classes": [
                    "NO_LEASES_PLEASE"
                ],
            },
        ],
        "client-classes": [
            {
                "name": "NO_LEASES_PLEASE",
                "test": "not member('ALL')",
                "only-if-required": true
            }
    }
}

"Real" prefix:

# cat /tmp/hn1_prefixv6
2001:db8:1234::/56

        "subnet6": [
            {
                "id": 1,
                "subnet": "2001:db8:1234::\/58",
                "option-data": [],
                "pools": [
                    {
                        "pool": "2001:db8:1234::\/64"
                    }
                ],
                "pd-pools": [
                    {
                        "prefix": "2001:db8:1234:20::",
                        "prefix-len": 59,
                        "delegated-len": 64,
                        "user-context": {
                            "uuid": "c6dabbe0-a0b2-4688-b198-a8402b9b2723"
                        }
                    }
                ],
                "reservations": [],
                "interface": "hn2",
                "user-context": {
                    "uuid": "ab5bdee9-6381-487e-966c-a1cee1bd0a39",
                    "dynamic_prefix": true,
                    "prefix_valid": true,
                    "prefix_source": "wan"
                },
            },
            {
                "id": 2,
                "subnet": "2001:db8:1234:68::\/61",
                "option-data": [],
                "pools": [
                    {
                        "pool": "2001:db8:1234:68::\/64"
                    }
                ],
                "pd-pools": [
                    {
                        "prefix": "2001:db8:1234:6c::",
                        "prefix-len": 62,
                        "delegated-len": 64,
                        "user-context": {
                            "uuid": "fa0a7323-dad8-47ea-92cc-b43bd6e61d37"
                        }
                    }
                ],
                "reservations": [],
                "interface": "hn3",
                "user-context": {
                    "uuid": "057de7ee-bc6e-4677-b6df-8b0ccdedf084",
                    "dynamic_prefix": true,
                    "prefix_valid": true,
                    "prefix_source": "wan"
                },
            },

[fichtner]

this looks nice! my only worries here are:

1. Validation of "track interface" relationship between subnet and prefix is not well-defined. In the old days you'd select a PD to be on a specific interface in which case it would already know which prefix to use (by looking up LAN -> WAN).
2. Only one dynamic PD with the current enforcement, but need to check the old code and the GUI workflow in order to judge.

[Monviech]

The main constraint here is that a subnet in kea must be unique. So you cannot attach the same prefix to multiple interfaces.

If we want to have that we would need more GUI magic that allows the WAN prefix to be splitted into smaller prefixes, or implement some partial address logic. Both would be fragile.

The current state that allows at least one network to host dynamic PD is a good start I think.

Im open for ideas here.

[fichtner]

If that's the constraint we want to go forward with I don't mind. It also limits the scope and one PD is better than none :)

[Monviech]

I try really hard to limit the scope with this one. Expanding scope later should be doable if users have needs that cannot be met with this model.

EG adding a new prefix ID field or something the like.

But since providers also like playing switcheroo with delegated prefix sizes for single customers all flexibility will bite someone at some point.

EDIT: All of these concerns to not apply anymore to the new model we use now that allows full flexibility.

[fichtner]

tentative approval for the draft. looks snappy.

[Monviech]

@fichtner Now the hook script will be easy. It doesnt need to know or calculate anything :)

• Regenerate template to get new dhcpv6 config
• Use config-reload (no need to post a file to any socket) https://kea.readthedocs.io/en/latest/arm/ctrl-channel.html#the-config-reload-command
• Wipe old leases in the dynamic subnet ids https://kea.readthedocs.io/en/latest/api.html#lease6-wipe

[Monviech]

Please be gentle Copilot

[Copilot]

Pull request overview

Adds dynamic IPv6 prefix delegation support to the Kea DHCPv6 service by deriving subnets/pools from tracked identity-association (idassoc6) prefixes and automatically regenerating/reloading Kea when the WAN IPv6 prefix changes (Issue #9941).

Changes:

• Add an Idassoc helper to compute per-interface on-link and allocatable IPv6 prefixes from tracked PD state.
• Extend Kea DHCPv6 model/GUI/config generation to support “dynamic prefix” subnets and auto-generated pools/PD pools.
• Add a hook script + plugin entry to wipe leases, regenerate config, and reload Kea on WAN IPv6 changes.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/opnsense/scripts/kea/kea_prefix_renew.py	Hook script to wipe dynamic-prefix leases, regenerate dhcp6 config, and reload Kea
src/opnsense/mvc/app/views/OPNsense/Kea/dhcpv6.volt	UI grid formatting + hide/show fields for dynamic prefix mode
src/opnsense/mvc/app/models/OPNsense/Kea/KeaDhcpv6.xml	Model updates for dynamic_prefix field and related UI/display tweaks
src/opnsense/mvc/app/models/OPNsense/Kea/KeaDhcpv6.php	Validation + config generation for dynamic-prefix subnets and PD pools
src/opnsense/mvc/app/library/OPNsense/Interface/Idassoc.php	New library to compute identity-association prefixes (on-link/allocated/associated)
src/opnsense/mvc/app/library/OPNsense/Firewall/Util.php	Add IPv6 prefix splitting helper for deriving non-overlapping child prefixes
src/opnsense/mvc/app/controllers/OPNsense/Kea/forms/dialogSubnet6.xml	Add Dynamic Prefix toggle and grid formatting for subnet/pools
src/opnsense/mvc/app/controllers/OPNsense/Kea/forms/dialogPDPool6.xml	Add grid formatting and styling for PD pool prefix fields
src/etc/inc/plugins.inc.d/kea.inc	Add pluginctl action for dhcpv6 config generation + newwanip(inet6) hook
plist	Install new Idassoc library and kea_prefix_renew script

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Monviech]

No, bad copilot, don't commit changes! Now I have to clean up. Meh.

[Monviech]

This is wrong here after all. KEA documentation:

The only-in-additional-list flag is not mandatory; when its value is set to false (the default), membership is determined during classification and is available for subnet selection, for instance. When the value is set to true, membership is evaluated only if the class appears in an evaluate-additional-classes list and is usable only for option configuration.

[Monviech]

this should also just become client-classes