dhcpd.leases keeps every lease change as an appended declaration, so one address can map to different clients at different times; the last entry is current.
01Location
DBDIR/dhcpd.leases (the directory is set when the server is built or configured)
DBDIR/dhcpd.leases~ , the previous copy left when the file is rewritten
A separate file for a second server instance started with the -lf option
02Questions it answers
Which client held a given IP address at a given moment?
Which MAC address, client identifier and host name did that client present?
In what binding state was the lease, and when did the current state end?
03Format and versions
Format
Free-form text of declarations: lease <ip-address> { starts ...; ends ...; cltt ...; binding state ...; hardware ethernet ...; uid ...; client-hostname "..."; }. The file is log-structured; when several declarations exist for one lease, the last one is in effect.
Applies to
As documented in the dhcpd.leases(5) manual page of the ISC DHCP server. The project's DHCPv4 and DHCPv6 lease formats differ, and other DHCP servers use other stores.
04Key fields
Field
What it tells you
lease <ip-address>
The single IP address the declaration describes.
starts / ends
Start and end of the lease; ends is when the current binding state expires.
cltt
The client's last transaction time.
binding state / next binding state
Without failover: active, free or abandoned. The next state is the one the lease moves to when the current state expires.
hardware
Hardware type and MAC address of the interface on which the lease will be used.
uid
The client identifier, if the client sent one. Normally an ARP type followed by the MAC address, but not required to be.
client-hostname
The host name sent by the client in the host-name option. Most clients send it; many specialised devices do not.
tstp, tsfp, atsfp
Failover timestamps; present only when the failover protocol is used.
05Timestamps
Field
Encoding
Note
starts, ends, cltt
weekday YYYY/MM/DD HH:MM:SS in UTC (default db-time-format)
The manual states that lease times are in UTC, not local time. The weekday is a number from 0 (Sunday) to 6 and is ignored on input.
starts, ends, cltt with db-time-format local
epoch <seconds>; # human-readable comment
The epoch value follows the server's clock. The comment shows the time in the configured zone as written and is meant for people only.
never
keyword
A lease that will not expire carries never instead of a date.
Preserve dhcpd.leases and dhcpd.leases~ together with dhcpd.conf, and note the file times. The rewrite process replaces the file from time to time.
Read the file in order. For a given address, a later declaration supersedes an earlier one, but the earlier ones show the history only until the next rewrite.
Convert the UTC lease times to the time base of the log you are matching, and select the declaration whose starts and ends contain the moment of interest. Check its binding state: free and abandoned declarations also carry times.
Record the MAC address, client identifier and host name together, and compare them with the switch, wireless controller or asset inventory.
State the result as 'at this time the address was leased to this client', not as a statement about who used the device.
07Interpretation pitfalls
An address maps to a host only for the span of a lease. The same address in a log from the morning and one from the afternoon can belong to different clients.
The file is rewritten from time to time, so old, expired declarations may be gone. An address missing from the file does not prove it was never leased.
client-hostname and uid are supplied by the client. A host name can be changed, and a MAC address can be set by software.
Devices with static addresses and servers other than ISC dhcpd leave no record here. A different DHCP service may keep its own log.
Contact us about examination services related to this page, support for expert witnesses, or collaboration. Please do not attach evidence files or personal data to your email.
