Kea DHCPv4: Support option-def and vendor spaces (extends #9942)

[Roskoov]

Important notices

• I have read the contributing guide lines at https://github.com/opnsense/core/blob/master/CONTRIBUTING.md
• I am convinced that my issue is new after having checked both open and closed issues

Is your feature request related to a problem? Please describe.

This extends opnsense/core#9942 (MVP for custom options, delivered in 26.1). The current Options tab supports standard DHCP options with custom encoding, but does not support Kea's option-def framework or vendor spaces.

Concrete use case: replacing an Orange (French ISP) Livebox with OPNsense requires sending DHCP option 125 (VIVSO, RFC 3925) with vendor sub-options in a vendor-3561 space. This needs:

1. Custom option-def entries to define sub-options in a vendor space
2. A space field in the option editor to target a vendor space instead of dhcp4
3. Support for vivso-suboptions to declare the enterprise number

Without these, Kea's VIVSO framework cannot be used from the GUI. Encoding option 125 as raw hex in the current Options tab does not work — Kea parses only the enterprise number and drops the sub-option payload (confirmed via tcpdump: Unknown (125), length 5: 0.0.13.233.0 instead of the full vendor data).

The only workaround is the manual configuration file, which disables all GUI management.

Describe the solution you like

• A section to define option-def entries (name, code, type, space)
• A space dropdown or text field in the Option editor
• These would allow the GUI to generate:

"option-def": [
  { "name": "vc-opt4", "code": 4, "type": "binary", "space": "vendor-3561" }
],
"option-data": [
  { "name": "vivso-suboptions", "data": "3561" },
  { "name": "vc-opt4", "space": "vendor-3561", "csv-format": false, "data": "343444343534" }
]

Additional context

This affects all French users replacing their Orange Livebox with OPNsense (common setup). Same limitation applies to any ISP or environment using DHCP option 125 with vendor sub-options (RFC 3925).

[Monviech]

Why should KEA parse anything if raw hex is sent? This feels suspicious. I would assume if you correctly construct the binary hex for option 125 that the client needs, it should work as well.

[Monviech]

Check with tcpdump what kind of binary hex your client receives when you construct it with the option def and suboption thing, write it down.

Send the same as raw hex, I assume that should work?

[Roskoov]

Sure, here's the tcpdump -XX from the working manual config (option-def + vivso framework).

Option 125 on the wire (from the DHCP Reply hex dump):

7d 29 00 00 0d e9 24 04 06 XX XX XX XX XX XX 05 0f XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX 06 09 XX XX XX XX XX XX XX XX XX

• 7d = option 125
• 29 = total length 41 bytes
• 00 00 0d e9 = enterprise number 3561
• 24 = sub-options data length (36 bytes)
• 04 06 ... = sub-option 4 (6 bytes)
• 05 0f ... = sub-option 5 (15 bytes)
• 06 09 ... = sub-option 6 (9 bytes)

(values redacted but structure preserved)

The data payload after the option code and length byte is exactly the same hex I sent as raw via the GUI: 00000DE924... same enterprise number, same sub-option TLVs, byte for byte.

But when sent as raw hex via the GUI (code: 125, csv-format: false, data: "00000DE924..."):

Unknown (125), length 5: 0.0.13.233.0

Only 5 bytes on the wire. The sub-option payload is gone.

With the manual config using option-def + vivso-suboptions + vendor-3561 space: full 41-byte option 125 on the wire, TV decoder authenticates correctly.

Same bytes, different result depending on whether Kea constructs option 125 via its vendor space framework or receives it as raw hex data.

---

For reference, here are the two configs side by side:

Working manual config (option-def + vivso framework):

"option-def": [
  { "name": "vc-opt4", "code": 4, "type": "binary", "space": "vendor-3561" },
  { "name": "vc-opt5", "code": 5, "type": "binary", "space": "vendor-3561" },
  { "name": "vc-opt6", "code": 6, "type": "binary", "space": "vendor-3561" }
],
"option-data": [
  { "name": "vendor-class-identifier", "csv-format": true, "always-send": true, "data": "sagem" },
  { "code": 77, "csv-format": false, "always-send": true, "data": "0d50435f4d4c54565f5748443934" },
  { "code": 90, "csv-format": false, "always-send": true, "data": "<redacted>" },
  { "name": "vivso-suboptions", "always-send": true, "data": "3561" },
  { "name": "vc-opt4", "space": "vendor-3561", "always-send": true, "csv-format": false, "data": "<redacted>" },
  { "name": "vc-opt5", "space": "vendor-3561", "always-send": true, "csv-format": false, "data": "<redacted>" },
  { "name": "vc-opt6", "space": "vendor-3561", "always-send": true, "csv-format": false, "data": "<redacted>" }
]

Result: full 41-byte option 125 on the wire, TV decoder works.

GUI-generated config (raw hex for option 125):

"option-data": [
  { "code": 125, "csv-format": false, "always-send": true, "data": "00000DE924..." }
]

Result: only 5 bytes on the wire (0.0.13.233.0), TV decoder fails.

[Monviech]

So it looks like Kea treats option 125 specially and reconstructs it using the VIVSO framework rather than forwarding raw bytes unchanged.

This is rather annoying and sounds like an upstream bug. If I set csv-format to false and inject raw bites, my expectation would be to send them out unchanged since it's just like any other payload.

Could you maybe open up an issue upstream with KEA about this and ask for clarification?

How does dnsmasq behave when sending the same raw bytes?

[Roskoov]

Tested with dnsmasq. Disabled Kea, enabled dnsmasq on my VLAN_TV only, set option 125 as raw hex with the same payload.

Unknown (125), length 41: 0.0.13.233.36.4.6.XX.XX.XX.XX.XX.XX.5.15.XX.XX.XX.XX.XX.XX.XX.XX.XX.XX.XX.XX.XX.XX.XX.6.9.XX.XX.XX.XX.XX.XX.XX.XX.XX

(values redacted, structure preserved)

Full 41 bytes on the wire. Same raw hex that Kea truncates to 5 bytes is sent as-is by dnsmasq.

Regarding the upstream report: I couldn't create an account on the ISC GitLab (requires an organizational email). I subscribed to the kea-users mailing list and sent the bug report there, waiting for a response. The full bug report content is in my previous comment if you'd like to open it on the ISC GitLab directly.

[Monviech]

Thank you for testing and going upstream, I think their user mailing list is the correct channel. Lets see what happens there and if its framed as a bug there too or a configuration issue, the latter I don't expect given the current evidence and working config in dnsmasq.

https://lists.isc.org/mailman/listinfo/kea-users

https://lists.isc.org/pipermail/kea-users/2026-March/006035.html

[Roskoov]

Finally managed to open the upstream issue on ISC GitLab: https://gitlab.isc.org/isc-projects/kea/-/issues/4442

[Monviech]

Moved since it looks like it only depends on the port and a future kea version now.

[Monviech]

I guess this is our issue again, I will take this back and try a way forward here:
opnsense/core#10509