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