MAN page from Mandrake 9.X dhcp-server-3.0-1.rc12.2mdk.i586.rpm

dhcpd.leases

Section: File Formats (5)
Index

NAME

dhcpd.leases - DHCP client lease database

DESCRIPTION

The Internet Software Consortium DHCP Server keeps a persistentdatabase of leases that it has assigned. This database is a free-formASCII file containing a series of lease declarations. Every time alease is acquired, renewed or released, its new value is recorded atthe end of the lease file. So if more than one declaration appearsfor 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 will start.To make the initial lease database, just create an empty file called/var/lib/dhcp/dhcpd.leases. You can do this with:

        touch /var/lib/dhcp/dhcpd.leases

In order to prevent the lease database from growing without bound, thefile is rewritten from time to time. First, a temporary leasedatabase is created and all known leases are dumped to it. Then, theold lease database is renamed /var/lib/dhcp/dhcpd.leases~. Finally, thenewly written lease database is moved into place.

FORMAT

Lease descriptions are stored in a format that is parsed by the samerecursive descent parser used to read thedhcpd.conf(5)anddhclient.conf(5)files. Lease files can contain lease declarations, and also group andsubgroup declarations, host declarations and failover statedeclarations. Group, subgroup and host declarations are used torecord objects created using the OMAPI protocol.

The lease file is a log-structured file - whenever a lease changes,the contents of that lease are written to the end of the file. Thismeans that it is entirely possible and quite reasonable for there tobe two or more declarations of the same lease in the lease file at thesame time. In that case, the instance of that particular lease thatappears last in the file is the one that is in effect.

Group, subgroup and host declarations in the lease file are handled inthe same manner, except that if any of these objects are deleted, arubout is written to the lease file. This is just the samedeclaration, with { deleted; } in the scope of thedeclaration. When the lease file is rewritten, any such rubouts thatcan be eliminated are eliminated. It is possible to delete adeclaration in the dhcpd.conf file; in this case, the ruboutcan never be eliminated from the dhcpd.leases file.

THE LEASE DECLARATION

lease ip-address { statements... }

Each lease declaration include the single IP address that has beenleased to the client. The statements within the braces define theduration of the lease and to whom it is assigned.

starts date;ends date;tstp date;tsfp date;

The start and end time of a lease are recorded using the startsand ends statements. The tstp statement is specified ifthe failover protocol is being used, and indicates what time the peerhas been told the lease expires. The tsfp statement isalso specified if the failover protocol is being used, and indicatesthe lease expiry time that the peer has acknowledged. The dateis specified as follows:

weekday year/month/day hour:minute:second

The weekday is present to make it easy for a human to tell when alease expires - it's specified as a number from zero to six, with zerobeing Sunday. The day of week is ignored on input. The year isspecified with the century, so it should generally be four digitsexcept for really long leases. The month is specified as a numberstarting with 1 for January. The day of the month is likewisespecified starting with 1. The hour is a number between 0 and 23, theminute a number between 0 and 59, and the second also a number between0 and 59.

Lease times are specified in Universal Coordinated Time (UTC), not inthe local time zone. There is probably nowhere in the world where thetimes recorded on a lease are always the same as wall clock times. Onmost unix machines, you can display the current time in UTC by typingdate -u.

If a lease will never expire, date is never instead of anactual date.

hardware hardware-type mac-address;

The hardware statement records the MAC address of the networkinterface on which the lease will be used. It is specified as aseries of hexadecimal octets, separated by colons.

uid client-identifier;

The uid statement records the client identifier used by theclient to acquire the lease. Clients are not required to send clientidentifiers, and this statement only appears if the client did in factsend one. Client identifiers are normally an ARP type (1 forethernet) followed by the MAC address, just like in the hardwarestatement, but this is not required.

The client identifier is recorded as a colon-separated hexadecimallist or as a quoted string. If it is recorded as a quoted string andit contains one or more non-printable characters, those characters arerepresented as octal escapes - a backslash character followed by threeoctal digits.

client-hostname hostname;

Most DHCP clients will send their hostname in the host-nameoption. If a client sends its hostname in this way, the hostname isrecorded on the lease with a client-hostname statement. Thisis not required by the protocol, however, so many specialized DHCPclients do not send a host-name option.

abandoned;

The abandoned statement indicates that the DHCP server hasabandoned the lease. In that case, the abandoned statementwill be used to indicate that the lease should not be reassigned.Please see the dhcpd.conf(5) manual page for information aboutabandoned leases.

binding state state;next binding state state;

The binding state statement declares the lease's binding state.When the DHCP server is not configured to use the failover protocol, alease's binding state will be either active or free. Thefailover protocol adds some additional transitional states, as well asthe backup state, which indicates that the lease is availablefor allocation by the failover secondary.

The next binding state statement indicates what state the leasewill move to when the current state expires. The time when thecurrent state expires is specified in the ends statement.

option agent.circuit-id string;option agent.remote-id string;

The option agent.circuit-id and option agent.remote-idstatements are used to record the circuit ID and remote ID optionssend by the relay agent, if the relay agent uses the relay agentinformation option. This allows these options to be usedconsistently in conditional evaluations even when the client iscontacting the server directly rather than through its relay agent.

set variable = value;

The set statement sets the value of a variable on the lease.For general information on variables, see the dhcp-eval(5)manual page.

The ddns-text variable

The ddns-text variable is used to record the value of theclient's TXT identification record when the interim ddns updatestyle has been used to update the DNS for a particular lease.

The ddns-fwd-name variable

The ddns-fwd-name variable records the value of the name used inupdating the client's A record if a DDNS update has been successfullydone by the server. The server may also have used this name toupdate the client's PTR record.

The ddns-client-fqdn variable

If the server is configured to use the interim ddns update style, andis also configured to allow clients to update their own fqdns, and theclient did in fact update its own fqdn, then theddns-client-fqdn variable records the name that the client hasindicated it is using. This is the name that the server will haveused to update the client's PTR record in this case.

The ddns-rev-name variable

If the server successfully updates the client's PTR record, thisvariable will record the name that the DHCP server used for the PTRrecord. The name to which the PTR record points will be either theddns-fwd-name or the ddns-client-fqdn.

on events { statements... }The on statement records a list of statements to execute if acertain event occurs. The possible events that can occur for anactive lease are release and expiry. More than one eventcan be specified - if so, the events are separated by '|' characters.

THE FAILOVER PEER STATE DECLARATION

The state of any failover peering arrangements is also recorded in thelease file, using the failover peer statement:

failover peer name state {my   state state at date;peer state state at date;}

The states of the peer named name is being recorded. Both thestate of the running server (my state) and the other failoverpartner (peer state) are recorded. The following states arepossible: unknown-state, partner-down, normal,communications-interrupted, resolution-interrupted,potential-conflict, recover, recover-done,shutdown, paused, and startup./var/lib/dhcp/dhcpd.leases

AUTHOR

dhcpd(8)was written by Ted Lemonunder a contract with Vixie Labs. Fundingfor this project was provided by the Internet Software Consortium.Information about the Internet Software Consortium can be found at:http://www.isc.org/

This document was created byman2html,using the manual pages.