Adding Custom Configuration in Kea DHCP Server with pfSense+ 25.03

marcosm · Mar 27, 2025, 8:30 PM

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"
    },
    {
      "name": "examplevendor",
      "code": 2,
      "space": "vendor-encapsulated-options-space",
      "type": "record",
      "array": false,
      "record-types": "ipv4-address, uint16, string"
    }
  ]
}

In Services / DHCP Server / LAN add the following:

{
  "option-data": [
    {
      "name": "vendor-encapsulated-options"
    },
    {
      "name": "unifi",
      "space": "vendor-encapsulated-options-space",
      "csv-format": false,
      "data": "0xc0000203"
    },
    {
      "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"
    }
  ]
}

It is also possible to add script hooks to Kea. Scripts are stored at /cf/conf/kea4_scripts.d and /cf/conf/kea6_scripts.d.

marcosm · Mar 4, 2025, 4:13 PM

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

jaysee3 · Mar 2, 2025, 7:46 AM

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 · Mar 2, 2025, 8:59 AM

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

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

Gertjan · Mar 2, 2025, 11:06 AM

@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 :

🔒 Log in to view

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 :

🔒 Log in to view

and the you'll see this :

🔒 Log in to view

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

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

jaysee3 · Mar 3, 2025, 2:57 AM

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 · Mar 3, 2025, 4:28 AM

@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 · Mar 3, 2025, 7:31 AM

@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 :

🔒 Log in to view

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.

marcosm · Mar 3, 2025, 8:45 PM

The change for custom configuration isn't available in the current public beta build. It will be available once we release a new public beta build. When that happens, I suggest removing the old custom condiguration then reverting the patch before upgrading. Once upgraded, follow the guide in the OP - the syntax is slightly different.

jaysee3 · Mar 3, 2025, 8:55 PM

@marcosm
Awesome. Thank you.

jaysee3 · Mar 4, 2025, 7:02 AM

@Gertjan switching type from string to binary did the trick for me. Not sure why type string wasn't working for me. ¯\_(ツ)_/¯

Thanks for all the help.

Gertjan · Mar 4, 2025, 7:02 AM

@jaysee3

You mean :

🔒 Log in to view

instead of https://redmine.pfsense.org/issues/15321 :

🔒 Log in to view

?

I've found out the same thing and that's why I'm using 'binary' instead of 'string'.
That said, I use this "code 43" for my Unifi devices, so they can find the controller. It seems they need the 'binary' format. For other devices that use this option 43, the format might be different.

EDaleH · Mar 26, 2025, 8:06 AM

As of the March 5th 25.03 Beta release:

The purpose of this reply is to clarify RFC8910 or DHCP114 syntax to support smart devices, in particular the iPhone under Captive Portal.

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

In Services / DHCP Server / Settings add the following:

For DHCP 114, it is already defined in Kea as "v4-captive-portal" so no entry needs to be made at all here. I did however have to enter a JSON from the sample, save it, then delete it and save it again before the JSON entry box showed up on the individual Captive Portal's DHCP configuration screen. I mention it here in case anyone has the same problem.

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

In Services / DHCP Server / LAN add the following:

I do not have captive portals on the LAN, all of mine are on OPT1 VLans so go to the correct Captive Portal in Services, DHCP Server, scroll to the bottom and add to the JSON Configuration box something like the following:

{
  "option-data":  [
      {
        "name": "v4-captive-portal",
        "data":  "https://sub.your-domain.com:8003/rfc8910.php?zone=vlan10" 
      }
    ]
}

The rfc8910.php file can be found in Redmine #15904 as RFC8910-w-allowed-MAC-IP-fix.php. It must be renamed to rfc8910.php and placed into /usr/local/captiveportal to work with the above example. Be careful to reference the correct port and vlan for your portal when creating the above JSON.

Gertjan · Apr 9, 2025, 8:27 PM

@EDaleH

Example :
I've 5 "Unifi UB Pro 6" APs on a pfSense, OPT1 network, which is a captive portal.
There are also 2 of these "Unifi UB Pro 6" on my pfSense LAN for wireless company devices.

I've chosen to use the DHCP method of announcing the IP of the UNIFI controller, so I need to create a

{
  "option-def": [
    {
      "space": "dhcp4",
      "name": "custom-option-vendor",
      "code": 43,
      "type": "binary" 
    }
  ]
}

on the main Services > DHCP Server > Settings page.

On the Services > DHCP Server > LAN page :

{
  "option-data":  [
      {
        "name": "custom-option-vendor",
        "data": "0104C0A80106" 
      }
    ]
}

where "0104C0A80106" stands for the IP 192.168.1.6, the IP of my Unifi controller.

The Services > DHCP Server > PORTAL (OPT1) which hosts the captive portal :
Here I announce the RFC8910 method - and also the Unifi controller location :

