]>
Commit | Line | Data |
---|---|---|
45d5370c | 1 | .\" dhcpd.leases.5 |
9f3d938c | 2 | .\" |
7512d88b | 3 | .\" Copyright (c) 2004-2017 by Internet Systems Consortium, Inc. ("ISC") |
98311e4b | 4 | .\" Copyright (c) 1996-2003 by Internet Software Consortium |
9f3d938c | 5 | .\" |
7512d88b TM |
6 | .\" This Source Code Form is subject to the terms of the Mozilla Public |
7 | .\" License, v. 2.0. If a copy of the MPL was not distributed with this | |
8 | .\" file, You can obtain one at http://mozilla.org/MPL/2.0/. | |
9f3d938c | 9 | .\" |
98311e4b DH |
10 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES |
11 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
12 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR | |
13 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
14 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
15 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT | |
16 | .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
9f3d938c | 17 | .\" |
98311e4b DH |
18 | .\" Internet Systems Consortium, Inc. |
19 | .\" 950 Charter Street | |
20 | .\" Redwood City, CA 94063 | |
21 | .\" <info@isc.org> | |
2c85ac9b | 22 | .\" https://www.isc.org/ |
98311e4b | 23 | .\" |
cf648f41 | 24 | .\" $Id: dhcpd.leases.5,v 1.17 2011/09/19 00:24:50 sar Exp $ |
f49473ba | 25 | .\" |
9f3d938c TL |
26 | .TH dhcpd.leases 5 |
27 | .SH NAME | |
28 | dhcpd.leases - DHCP client lease database | |
29 | .SH DESCRIPTION | |
98311e4b | 30 | The Internet Systems Consortium DHCP Server keeps a persistent |
9f3d938c | 31 | database of leases that it has assigned. This database is a free-form |
45d5370c TL |
32 | ASCII file containing a series of lease declarations. Every time a |
33 | lease is acquired, renewed or released, its new value is recorded at | |
34 | the end of the lease file. So if more than one declaration appears | |
35 | for a given lease, the last one in the file is the current one. | |
9f3d938c TL |
36 | .PP |
37 | When dhcpd is first installed, there is no lease database. However, | |
38 | dhcpd requires that a lease database be present before it will start. | |
39 | To make the initial lease database, just create an empty file called | |
43d5ca99 TL |
40 | DBDIR/dhcpd.leases. You can do this with: |
41 | .PP | |
42 | .nf | |
43 | touch DBDIR/dhcpd.leases | |
44 | .fi | |
9f3d938c TL |
45 | .PP |
46 | In order to prevent the lease database from growing without bound, the | |
47 | file is rewritten from time to time. First, a temporary lease | |
48 | database is created and all known leases are dumped to it. Then, the | |
49 | old lease database is renamed DBDIR/dhcpd.leases~. Finally, the | |
50 | newly written lease database is moved into place. | |
aeb683ee SR |
51 | .PP |
52 | In order to process both DHCPv4 and DHCPv6 messages you will need to | |
53 | run two separate instances of the dhcpd process. Each of these | |
54 | instances will need it's own lease file. You can use the \fI-lf\fR | |
55 | option on the server's command line to specify a different lease file | |
56 | name for one or both servers. | |
9f3d938c | 57 | .SH FORMAT |
eb4b6456 TL |
58 | Lease descriptions are stored in a format that is parsed by the same |
59 | recursive descent parser used to read the | |
60 | .B dhcpd.conf(5) | |
61 | and | |
62 | .B dhclient.conf(5) | |
b276ad75 TL |
63 | files. Lease files can contain lease declarations, and also group and |
64 | subgroup declarations, host declarations and failover state | |
65 | declarations. Group, subgroup and host declarations are used to | |
66 | record objects created using the OMAPI protocol. | |
eb4b6456 | 67 | .PP |
b276ad75 TL |
68 | The lease file is a log-structured file - whenever a lease changes, |
69 | the contents of that lease are written to the end of the file. This | |
70 | means that it is entirely possible and quite reasonable for there to | |
71 | be two or more declarations of the same lease in the lease file at the | |
72 | same time. In that case, the instance of that particular lease that | |
73 | appears last in the file is the one that is in effect. | |
74 | .PP | |
75 | Group, subgroup and host declarations in the lease file are handled in | |
76 | the same manner, except that if any of these objects are deleted, a | |
77 | \fIrubout\fR is written to the lease file. This is just the same | |
78 | declaration, with \fB{ deleted; }\fR in the scope of the | |
79 | declaration. When the lease file is rewritten, any such rubouts that | |
80 | can be eliminated are eliminated. It is possible to delete a | |
81 | declaration in the \fBdhcpd.conf\fR file; in this case, the rubout | |
82 | can never be eliminated from the \fBdhcpd.leases\fR file. | |
aeb683ee SR |
83 | .SH COMMON STATEMENTS FOR LEASE DECLARATIONS |
84 | While the lease file formats for DHCPv4 and DHCPv6 are different | |
85 | they share many common statements and structures. This section | |
86 | describes the common statements while the succeeding sections | |
87 | describe the protocol specific statements. | |
eb4b6456 | 88 | .PP |
aeb683ee | 89 | .B Dates |
64e1823d | 90 | .PP |
aeb683ee | 91 | A \fIdate\fR is specified in two ways, depending on the configuration |
64e1823d DH |
92 | value for the \fBdb-time-format\fR parameter. If it was set to \fIdefault\fR, |
93 | then the \fIdate\fR fields appear as follows: | |
eb4b6456 | 94 | .PP |
b276ad75 | 95 | .I weekday year\fB/\fImonth\fB/\fIday hour\fB:\fIminute\fB:\fIsecond\fR |
eb4b6456 TL |
96 | .PP |
97 | The weekday is present to make it easy for a human to tell when a | |
98 | lease expires - it's specified as a number from zero to six, with zero | |
45d5370c TL |
99 | being Sunday. The day of week is ignored on input. The year is |
100 | specified with the century, so it should generally be four digits | |
101 | except for really long leases. The month is specified as a number | |
102 | starting with 1 for January. The day of the month is likewise | |
103 | specified starting with 1. The hour is a number between 0 and 23, the | |
104 | minute a number between 0 and 59, and the second also a number between | |
105 | 0 and 59. | |
106 | .PP | |
b276ad75 TL |
107 | Lease times are specified in Universal Coordinated Time (UTC), not in |
108 | the local time zone. There is probably nowhere in the world where the | |
109 | times recorded on a lease are always the same as wall clock times. On | |
110 | most unix machines, you can display the current time in UTC by typing | |
111 | \fBdate -u\fR. | |
112 | .PP | |
64e1823d DH |
113 | If the \fBdb-time-format\fR was configured to \fIlocal\fR, then |
114 | the \fIdate\fR fields appear as follows: | |
115 | .PP | |
116 | \fBepoch\fR \fI<seconds-since-epoch>\fR\fB; #\fR \fI<day-name> <month-name> | |
117 | <day-number> <hours>\fR\fB:\fR\fI<minutes>\fR\fB:\fR\fI<seconds> <year>\fR | |
118 | .PP | |
119 | The \fIseconds-since-epoch\fR is as according to the system's local clock (often | |
120 | referred to as "unix time"). The \fB#\fR symbol supplies a comment that | |
121 | describes what actual time this is as according to the system's configured | |
122 | timezone, at the time the value was written. It is provided only for human | |
123 | inspection. | |
124 | .PP | |
b276ad75 TL |
125 | If a lease will never expire, \fIdate\fR is \fBnever\fR instead of an |
126 | actual date. | |
127 | .PP | |
aeb683ee SR |
128 | .B General Variables |
129 | .PP | |
130 | As part of the processing of a lease information may be attached to the | |
131 | lease structure, for example the DDNS information or if you specify a | |
132 | variable in your configuration file. Some of these, like the DDNS | |
133 | information, have specific descriptions below. For others, such as | |
134 | any you might define, a generic line of the following will be included. | |
135 | .PP | |
136 | .B set \fIvariable\fB = \fIvalue\fB; | |
137 | .PP | |
138 | The \fBset\fR statement sets the value of a variable on the lease. | |
139 | For general information on variables, see the \fBdhcp-eval(5)\fR | |
140 | manual page. | |
141 | .PP | |
142 | .B DDNS Variables | |
143 | .PP | |
144 | .nf | |
145 | .B The \fIddns-text\fB and \fIddns-dhcid\fB variables | |
146 | .PP | |
147 | These variables are used to record the value of the client's identification | |
148 | record when the server has updated DNS for a particular lease. The text | |
149 | record is used with the interim DDNS update style while the dhcid record | |
150 | is used for the standard DDNS update style. | |
151 | .PP | |
152 | .B The \fIddns-fwd-name\fB variable | |
153 | .PP | |
154 | This variable records the value of the name used in | |
155 | updating the client's A record if a DDNS update has been successfully | |
156 | done by the server. The server may also have used this name to | |
157 | update the client's PTR record. | |
158 | .PP | |
159 | .B The \fIddns-client-fqdn\fB variable | |
160 | .PP | |
161 | If the server is configured both to use the interim or standard DDNS update | |
162 | style, and to allow clients to update their own FQDNs, then if the | |
163 | client did in fact update its own FQDN, the | |
164 | \fIddns-client-fqdn\fR variable records the name that the client has | |
165 | indicated it is using. This is the name that the server will have | |
166 | used to update the client's PTR record in this case. | |
167 | .PP | |
168 | .B The \fIddns-rev-name\fB variable | |
169 | .PP | |
170 | If the server successfully updates the client's PTR record, this | |
171 | variable will record the name that the DHCP server used for the PTR | |
172 | record. The name to which the PTR record points will be either the | |
173 | \fIddns-fwd-name\fR or the \fIddns-client-fqdn\fR. | |
174 | .PP | |
175 | .B Executable Statements | |
176 | .PP | |
177 | .B on \fIevents\fB { \fIstatements...\fB } | |
178 | The \fBon\fR statement records a list of statements to execute if a | |
179 | certain event occurs. The possible events that can occur for an | |
180 | active lease are \fBrelease\fR and \fBexpiry\fR. More than one event | |
181 | can be specified - if so, the events are separated by '|' characters. | |
182 | .PP | |
347d4962 TM |
183 | The \fIauthoring-byte-order\fR statement |
184 | .RS 0.25i | |
185 | .PP | |
186 | .B authoring-byte-order \fR[ \fIbig-endian\fR | \fIlittle-endian\fR ] \fB;\fR | |
187 | .PP | |
188 | This statement is automatically added to the top of new lease files by | |
189 | the server. It indicates the internal byte order of the server. This | |
190 | permits lease files generated on a server with one form of byte order | |
191 | to be read by a server with a different form. Lease files which do not | |
192 | contain this entry are simply treated as having the same byte order as | |
193 | the server reading them. If you are migrating lease files generated | |
194 | by a server that predates this statement and is of a different byte | |
195 | order than the your destination server, you can manually add this | |
196 | statement. It must proceed any lease entries. Valid values for this | |
197 | parameter are \fIlittle-endian\fR and \fIbig-endian\fR. | |
198 | .RE | |
199 | .PP | |
aeb683ee SR |
200 | .SH THE DHCPv4 LEASE DECLARATION |
201 | .PP | |
202 | .B lease \fIip-address\fB { \fIstatements...\fB } | |
203 | .PP | |
204 | Each lease declaration includes the single IP address that has been | |
205 | leased to the client. The statements within the braces define the | |
206 | duration of the lease and to whom it is assigned. | |
207 | .PP | |
208 | .nf | |
209 | .B starts \fIdate\fB;\fR | |
210 | .B ends \fIdate\fB;\fR | |
211 | .B tstp \fIdate\fB;\fR | |
212 | .B tsfp \fIdate\fB;\fR | |
213 | .B atsfp \fIdate\fB;\fR | |
214 | .B cltt \fIdate\fB;\fR | |
215 | .fi | |
216 | .PP | |
217 | The start and end time of a lease are recorded using the \fBstarts\fR | |
218 | and \fBends\fR statements. The \fBtstp\fR statement is present if | |
219 | the failover protocol is being used, and indicates what time the peer | |
220 | has been told the lease expires. The \fBtsfp\fR statement is | |
221 | also present if the failover protocol is being used, and indicates | |
222 | the lease expiry time that the peer has acknowledged. | |
223 | The \fBatsfp\fR statement is the actual time sent from the failover | |
224 | partner. | |
225 | The \fBcltt\fR statement is the client's last transaction time. | |
226 | .PP | |
227 | See the description of dates in the section on common structures. | |
228 | .PP | |
b276ad75 TL |
229 | .B hardware \fIhardware-type mac-address\fB;\fR |
230 | .PP | |
231 | The hardware statement records the MAC address of the network | |
232 | interface on which the lease will be used. It is specified as a | |
98311e4b | 233 | series of hexadecimal octets, separated by colons. |
b276ad75 TL |
234 | .PP |
235 | .B uid \fIclient-identifier\fB;\fR | |
236 | .PP | |
237 | The \fBuid\fR statement records the client identifier used by the | |
238 | client to acquire the lease. Clients are not required to send client | |
239 | identifiers, and this statement only appears if the client did in fact | |
240 | send one. Client identifiers are normally an ARP type (1 for | |
241 | ethernet) followed by the MAC address, just like in the \fBhardware\fI | |
242 | statement, but this is not required. | |
243 | .PP | |
98311e4b | 244 | The client identifier is recorded as a colon-separated hexadecimal |
08a51b98 TL |
245 | list or as a quoted string. If it is recorded as a quoted string and |
246 | it contains one or more non-printable characters, those characters are | |
247 | represented as octal escapes - a backslash character followed by three | |
cc1bd34e TM |
248 | octal digits. The format used is determined by the lease-id-format |
249 | parameter, which defaults to octal. | |
eb4b6456 | 250 | .PP |
b276ad75 | 251 | .B client-hostname "\fIhostname\fB";\fR |
eb4b6456 | 252 | .PP |
b276ad75 TL |
253 | Most DHCP clients will send their hostname in the \fIhost-name\fR |
254 | option. If a client sends its hostname in this way, the hostname is | |
255 | recorded on the lease with a \fBclient-hostname\fR statement. This | |
256 | is not required by the protocol, however, so many specialized DHCP | |
257 | clients do not send a host-name option. | |
eb4b6456 | 258 | .PP |
aeb683ee | 259 | .nf |
b276ad75 TL |
260 | .B binding state \fIstate\fB; |
261 | .B next binding state \fIstate\fB; | |
aeb683ee | 262 | .fi |
eb4b6456 | 263 | .PP |
b276ad75 TL |
264 | The \fBbinding state\fR statement declares the lease's binding state. |
265 | When the DHCP server is not configured to use the failover protocol, a | |
112d76f6 TM |
266 | lease's binding state may be \fBactive\fR, \fBfree\fR or \fBabandoned\fR. |
267 | The failover protocol adds some additional transitional states, as well as | |
b276ad75 | 268 | the \fBbackup\fR state, which indicates that the lease is available |
112d76f6 TM |
269 | for allocation by the failover secondary. Please see the \fBdhcpd.conf(5)\fR |
270 | manual page for more information about abandoned leases. | |
eb4b6456 | 271 | .PP |
b276ad75 TL |
272 | The \fBnext binding state\fR statement indicates what state the lease |
273 | will move to when the current state expires. The time when the | |
274 | current state expires is specified in the \fIends\fR statement. | |
eb4b6456 | 275 | .PP |
aeb683ee SR |
276 | .B rewind binding state \fIstate\fB; |
277 | .PP | |
278 | This statement is part of an optimization for | |
279 | use with failover. This helps a server rewind a lease to the state most | |
280 | recently transmitted to its peer. | |
281 | .PP | |
282 | .nf | |
b276ad75 TL |
283 | .B option agent.circuit-id \fIstring\fR; |
284 | .B option agent.remote-id \fIstring\fR; | |
aeb683ee | 285 | .fi |
eb4b6456 | 286 | .PP |
aeb683ee SR |
287 | These statements are used to record the circuit ID and remote ID options |
288 | sent by the relay agent, if the relay agent uses the \fIrelay agent | |
b276ad75 TL |
289 | information option\fR. This allows these options to be used |
290 | consistently in conditional evaluations even when the client is | |
291 | contacting the server directly rather than through its relay agent. | |
eb4b6456 | 292 | .PP |
aeb683ee | 293 | .B The \fIvendor-class-identifier\fB variable |
eb4b6456 | 294 | .PP |
aeb683ee SR |
295 | The server retains the client-supplied Vendor Class Identifier option |
296 | for informational purposes, and to render them in DHCPLEASEQUERY responses. | |
eb4b6456 | 297 | .PP |
aeb683ee SR |
298 | .nf |
299 | .B bootp; | |
300 | .B reserved; | |
301 | .fi | |
45d5370c | 302 | .PP |
aeb683ee SR |
303 | If present, they indicate that the BOOTP and RESERVED failover flags |
304 | (respectively) should be set. BOOTP | |
305 | and RESERVED dynamic leases are treated differently than normal dynamic leases, | |
306 | as they may only be used by the client to which they are currently allocated. | |
b276ad75 | 307 | .PP |
aeb683ee SR |
308 | .B Other |
309 | Additional options or executable statements may be included, see the description | |
310 | of them in the section on common structures. | |
311 | .RE | |
b276ad75 | 312 | .PP |
aeb683ee | 313 | .SH THE DHCPv6 LEASE (IA) DECLARATION |
b276ad75 | 314 | .PP |
aeb683ee SR |
315 | .nf |
316 | .B ia_ta \fI IAID_DUID\fB { \fIstatements...\fB } | |
317 | .B ia_na \fI IAID_DUID\fB { \fIstatements...\fB } | |
318 | .B ia_pd \fI IAID_DUID\fB { \fIstatements...\fB } | |
319 | .fi | |
b276ad75 | 320 | .PP |
aeb683ee SR |
321 | Each lease declaration starts with a tag indicating the type of the lease. |
322 | ia_ta is for temporary addresses, ia_na is for non-temporary addresses and | |
323 | ia_pd is for prefix delegation. Following this tag is the combined IAID | |
112d76f6 | 324 | and DUID from the client for this lease. |
b276ad75 | 325 | .PP |
aeb683ee SR |
326 | The IAID_DUID value is recorded as a colon-separated hexadecimal |
327 | list or as a quoted string. If it is recorded as a quoted string and | |
328 | it contains one or more non-printable characters, those characters are | |
329 | represented as octal escapes - a backslash character followed by three | |
cc1bd34e TM |
330 | octal digits. The format used is governed by the lease-id-format parameter, |
331 | which defaults to octal. | |
b276ad75 | 332 | .PP |
aeb683ee | 333 | .B cltt \fIdate\fB;\fR |
b276ad75 | 334 | .PP |
aeb683ee | 335 | The \fBcltt\fR statement is the client's last transaction time. |
656b1ece | 336 | .PP |
aeb683ee | 337 | See the description of dates in the section on common structures. |
656b1ece | 338 | .PP |
aeb683ee SR |
339 | .nf |
340 | .B iaaddr \fIipv6-address\fB { \fIstatements...\fB } | |
341 | .B iaprefix \fIipv6-address/prefix-length\fB { \fIstatements...\fB } | |
342 | .PP | |
343 | Within a given lease there can be multiple iaaddr and iaprefix statements. | |
344 | Each will have either an IPv6 address or an IPv6 prefix (an address and | |
345 | a prefix length indicating a CIDR style block of addresses). The following | |
112d76f6 | 346 | statements may occur Within each iaaddr or iaprefix. |
aeb683ee SR |
347 | .PP |
348 | .B binding state \fIstate\fB; | |
349 | .PP | |
350 | The \fBbinding state\fR statement declares the lease's binding state. | |
351 | In DHCPv6 you will normally see this as \fIactive\fR or \fIexpired\fR. | |
352 | .PP | |
353 | .B preferred-life \fIlifetime\fB; | |
354 | .PP | |
355 | The IPv6 preferred lifetime associated with this address, in seconds. | |
356 | .PP | |
357 | .B max-life \fIlifetime\fB; | |
358 | .PP | |
359 | The valid lifetime associated with this address, in seconds. | |
360 | .PP | |
361 | .B ends \fIdate\fB;\fR | |
362 | .PP | |
363 | The end time of the lease. See the description of dates in the section on | |
364 | common structures. | |
365 | .PP | |
366 | Additional options or executable statements may be included. See the description | |
367 | of them in the section on common structures. | |
1db5e2c0 | 368 | .PP |
1db5e2c0 | 369 | .RE |
b276ad75 TL |
370 | .SH THE FAILOVER PEER STATE DECLARATION |
371 | The state of any failover peering arrangements is also recorded in the | |
372 | lease file, using the \fBfailover peer\fR statement: | |
373 | .PP | |
374 | .nf | |
375 | .B failover peer "\fIname\fB" state { | |
376 | .B my state \fIstate\fB at \fIdate\fB; | |
377 | .B peer state \fIstate\fB at \fIdate\fB; | |
378 | .B } | |
379 | .fi | |
45d5370c | 380 | .PP |
b276ad75 TL |
381 | The states of the peer named \fIname\fR is being recorded. Both the |
382 | state of the running server (\fBmy state\fR) and the other failover | |
383 | partner (\fIpeer state\fR) are recorded. The following states are | |
384 | possible: \fBunknown-state\fR, \fBpartner-down\fR, \fBnormal\fR, | |
385 | \fBcommunications-interrupted\fR, \fBresolution-interrupted\fR, | |
386 | \fBpotential-conflict\fR, \fBrecover\fR, \fBrecover-done\fR, | |
387 | \fBshutdown\fR, \fBpaused\fR, and \fBstartup\fR. | |
cf648f41 SR |
388 | .RE |
389 | .SH FILES | |
390 | .B DBDIR/dhcpd.leases DBDIR/dhcpd.leases~ | |
9f3d938c | 391 | .SH SEE ALSO |
b276ad75 | 392 | dhcpd(8), dhcp-options(5), dhcp-eval(5), dhcpd.conf(5), RFC2132, RFC2131. |
9f3d938c TL |
393 | .SH AUTHOR |
394 | .B dhcpd(8) | |
edad9be5 | 395 | is maintained by ISC. |
98311e4b | 396 | Information about Internet Systems Consortium can be found at: |
2c85ac9b | 397 | .B https://www.isc.org/ |