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 In order to process both DHCPv4 and DHCPv6 messages you will need to
30 run two separate instances of the dhcpd process. Each of these
31 instances will need it's own lease file. You can use the -lf option on
32 the server's command line to specify a different lease file name for
33 one or both servers.
34
36 Lease descriptions are stored in a format that is parsed by the same
37 recursive descent parser used to read the dhcpd.conf(5) and
38 dhclient.conf(5) files. Lease files can contain lease declarations,
39 and also group and subgroup declarations, host declarations and
40 failover state declarations. Group, subgroup and host declarations are
41 used to record objects created using the OMAPI protocol.
42 The lease file is a log-structured file - whenever a lease changes, the
44 contents of that lease are written to the end of the file. This means
45 that it is entirely possible and quite reasonable for there to be two
46 or more declarations of the same lease in the lease file at the same
47 time. In that case, the instance of that particular lease that
48 appears last in the file is the one that is in effect.
49 Group, subgroup and host declarations in the lease file are handled in
51 the same manner, except that if any of these objects are deleted, a
52 rubout is written to the lease file. This is just the same declara‐
53 tion, with { deleted; } in the scope of the declaration. When the
54 lease file is rewritten, any such rubouts that can be eliminated are
55 eliminated. It is possible to delete a declaration in the dhcpd.conf
56 file; in this case, the rubout can never be eliminated from the
57 dhcpd.leases file.
58
60 While the lease file formats for DHCPv4 and DHCPv6 are different they
61 share many common statements and structures. This section describes
62 the common statements while the succeeding sections describe the proto‐
63 col specific statements.
64 Dates
66 A date is specified in two ways, depending on the configuration value
68 for the db-time-format parameter. If it was set to default, then the
69 date fields appear as follows:
70 weekday year/month/day hour:minute:second
72 The weekday is present to make it easy for a human to tell when a lease
74 expires - it's specified as a number from zero to six, with zero being
75 Sunday. The day of week is ignored on input. The year is specified
76 with the century, so it should generally be four digits except for
77 really long leases. The month is specified as a number starting with 1
78 for January. The day of the month is likewise specified starting with
79 1. The hour is a number between 0 and 23, the minute a number between
80 0 and 59, and the second also a number between 0 and 59.
81 Lease times are specified in Universal Coordinated Time (UTC), not in
83 the local time zone. There is probably nowhere in the world where the
84 times recorded on a lease are always the same as wall clock times. On
85 most unix machines, you can display the current time in UTC by typing
86 date -u.
87 If the db-time-format was configured to local, then the date fields
89 appear as follows:
90 epoch <seconds-since-epoch>; # <day-name> <month-name> <day-number>
92 <hours>:<minutes>:<seconds> <year>
93 The seconds-since-epoch is as according to the system's local clock
95 (often referred to as "unix time"). The # symbol supplies a comment
96 that describes what actual time this is as according to the system's
97 configured timezone, at the time the value was written. It is provided
98 only for human inspection.
99 If a lease will never expire, date is never instead of an actual date.
101 General Variables
103 As part of the processing of a lease information may be attached to the
105 lease structure, for example the DDNS information or if you specify a
106 variable in your configuration file. Some of these, like the DDNS
107 information, have specific descriptions below. For others, such as any
108 you might define, a generic line of the following will be included.
109 set variable = value;
111 The set statement sets the value of a variable on the lease. For gen‐
113 eral information on variables, see the dhcp-eval(5) manual page.
114 DDNS Variables
116 The ddns-text and ddns-dhcid variables
118 These variables are used to record the value of the client's identification
120 record when the server has updated DNS for a particular lease. The text
121 record is used with the interim DDNS update style while the dhcid record
122 is used for the standard DDNS update style.
123 The ddns-fwd-name variable
125 This variable records the value of the name used in
127 updating the client's A record if a DDNS update has been successfully
128 done by the server. The server may also have used this name to
129 update the client's PTR record.
130 The ddns-client-fqdn variable
132 If the server is configured both to use the interim or standard DDNS update
134 style, and to allow clients to update their own FQDNs, then if the
135 client did in fact update its own FQDN, the
136 ddns-client-fqdn variable records the name that the client has
137 indicated it is using. This is the name that the server will have
138 used to update the client's PTR record in this case.
139 The ddns-rev-name variable
141 If the server successfully updates the client's PTR record, this
143 variable will record the name that the DHCP server used for the PTR
144 record. The name to which the PTR record points will be either the
145 ddns-fwd-name or the ddns-client-fqdn.
146 Executable Statements
148 on events { statements... }
150 The on statement records a list of statements to execute if a
151 certain event occurs. The possible events that can occur for an
152 active lease are release and expiry. More than one event
153 can be specified - if so, the events are separated by '|' characters.
154 The authoring-byte-order statement
156 authoring-byte-order [ big-endian | little-endian ] ;
158 This statement is automatically added to the top of new lease files by
160 the server. It indicates the internal byte order of the server. This
161 permits lease files generated on a server with one form of byte order
162 to be read by a server with a different form. Lease files which do not
163 contain this entry are simply treated as having the same byte order as
164 the server reading them. If you are migrating lease files generated
165 by a server that predates this statement and is of a different byte
166 order than the your destination server, you can manually add this
167 statement. It must proceed any lease entries. Valid values for this
168 parameter are little-endian and big-endian.
169
171 lease ip-address { statements... }
172 Each lease declaration includes the single IP address that has been
174 leased to the client. The statements within the braces define the
175 duration of the lease and to whom it is assigned.
176 starts date;
178 ends date;
179 tstp date;
180 tsfp date;
181 atsfp date;
182 cltt date;
183 The start and end time of a lease are recorded using the starts and
185 ends statements. The tstp statement is present if the failover proto‐
186 col is being used, and indicates what time the peer has been told the
187 lease expires. The tsfp statement is also present if the failover
188 protocol is being used, and indicates the lease expiry time that the
189 peer has acknowledged. The atsfp statement is the actual time sent
190 from the failover partner. The cltt statement is the client's last
191 transaction time.
192 See the description of dates in the section on common structures.
194 hardware hardware-type mac-address;
196 The hardware statement records the MAC address of the network interface
198 on which the lease will be used. It is specified as a series of hexa‐
199 decimal octets, separated by colons.
200 uid client-identifier;
202 The uid statement records the client identifier used by the client to
204 acquire the lease. Clients are not required to send client identi‐
205 fiers, and this statement only appears if the client did in fact send
206 one. Client identifiers are normally an ARP type (1 for ethernet)
207 followed by the MAC address, just like in the hardware statement, but
208 this is not required.
209 The client identifier is recorded as a colon-separated hexadecimal list
211 or as a quoted string. If it is recorded as a quoted string and it
212 contains one or more non-printable characters, those characters are
213 represented as octal escapes - a backslash character followed by three
214 octal digits. The format used is determined by the lease-id-format
215 parameter, which defaults to octal.
216 client-hostname hostname ;
218 Most DHCP clients will send their hostname in the host-name option. If
220 a client sends its hostname in this way, the hostname is recorded on
221 the lease with a client-hostname statement. This is not required by
222 the protocol, however, so many specialized DHCP clients do not send a
223 host-name option.
224 binding state state;
226 next binding state state;
227 The binding state statement declares the lease's binding state. When
229 the DHCP server is not configured to use the failover protocol, a
230 lease's binding state may be active, free or abandoned. The failover
231 protocol adds some additional transitional states, as well as the
232 backup state, which indicates that the lease is available for alloca‐
233 tion by the failover secondary. Please see the dhcpd.conf(5) manual
234 page for more information about abandoned leases.
235 The next binding state statement indicates what state the lease will
237 move to when the current state expires. The time when the current
238 state expires is specified in the ends statement.
239 rewind binding state state;
241 This statement is part of an optimization for use with failover. This
243 helps a server rewind a lease to the state most recently transmitted to
244 its peer.
245 option agent.circuit-id string;
247 option agent.remote-id string;
248 These statements are used to record the circuit ID and remote ID
250 options sent by the relay agent, if the relay agent uses the relay
251 agent information option. This allows these options to be used con‐
252 sistently in conditional evaluations even when the client is contacting
253 the server directly rather than through its relay agent.
254 The vendor-class-identifier variable
256 The server retains the client-supplied Vendor Class Identifier option
258 for informational purposes, and to render them in DHCPLEASEQUERY
259 responses.
260 bootp;
262 reserved;
263 If present, they indicate that the BOOTP and RESERVED failover flags
265 (respectively) should be set. BOOTP and RESERVED dynamic leases are
266 treated differently than normal dynamic leases, as they may only be
267 used by the client to which they are currently allocated.
268 Other Additional options or executable statements may be included, see
270 the description of them in the section on common structures.
271
273 ia_ta IAID_DUID { statements... }
274 ia_na IAID_DUID { statements... }
275 ia_pd IAID_DUID { statements... }
276 Each lease declaration starts with a tag indicating the type of the
278 lease. ia_ta is for temporary addresses, ia_na is for non-temporary
279 addresses and ia_pd is for prefix delegation. Following this tag is
280 the combined IAID and DUID from the client for this lease.
281 The IAID_DUID value is recorded as a colon-separated hexadecimal list
283 or as a quoted string. If it is recorded as a quoted string and it
284 contains one or more non-printable characters, those characters are
285 represented as octal escapes - a backslash character followed by three
286 octal digits. The format used is governed by the lease-id-format
287 parameter, which defaults to octal.
288 cltt date;
290 The cltt statement is the client's last transaction time.
292 See the description of dates in the section on common structures.
294 iaaddr ipv6-address { statements... }
296 iaprefix ipv6-address/prefix-length { statements... }
297 Within a given lease there can be multiple iaaddr and iaprefix statements.
299 Each will have either an IPv6 address or an IPv6 prefix (an address and
300 a prefix length indicating a CIDR style block of addresses). The following
301 statements may occur Within each iaaddr or iaprefix.
302 binding state state;
304 The binding state statement declares the lease's binding state.
306 In DHCPv6 you will normally see this as active or expired.
307 preferred-life lifetime;
309 The IPv6 preferred lifetime associated with this address, in seconds.
311 max-life lifetime;
313 The valid lifetime associated with this address, in seconds.
315 ends date;
317 The end time of the lease. See the description of dates in the section on
319 common structures.
320 Additional options or executable statements may be included. See the description
322 of them in the section on common structures.
323
325 The state of any failover peering arrangements is also recorded in the
326 lease file, using the failover peer statement:
327 failover peer name state {
329 my state state at date;
330 peer state state at date;
331 }
332 The states of the peer named name is being recorded. Both the state
334 of the running server (my state) and the other failover partner (peer
335 state) are recorded. The following states are possible: unknown-
336 state, partner-down, normal, communications-interrupted, resolution-
337 interrupted, potential-conflict, recover, recover-done, shutdown,
338 paused, and startup.
339
341 /var/lib/dhcpd/dhcpd.leases /var/lib/dhcpd/dhcpd.leases~
342
344 dhcpd(8), dhcp-options(5), dhcp-eval(5), dhcpd.conf(5), RFC2132,
345 RFC2131.
346
348 dhcpd(8) is maintained by ISC. Information about Internet Systems Con‐
349 sortium can be found at: https://www.isc.org/
350 dhcpd.leases(5)