{
  "option-data":  [
      {
        "name": "v4-captive-portal",
        "data":  "https://portal.bhf.tld:8003/rfc8910.php?zone=cpzone1" 
      },
      {
        "name": "custom-option-vendor",
        "data": "0104C0A80106" 
      }
    ]
}

Btw : "cpzone1" is the name of the captive portal zone present on the OPT interface, 8003 is the port I used for this interface.

The latest pfSense Beta version 25.03.b.20250306.0140 offers two new things here :
There is now a Custom JSON Configuration general config section, valid for the entire DHCP scope, and a Custom JSON Configuration for each interface.
Whatever you enter in the Custom JSON Configuration section is sanity-checked using "lint", and not taken in account when issues (syntax errors) are found.
Be ware : if errors are found, the manually entered data into a Custom JSON Configuration isn't used, so the server will start without it and you'll have a system notification asking you to look at the system log, where you will find, for example :

🔒 Log in to view

The actual error

/services_dhcp.php: The command '/usr/local/sbin/kea-dhcp4 -t /usr/local/etc/kea/kea-dhcp4.conf' returned exit code '1', the output was 'Syntax check failed with: /usr/local/etc/kea/kea-dhcp4.conf:114.25-29: got unexpected keyword "lan" in pools map.'

so you'll know there was a "'Syntax check failed".
Double check your JSON structure ^^

The good thing here is, if there was an JSON error, the DHCPv4 still runs, not leaving you without DHCP active.

marcosm · Mar 27, 2025, 8:26 PM

The space vendor-encapsulated-options-space is set up differently; code specifies the sub-option and the length can be omitted. Hence what would previously be defined in the ISC DHCP GUI as 0104c0000203 can be specified as either c0000203 or 0xc0000203 (the hex prefix is optional). To get this value, use an IP to hex converter.

However, missing from the example in the OP was "csv-format": false (referenced in the Kea docs) - I've updated the example accordingly.

FCS001FCS · Apr 9, 2025, 8:27 PM

@Gertjan

I have a test minipc system I just installed pfSense CE 2.8 beta and want to go with KEA DCHP but need to inform my 2 Unifi Mini Flex Switches via the DCHP-Option 43 for a Unifi Network Controller that is on another sub-net. It worked with ISC on CE 2.7 so wanted to have the same function using KEA.

I followed as best I could your examples and think it works. I did not find any "php-frm" errors in the General Log after a Reboot, so can I assume it works?

How can I check that the Option 43 is actually sent/working?

Screenshots of my entries:

"Services > DHCP Server > Settings":
🔒 Log in to view

"Services > DHCP Server > LAN": (last few digits changed in "data" for security but are actually correct for my IP)
🔒 Log in to view

Gertjan · Apr 10, 2025, 6:43 AM

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

How can I check that the Option 43 is actually sent/working?

That's the easy part ^^
Ask it ? ( ! )

Here :

🔒 Log in to view

Select :
The interface, for example your LAN
View options : you want details : High
Protocol : UDP
Ports : 67 and 68

and hit Start.

Fire up you favorite SSH client, for example, Putty.
SSH into your Unifi AP on LAN, mine is 192.168.1.254
This will works, as the real admin want control, so the've set up their devices with :

🔒 Log in to view

so there is the login user name and password

Your in !
type

info

To see more, type

ps | grep 'dhcp'

and now you see the dhcp client config file, so you can find even more, like the /etc/persistent/cfg/mgmt file.
Anyway, I can see that my controller is :

U6ProBureau-BZ.6.6.77# info

Model:       U6-Pro
Version:     6.6.77.15402
MAC Address: 28:70:4e:62:31:5d
IP Address:  192.168.1.254
Hostname:    U6ProBureau
Uptime:      1454 seconds
NTP:         Synchronized

