Introduction
In some cases, administrators may want to configure Kea to use the "Shared Lease Database" High Availability method. This method has certain advantages when compared to the HA Hook. The advantages and disadvantages of each method are covered in the Kea HA Strategies Comparison document. In this document, the focus will be on configuring the Shared Lease Database method in Kea.
Please note that the Shared Lease Database is relevant to both DHCPv4 and DHCPv6. Throughout this document, you will find links to the DHCPv4 section in Kea's ARM. Any of these, unless otherwise noted, could have just as easily pointed to the DHCPv6 section as they are relevant to both.
How Does Shared Lease Database Work?
This method of achieving High Availability is very simple. The basic idea is that two or more Kea servers which are configured for the same shared networks and/or subnets are pointed to the same database server and schema in the "lease-database" statement. The Kea servers may serve the same local subnet(s) or even receive the same relayed traffic from the relay agents. The Kea servers are not aware of each other and are just offering addresses to clients that they find free in the database schema. The reason this works is that the Kea servers, when using PostgreSQL or MySQL as the storage in "lease-database", do not retain any local notion of the leases that are stored there. The database must be consulted during all allocation actions. Because of this, the servers that are all pointed at the same schema are able to de facto share this lease information thus avoiding duplicate address assignments and achieving High Availability.
Some Requirements
The Shared Lease Database method does impose a couple of restrictions.
- At least Kea 2.6.2 is required as resolution of two issues (3751 and 3798) are required for trouble free use of the Shared Lease Database method.
- The only practical lease allocator is the Random Allocator as the Free Lease Queue is not suitable for use with the Shared Lease Database method. Additionally, the default Iterative Allocator will result in multiple servers offering the same address to multiple clients. While this doesn't cause lasting problems, it does result in retransmissions as clients must start the DORA process over again. Both the Random and Iterative Allocators are notably slow when used with a lease database stored in MySQL or PostgreSQL and the subnet does not have many addresses left. The Free Lease Queue is meant to be much faster in this scenario, but does not work with the Shared Lease Database.
As noted in Gitlab issue 2856 where a couple of our engineers did some performance testing, the Random Allocator and MySQL or Mariadb* are not a good combination if you have a large deployment. As the issue notes, performance starts to degrade when you reach a half million leases in use. Administrators who will have such a large deployment should be sure to use PostgreSQL which does not have this performance problem.
*Note: MariaDB does seem to perform better than MySQL, but still not as well as PostgreSQL in relation to the Random Lease Allocator.
Configuring the Shared Lease Database
It is possible that exactly the same configuration may be used on all servers that are participating in the Shared Lease Database relationship. The assumption in this article is that this is the case. Therefore, there is only one configuration shown here.
All Servers Configuration
First, some notes about some interesting parameters in the configuration below.
- You can see
"allocator": "random",has been added globally. This is because, as mentioned earlier, this is the allocator that will work the best. - A
multi-threadingsection is shown. This contains values that might be appropriate for MySQL database storage of leases. See here for further information. - Lease Caching should be enabled to prevent unnecessary load. This is enabled by
"cache-threshold": 0.25,. - In DHCPv4, some clients may have difficulty if the T1 and T2 timers are not sent. Adding
"calculate-tee-times": true,causes Kea to compute these values and send them. This is a matter of user preference and has nothing to do with the Shared Lease Database. - The final parameter shown here, that similarly has nothing to do with the Shared Lease Database, is
"decline-probation-period": 15,which shortens the probation period of declined addresses to 15 seconds from the default 86,400 seconds. At times, a client may experience a problem and decline all addresses offered. This can lead to pool exhaustion with the default value on the probation period. Please note that this parameter is DHCPv4 only.
Kea Shared Lease Database Configuration
{
"Dhcp4": {
"interfaces-config": {
"interfaces": [
"ens256"
]
},
"allocator": "random",
"lease-database": {
"type": "mysql",
"host": "192.168.115.128",
"name": "kea",
"user": "kea",
"password": "kea"
},
"multi-threading": {
"enable-multi-threading": true,
"thread-pool-size": 12,
"packet-queue-size": 792
},
"valid-lifetime": 300,
"cache-threshold": 0.25,
"calculate-tee-times": true,
"decline-probation-period": 15,
"subnet4": [
{
"subnet": "10.1.2.0/24",
"id": 1,
"option-data": [
{
"name": "routers",
"data": "10.1.2.1"
}
],
"pools": [
{
"pool": "10.1.2.100 - 10.1.2.200"
}
]
}
],
"loggers": [
{
"name": "kea-dhcp4",
"severity": "INFO",
"output_options": [
{
"output": "stdout"
}
]
}
]
}
}
Please note that the configuration above does not show any values for the lease-database configuration that will cause the Kea server to retry the database connection if it is lost. In production, the connection should be more resilient. Parameters like: retry-on-startup, reconnect-wait-time, and max-reconnect-tries should be used. See here for further information.
Starting the Servers
No special care needs to be taken here. Servers can come and go as they please. There are no states to manage. As long as one server remains (and the database server, of course, is still available), clients should still be served.
Testing the Servers
A test of the functionality can be easily performed by starting multiple servers with a configuration similar to the one shown earlier. After the Kea servers are able to connect to the database server, the test utility "perfdhcp" can be used to simulate clients. In our testing, we used: sudo perfdhcp -4 -r 1 -R 101 -p 204 -l ens256 to send traffic to the Kea servers that were local to the "ens256" interface. Logs like the below excerpts should appear showing the allocation of addresses:
Kea Server 1 Logs
2025-05-15 17:12:31.381 INFO [kea-dhcp4.leases/2521.281473711538048] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:08], cid=[01:00:0c:01:02:03:08], tid=0x4: lease 10.1.2.110 will be offered
2025-05-15 17:12:31.383 INFO [kea-dhcp4.leases/2521.281473703145344] DHCP4_LEASE_ALLOC [hwtype=1 00:0c:01:02:03:08], cid=[01:00:0c:01:02:03:08], tid=0x4: lease 10.1.2.110 has been allocated for 300 seconds
2025-05-15 17:12:32.388 INFO [kea-dhcp4.leases/2521.281473694752640] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:09], cid=[01:00:0c:01:02:03:09], tid=0x5: lease 10.1.2.109 will be offered
2025-05-15 17:12:32.388 INFO [kea-dhcp4.leases/2521.281473694752640] DHCP4_LEASE_REUSE [hwtype=1 00:0c:01:02:03:09], cid=[01:00:0c:01:02:03:09], tid=0x5: lease 10.1.2.109 has been reused for 300 seconds
2025-05-15 17:12:33.381 INFO [kea-dhcp4.leases/2521.281473770286976] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:0a], cid=[01:00:0c:01:02:03:0a], tid=0x6: lease 10.1.2.157 will be offered
2025-05-15 17:12:33.383 INFO [kea-dhcp4.leases/2521.281473753501568] DHCP4_LEASE_ALLOC [hwtype=1 00:0c:01:02:03:0a], cid=[01:00:0c:01:02:03:0a], tid=0x6: lease 10.1.2.157 has been allocated for 300 seconds
2025-05-15 17:12:34.381 INFO [kea-dhcp4.leases/2521.281473745108864] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:0b], cid=[01:00:0c:01:02:03:0b], tid=0x7: lease 10.1.2.107 will be offered
2025-05-15 17:12:34.384 INFO [kea-dhcp4.leases/2521.281473736716160] DHCP4_LEASE_ALLOC [hwtype=1 00:0c:01:02:03:0b], cid=[01:00:0c:01:02:03:0b], tid=0x7: lease 10.1.2.107 has been allocated for 300 seconds
2025-05-15 17:12:35.381 INFO [kea-dhcp4.leases/2521.281473761894272] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:0c], cid=[01:00:0c:01:02:03:0c], tid=0x8: lease 10.1.2.131 will be offered
2025-05-15 17:12:35.383 INFO [kea-dhcp4.leases/2521.281473728323456] DHCP4_LEASE_ALLOC [hwtype=1 00:0c:01:02:03:0c], cid=[01:00:0c:01:02:03:0c], tid=0x8: lease 10.1.2.131 has been allocated for 300 seconds
2025-05-15 17:12:36.381 INFO [kea-dhcp4.leases/2521.281473719930752] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:0d], cid=[01:00:0c:01:02:03:0d], tid=0x9: lease 10.1.2.145 will be offered
2025-05-15 17:12:36.382 INFO [kea-dhcp4.leases/2521.281473686359936] DHCP4_LEASE_ALLOC [hwtype=1 00:0c:01:02:03:0d], cid=[01:00:0c:01:02:03:0d], tid=0x9: lease 10.1.2.145 has been allocated for 300 seconds
2025-05-15 17:12:37.381 INFO [kea-dhcp4.leases/2521.281473711538048] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:0e], cid=[01:00:0c:01:02:03:0e], tid=0xa: lease 10.1.2.197 will be offered
2025-05-15 17:12:37.382 INFO [kea-dhcp4.leases/2521.281473703145344] DHCP4_LEASE_ALLOC [hwtype=1 00:0c:01:02:03:0e], cid=[01:00:0c:01:02:03:0e], tid=0xa: lease 10.1.2.197 has been allocated for 300 seconds
Kea Server 2 Logs
2025-05-15 17:12:31.375 INFO [kea-dhcp4.leases/2097.281473308381056] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:08], cid=[01:00:0c:01:02:03:08], tid=0x4: lease 10.1.2.110 will be offered
2025-05-15 17:12:32.375 INFO [kea-dhcp4.leases/2097.281473291595648] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:09], cid=[01:00:0c:01:02:03:09], tid=0x5: lease 10.1.2.109 will be offered
2025-05-15 17:12:32.379 INFO [kea-dhcp4.leases/2097.281473283202944] DHCP4_LEASE_ALLOC [hwtype=1 00:0c:01:02:03:09], cid=[01:00:0c:01:02:03:09], tid=0x5: lease 10.1.2.109 has been allocated for 300 seconds
2025-05-15 17:12:33.375 INFO [kea-dhcp4.leases/2097.281473367129984] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:0a], cid=[01:00:0c:01:02:03:0a], tid=0x6: lease 10.1.2.157 will be offered
2025-05-15 17:12:34.390 INFO [kea-dhcp4.leases/2097.281473358737280] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:0b], cid=[01:00:0c:01:02:03:0b], tid=0x7: lease 10.1.2.107 will be offered
2025-05-15 17:12:34.390 INFO [kea-dhcp4.leases/2097.281473358737280] DHCP4_LEASE_REUSE [hwtype=1 00:0c:01:02:03:0b], cid=[01:00:0c:01:02:03:0b], tid=0x7: lease 10.1.2.107 has been reused for 300 seconds
2025-05-15 17:12:35.375 INFO [kea-dhcp4.leases/2097.281473333559168] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:0c], cid=[01:00:0c:01:02:03:0c], tid=0x8: lease 10.1.2.131 will be offered
2025-05-15 17:12:36.375 INFO [kea-dhcp4.leases/2097.281473325166464] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:0d], cid=[01:00:0c:01:02:03:0d], tid=0x9: lease 10.1.2.145 will be offered
2025-05-15 17:12:37.375 INFO [kea-dhcp4.leases/2097.281473308381056] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:0e], cid=[01:00:0c:01:02:03:0e], tid=0xa: lease 10.1.2.197 will be offered
Both servers are allocating addresses. It can be thought of as a desired race condition. One server will allocate an address to the client, and the other will not. You may occasionally see DHCP4_LEASE_REUSE messages in one or the other server. This happens when one server has managed to allocate the lease before the other server has managed to look up the lease. The slower server will find that a lease already exists (because the quicker server just allocated it) and will reply to the client with the same lease parameters. None of this matters to the client who has already stopped listening after the first reply. The below combined server log excerpt shows this behavior:
Lease Reuse
2025-05-15 17:15:41.179 INFO [kea-dhcp4.leases/2552.281472775372672] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:1a], cid=[01:00:0c:01:02:03:1a], tid=0x16: lease 10.1.2.198 will be offered
2025-05-15 17:15:41.180 INFO [kea-dhcp4.leases/2552.281472766979968] DHCP4_LEASE_ALLOC [hwtype=1 00:0c:01:02:03:1a], cid=[01:00:0c:01:02:03:1a], tid=0x16: lease 10.1.2.198 has been allocated for 300 seconds
# The above is from server 1 and the below is from server 2. Both serving the same client about 8 or 9 ms apart.
2025-05-15 17:15:41.188 INFO [kea-dhcp4.leases/2132.281472879878016] DHCP4_LEASE_OFFER [hwtype=1 00:0c:01:02:03:1a], cid=[01:00:0c:01:02:03:1a], tid=0x16: lease 10.1.2.198 will be offered
2025-05-15 17:15:41.188 INFO [kea-dhcp4.leases/2132.281472879878016] DHCP4_LEASE_REUSE [hwtype=1 00:0c:01:02:03:1a], cid=[01:00:0c:01:02:03:1a], tid=0x16: lease 10.1.2.198 has been reused for 300 seconds
Conclusion
The Kea "Shared Lease Database" method of achieving High Availability is valid for some use cases. The setup is extremely simple. There are several drawbacks to this method, however, which are covered in this document.