ISC DHCP Lease File

After the DHCP server is configured and started, the lease file records lease transactions. The lease file can be specified using the lease-file-name parameter in the DHCP configuration file, and the default if not specified is /var/lib/dhcpd/dhcpd.leases. This file is an ASCII text file that is appended with new lease transaction information. Thus the last entry for a given lease indicates its current status. The lease file is rewritten occasionally to prevent excessive file growth. A temporary file is created containing the current lease file, the last file is renamed with a ~ suffix (e.g. /var/lib/dhcpd/dhcpd.leases~), then the temporary file is renamed to the configured lease file name. In addition to lease transaction information, the lease file contains statements regarding group, subgroup, host declarations made via the OMAPI interface (discussed below) as a form of audit log. The lease file also contains failover state change transactions.

Within the lease file, expression of each date utilizes the following [default] formatting in UTC time:

W YYYY/MM/DD HH:MM:SS

where W is the day of the week specified as an integer from 0 (Sunday) to 6 (Saturday)

YYYY is the year

MM the month (01-12)

DD the day (01-31)

HH the hour (0-23)

MM the minute (00-59) and

SS the second (00-59).

When the db-time-format local; configuration parameter is specified in the DHCP configuration file, the format of each date is:

epoch seconds-since-epoch #day-name month-name DD HH:MM:SS YYYY

where seconds-since-epoch indicates the number of seconds since midnight, January 1, 1970 according to the server's clock. The # character indicates that the remaining time entry is a comment for human consumption, with the day-name being the name of the day (e.g., Monday), the month-name being the name of the month (e.g., March) and the DD, HH, MM, SS, and YYYY formatted as with the default formatting above.

Lease Records

Each lease entry in the lease file has the format:

lease ip-address { statements }

where ip-address is the IP address for which this lease transaction applies

statements are those defined below.

The statements within the lease entry contain the following:

• starts date; - the start time of the lease as encoded according to the date formatting just described.
• ends date; - the end time of the lease as encoded according to the date formatting just described; for infinite leases, the date is set to never.
• tstp date; - if failover is in applicable for this lease, the date is the encoded date for the lease expiration conveyed to the failover peer
• tsfp date; - if failover is applicable for this lease, the date is the encoded date which the failover peer acknowledged
• atsfp date; - if failover is applicable for this lease, the date is the actual time sent by the failover partner.
• cltt date; - the last client transaction time.
• hardware hardware-type hardware-address; the MAC type and address associated with the client of the lease
• uid client-identifier;- the client identifier for the client assigned the lease if sent by the client during the lease transaction; the client-identifier field is encoded as colon-separated octets in hexadecimal or as a quoted string (with any non-printable characters encoded in octal format, e.g., \036).
• client-hostname hostname; the hostname sent by the client during the lease transaction (if sent)
• abandoned; - indicates that this lease has been abandoned, e.g., when an address was pinged before being leased and a ping response was received.
• binding state state; - indicates the lease's binding state, either active or free. When using failover, the backup state may be used.
• next binding state state; - indicates the state following the current state when the current state expires
• option agent.circuit-id string; - the relay agent information option circuit ID suboption value if provided by the relay agent.
• option agent.remote-id string; - the relay agent information option remote ID suboption value if provided by the relay agent.
• set variable = value; - sets the value to the variable for the lease, e.g., as the result of conditional evaluation performed by the server for the packet.
• ddns-text variable; - identifies the TXT record Rdata field associated with the client as used for the interim DDNS update method
• ddns-fwd-name variable; - indicates the name (owner) field of the A record update to DNS if the update was successfully performed
• ddns-client-fqdn variable; - indicates the client-provided FQDN information (option 81) in the case when the client requested and was permitted to update its own A record.
• ddns-rev-name variable; - provides the Rdata field of the PTR record if a successful update of the PTR record was made using DDNS. This value should be the same as either ddns-fwd-name or ddns-client-fqdn
• on events [| event] { statements } - records a list of statements that will be executed if the event occurs; possible event types for an active lease are release and expiry.

Additional Lease File Information

Host, group and subgroup transactions made via the OMAPI interface are also included in the lease file. The format of these entries is equivalent to the format used in the configuration file. If one of these objects are deleted via the OMAPI interface, the declaration is included in the lease file with { deleted; } within the scope of the declaration statement.

The lease file also records failover state information formatted as follows.

failover peer name state {

my state state at date;

peer state state at date;

}

where:

name is the name of the failover declaration within the configuration file

date is formatted as described above

state is one of the following:

• unknown-state
• partner-down
• normal
• communications interrupted
• resolution interrupted
• potential conflict
• recover
• recover done
• shutdown
• paused
• startup