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 atsfp date;
65 cltt date;
66 The start and end time of a lease are recorded using the starts and
68 ends statements. The tstp statement is specified if the failover pro‐
69 tocol is being used, and indicates what time the peer has been told the
70 lease expires. The tsfp statement is also specified if the failover
71 protocol is being used, and indicates the lease expiry time that the
72 peer has acknowledged. The atsfp statement is the actual time sent
73 from the failover partner. The cltt statement is the client's last
74 transaction time.
75 The date is specified in two ways, depending on the configuration value
77 for the db-time-format parameter. If it was set to default, then the
78 date fields appear as follows:
79 weekday year/month/day hour:minute:second
81 The weekday is present to make it easy for a human to tell when a lease
83 expires - it's specified as a number from zero to six, with zero being
84 Sunday. The day of week is ignored on input. The year is specified
85 with the century, so it should generally be four digits except for
86 really long leases. The month is specified as a number starting with 1
87 for January. The day of the month is likewise specified starting with
88 1. The hour is a number between 0 and 23, the minute a number between
89 0 and 59, and the second also a number between 0 and 59.
90 Lease times are specified in Universal Coordinated Time (UTC), not in
92 the local time zone. There is probably nowhere in the world where the
93 times recorded on a lease are always the same as wall clock times. On
94 most unix machines, you can display the current time in UTC by typing
95 date -u.
96 If the db-time-format was configured to local, then the date fields
98 appear as follows:
99 epoch <seconds-since-epoch>; # <day-name> <month-name> <day-number>
101 <hours>:<minutes>:<seconds> <year>
102 The seconds-since-epoch is as according to the system's local clock
104 (often referred to as "unix time"). The # symbol supplies a comment
105 that describes what actual time this is as according to the system's
106 configured timezone, at the time the value was written. It is provided
107 only for human inspection.
108 If a lease will never expire, date is never instead of an actual date.
110 hardware hardware-type mac-address;
112 The hardware statement records the MAC address of the network interface
114 on which the lease will be used. It is specified as a series of hexa‐
115 decimal octets, separated by colons.
116 uid client-identifier;
118 The uid statement records the client identifier used by the client to
120 acquire the lease. Clients are not required to send client identi‐
121 fiers, and this statement only appears if the client did in fact send
122 one. Client identifiers are normally an ARP type (1 for ethernet)
123 followed by the MAC address, just like in the hardware statement, but
124 this is not required.
125 The client identifier is recorded as a colon-separated hexadecimal list
127 or as a quoted string. If it is recorded as a quoted string and it
128 contains one or more non-printable characters, those characters are
129 represented as octal escapes - a backslash character followed by three
130 octal digits.
131 client-hostname hostname ;
133 Most DHCP clients will send their hostname in the host-name option. If
135 a client sends its hostname in this way, the hostname is recorded on
136 the lease with a client-hostname statement. This is not required by
137 the protocol, however, so many specialized DHCP clients do not send a
138 host-name option.
139 abandoned;
141 The abandoned statement indicates that the DHCP server has abandoned
143 the lease. In that case, the abandoned statement will be used to
144 indicate that the lease should not be reassigned. Please see the
145 dhcpd.conf(5) manual page for information about abandoned leases.
146 binding state state; next binding state state;
148 The binding state statement declares the lease's binding state. When
150 the DHCP server is not configured to use the failover protocol, a
151 lease's binding state will be either active or free. The failover
152 protocol adds some additional transitional states, as well as the
153 backup state, which indicates that the lease is available for alloca‐
154 tion by the failover secondary.
155 The next binding state statement indicates what state the lease will
157 move to when the current state expires. The time when the current
158 state expires is specified in the ends statement.
159 option agent.circuit-id string; option agent.remote-id string;
161 The option agent.circuit-id and option agent.remote-id statements are
163 used to record the circuit ID and remote ID options send by the relay
164 agent, if the relay agent uses the relay agent information option.
165 This allows these options to be used consistently in conditional evalu‐
166 ations even when the client is contacting the server directly rather
167 than through its relay agent.
168 set variable = value;
170 The set statement sets the value of a variable on the lease. For gen‐
172 eral information on variables, see the dhcp-eval(5) manual page.
173 The ddns-text variable
175 The ddns-text variable is used to record the value of the client's TXT
177 identification record when the interim ddns update style has been used
178 to update the DNS for a particular lease.
179 The ddns-fwd-name variable
181 The ddns-fwd-name variable records the value of the name used in updat‐
183 ing the client's A record if a DDNS update has been successfully done
184 by the server. The server may also have used this name to update the
185 client's PTR record.
186 The ddns-client-fqdn variable
188 If the server is configured to use the interim ddns update style, and
190 is also configured to allow clients to update their own fqdns, and the
191 client did in fact update its own fqdn, then the ddns-client-fqdn vari‐
192 able records the name that the client has indicated it is using. This
193 is the name that the server will have used to update the client's PTR
194 record in this case.
195 The ddns-rev-name variable
197 If the server successfully updates the client's PTR record, this vari‐
199 able will record the name that the DHCP server used for the PTR record.
200 The name to which the PTR record points will be either the ddns-fwd-
201 name or the ddns-client-fqdn.
202 The vendor-class-identifier variable
204 The server retains the client-supplied Vendor Class Identifier option
206 for informational purposes, and to render them in DHCPLEASEQUERY
207 responses.
208 on events { statements... } The on statement records a list of state‐
210 ments to execute if a certain event occurs. The possible events that
211 can occur for an active lease are release and expiry. More than one
212 event can be specified - if so, the events are separated by '|' charac‐
213 ters.
214 bootp; reserved; These two statements are effectively flags. If
216 present, they indicate that the BOOTP and RESERVED failover flags,
217 respectively, should be set. BOOTP and RESERVED dynamic leases are
218 treated differently than normal dynamic leases, as they may only be
219 used by the client to which they are currently allocated.
220
222 The state of any failover peering arrangements is also recorded in the
223 lease file, using the failover peer statement:
224 failover peer name state {
226 my state state at date;
227 peer state state at date;
228 }
229 The states of the peer named name is being recorded. Both the state
231 of the running server (my state) and the other failover partner (peer
232 state) are recorded. The following states are possible: unknown-
233 state, partner-down, normal, communications-interrupted, resolution-
234 interrupted, potential-conflict, recover, recover-done, shutdown,
235 paused, and startup.
236
238 /var/lib/dhcpd/dhcpd.leases /var/lib/dhcpd/dhcpd.leases~
239
241 dhcpd(8), dhcp-options(5), dhcp-eval(5), dhcpd.conf(5), RFC2132,
242 RFC2131.
243
245 dhcpd(8) was written by Ted Lemon under a contract with Vixie Labs.
246 Funding for this project was provided by Internet Systems Consortium.
247 Information about Internet Systems Consortium can be found at:
248 https://www.isc.org/
249 dhcpd.leases(5)