Doc bug: DHCP high-availability

Hi all,

I have been trying to implement the DHCP-HA per doc example and failed. Debugging leads me to the conclusion that the example is wrong.

In the example, the primary and secondary instances are configured with this option:

set service dhcp-server high-availability name 'NET-VYOS'

I assumed it to be a descriptive name for the DHCP HA instance since it’s the same value for both instances.

However, to make HA work, this must be the peer name of the other instance.
Assuming we have two instances, lab-router-01 (primary) and lab-router-02 (secondary), the correct syntax would be on

primary / lab-router-01

set service dhcp-server high-availability name 'lab-router-02'

secondary/ lab-router-02

set service dhcp-server high-availability name 'lab-router-01'


Why do I come to that conclusion?
The name gets added to the kea config file as a peer for high-availability:

$ cat /run/kea/kea-dhcp4.conf
[...]

       "hooks-libraries": [
            {
                "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so",
                "parameters": {
                    "high-availability": [{"this-server-name": "lab-router-01", "mode": "load-balancing", "heartbeat-delay": 10000, "max-response-delay": 10000, "max-ack-delay": 5000, "max-unacked-clients": 0, "peers": [{"name": "lab-router-01", "url": "http://xxxx:647/", "role": "primary", "auto-failover": true}, {"name": " NET-VYOS", "url": "http://xxxx:647/", "role": "secondary", "auto-failover": true}]}]
                }

The DHCP server logs will show you an error when the name does not match the peer instance name:

May 02 06:51:03 kea-dhcp4[123293]: 2025-05-02 06:51:03.102 WARN  [kea-dhcp4.ha-hooks/123293.139880306783936] HA_HEARTBEAT_FAILED lab-router-01: heartbeat to NET-VYOS (http://xxxx:647/) failed: lab-router-01 matches no configured 'server-name' (error code 1)
May 02 06:51:03 kea-dhcp4[123293]: 2025-05-02 06:51:03.102 WARN  [kea-dhcp4.ha-hooks/123293.139880306783936] HA_COMMUNICATION_INTERRUPTED lab-router-01: communication with NET-VYOS is interrupted

Personally I would recommend to use option82 instead.

This way you can have two or more DHCP-servers configured but there is no leasefile that needs to be synced between them.

Option82 will handy out leases based on option82 information provided by the DHCP-replay along the road (normally the switch itself with the clients or the L3-switch used as gateway). This way whatever is connected to SW1-INT4 will always get the same lease no matter what mac or DUID that client presents.