ChorusOS man pages section 4CC: Files

dhcpd.leases(4cc)

NAME

dhcpd.leases- DHCP client lease database

DESCRIPTION

The Internet Software Consortium DHCP Server maintains a persistent database of leases that it has assigned. This database is a free-form ASCII file containing a series of lease declarations. Every time a lease is acquired, renewed or released, its new value is recorded at the end of the lease file. If more than one declaration appears for a given lease, the last one in the file is the current one.

When dhcpd is first installed, there is no lease database. However, dhcpd requires that a lease database be present before it starts. To make the initial lease database, create an empty file called DBDIR/dhcpd.leases.

In order to prevent the lease database from growing too large, the file is rewritten from time to time. First, a temporary lease database is created and all known leases are dumped to it. Then, the old lease database is renamed DBDIR/dhcpd.leases~. Finally, the newly written lease database is moved into place.

There is a window of vulnerability if the dhcpd process is killed or the system crashes after the old lease database has been renamed but before the new one has been moved into place. This situation means that there is no DBDIR/dhcpd.leases file. In this case, dhcpd refuses to start, and requires manual intervention. DO NOT simply create a new lease file when this happens - if you do, you lose all your old bindings. Instead, rename DBDIR/dhcpd.leases~ to DBDIR/dhcpd.leases, restoring the old, valid lease file, and then start dhcpd. This guarantees that a valid lease file is restored.

FORMAT

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

lease ip-address { statements... }

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 start and end time of a lease are recorded using the ``starts'' and ``ends'' statements:

starts date;
ends date;

Dates are specified as follows:

weekday year/month/day hour:minute:second

The weekday is present to make it easy for a human to tell when a lease expires. Weekdays are 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 very 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 Greenwich Mean Time (GMT), not in local time. As Greenwich is on Daylight Savings Time part of the year, there is nowhere in the world where the times recorded on a lease are always identical to wall clock times. On a UNIX system, you can obtain the current time in GMT by typing date -u.

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

hardware hardware-type mac-address;

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:

uid client-identifier;

The client identifier 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 "hostname";

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

hostname "hostname";

The DHCP server may determine that a lease has been misused in some way, either because a client that has been assigned a lease issues a NAK, or because the server's own attempt to see whether 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.

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 whether 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 is abandoned again.

If a client requests an abandoned address, the server treats that the reason the address was abandoned is that the lease file is corrupted, and that the client is the machine that responded when the lease was probed. This causes it to be abandoned. The address is immediately re-assigned to the client.

FILES

dhcpd.leases

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

AUTHOR

dhcpd.leases was originally written by Ted Lemon <mellon@vix.com> under a contract with Vixie Labs. Funding for this project was provided by the Internet Software Consortium. Information about the Internet Software Consortium can be found at http://www.isc.org/isc.

ChorusOS 5.0 Last Revised December 2001