1dhcpd.leases(5) File Formats Manual dhcpd.leases(5)
2
6 dhcpd.leases - DHCP client lease database
7
9 The Internet Systems Consortium DHCP Server keeps a persistent database
10 of leases that it has assigned. This database is a free-form ASCII
11 file containing a series of lease declarations. Every time a lease is
12 acquired, renewed or released, its new value is recorded at the end of
13 the lease file. So if more than one declaration appears for a given
14 lease, the last one in the file is the current one.
15 When dhcpd is first installed, there is no lease database. However,
17 dhcpd requires that a lease database be present before it will start.
18 To make the initial lease database, just create an empty file called
19 /var/lib/dhcpd/dhcpd.leases. You can do this with:
20 touch /var/lib/dhcpd/dhcpd.leases
22 In order to prevent the lease database from growing without bound, the
24 file is rewritten from time to time. First, a temporary lease data‐
25 base is created and all known leases are dumped to it. Then, the old
26 lease database is renamed /var/lib/dhcpd/dhcpd.leases~. Finally, the
27 newly written lease database is moved into place.
28
30 Lease descriptions are stored in a format that is parsed by the same
31 recursive descent parser used to read the dhcpd.conf(5) and
32 dhclient.conf(5) files. Lease files can contain lease declarations,
33 and also group and subgroup declarations, host declarations and
34 failover state declarations. Group, subgroup and host declarations are
35 used to record objects created using the OMAPI protocol.
36 The lease file is a log-structured file - whenever a lease changes, the
38 contents of that lease are written to the end of the file. This means
39 that it is entirely possible and quite reasonable for there to be two
40 or more declarations of the same lease in the lease file at the same
41 time. In that case, the instance of that particular lease that
42 appears last in the file is the one that is in effect.
43 Group, subgroup and host declarations in the lease file are handled in
45 the same manner, except that if any of these objects are deleted, a
46 rubout is written to the lease file. This is just the same declara‐
47 tion, with { deleted; } in the scope of the declaration. When the
48 lease file is rewritten, any such rubouts that can be eliminated are
49 eliminated. It is possible to delete a declaration in the dhcpd.conf
50 file; in this case, the rubout can never be eliminated from the
51 dhcpd.leases file.
52
54 lease ip-address { statements... }
55 Each lease declaration includes the single IP address that has been
57 leased to the client. The statements within the braces define the
58 duration of the lease and to whom it is assigned.
59 starts date;
61 ends date;
62 tstp date;
63 tsfp date;
64 The start and end time of a lease are recorded using the starts and
66 ends statements. The tstp statement is specified if the failover pro‐
67 tocol is being used, and indicates what time the peer has been told the
68 lease expires. The tsfp statement is also specified if the failover
69 protocol is being used, and indicates the lease expiry time that the
70 peer has acknowledged. The date is specified as follows:
71 weekday year/month/day hour:minute:second
73 The weekday is present to make it easy for a human to tell when a lease
75 expires - it's specified as a number from zero to six, with zero being
76 Sunday. The day of week is ignored on input. The year is specified
77 with the century, so it should generally be four digits except for
78 really long leases. The month is specified as a number starting with 1
79 for January. The day of the month is likewise specified starting with
80 1. The hour is a number between 0 and 23, the minute a number between
81 0 and 59, and the second also a number between 0 and 59.
82 Lease times are specified in Universal Coordinated Time (UTC), not in
84 the local time zone. There is probably nowhere in the world where the
85 times recorded on a lease are always the same as wall clock times. On
86 most unix machines, you can display the current time in UTC by typing
87 date -u.
88 If a lease will never expire, date is never instead of an actual date.
90 hardware hardware-type mac-address;
92 The hardware statement records the MAC address of the network interface
94 on which the lease will be used. It is specified as a series of hexa‐
95 decimal octets, separated by colons.
96 uid client-identifier;
98 The uid statement records the client identifier used by the client to
100 acquire the lease. Clients are not required to send client identi‐
101 fiers, and this statement only appears if the client did in fact send
102 one. Client identifiers are normally an ARP type (1 for ethernet)
103 followed by the MAC address, just like in the hardware statement, but
104 this is not required.
105 The client identifier is recorded as a colon-separated hexadecimal list
107 or as a quoted string. If it is recorded as a quoted string and it
108 contains one or more non-printable characters, those characters are
109 represented as octal escapes - a backslash character followed by three
110 octal digits.
111 client-hostname hostname ;
113 Most DHCP clients will send their hostname in the host-name option. If
115 a client sends its hostname in this way, the hostname is recorded on
116 the lease with a client-hostname statement. This is not required by
117 the protocol, however, so many specialized DHCP clients do not send a
118 host-name option.
119 abandoned;
121 The abandoned statement indicates that the DHCP server has abandoned
123 the lease. In that case, the abandoned statement will be used to
124 indicate that the lease should not be reassigned. Please see the
125 dhcpd.conf(5) manual page for information about abandoned leases.
126 binding state state; next binding state state;
128 The binding state statement declares the lease's binding state. When
130 the DHCP server is not configured to use the failover protocol, a
131 lease's binding state will be either active or free. The failover
132 protocol adds some additional transitional states, as well as the
133 backup state, which indicates that the lease is available for alloca‐
134 tion by the failover secondary.
135 The next binding state statement indicates what state the lease will
137 move to when the current state expires. The time when the current
138 state expires is specified in the ends statement.
139 option agent.circuit-id string; option agent.remote-id string;
141 The option agent.circuit-id and option agent.remote-id statements are
143 used to record the circuit ID and remote ID options send by the relay
144 agent, if the relay agent uses the relay agent information option.
145 This allows these options to be used consistently in conditional evalu‐
146 ations even when the client is contacting the server directly rather
147 than through its relay agent.
148 set variable = value;
150 The set statement sets the value of a variable on the lease. For gen‐
152 eral information on variables, see the dhcp-eval(5) manual page.
153 The ddns-text variable
155 The ddns-text variable is used to record the value of the client's TXT
157 identification record when the interim ddns update style has been used
158 to update the DNS for a particular lease.
159 The ddns-fwd-name variable
161 The ddns-fwd-name variable records the value of the name used in updat‐
163 ing the client's A record if a DDNS update has been successfully done
164 by the server. The server may also have used this name to update the
165 client's PTR record.
166 The ddns-client-fqdn variable
168 If the server is configured to use the interim ddns update style, and
170 is also configured to allow clients to update their own fqdns, and the
171 client did in fact update its own fqdn, then the ddns-client-fqdn vari‐
172 able records the name that the client has indicated it is using. This
173 is the name that the server will have used to update the client's PTR
174 record in this case.
175 The ddns-rev-name variable
177 If the server successfully updates the client's PTR record, this vari‐
179 able will record the name that the DHCP server used for the PTR record.
180 The name to which the PTR record points will be either the ddns-fwd-
181 name or the ddns-client-fqdn.
182 on events { statements... } The on statement records a list of state‐
184 ments to execute if a certain event occurs. The possible events that
185 can occur for an active lease are release and expiry. More than one
186 event can be specified - if so, the events are separated by '|' charac‐
187 ters.
188
190 The state of any failover peering arrangements is also recorded in the
191 lease file, using the failover peer statement:
192 failover peer name state {
194 my state state at date;
195 peer state state at date;
196 }
197 The states of the peer named name is being recorded. Both the state
199 of the running server (my state) and the other failover partner (peer
200 state) are recorded. The following states are possible: unknown-
201 state, partner-down, normal, communications-interrupted, resolution-
202 interrupted, potential-conflict, recover, recover-done, shutdown,
203 paused, and startup. /var/lib/dhcpd/dhcpd.leases
204
206 dhcpd(8), dhcp-options(5), dhcp-eval(5), dhcpd.conf(5), RFC2132,
207 RFC2131.
208
210 dhcpd(8) was written by Ted Lemon under a contract with Vixie Labs.
211 Funding for this project was provided by Internet Systems Consortium.
212 Information about Internet Systems Consortium can be found at:
213 http://www.isc.org/
214 dhcpd.leases(5)