Status:      Connected (http://192.168.1.6:8080/inform)

From the unifi command line, type

reboot

You can also do what all the others do : remove the power for a moment ^^

Now you'll see the pfSense capture showing the result : after 5 seconds or so : first

08:05:16.976611 IP (tos 0x0, ttl 64, id 0, offset 0, flags [none], proto UDP (17), length 328)
    0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from 28:70:4e:62:31:5d, length 300, xid 0x53bf373d, secs 51400, Flags [none] (0x0000)
	  Client-Ethernet-Address 28:70:4e:62:31:5d
	  Vendor-rfc1048 Extensions
	    Magic Cookie 0x63825363
	    DHCP-Message (53), length 1: Request
	    Client-ID (61), length 7: ether 28:70:4e:62:31:5d
	    Requested-IP (50), length 4: 192.168.1.254
	    Server-ID (54), length 4: 192.168.1.1
	    MSZ (57), length 2: 576
	    Parameter-Request (55), length 8: 
	      Subnet-Mask (1), Default-Gateway (3), Domain-Name-Server (6), Hostname (12)
	      Domain-Name (15), BR (28), NTP (42), Vendor-Option (43)
	    Vendor-Class (60), length 4: "ubnt"
	    Hostname (12), length 11: "U6ProBureau"

Note that it knew it had "192.168.1.254" before, so it's asking again for this IP.
See also the "Option 43 request".

The answer from Kea :

08:05:16.982496 IP (tos 0x10, ttl 128, id 0, offset 0, flags [DF], proto UDP (17), length 347)
    192.168.1.1.67 > 192.168.1.254.68: [udp sum ok] BOOTP/DHCP, Reply, length 319, xid 0x53bf373d, Flags [none] (0x0000)
	  Your-IP 192.168.1.254
	  Client-Ethernet-Address 28:70:4e:62:31:5d
	  Vendor-rfc1048 Extensions
	    Magic Cookie 0x63825363
	    DHCP-Message (53), length 1: ACK
	    Subnet-Mask (1), length 4: 255.255.255.0
	    Default-Gateway (3), length 4: 192.168.1.1
	    Domain-Name-Server (6), length 4: 192.168.1.1
	    Hostname (12), length 7: "ub6pro4"
	    Domain-Name (15), length 20: "bhf.tld"
	    NTP (42), length 4: 192.168.1.1
	    Vendor-Option (43), length 6: 1.4.192.168.1.6
	    Lease-Time (51), length 4: 21600
	    Server-ID (54), length 4: 192.168.1.1

Kea agreed for the requested IP : 192.168.1.254 - yours will be different.
And see also the Option 43 proposal :

Vendor-Option (43), length 6: 1.4.192.168.1.6

and I presume this the 'encoded' ("1" for IPv4, "4" for 4bytes and 192.168.1.6 which is my controller IP.

A even better test would be : instead of rebooting your AP, reset it with the button on the back.
This will wipe all internal AP settings, and it should find all the correct settings when doing it's initial DHCP request.
After a total reset, and an initial setup, it should show up in your controller like nothing happened.
I didn't test this .....

Be ware of the Plan B :
Resolver settings, Host Overrides :
Set :
🔒 Log in to view

If the DHCP method didn't work out, the DNS method is used : it searches for the "unifi" host name and uses that IP as the controller IP.

FCS001FCS · Apr 10, 2025, 9:00 AM

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

Kea agreed for the requested IP : 192.168.1.254 - yours will be different.
And see also the Option 43 proposal :

Vendor-Option (43), length 6: 1.4.192.168.1.6

Excellent, that worked great!

I setup the packet capture as you detailed and ran it, then for good measure, unplugged and plugged the LAN RJ45 to the Flex-Mini Switch. In the packet capture I got exactly as you stated, the "Vendor Option (43)" but with the IP of my Unifi Network Controller.

Thanks for the confirmation and I hope others going to KEA on pfSense CE 2.8 Beta can find this thread to also help them out.

BTW, the Unifi USW Flex-Mini (old 1G version) is one of the only Unifi Switches that does not have SSH capability, so the DCHP Option 43 is the only way to set the "Inform" IP for an out of sub-network Unifi Controller. Just some info for others in the same situation as I am.

Gertjan · Apr 10, 2025, 11:39 AM

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

that does not have SSH capability, so the DCHP Option 43 is the only way to set the "Inform" IP for an out of sub-network Unifi Controller

If the " Flex-Mini Switch" doesn't have SSH ... not an issue.
It probably still supports DNS.
So it will request the "unifi" host name, thus finding your controller's IP. ... I guess.

And thanks, I never thought about that : I've a "US 8 60W" POE 8 port switch myself, and it has an SSH access :

US-8-60W-US.7.1.26# info

Model:       US-8-60W
Version:     7.1.26.15869
MAC Address: d8:b3:70:83:49:88
IP Address:  192.168.2.2
Hostname:    US-8-60W
Uptime:      6661215 seconds
NTP:         Synchronized

Status:      Connected (http://192.168.1.6:8080/inform)

This switch and several AP live on the 192.168.2.0/24 network, my captive portal, and the Unifi controller is on the pfSense LAN, 192.168.1.6.
I've also 3 Unifi APs on the 192.168.1.0/24 LAN network.

FCS001FCS · Apr 10, 2025, 1:07 PM

FYI - Just for confirmation, I factory reset the 2 USW Flex Mini Switches (White steady LED) to see if they would be available for adoption again in the Unifi Controller.

One showed up after some restarts of switches and pfSense and I could adopt it without removing it from the Unifi Network Controller (steady Blue LED).

The other switch would just not show up as adoptable in the Unifi Controller. I ended up removing that switch from the Controller and adopting it fresh. I had to re-setup the VLANs on that switch, but it was not much of an issue, as its a very simple setup.

I do not think it was a KEA issue, as I checked with the Packet Capture process and the DCHP Option 43 seemed to have been set in the switches, but the Controller just did not see it.

So, if someone else is in a similar situation, maybe a fresh start for the Unifi Controller may be the easiest approach, i.e. remove all old devices and see if they comeback for adoption as new devices.

Note: Your mileage may vary :)

All working now in my test setup, so happy days.