dhcpd.leases`

Store information on DHCP leases

When a client requests an IP address under DHCP, the dhcpd daemon assigns an address from a pool of IP addresses stored in the /etc/dhcpd.conf file. Before dhcpd grants the client a lease on this address, it records the details of the lease in the leases database, a free-form ASCII file (/var/state/dhcp/dhcpd.leases) that contains a series of lease declarations. The daemon makes sure that the contents of the file are flushed to disk, ensuring that, even in the event of a system crash, dhcpd will not forget about a lease that it has assigned. On startup, after reading the dhcpd.conf file, dhcpd also reads the saved dhcpd.leases file.

Every time a lease is acquired, renewed or released, its new value is recorded at the end of the lease file. So if more than one declaration appears for a given lease, the last one in the file is the current one.

New leases are appended to the end of the dhcpd.leases file. From time to time, dhcpd removes obsolete information to prevent the file becoming too large.

There is no lease database when you first install dhcpd but the daemon will not start without one, so before you can offer DHCP services, you have to create an empty file called /var/state/dhcpd/dhcpd.leases.

In order to prevent the lease database from growing without bound, dhcpd rewrites the file from time to time. First, dhcpd creates a temporary lease database and dumps all known leases to it. Then, it renames the old lease database as /var/state/dhcpd/dhcpd.leases~ to create a backup copy. Finally, it writes the new lease database as /var/state/dhcpd/dhcpd.leases.

This process does have a window of vulnerability. If dhcpd is killed or the system crashes after the old lease database has been renamed but before the new one has been moved into place, there will be no /var/state/dhcpd/dhcpd.leases file. In this case, dhcpd will refuse to start, and will require manual intervention. If this happens, do not create a new lease file or you will lose all your old bindings, and your new lease file will not match the lease information kept by the client hosts. Instead, rename /var/state/dhcpd/dhcpd.leases~ as /var/state/dhcpd/dhcpd.leases, restoring the old, valid lease file, and then start dhcpd. This guarantees that a valid lease file will be restored.

Lease descriptions are stored in a format that is parsed by the same recursive descent parser used to read /etc/dhcpd.conf files. Currently, the only declaration that is used in the dhcpd.leases file is the lease declaration.

Each lease declaration includes the single IP address that has been leased to the client. The statements within the braces define the duration of the lease and to whom it is assigned.

The duration of a lease is recorded as the starts and ends statements. Dates are specified as follows:

weekday yyyy/mm/dd hh:mm:ss;

The weekday is present to make it easy for you to tell when a lease expires: it's specified as a number from zero to six, with zero being Sunday. The day of week is ignored on input. The year is specified with the century, so it should generally be four digits except for really long leases. The month is specified as a number starting with 1 for January. The day of the month is likewise specified starting with 1. The hour is a number between 0 and 23, the minute a number between 0 and 59, and the second also a number between 0 and 59. Lease times are specified in UCT, not in the local time zone.

DHCP leases can be assigned almost any length from zero seconds to infinity. What lease length makes sense for any given subnet, or for any given installation, will vary depending on the kinds of hosts being served. For example, in an office environment where you add or remove systems infrequently, you might allow monthly leases whereas in a final test environment on a manufacturing floor, you might want to restrict leases to 30 minutes or so.

The MAC address of the network interface that was used to acquire the lease is recorded with the hardware statement:

hardware <var>hardware-type</var> <var>mac-address</var>;

The mac-address is specified as a series of hexadecimal octets, separated by colons.

If the client used a client identifier to acquire its address, the client identifier is recorded using the uid statement, like this:

uid <var>client-identifier</var>;

The client-identifier variable is recorded as a series of hexadecimal octets, regardless of whether the client specifies an ASCII string or uses the newer hardware type/MAC address format.

If the client sends a hostname using the Client Hostname option, as specified in some versions of the DHCP-DNS Interaction draft, that hostname is recorded using the client-hostname statement:

client-hostname "<var>hostname</var>";

If the client sends its hostname using the Hostname option, as Windows 95 does, it is recorded using the hostname statement:

hostname "<var>hostname</var>";

The DHCP server may determine that a lease has been misused in some way, either because a client that has been assigned a lease NAKs it, or because the server's own attempt to see if an address is in use prior to reusing it reveals that the address is in fact already in use. In that case, the abandoned statement is used to indicate that the lease should not be reassigned, like this:

abandoned;

Abandoned leases are reclaimed automatically. When a client asks for a new address, and the server finds that there are no new addresses, it checks to see if there are any abandoned leases, and allocates the least recently abandoned lease. The standard mechanisms for checking for lease address conflicts are still followed, so if the abandoned lease's IP address is still in use, it will be re-abandoned.

If a client requests an abandoned address, the server assumes that the reason the address was abandoned was that the lease file was corrupted, and that the client is the machine that responded when the lease was probed, causing it to be abandoned. In that case, the address is immediately assigned to the client.

Examples:

Here's an example of a typical lease entry:

lease 192.168.42.1 {
starts 0 2000/01/30 08:02:54;
ends 5 2000/02/04 08:02:54;
hardware ethernet
   00:50:04:53:D5:57;
uid 01:00:50:04:53:D5:57;
client-hostname "PC0097";
}

`/var/state/dhcp/dhcpd.leases`

Name:

Description:

Examples:

See also: