About this article: AI-assisted writing, reviewed against the cited sources. This is source research, not a lab validation of the procedures. Check the stated versions and your own recovery requirements before making changes.
DHCP recovery fails when people restore "the DHCP server" as if it were one file. It is at least two stores, and if it updates DNS it is three.
RFC 2131 describes DHCP's first service as persistent storage of network parameters for clients, a key-value entry per client. The key identifies the client. The value is the parameters, including the address. Separately, dynamic allocation is the mechanism that reuses an address once the client no longer needs it, so a limited pool can be shared. The pool is the policy. The stored entries are the memory of who has what. Kea 3.2.1 keeps that memory in a lease database. With the memfile backend, the server holds leases in memory and writes them to a CSV file on disk.
DNS is a third store. Kea can send a name-change request to its DHCP-DDNS process asking for an A record, a PTR record, or both, for a fully qualified name and a lease address. Enabling updates does not by itself prove all saved leases will be republished. Subsequent lease/client events and the configured name-change policy can generate requests, which D2 routes to its configured DNS servers. Restored DHCP and DNS state therefore need reconciliation before updates resume. If you restore an empty lease file and a wide pool, dynamic allocation has no memory of the addresses it already handed out.
This article is the order in which to decide among those stores. It is not a Kea configuration to install, and no server was started.
Why it matters
After a DHCP server is lost, many clients still have an address and keep using it until their own lease timers say otherwise. Those timers were not re-read for this article, and no client timeout is stated here. What the server side has lost is the memory RFC 2131 calls persistent storage. A new process with the right subnets and an empty lease file does not know which addresses in the pool were in use. Dynamic allocation exists specifically to reuse addresses that are no longer needed. An address that is still in use, and that the server has forgotten, looks like an address that is free.
The address plan, whether it lives in a spreadsheet, a database, or an IP address-management product, is a fourth opinion if you let it be. This article opened no IPAM product, so it gives no product's backup steps. It treats the plan as the record of which ranges may be issued, which are reserved, and which names were intended. The lease file is the record of what was issued. They disagree after any outage that is long enough for one of them to have been restored from an older copy. The recovery is the choice of which one wins, made before the server starts answering.
What Kea actually stores
The Kea 3.2.1 manual's worked example uses memfile and calls it the simplest backend: an in-memory database, with leases stored on disk as CSV. Writing those updates is controlled by persist. The manual says true enables writing lease updates to the lease file. The default file name is [kea-install-dir]/var/lib/kea/kea-leases4.csv.
A later note in the same manual matters more than the default path. As of Kea 2.7.9, lease files may only be loaded from the data directory chosen at compile time, that same var/lib/kea path, unless the environment variable KEA_DHCP_DATA_DIR overrides it at startup. A restore that puts the CSV somewhere else, because that is where the backup system likes files, is a file the server is documented not to load. The recovery copy has to land in the directory this build will read, or the override has to be set on purpose and recorded. The documented result for a disallowed path is refusal to start or an unrecoverable error in an already running process; it is not a successful empty-lease start.
The file is not a clean table of current leases until it has been cleaned. lfc-interval is how often, in seconds, the server runs lease file cleanup, which removes redundant historical information and shrinks the file. The default is 3600. Zero disables it. A copy taken between cleanups can contain more than one row for the same lease. The manual also says that when the server loads a lease file it does so row by row, and max-row-errors is how many bad rows it will tolerate before it stops trying to load the file. A truncated backup, or a file joined from two generations, can hit that stop. The following lease-cleanup section explicitly says the latest lease entry for a client is used and previous entries discarded during loading. Historical rows are normal append-only history, not corruption by themselves. A file not validated against the compatible server remains an unverified recovery artefact; do not mistake its existence for a tested restore.
The configuration beside that file is the subnets and pools. The manual says the subnet list is the structure the server uses to process client requests, and the worked dynamic-allocation example includes a subnet and pools. A pool is required for that example’s dynamic allocation, not a universal claim that reservation-only designs cannot exist. Options such as the DNS servers to hand to clients live with that configuration. Restoring the lease file without the subnets restores memory the server may not be willing to serve. Restoring the subnets without the lease file restores the permission to allocate, without the memory of allocations already made. Both files are the server. The manual presents them as different objects, and the recovery has to as well.
What a name-change request will do
When DHCP-DDNS is in use, kea-dhcp4 sends name-change requests to kea-dhcp-ddns, which the manual calls D2. Each request says whether to add or remove DNS entries, whether the change is forward (A), reverse (PTR), or both, and it carries the fully qualified domain name, the lease address, and a DHCID that identifies the client associated with that name. Where to send them is not a per-subnet afterthought. The manual says the connectivity parameters, including enable-updates, server-ip and server-port, are specified in the top-level dhcp-ddns section.
There are two separate destinations. In kea-dhcp4, dhcp-ddns.server-ip identifies D2, the Kea DHCP-DDNS process that receives name-change requests. It is not the authoritative DNS server address. D2 has its own configuration: forward and reverse domain mappings select lists of authoritative dns-servers, with applicable TSIG credentials and update policy. The Kea DHCP-DDNS manual documents those mappings and first-to-last server preference.
Recovery must reconcile both hops: DHCP to the intended D2 service, then D2 to the intended authoritative DNS service for each forward or reverse domain. Pointing the DHCP NCR endpoint at a BIND primary does not turn NCRs into DNS UPDATE messages. A reachable D2 can still fail to update DNS when its domain mapping, server list, TSIG key or server-side permissions are wrong.
BIND 9.20.30 explains authoritative primary and secondary roles. Accept the intended zone contents and update authority before permitting D2 to modify them. The exact update-authorization configuration is outside this article; no DNS update was sent.
A request can ask for forward updates, reverse updates or both. A mismatch between the resulting records does not prove that the request intentionally selected only one direction: one operation may have failed, permissions can differ, and earlier data can remain. Inspect the actual request, D2 outcomes and authoritative records. DHCID-based conflict handling and configured update modes also mean requests are not unconditional overwrite instructions. A service restart does not itself guarantee a full reconciliation of every old lease with DNS.
The address plan is not the lease file
No IPAM product manual was opened. The plan is included because it is the usual place an organisation records reservations, ranges that must not be issued, and names that DHCP does not own. After a restore, three comparisons matter, and they are editorial checks rather than Kea features:
The pools in the Kea configuration against the ranges the plan says may be dynamic. A restored configuration from before a range was retired will issue addresses the plan has since given to something else.
The leases in the CSV against the reservations in the plan. A lease matching a reservation for the same client can be expected. An overlap assigned to different clients, or to a retired range, needs reconciliation. The manual does not, in the section read here, say which one the server will prefer. Do not start the service in order to find out.
The names in the plan against the names in the DNS zone you are about to let DHCP update. Do not assume automatic reconciliation: update policy, DHCID ownership, generated requests and failures determine what changes. Compare actual authoritative results with the intended name/address mapping.
Our recommendation: pick the winner in writing before the process listens. For addresses that clients are still using, the lease file is usually the better record of fact, and the plan is updated to match it. A later reservation does not revoke an address a client still holds. Preserve evidence of active leases and use an approved conflict-resolution plan; discarding those records can make live addresses appear free and create duplicates. "Usually" is a judgement. It is not a Kea setting. The wrong judgement is to load every file you have because each one is called a backup.
What to decide, in order
First, the intended authoritative DNS service, its accepted zone content, D2’s domain/server mappings, and the DHCP-to-D2 endpoint. If you do not yet know, the restored Kea configuration should not have updates enabled. The manual makes enable-updates a setting. Leaving it off until the zone is chosen is a use of that setting, not a second product.
Second, the subnet and pool configuration that matches the ranges you are willing to issue today, including the DNS servers the clients should be told. This is the policy file, not the CSV.
Third, the lease file, copied into the data directory this Kea build will load, from a generation you have chosen, knowing it may contain historical rows if cleanup has not run. A file that fails max-row-errors is not a partial success. The server stops loading it. Have another copy that you have reason to believe loads, taken from the same version's data directory rather than assembled by hand.
Fourth, the comparison with the address plan. Conflicts are resolved before the server answers, not by watching which client complains.
Fifth, enable updates only after a client renewal would amend the zone you mean to publish. The first requests will add or remove A and PTR records for the name, address and client identifier in the lease. That is what the manual says an NCR contains. It will not repair a zone whose serial and delegation are still pointed at a dead primary. Fix that first, or leave updates off.
Do not treat a snapshot of the whole virtual machine as a substitute for knowing these three generations match. A disk image can still hold a lease file from 10:00 and a zone file from last week if those writes were not consistent with each other. This article did not test any image tool. Consistency is a property you check, not a property the word snapshot guarantees.
Risks and limits
RFC 2131 is March 1997. The persistent-storage model and the definition of dynamic allocation are what this article uses. It does not state client retransmission timers, and none are given here.
The Kea manual opened is the stable 3.2.1 book. The lease-directory restriction is stated there as applying as of Kea 2.7.9. Other backends, including databases, are mentioned by the manual as more extensive than the memfile example and were not specified here. High-availability between Kea servers was not in the sections read. A pair that replicates leases can change which file is current. Do not assume a single CSV is the only copy until you have read that part of the manual for the version you run.
The manual states that the latest lease entry for a client wins when memfile history is loaded. Subnet changes and HA introduce further reconciliation rules; those operational procedures were not tested here.
No IPAM vendor's export format is described. BIND is cited only for where a zone is edited versus where it is transferred. Dynamic update policy inside BIND was not opened.
No Kea process was started, no CSV was loaded, and no DNS update was sent.
Research and verification
Drafted with AI assistance on 11 November 2026 and independently source-reviewed on 13 November 2026. No equipment was configured, no article commands were executed and no lab behaviour is claimed. This is educational source research, not an approved production recovery procedure.
Sources
-
ISC, The DHCP-DDNS Server, Kea 3.2.1: https://kea.readthedocs.io/en/stable/arm/ddns.html. Independently reopened 13 November 2026; D2 domain mappings, authoritative DNS servers, TSIG and conflict handling.
-
RFC 2131, Dynamic Host Configuration Protocol, R. Droms, March 1997. https://www.rfc-editor.org/rfc/rfc2131.txt — section 2.1, persistent storage of client parameters; introduction, dynamic allocation as reuse of an address the client no longer needs. Independently reopened 13 November 2026.
- ISC, The DHCPv4 Server, Kea 3.2.1 Administrator Reference Manual, chapter 8. https://kea.readthedocs.io/en/stable/arm/dhcp4-srv.html — memfile CSV lease store;
persist; default lease path; data-directory restriction as of 2.7.9 andKEA_DHCP_DATA_DIR;lfc-intervaldefault 3600;max-row-errors; subnet and pool configuration; name-change requests to kea-dhcp-ddns, including A, PTR, FQDN, lease address and DHCID;dhcp-ddnsconnectivity settings. Independently reopened 13 November 2026. - ISC, Configurations and Zone Files, BIND 9.20.30, chapter 3. https://bind9.readthedocs.io/en/stable/chapter3.html — primary reads the zone from a file; secondary receives a transfer. Used only to identify where DNS changes have to land. Independently reopened 13 November 2026.
This article was originally published on .