]>
Commit | Line | Data |
---|---|---|
45d5370c | 1 | .\" dhcpd.leases.5 |
9f3d938c | 2 | .\" |
98311e4b DH |
3 | .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") |
4 | .\" Copyright (c) 1996-2003 by Internet Software Consortium | |
9f3d938c | 5 | .\" |
98311e4b DH |
6 | .\" Permission to use, copy, modify, and distribute this software for any |
7 | .\" purpose with or without fee is hereby granted, provided that the above | |
8 | .\" copyright notice and this permission notice appear in all copies. | |
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> | |
22 | .\" http://www.isc.org/ | |
23 | .\" | |
24 | .\" This software has been written for Internet Systems Consortium | |
b276ad75 | 25 | .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc. |
98311e4b | 26 | .\" To learn more about Internet Systems Consortium, see |
b276ad75 TL |
27 | .\" ``http://www.isc.org/''. To learn more about Vixie Enterprises, |
28 | .\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see | |
29 | .\" ``http://www.nominum.com''. | |
f49473ba | 30 | .\" |
d4d2c475 | 31 | .\" $Id: dhcpd.leases.5,v 1.12 2008/11/20 15:18:28 jreed Exp $ |
f49473ba | 32 | .\" |
9f3d938c TL |
33 | .TH dhcpd.leases 5 |
34 | .SH NAME | |
35 | dhcpd.leases - DHCP client lease database | |
36 | .SH DESCRIPTION | |
98311e4b | 37 | The Internet Systems Consortium DHCP Server keeps a persistent |
9f3d938c | 38 | database of leases that it has assigned. This database is a free-form |
45d5370c TL |
39 | ASCII file containing a series of lease declarations. Every time a |
40 | lease is acquired, renewed or released, its new value is recorded at | |
41 | the end of the lease file. So if more than one declaration appears | |
42 | for a given lease, the last one in the file is the current one. | |
9f3d938c TL |
43 | .PP |
44 | When dhcpd is first installed, there is no lease database. However, | |
45 | dhcpd requires that a lease database be present before it will start. | |
46 | To make the initial lease database, just create an empty file called | |
43d5ca99 TL |
47 | DBDIR/dhcpd.leases. You can do this with: |
48 | .PP | |
49 | .nf | |
50 | touch DBDIR/dhcpd.leases | |
51 | .fi | |
9f3d938c TL |
52 | .PP |
53 | In order to prevent the lease database from growing without bound, the | |
54 | file is rewritten from time to time. First, a temporary lease | |
55 | database is created and all known leases are dumped to it. Then, the | |
56 | old lease database is renamed DBDIR/dhcpd.leases~. Finally, the | |
57 | newly written lease database is moved into place. | |
9f3d938c | 58 | .SH FORMAT |
eb4b6456 TL |
59 | Lease descriptions are stored in a format that is parsed by the same |
60 | recursive descent parser used to read the | |
61 | .B dhcpd.conf(5) | |
62 | and | |
63 | .B dhclient.conf(5) | |
b276ad75 TL |
64 | files. Lease files can contain lease declarations, and also group and |
65 | subgroup declarations, host declarations and failover state | |
66 | declarations. Group, subgroup and host declarations are used to | |
67 | record objects created using the OMAPI protocol. | |
eb4b6456 | 68 | .PP |
b276ad75 TL |
69 | The lease file is a log-structured file - whenever a lease changes, |
70 | the contents of that lease are written to the end of the file. This | |
71 | means that it is entirely possible and quite reasonable for there to | |
72 | be two or more declarations of the same lease in the lease file at the | |
73 | same time. In that case, the instance of that particular lease that | |
74 | appears last in the file is the one that is in effect. | |
75 | .PP | |
76 | Group, subgroup and host declarations in the lease file are handled in | |
77 | the same manner, except that if any of these objects are deleted, a | |
78 | \fIrubout\fR is written to the lease file. This is just the same | |
79 | declaration, with \fB{ deleted; }\fR in the scope of the | |
80 | declaration. When the lease file is rewritten, any such rubouts that | |
81 | can be eliminated are eliminated. It is possible to delete a | |
82 | declaration in the \fBdhcpd.conf\fR file; in this case, the rubout | |
83 | can never be eliminated from the \fBdhcpd.leases\fR file. | |
84 | .SH THE LEASE DECLARATION | |
85 | .PP | |
86 | .B lease \fIip-address\fB { \fIstatements...\fB } | |
eb4b6456 | 87 | .PP |
98311e4b | 88 | Each lease declaration includes the single IP address that has been |
eb4b6456 TL |
89 | leased to the client. The statements within the braces define the |
90 | duration of the lease and to whom it is assigned. | |
91 | .PP | |
b276ad75 TL |
92 | .nf |
93 | .B starts \fIdate\fB;\fR | |
94 | .B ends \fIdate\fB;\fR | |
95 | .B tstp \fIdate\fB;\fR | |
96 | .B tsfp \fIdate\fB;\fR | |
d4d2c475 JR |
97 | .B atsfp \fIdate\fB;\fR |
98 | .B cltt \fIdate\fB;\fR | |
b276ad75 | 99 | .fi |
eb4b6456 | 100 | .PP |
b276ad75 TL |
101 | The start and end time of a lease are recorded using the \fBstarts\fR |
102 | and \fBends\fR statements. The \fBtstp\fR statement is specified if | |
103 | the failover protocol is being used, and indicates what time the peer | |
104 | has been told the lease expires. The \fBtsfp\fR statement is | |
105 | also specified if the failover protocol is being used, and indicates | |
d4d2c475 JR |
106 | the lease expiry time that the peer has acknowledged. |
107 | The \fBatsfp\fR statement is the actual time sent from the failover | |
108 | partner. | |
109 | The \fBcltt\fR statement is the client's last transaction time. | |
110 | The \fIdate\fR is specified as follows: | |
eb4b6456 | 111 | .PP |
b276ad75 | 112 | .I weekday year\fB/\fImonth\fB/\fIday hour\fB:\fIminute\fB:\fIsecond\fR |
eb4b6456 TL |
113 | .PP |
114 | The weekday is present to make it easy for a human to tell when a | |
115 | lease expires - it's specified as a number from zero to six, with zero | |
45d5370c TL |
116 | being Sunday. The day of week is ignored on input. The year is |
117 | specified with the century, so it should generally be four digits | |
118 | except for really long leases. The month is specified as a number | |
119 | starting with 1 for January. The day of the month is likewise | |
120 | specified starting with 1. The hour is a number between 0 and 23, the | |
121 | minute a number between 0 and 59, and the second also a number between | |
122 | 0 and 59. | |
123 | .PP | |
b276ad75 TL |
124 | Lease times are specified in Universal Coordinated Time (UTC), not in |
125 | the local time zone. There is probably nowhere in the world where the | |
126 | times recorded on a lease are always the same as wall clock times. On | |
127 | most unix machines, you can display the current time in UTC by typing | |
128 | \fBdate -u\fR. | |
129 | .PP | |
130 | If a lease will never expire, \fIdate\fR is \fBnever\fR instead of an | |
131 | actual date. | |
132 | .PP | |
133 | .B hardware \fIhardware-type mac-address\fB;\fR | |
134 | .PP | |
135 | The hardware statement records the MAC address of the network | |
136 | interface on which the lease will be used. It is specified as a | |
98311e4b | 137 | series of hexadecimal octets, separated by colons. |
b276ad75 TL |
138 | .PP |
139 | .B uid \fIclient-identifier\fB;\fR | |
140 | .PP | |
141 | The \fBuid\fR statement records the client identifier used by the | |
142 | client to acquire the lease. Clients are not required to send client | |
143 | identifiers, and this statement only appears if the client did in fact | |
144 | send one. Client identifiers are normally an ARP type (1 for | |
145 | ethernet) followed by the MAC address, just like in the \fBhardware\fI | |
146 | statement, but this is not required. | |
147 | .PP | |
98311e4b | 148 | The client identifier is recorded as a colon-separated hexadecimal |
08a51b98 TL |
149 | list or as a quoted string. If it is recorded as a quoted string and |
150 | it contains one or more non-printable characters, those characters are | |
151 | represented as octal escapes - a backslash character followed by three | |
152 | octal digits. | |
eb4b6456 | 153 | .PP |
b276ad75 | 154 | .B client-hostname "\fIhostname\fB";\fR |
eb4b6456 | 155 | .PP |
b276ad75 TL |
156 | Most DHCP clients will send their hostname in the \fIhost-name\fR |
157 | option. If a client sends its hostname in this way, the hostname is | |
158 | recorded on the lease with a \fBclient-hostname\fR statement. This | |
159 | is not required by the protocol, however, so many specialized DHCP | |
160 | clients do not send a host-name option. | |
eb4b6456 | 161 | .PP |
b276ad75 | 162 | .B abandoned; |
eb4b6456 | 163 | .PP |
b276ad75 TL |
164 | The \fBabandoned\fR statement indicates that the DHCP server has |
165 | abandoned the lease. In that case, the \fBabandoned\fR statement | |
166 | will be used to indicate that the lease should not be reassigned. | |
167 | Please see the \fBdhcpd.conf(5)\fR manual page for information about | |
168 | abandoned leases. | |
eb4b6456 | 169 | .PP |
b276ad75 TL |
170 | .B binding state \fIstate\fB; |
171 | .B next binding state \fIstate\fB; | |
eb4b6456 | 172 | .PP |
b276ad75 TL |
173 | The \fBbinding state\fR statement declares the lease's binding state. |
174 | When the DHCP server is not configured to use the failover protocol, a | |
175 | lease's binding state will be either \fBactive\fR or \fBfree\fR. The | |
176 | failover protocol adds some additional transitional states, as well as | |
177 | the \fBbackup\fR state, which indicates that the lease is available | |
178 | for allocation by the failover secondary. | |
eb4b6456 | 179 | .PP |
b276ad75 TL |
180 | The \fBnext binding state\fR statement indicates what state the lease |
181 | will move to when the current state expires. The time when the | |
182 | current state expires is specified in the \fIends\fR statement. | |
eb4b6456 | 183 | .PP |
b276ad75 TL |
184 | .B option agent.circuit-id \fIstring\fR; |
185 | .B option agent.remote-id \fIstring\fR; | |
eb4b6456 | 186 | .PP |
b276ad75 TL |
187 | The \fBoption agent.circuit-id\fR and \fBoption agent.remote-id\fR |
188 | statements are used to record the circuit ID and remote ID options | |
189 | send by the relay agent, if the relay agent uses the \fIrelay agent | |
190 | information option\fR. This allows these options to be used | |
191 | consistently in conditional evaluations even when the client is | |
192 | contacting the server directly rather than through its relay agent. | |
eb4b6456 | 193 | .PP |
b276ad75 | 194 | .B set \fIvariable\fB = \fIvalue\fB; |
eb4b6456 | 195 | .PP |
b276ad75 TL |
196 | The \fBset\fR statement sets the value of a variable on the lease. |
197 | For general information on variables, see the \fBdhcp-eval(5)\fR | |
198 | manual page. | |
eb4b6456 | 199 | .PP |
b276ad75 | 200 | .B The \fIddns-text\fB variable |
45d5370c | 201 | .PP |
b276ad75 TL |
202 | The \fIddns-text\fR variable is used to record the value of the |
203 | client's TXT identification record when the interim ddns update | |
204 | style has been used to update the DNS for a particular lease. | |
205 | .PP | |
206 | .B The \fIddns-fwd-name\fB variable | |
207 | .PP | |
208 | The \fIddns-fwd-name\fB variable records the value of the name used in | |
209 | updating the client's A record if a DDNS update has been successfully | |
210 | done by the server. The server may also have used this name to | |
211 | update the client's PTR record. | |
212 | .PP | |
213 | .B The \fIddns-client-fqdn\fB variable | |
214 | .PP | |
215 | If the server is configured to use the interim ddns update style, and | |
216 | is also configured to allow clients to update their own fqdns, and the | |
217 | client did in fact update its own fqdn, then the | |
218 | \fIddns-client-fqdn\fR variable records the name that the client has | |
219 | indicated it is using. This is the name that the server will have | |
220 | used to update the client's PTR record in this case. | |
221 | .PP | |
222 | .B The \fIddns-rev-name\fB variable | |
223 | .PP | |
224 | If the server successfully updates the client's PTR record, this | |
225 | variable will record the name that the DHCP server used for the PTR | |
226 | record. The name to which the PTR record points will be either the | |
227 | \fIddns-fwd-name\fR or the \fIddns-client-fqdn\fR. | |
228 | .PP | |
229 | .B on \fIevents\fB { \fIstatements...\fB } | |
230 | The \fBon\fI statement records a list of statements to execute if a | |
231 | certain event occurs. The possible events that can occur for an | |
232 | active lease are \fBrelease\fR and \fBexpiry\fR. More than one event | |
98311e4b | 233 | can be specified - if so, the events are separated by '|' characters. |
1db5e2c0 DH |
234 | .PP |
235 | .B bootp; | |
236 | .B reserved; | |
237 | These two statements are effectively flags. If present, they indicate that | |
238 | the BOOTP and RESERVED failover flags, respectively, should be set. BOOTP | |
239 | and RESERVED dynamic leases are treated differently than normal dynamic leases, | |
240 | as they may only be used by the client to which they are currently allocated. | |
241 | .RE | |
b276ad75 TL |
242 | .SH THE FAILOVER PEER STATE DECLARATION |
243 | The state of any failover peering arrangements is also recorded in the | |
244 | lease file, using the \fBfailover peer\fR statement: | |
245 | .PP | |
246 | .nf | |
247 | .B failover peer "\fIname\fB" state { | |
248 | .B my state \fIstate\fB at \fIdate\fB; | |
249 | .B peer state \fIstate\fB at \fIdate\fB; | |
250 | .B } | |
251 | .fi | |
45d5370c | 252 | .PP |
b276ad75 TL |
253 | The states of the peer named \fIname\fR is being recorded. Both the |
254 | state of the running server (\fBmy state\fR) and the other failover | |
255 | partner (\fIpeer state\fR) are recorded. The following states are | |
256 | possible: \fBunknown-state\fR, \fBpartner-down\fR, \fBnormal\fR, | |
257 | \fBcommunications-interrupted\fR, \fBresolution-interrupted\fR, | |
258 | \fBpotential-conflict\fR, \fBrecover\fR, \fBrecover-done\fR, | |
259 | \fBshutdown\fR, \fBpaused\fR, and \fBstartup\fR. | |
9f3d938c TL |
260 | .B DBDIR/dhcpd.leases |
261 | .SH SEE ALSO | |
b276ad75 | 262 | dhcpd(8), dhcp-options(5), dhcp-eval(5), dhcpd.conf(5), RFC2132, RFC2131. |
9f3d938c TL |
263 | .SH AUTHOR |
264 | .B dhcpd(8) | |
98311e4b | 265 | was written by Ted Lemon |
9f3d938c | 266 | under a contract with Vixie Labs. Funding |
98311e4b DH |
267 | for this project was provided by Internet Systems Consortium. |
268 | Information about Internet Systems Consortium can be found at: | |
43d5ca99 | 269 | .B http://www.isc.org/ |