Adding Custom Configuration in Kea DHCP Server with pfSense+ 25.03

[marcosm]

Similarly to how custom configuration is possible with the DNS Resolver and OpenVPN services, the pfSense+ 25.03 release brings custom configuration support for the Kea-backed DHCP Server. A common setting used with the deprecated ISC DHCP Server is "Custom DHCP Options". The following is a quick guide on how the same can be accomplished with the "Custom Configuration" setting for Kea.

Note: DHCP options which are already defined in Kea, such as v4-captive-portal (option 114), must not be re-defined in the custom configuration. The Kea manual (see "List of standard DHCPv4 options configurable by an administrator") lists these predefined options.

Here's an example that configures option 114 and option 43 with two vendors (unifi and an example from the Kea manual). Option 43 is a bit special and requires additional definition. Note that option 114 may require additional configuration in Captive Portal (e.g. for RFC8908 support).

In Services / DHCP Server / Settings add the following:

{
  "option-def": [
    {
      "name": "unifi",
      "code": 1,
      "space": "vendor-encapsulated-options-space",
      "type": "string",
      "encapsulate": ""
    },
    {
      "name": "examplevendor",
      "code": 2,
      "space": "vendor-encapsulated-options-space",
      "type": "record",
      "array": false,
      "record-types": "ipv4-address, uint16, string",
      "encapsulate": ""
    }
  ]
}

In Services / DHCP Server / LAN add the following:

{
  "option-data": [
    {
      "name": "vendor-encapsulated-options"
    },
    {
      "name": "unifi",
      "space": "vendor-encapsulated-options-space",
      "data": "01:04:c0:00:02:03"
    },
    {
      "name": "examplevendor",
      "space": "vendor-encapsulated-options-space",
      "csv-format": true,
      "data": "192.0.2.3, 123, Hello World"
    },
    {
      "name": "v4-captive-portal",
      "data": "https://captiveportal.example.com:8003/index.php?zone=guest"
    }
  ]
}

[marcosm]

Side-note: here's a helpful tool to validate the JSON data before adding it to the custom configuration:
https://string.is/json-formatter

[jaysee3]

Hi,

I have just updated to the latest beta of pfSense+ 25.03, but I do not see where I could add these in Services / DHCP Server / Settings or Services / DHCP Server / LAN.

I'm sure I'm missing something basic or a critical step somewhere, but I don't know what. Besides setting the Server Backend to Kea DHCP, is there anything else I need to do?

Thanks.

[patient0]

@jaysee3 Mmh, never used this feature and went looking for it. It doesn't show for me neither (on 25.03-BETA):

It is not in the "High Availability" section and below that section is nothing.

[Gertjan]

@jaysee3 said in Adding Custom Configuration in Kea DHCP Server with pfSense+ 25.03:

I have just updated to the latest beta of pfSense+ 25.03

This :

tells me your 25.03 dates from early February, so the functionality isn't in our Beta, but in the new beta, not yet available.

As referenced in this thread (see above), go see here : https://forum.netgate.com/topic/190373/feature-15321-shows-how-to-use-option-114-in-kea/8?_=1740912940403, install the patch mentioned here : Redmine #15321.
This one :

and the you'll see this :

at the bottom of : Services > DHCP Server >Settings.

Or wait a while for a new, more recent beta to become available.

[jaysee3]

So in the post before mine, @EDaleH, mentioned this in the linked thread:
"See Adding Custom Configuration in Kea DHCP Server with pfSense+ 25.03 for current information on Plus release 25.03

Now that options are directly supported, the patch will no longer be required. The syntax is the same as it was for the patch."
So I assumed that to be true. Considering this is a different thread and without that context (patch), it would be nice to have confirmation either way (RE: patch required).

I've come full circle. I the Redmine link, I see this post referenced, so can assume it's required.

[jaysee3]

@jaysee3
Meant to edit the original post for clarity but waited too long.

The comment from @EDaleH about not needing the patch was a little confusing, but I've come full circle. In the Redmine link, I see our/this post referenced, so can assume it's required.

With that said, I've applied the latest patch by Dale, but I only see 1 Custom Option input box under Services/DHCP Server/Settings (for the option-def). I don't see the corresponding input box for under each interface (for the option-data) mention by the OP. I have tried to put both definitions and data in that one box but it doesn't seem to work.

[Gertjan]

@jaysee3 said in Adding Custom Configuration in Kea DHCP Server with pfSense+ 25.03:

I don't see the corresponding input box for under each interface

That's correct.
The custom box contains settings that are global :

The json text is very picky about the syntax, it has to be correct, or it is discarded.
That's why a json-formatter validator is proposed ^^ It won't test the validity though.

The patch and parameters work fine for me.
On my captive portal interface, "opt2", the "v4-captive-portal" option is send (the rfc8910 login URL).
On my LAN interface, "custom-option-vendor" is send, with the data "0104C0A80106" = 192.168.1.6.