]>
Commit | Line | Data |
---|---|---|
08fe7cdb TL |
1 | .\" dhcpd.conf.5 |
2 | .\" | |
49a7fb58 | 3 | .\" Copyright (C) 2004-2022 Internet Systems Consortium, Inc. ("ISC") |
98311e4b | 4 | .\" Copyright (c) 1996-2003 by Internet Software Consortium |
08fe7cdb | 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/. | |
08fe7cdb | 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. | |
08fe7cdb | 17 | .\" |
98311e4b | 18 | .\" Internet Systems Consortium, Inc. |
429a56d7 TM |
19 | .\" PO Box 360 |
20 | .\" Newmarket, NH 03857 USA | |
98311e4b | 21 | .\" <info@isc.org> |
2c85ac9b | 22 | .\" https://www.isc.org/ |
98311e4b DH |
23 | .\" |
24 | .\" This software has been written for Internet Systems Consortium | |
69c620f2 | 25 | .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc. |
f49473ba | 26 | .\" |
5a38e43f SR |
27 | .\" Support and other services are available for ISC products - see |
28 | .\" https://www.isc.org for more information or to learn more about ISC. | |
29 | .\" | |
6f1a6f94 | 30 | .\" $Id: dhcpd.conf.5,v 1.114 2012/04/02 22:47:35 sar Exp $ |
f49473ba | 31 | .\" |
5e6b52dc | 32 | .TH dhcpd.conf 5 |
d250c5b9 TL |
33 | .SH NAME |
34 | dhcpd.conf - dhcpd configuration file | |
35 | .SH DESCRIPTION | |
36 | The dhcpd.conf file contains configuration information for | |
5e6b52dc | 37 | .IR dhcpd, |
98311e4b | 38 | the Internet Systems Consortium DHCP Server. |
5e6b52dc | 39 | .PP |
a0497ac5 SR |
40 | The dhcpd.conf file is a free-form ASCII text file. It is parsed by |
41 | the recursive-descent parser built into dhcpd. The file may contain | |
5e6b52dc | 42 | extra tabs and newlines for formatting purposes. Keywords in the file |
a0497ac5 SR |
43 | are case-insensitive. Comments may be placed anywhere within the |
44 | file (except within quotes). Comments begin with the # character and | |
5e6b52dc TL |
45 | end at the end of the line. |
46 | .PP | |
a0497ac5 | 47 | The file essentially consists of a list of statements. Statements |
5e6b52dc TL |
48 | fall into two broad categories - parameters and declarations. |
49 | .PP | |
50 | Parameter statements either say how to do something (e.g., how long a | |
51 | lease to offer), whether to do something (e.g., should dhcpd provide | |
52 | addresses to unknown clients), or what parameters to provide to the | |
53 | client (e.g., use gateway 220.177.244.7). | |
54 | .PP | |
55 | Declarations are used to describe the topology of the | |
56 | network, to describe clients on the network, to provide addresses that | |
57 | can be assigned to clients, or to apply a group of parameters to a | |
a0497ac5 | 58 | group of declarations. In any group of parameters and declarations, |
5e6b52dc TL |
59 | all parameters must be specified before any declarations which depend |
60 | on those parameters may be specified. | |
61 | .PP | |
98311e4b | 62 | Declarations about network topology include the \fIshared-network\fR |
a0497ac5 | 63 | and the \fIsubnet\fR declarations. If clients on a subnet are to be |
98311e4b | 64 | assigned addresses |
5e6b52dc | 65 | dynamically, a \fIrange\fR declaration must appear within the |
a0497ac5 | 66 | \fIsubnet\fR declaration. For clients with statically assigned |
5e6b52dc | 67 | addresses, or for installations where only known clients will be |
a0497ac5 | 68 | served, each such client must have a \fIhost\fR declaration. If |
5e6b52dc TL |
69 | parameters are to be applied to a group of declarations which are not |
70 | related strictly on a per-subnet basis, the \fIgroup\fR declaration | |
71 | can be used. | |
72 | .PP | |
612bc350 | 73 | For every subnet which will be served, and for every subnet |
73eaf823 TL |
74 | to which the dhcp server is connected, there must be one \fIsubnet\fR |
75 | declaration, which tells dhcpd how to recognize that an address is on | |
76 | that subnet. A \fIsubnet\fR declaration is required for each subnet | |
77 | even if no addresses will be dynamically allocated on that subnet. | |
5e6b52dc TL |
78 | .PP |
79 | Some installations have physical networks on which more than one IP | |
a0497ac5 | 80 | subnet operates. For example, if there is a site-wide requirement |
5e6b52dc TL |
81 | that 8-bit subnet masks be used, but a department with a single |
82 | physical ethernet network expands to the point where it has more than | |
83 | 254 nodes, it may be necessary to run two 8-bit subnets on the same | |
a0497ac5 | 84 | ethernet until such time as a new physical network can be added. In |
b8f73859 | 85 | this case, the \fIsubnet\fR declarations for these two networks must be |
5e6b52dc TL |
86 | enclosed in a \fIshared-network\fR declaration. |
87 | .PP | |
7d6180be DH |
88 | Note that even when the \fIshared-network\fR declaration is absent, an |
89 | empty one is created by the server to contain the \fIsubnet\fR (and any scoped | |
90 | parameters included in the \fIsubnet\fR). For practical purposes, this means | |
91 | that "stateless" DHCP clients, which are not tied to addresses (and therefore | |
92 | subnets) will receive the same configuration as stateful ones. | |
93 | .PP | |
5e6b52dc TL |
94 | Some sites may have departments which have clients on more than one |
95 | subnet, but it may be desirable to offer those clients a uniform set | |
96 | of parameters which are different than what would be offered to | |
a0497ac5 | 97 | clients from other departments on the same subnet. For clients which |
5e6b52dc TL |
98 | will be declared explicitly with \fIhost\fR declarations, these |
99 | declarations can be enclosed in a \fIgroup\fR declaration along with | |
a0497ac5 | 100 | the parameters which are common to that department. For clients |
49f6028f TL |
101 | whose addresses will be dynamically assigned, class declarations and |
102 | conditional declarations may be used to group parameter assignments | |
103 | based on information the client sends. | |
5e6b52dc TL |
104 | .PP |
105 | When a client is to be booted, its boot parameters are determined by | |
49f6028f | 106 | consulting that client's \fIhost\fR declaration (if any), and then |
9f8b2a7f | 107 | consulting any \fIclass\fR declarations matching the client, |
49f6028f | 108 | followed by the \fIpool\fR, \fIsubnet\fR and \fIshared-network\fR |
a0497ac5 | 109 | declarations for the IP address assigned to the client. Each of |
49f6028f TL |
110 | these declarations itself appears within a lexical scope, and all |
111 | declarations at less specific lexical scopes are also consulted for | |
a0497ac5 | 112 | client option declarations. Scopes are never considered |
49f6028f TL |
113 | twice, and if parameters are declared in more than one scope, the |
114 | parameter declared in the most specific scope is the one that is | |
115 | used. | |
5e6b52dc TL |
116 | .PP |
117 | When dhcpd tries to find a \fIhost\fR declaration for a client, it | |
118 | first looks for a \fIhost\fR declaration which has a | |
98311e4b | 119 | \fIfixed-address\fR declaration that lists an IP address that is valid |
a0497ac5 | 120 | for the subnet or shared network on which the client is booting. If |
98311e4b DH |
121 | it doesn't find any such entry, it tries to find an entry which has |
122 | no \fIfixed-address\fR declaration. | |
5e6b52dc TL |
123 | .SH EXAMPLES |
124 | .PP | |
125 | A typical dhcpd.conf file will look something like this: | |
126 | .nf | |
127 | ||
5e6b52dc TL |
128 | .I global parameters... |
129 | ||
d9dc2726 TL |
130 | subnet 204.254.239.0 netmask 255.255.255.224 { |
131 | \fIsubnet-specific parameters...\fR | |
132 | range 204.254.239.10 204.254.239.30; | |
133 | } | |
134 | ||
135 | subnet 204.254.239.32 netmask 255.255.255.224 { | |
136 | \fIsubnet-specific parameters...\fR | |
137 | range 204.254.239.42 204.254.239.62; | |
5e6b52dc TL |
138 | } |
139 | ||
140 | subnet 204.254.239.64 netmask 255.255.255.224 { | |
141 | \fIsubnet-specific parameters...\fR | |
142 | range 204.254.239.74 204.254.239.94; | |
143 | } | |
144 | ||
145 | group { | |
146 | \fIgroup-specific parameters...\fR | |
147 | host zappo.test.isc.org { | |
148 | \fIhost-specific parameters...\fR | |
149 | } | |
150 | host beppo.test.isc.org { | |
151 | \fIhost-specific parameters...\fR | |
152 | } | |
153 | host harpo.test.isc.org { | |
154 | \fIhost-specific parameters...\fR | |
155 | } | |
156 | } | |
157 | ||
158 | .ce 1 | |
159 | Figure 1 | |
160 | ||
161 | .fi | |
d250c5b9 | 162 | .PP |
612bc350 | 163 | Notice that at the beginning of the file, there's a place |
a0497ac5 | 164 | for global parameters. These might be things like the organization's |
5e6b52dc | 165 | domain name, the addresses of the name servers (if they are common to |
a0497ac5 | 166 | the entire organization), and so on. So, for example: |
5e6b52dc TL |
167 | .nf |
168 | ||
169 | option domain-name "isc.org"; | |
ee31d992 | 170 | option domain-name-servers ns1.isc.org, ns2.isc.org; |
5e6b52dc TL |
171 | |
172 | .ce 1 | |
173 | Figure 2 | |
174 | .fi | |
d250c5b9 | 175 | .PP |
d9dc2726 TL |
176 | As you can see in Figure 2, you can specify host addresses in |
177 | parameters using their domain names rather than their numeric IP | |
178 | addresses. If a given hostname resolves to more than one IP address | |
179 | (for example, if that host has two ethernet interfaces), then where | |
180 | possible, both addresses are supplied to the client. | |
47c9ea95 | 181 | .PP |
5e6b52dc TL |
182 | The most obvious reason for having subnet-specific parameters as |
183 | shown in Figure 1 is that each subnet, of necessity, has its own | |
a0497ac5 | 184 | router. So for the first subnet, for example, there should be |
5e6b52dc TL |
185 | something like: |
186 | .nf | |
187 | ||
188 | option routers 204.254.239.1; | |
189 | .fi | |
d250c5b9 | 190 | .PP |
a0497ac5 | 191 | Note that the address here is specified numerically. This is not |
5e6b52dc TL |
192 | required - if you have a different domain name for each interface on |
193 | your router, it's perfectly legitimate to use the domain name for that | |
a0497ac5 | 194 | interface instead of the numeric address. However, in many cases |
5e6b52dc TL |
195 | there may be only one domain name for all of a router's IP addresses, and |
196 | it would not be appropriate to use that name here. | |
197 | .PP | |
198 | In Figure 1 there is also a \fIgroup\fR statement, which provides | |
199 | common parameters for a set of three hosts - zappo, beppo and harpo. | |
200 | As you can see, these hosts are all in the test.isc.org domain, so it | |
201 | might make sense for a group-specific parameter to override the domain | |
202 | name supplied to these hosts: | |
203 | .nf | |
204 | ||
205 | option domain-name "test.isc.org"; | |
206 | .fi | |
207 | .PP | |
208 | Also, given the domain they're in, these are probably test machines. | |
209 | If we wanted to test the DHCP leasing mechanism, we might set the | |
210 | lease timeout somewhat shorter than the default: | |
211 | ||
212 | .nf | |
213 | max-lease-time 120; | |
214 | default-lease-time 120; | |
215 | .fi | |
d250c5b9 | 216 | .PP |
5e6b52dc | 217 | You may have noticed that while some parameters start with the |
a0497ac5 | 218 | \fIoption\fR keyword, some do not. Parameters starting with the |
5e6b52dc TL |
219 | \fIoption\fR keyword correspond to actual DHCP options, while |
220 | parameters that do not start with the option keyword either control | |
9f8b2a7f | 221 | the behavior of the DHCP server (e.g., how long a lease dhcpd will |
5e6b52dc TL |
222 | give out), or specify client parameters that are not optional in the |
223 | DHCP protocol (for example, server-name and filename). | |
224 | .PP | |
a0497ac5 | 225 | In Figure 1, each host had \fIhost-specific parameters\fR. These |
5e6b52dc | 226 | could include such things as the \fIhostname\fR option, the name of a |
98311e4b | 227 | file to upload (the \fIfilename\fR parameter) and the address of the |
5e6b52dc | 228 | server from which to upload the file (the \fInext-server\fR |
a0497ac5 | 229 | parameter). In general, any parameter can appear anywhere that |
5e6b52dc TL |
230 | parameters are allowed, and will be applied according to the scope in |
231 | which the parameter appears. | |
232 | .PP | |
a0497ac5 | 233 | Imagine that you have a site with a lot of NCD X-Terminals. These |
5e6b52dc | 234 | terminals come in a variety of models, and you want to specify the |
a0497ac5 | 235 | boot files for each model. One way to do this would be to have host |
5e6b52dc TL |
236 | declarations for each server and group them by model: |
237 | .nf | |
238 | ||
239 | group { | |
240 | filename "Xncd19r"; | |
241 | next-server ncd-booter; | |
242 | ||
243 | host ncd1 { hardware ethernet 0:c0:c3:49:2b:57; } | |
244 | host ncd4 { hardware ethernet 0:c0:c3:80:fc:32; } | |
245 | host ncd8 { hardware ethernet 0:c0:c3:22:46:81; } | |
246 | } | |
247 | ||
248 | group { | |
249 | filename "Xncd19c"; | |
250 | next-server ncd-booter; | |
251 | ||
252 | host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; } | |
253 | host ncd3 { hardware ethernet 0:c0:c3:00:14:11; } | |
254 | } | |
255 | ||
256 | group { | |
257 | filename "XncdHMX"; | |
258 | next-server ncd-booter; | |
259 | ||
260 | host ncd1 { hardware ethernet 0:c0:c3:11:90:23; } | |
261 | host ncd4 { hardware ethernet 0:c0:c3:91:a7:8; } | |
262 | host ncd8 { hardware ethernet 0:c0:c3:cc:a:8f; } | |
263 | } | |
264 | .fi | |
d9dc2726 TL |
265 | .SH ADDRESS POOLS |
266 | .PP | |
267 | The | |
01fa619f SR |
268 | \fBpool\fR and \fBpool6\fR |
269 | declarations can be used to specify a pool of addresses that will be | |
d9dc2726 | 270 | treated differently than another pool of addresses, even on the same |
a0497ac5 | 271 | network segment or subnet. For example, you may want to provide a |
d9dc2726 TL |
272 | large set of addresses that can be assigned to DHCP clients that are |
273 | registered to your DHCP server, while providing a smaller set of | |
274 | addresses, possibly with short lease times, that are available for | |
a0497ac5 | 275 | unknown clients. If you have a firewall, you may be able to arrange |
d9dc2726 TL |
276 | for addresses from one pool to be allowed access to the Internet, |
277 | while addresses in another pool are not, thus encouraging users to | |
a0497ac5 | 278 | register their DHCP clients. To do this, you would set up a pair of |
d9dc2726 TL |
279 | pool declarations: |
280 | .PP | |
281 | .nf | |
282 | subnet 10.0.0.0 netmask 255.255.255.0 { | |
283 | option routers 10.0.0.254; | |
284 | ||
285 | # Unknown clients get this pool. | |
286 | pool { | |
287 | option domain-name-servers bogus.example.com; | |
288 | max-lease-time 300; | |
289 | range 10.0.0.200 10.0.0.253; | |
98311e4b | 290 | allow unknown-clients; |
d9dc2726 TL |
291 | } |
292 | ||
293 | # Known clients get this pool. | |
294 | pool { | |
295 | option domain-name-servers ns1.example.com, ns2.example.com; | |
296 | max-lease-time 28800; | |
297 | range 10.0.0.5 10.0.0.199; | |
98311e4b | 298 | deny unknown-clients; |
d9dc2726 TL |
299 | } |
300 | } | |
301 | .fi | |
302 | .PP | |
303 | It is also possible to set up entirely different subnets for known and | |
304 | unknown clients - address pools exist at the level of shared networks, | |
305 | so address ranges within pool declarations can be on different | |
306 | subnets. | |
1a67a4d7 TL |
307 | .PP |
308 | As you can see in the preceding example, pools can have permit lists | |
309 | that control which clients are allowed access to the pool and which | |
310 | aren't. Each entry in a pool's permit list is introduced with the | |
311 | .I allow | |
a0497ac5 | 312 | or \fIdeny\fR keyword. If a pool has a permit list, then only those |
1a67a4d7 | 313 | clients that match specific entries on the permit list will be |
a0497ac5 | 314 | eligible to be assigned addresses from the pool. If a pool has a |
1a67a4d7 | 315 | deny list, then only those clients that do not match any entries on |
a0497ac5 | 316 | the deny list will be eligible. If both permit and deny lists exist |
1a67a4d7 TL |
317 | for a pool, then only clients that match the permit list and do not |
318 | match the deny list will be allowed access. | |
01fa619f | 319 | .PP |
81437269 | 320 | The \fBpool6\fR declaration is similar to the \fBpool\fR declaration. |
01fa619f SR |
321 | Currently it is only allowed within a \fBsubnet6\fR declaration, and |
322 | may not be included directly in a shared network declaration. | |
323 | In addition to the \fBrange6\fR statement it allows the \fBprefix6\fR | |
324 | statement to be included. You may include \fBrange6\fR statements | |
26243975 | 325 | for both NA and TA and \fBprefix6\fR statements in a single |
01fa619f | 326 | \fBpool6\fR statement. |
0295cbac | 327 | .SH DYNAMIC ADDRESS ALLOCATION |
1a67a4d7 TL |
328 | Address allocation is actually only done when a client is in the INIT |
329 | state and has sent a DHCPDISCOVER message. If the client thinks it | |
330 | has a valid lease and sends a DHCPREQUEST to initiate or renew that | |
331 | lease, the server has only three choices - it can ignore the | |
332 | DHCPREQUEST, send a DHCPNAK to tell the client it should stop using | |
333 | the address, or send a DHCPACK, telling the client to go ahead and use | |
0295cbac TL |
334 | the address for a while. |
335 | .PP | |
336 | If the server finds the address the client is requesting, and that | |
337 | address is available to the client, the server will send a DHCPACK. | |
338 | If the address is no longer available, or the client isn't permitted | |
339 | to have it, the server will send a DHCPNAK. If the server knows | |
9f8b2a7f TL |
340 | nothing about the address, it will remain silent, unless the address |
341 | is incorrect for the network segment to which the client has been | |
0295cbac TL |
342 | attached and the server is authoritative for that network segment, in |
343 | which case the server will send a DHCPNAK even though it doesn't know | |
344 | about the address. | |
345 | .PP | |
98311e4b | 346 | There may be a host declaration matching the client's identification. |
417b7b4a | 347 | If that host declaration contains a fixed-address declaration that |
98311e4b | 348 | lists an IP address that is valid for the network segment to which the |
f54a146c TM |
349 | client is connected, the DHCP server will never do dynamic address allocation. |
350 | In this case, the client is \fIrequired\fR to take the address specified | |
351 | in the host declaration. If the client sends a DHCPREQUEST for some other | |
352 | address, the server will respond with a DHCPNAK. | |
1a67a4d7 TL |
353 | .PP |
354 | When the DHCP server allocates a new address for a client (remember, | |
355 | this only happens if the client has sent a DHCPDISCOVER), it first | |
356 | looks to see if the client already has a valid lease on an IP address, | |
357 | or if there is an old IP address the client had before that hasn't yet | |
358 | been reassigned. In that case, the server will take that address and | |
359 | check it to see if the client is still permitted to use it. If the | |
360 | client is no longer permitted to use it, the lease is freed if the | |
361 | server thought it was still in use - the fact that the client has sent | |
362 | a DHCPDISCOVER proves to the server that the client is no longer using | |
363 | the lease. | |
364 | .PP | |
365 | If no existing lease is found, or if the client is forbidden to | |
366 | receive the existing lease, then the server will look in the list of | |
367 | address pools for the network segment to which the client is attached | |
368 | for a lease that is not in use and that the client is permitted to | |
a0497ac5 | 369 | have. It looks through each pool declaration in sequence (all |
1a67a4d7 TL |
370 | .I range |
371 | declarations that appear outside of pool declarations are grouped into | |
a0497ac5 | 372 | a single pool with no permit list). If the permit list for the pool |
1a67a4d7 | 373 | allows the client to be allocated an address from that pool, the pool |
a0497ac5 SR |
374 | is examined to see if there is an address available. If so, then the |
375 | client is tentatively assigned that address. Otherwise, the next | |
376 | pool is tested. If no addresses are found that can be assigned to | |
1a67a4d7 TL |
377 | the client, no response is sent to the client. |
378 | .PP | |
379 | If an address is found that the client is permitted to have, and that | |
380 | has never been assigned to any client before, the address is | |
a0497ac5 | 381 | immediately allocated to the client. If the address is available for |
1a67a4d7 TL |
382 | allocation but has been previously assigned to a different client, the |
383 | server will keep looking in hopes of finding an address that has never | |
384 | before been assigned to a client. | |
98311e4b DH |
385 | .PP |
386 | The DHCP server generates the list of available IP addresses from a | |
a0497ac5 | 387 | hash table. This means that the addresses are not sorted in any |
98311e4b | 388 | particular order, and so it is not possible to predict the order in |
a0497ac5 | 389 | which the DHCP server will allocate IP addresses. Users of previous |
98311e4b DH |
390 | versions of the ISC DHCP server may have become accustomed to the DHCP |
391 | server allocating IP addresses in ascending order, but this is no | |
392 | longer possible, and there is no way to configure this behavior with | |
393 | version 3 of the ISC DHCP server. | |
3c807354 | 394 | .SH IP ADDRESS CONFLICT PREVENTION |
a25a18d7 | 395 | The DHCP server checks IP addresses to see if they are in use before |
a0497ac5 SR |
396 | allocating them to clients. It does this by sending an ICMP Echo |
397 | request message to the IP address being allocated. If no ICMP Echo | |
a25a18d7 TL |
398 | reply is received within a second, the address is assumed to be free. |
399 | This is only done for leases that have been specified in range | |
400 | statements, and only when the lease is thought by the DHCP server to | |
401 | be free - i.e., the DHCP server or its failover peer has not listed | |
402 | the lease as in use. | |
403 | .PP | |
404 | If a response is received to an ICMP Echo request, the DHCP server | |
405 | assumes that there is a configuration error - the IP address is in use | |
a0497ac5 | 406 | by some host on the network that is not a DHCP client. It marks the |
a5252220 TM |
407 | address as abandoned, and will not assign it to clients. The lease will |
408 | remain abandoned for a minimum of abandon-lease-time seconds. | |
a25a18d7 TL |
409 | .PP |
410 | If a DHCP client tries to get an IP address, but none are available, | |
411 | but there are abandoned IP addresses, then the DHCP server will | |
a0497ac5 | 412 | attempt to reclaim an abandoned IP address. It marks one IP address |
a25a18d7 | 413 | as free, and then does the same ICMP Echo request check described |
a0497ac5 | 414 | previously. If there is no answer to the ICMP Echo request, the |
a25a18d7 TL |
415 | address is assigned to the client. |
416 | .PP | |
417 | The DHCP server does not cycle through abandoned IP addresses if the | |
a0497ac5 | 418 | first IP address it tries to reclaim is free. Rather, when the next |
a25a18d7 TL |
419 | DHCPDISCOVER comes in from the client, it will attempt a new |
420 | allocation using the same method described here, and will typically | |
421 | try a new IP address. | |
59d36179 TL |
422 | .SH DHCP FAILOVER |
423 | This version of the ISC DHCP server supports the DHCP failover | |
a0497ac5 | 424 | protocol as documented in draft-ietf-dhc-failover-12.txt. This is |
59d36179 TL |
425 | not a final protocol document, and we have not done interoperability |
426 | testing with other vendors' implementations of this protocol, so you | |
427 | must not assume that this implementation conforms to the standard. | |
428 | If you wish to use the failover protocol, make sure that both failover | |
429 | peers are running the same version of the ISC DHCP server. | |
430 | .PP | |
431 | The failover protocol allows two DHCP servers (and no more than two) | |
a0497ac5 | 432 | to share a common address pool. Each server will have about half of |
59d36179 | 433 | the available IP addresses in the pool at any given time for |
a0497ac5 | 434 | allocation. If one server fails, the other server will continue to |
59d36179 TL |
435 | renew leases out of the pool, and will allocate new addresses out of |
436 | the roughly half of available addresses that it had when | |
437 | communications with the other server were lost. | |
438 | .PP | |
439 | It is possible during a prolonged failure to tell the remaining server | |
440 | that the other server is down, in which case the remaining server will | |
441 | (over time) reclaim all the addresses the other server had available | |
a0497ac5 | 442 | for allocation, and begin to reuse them. This is called putting the |
59d36179 TL |
443 | server into the PARTNER-DOWN state. |
444 | .PP | |
8100bfb0 | 445 | You can put the server into the PARTNER-DOWN state either by using the |
98311e4b | 446 | .B omshell (1) |
29728510 | 447 | command or by stopping the server, editing the last failover state |
a0497ac5 | 448 | declaration in the lease file, and restarting the server. If you use |
29728510 | 449 | this last method, change the "my state" line to: |
8100bfb0 TL |
450 | .PP |
451 | .nf | |
452 | .B failover peer "\fIname\fB" state { | |
01fa619f | 453 | .B my state partner-down;. |
8100bfb0 TL |
454 | .B peer state \fIstate\fB at \fIdate\fB; |
455 | .B } | |
456 | .fi | |
457 | .PP | |
29728510 JR |
458 | It is only required to change "my state" as shown above. |
459 | .PP | |
59d36179 TL |
460 | When the other server comes back online, it should automatically |
461 | detect that it has been offline and request a complete update from the | |
462 | server that was running in the PARTNER-DOWN state, and then both | |
463 | servers will resume processing together. | |
464 | .PP | |
465 | It is possible to get into a dangerous situation: if you put one | |
466 | server into the PARTNER-DOWN state, and then *that* server goes down, | |
467 | and the other server comes back up, the other server will not know | |
468 | that the first server was in the PARTNER-DOWN state, and may issue | |
469 | addresses previously issued by the other server to different clients, | |
a0497ac5 | 470 | resulting in IP address conflicts. Before putting a server into |
59d36179 TL |
471 | PARTNER-DOWN state, therefore, make |
472 | .I sure | |
473 | that the other server will not restart automatically. | |
474 | .PP | |
475 | The failover protocol defines a primary server role and a secondary | |
a0497ac5 | 476 | server role. There are some differences in how primaries and |
59d36179 TL |
477 | secondaries act, but most of the differences simply have to do with |
478 | providing a way for each peer to behave in the opposite way from the | |
a0497ac5 | 479 | other. So one server must be configured as primary, and the other |
59d36179 TL |
480 | must be configured as secondary, and it doesn't matter too much which |
481 | one is which. | |
90e0ef94 TL |
482 | .SH FAILOVER STARTUP |
483 | When a server starts that has not previously communicated with its | |
484 | failover peer, it must establish communications with its failover peer | |
a0497ac5 | 485 | and synchronize with it before it can serve clients. This can happen |
90e0ef94 TL |
486 | either because you have just configured your DHCP servers to perform |
487 | failover for the first time, or because one of your failover servers | |
488 | has failed catastrophically and lost its database. | |
489 | .PP | |
490 | The initial recovery process is designed to ensure that when one | |
491 | failover peer loses its database and then resynchronizes, any leases | |
492 | that the failed server gave out before it failed will be honored. | |
493 | When the failed server starts up, it notices that it has no saved | |
494 | failover state, and attempts to contact its peer. | |
495 | .PP | |
496 | When it has established contact, it asks the peer for a complete copy | |
497 | its peer's lease database. The peer then sends its complete database, | |
498 | and sends a message indicating that it is done. The failed server | |
499 | then waits until MCLT has passed, and once MCLT has passed both | |
500 | servers make the transition back into normal operation. This waiting | |
501 | period ensures that any leases the failed server may have given out | |
502 | while out of contact with its partner will have expired. | |
503 | .PP | |
504 | While the failed server is recovering, its partner remains in the | |
505 | partner-down state, which means that it is serving all clients. The | |
506 | failed server provides no service at all to DHCP clients until it has | |
507 | made the transition into normal operation. | |
508 | .PP | |
509 | In the case where both servers detect that they have never before | |
510 | communicated with their partner, they both come up in this recovery | |
a0497ac5 | 511 | state and follow the procedure we have just described. In this case, |
90e0ef94 | 512 | no service will be provided to DHCP clients until MCLT has expired. |
59d36179 TL |
513 | .SH CONFIGURING FAILOVER |
514 | In order to configure failover, you need to write a peer declaration | |
515 | that configures the failover protocol, and you need to write peer | |
516 | references in each pool declaration for which you want to do | |
a0497ac5 SR |
517 | failover. You do not have to do failover for all pools on a given |
518 | network segment. You must not tell one server it's doing failover | |
519 | on a particular address pool and tell the other it is not. You must | |
59d36179 | 520 | not have any common address pools on which you are not doing |
98311e4b DH |
521 | failover. A pool declaration that utilizes failover would look like this: |
522 | .PP | |
523 | .nf | |
524 | pool { | |
525 | failover peer "foo"; | |
98311e4b DH |
526 | \fIpool specific parameters\fR |
527 | }; | |
528 | .fi | |
529 | .PP | |
59d36179 TL |
530 | The server currently does very little sanity checking, so if you |
531 | configure it wrong, it will just fail in odd ways. I would recommend | |
532 | therefore that you either do failover or don't do failover, but don't | |
533 | do any mixed pools. Also, use the same master configuration file for | |
98311e4b | 534 | both servers, and have a separate file that contains the peer |
59d36179 TL |
535 | declaration and includes the master file. This will help you to avoid |
536 | configuration mismatches. As our implementation evolves, this will | |
537 | become less of a problem. A basic sample dhcpd.conf file for a | |
538 | primary server might look like this: | |
539 | .PP | |
540 | .nf | |
541 | failover peer "foo" { | |
542 | primary; | |
60bba434 | 543 | address anthrax.rc.example.com; |
59d36179 | 544 | port 519; |
60bba434 | 545 | peer address trantor.rc.example.com; |
59d36179 TL |
546 | peer port 520; |
547 | max-response-delay 60; | |
548 | max-unacked-updates 10; | |
549 | mclt 3600; | |
98311e4b | 550 | split 128; |
59d36179 TL |
551 | load balance max seconds 3; |
552 | } | |
553 | ||
554 | include "/etc/dhcpd.master"; | |
555 | .fi | |
556 | .PP | |
557 | The statements in the peer declaration are as follows: | |
558 | .PP | |
417b7b4a | 559 | The |
59d36179 | 560 | .I primary |
3c807354 | 561 | and |
59d36179 | 562 | .I secondary |
3c807354 TL |
563 | statements |
564 | .RS 0.25i | |
59d36179 | 565 | .PP |
3c807354 | 566 | [ \fBprimary\fR | \fBsecondary\fR ]\fB;\fR |
59d36179 TL |
567 | .PP |
568 | This determines whether the server is primary or secondary, as | |
569 | described earlier under DHCP FAILOVER. | |
3c807354 | 570 | .RE |
59d36179 | 571 | .PP |
417b7b4a | 572 | The |
59d36179 | 573 | .I address |
3c807354 TL |
574 | statement |
575 | .RS 0.25i | |
59d36179 | 576 | .PP |
3c807354 | 577 | .B address \fIaddress\fR\fB;\fR |
59d36179 | 578 | .PP |
98311e4b DH |
579 | The \fBaddress\fR statement declares the IP address or DNS name on which the |
580 | server should listen for connections from its failover peer, and also the | |
581 | value to use for the DHCP Failover Protocol server identifier. Because this | |
582 | value is used as an identifier, it may not be omitted. | |
3c807354 | 583 | .RE |
59d36179 | 584 | .PP |
417b7b4a | 585 | The |
59d36179 | 586 | .I peer address |
3c807354 TL |
587 | statement |
588 | .RS 0.25i | |
59d36179 | 589 | .PP |
3c807354 | 590 | .B peer address \fIaddress\fR\fB;\fR |
59d36179 | 591 | .PP |
98311e4b DH |
592 | The \fBpeer address\fR statement declares the IP address or DNS name to |
593 | which the server should connect to reach its failover peer for failover | |
59d36179 | 594 | messages. |
3c807354 | 595 | .RE |
59d36179 | 596 | .PP |
417b7b4a | 597 | The |
59d36179 | 598 | .I port |
3c807354 TL |
599 | statement |
600 | .RS 0.25i | |
59d36179 | 601 | .PP |
3c807354 | 602 | .B port \fIport-number\fR\fB;\fR |
59d36179 TL |
603 | .PP |
604 | The \fBport\fR statement declares the TCP port on which the server | |
d340bc24 DH |
605 | should listen for connections from its failover peer. This statement |
606 | may be omitted, in which case the IANA assigned port number 647 will be | |
607 | used by default. | |
3c807354 | 608 | .RE |
59d36179 | 609 | .PP |
417b7b4a | 610 | The |
59d36179 | 611 | .I peer port |
3c807354 TL |
612 | statement |
613 | .RS 0.25i | |
59d36179 | 614 | .PP |
3c807354 | 615 | .B peer port \fIport-number\fR\fB;\fR |
59d36179 TL |
616 | .PP |
617 | The \fBpeer port\fR statement declares the TCP port to which the | |
618 | server should connect to reach its failover peer for failover | |
d340bc24 DH |
619 | messages. This statement may be omitted, in which case the IANA |
620 | assigned port number 647 will be used by default. | |
3c807354 | 621 | .RE |
59d36179 | 622 | .PP |
2426234f | 623 | The |
59d36179 | 624 | .I max-response-delay |
3c807354 TL |
625 | statement |
626 | .RS 0.25i | |
59d36179 | 627 | .PP |
3c807354 | 628 | .B max-response-delay \fIseconds\fR\fB;\fR |
59d36179 TL |
629 | .PP |
630 | The \fBmax-response-delay\fR statement tells the DHCP server how | |
631 | many seconds may pass without receiving a message from its failover | |
a0497ac5 | 632 | peer before it assumes that connection has failed. This number |
59d36179 TL |
633 | should be small enough that a transient network failure that breaks |
634 | the connection will not result in the servers being out of | |
635 | communication for a long time, but large enough that the server isn't | |
a0497ac5 | 636 | constantly making and breaking connections. This parameter must be |
59d36179 | 637 | specified. |
3c807354 | 638 | .RE |
59d36179 | 639 | .PP |
51c4d3f5 DH |
640 | The |
641 | .I max-unacked-updates | |
642 | statement | |
643 | .RS 0.25i | |
644 | .PP | |
3c807354 | 645 | .B max-unacked-updates \fIcount\fR\fB;\fR |
59d36179 | 646 | .PP |
0f0397ac | 647 | The \fBmax-unacked-updates\fR statement tells the remote DHCP server how |
9f8b2a7f | 648 | many BNDUPD messages it can send before it receives a BNDACK |
a0497ac5 SR |
649 | from the local system. We don't have enough operational experience |
650 | to say what a good value for this is, but 10 seems to work. This | |
59d36179 | 651 | parameter must be specified. |
3c807354 | 652 | .RE |
59d36179 | 653 | .PP |
417b7b4a | 654 | The |
59d36179 | 655 | .I mclt |
3c807354 TL |
656 | statement |
657 | .RS 0.25i | |
59d36179 | 658 | .PP |
3c807354 | 659 | .B mclt \fIseconds\fR\fB;\fR |
59d36179 | 660 | .PP |
a0497ac5 | 661 | The \fBmclt\fR statement defines the Maximum Client Lead Time. It |
59d36179 | 662 | must be specified on the primary, and may not be specified on the |
a0497ac5 SR |
663 | secondary. This is the length of time for which a lease may be |
664 | renewed by either failover peer without contacting the other. The | |
59d36179 | 665 | longer you set this, the longer it will take for the running server to |
a0497ac5 | 666 | recover IP addresses after moving into PARTNER-DOWN state. The |
59d36179 | 667 | shorter you set it, the more load your servers will experience when |
a0497ac5 | 668 | they are not communicating. A value of something like 3600 is |
59d36179 TL |
669 | probably reasonable, but again bear in mind that we have no real |
670 | operational experience with this. | |
3c807354 | 671 | .RE |
59d36179 | 672 | .PP |
417b7b4a | 673 | The |
59d36179 | 674 | .I split |
3c807354 TL |
675 | statement |
676 | .RS 0.25i | |
59d36179 | 677 | .PP |
2a537542 | 678 | .B split \fIbits\fR\fB;\fR |
59d36179 TL |
679 | .PP |
680 | The split statement specifies the split between the primary and | |
a0497ac5 | 681 | secondary for the purposes of load balancing. Whenever a client |
59d36179 | 682 | makes a DHCP request, the DHCP server runs a hash on the client |
2426234f DH |
683 | identification, resulting in value from 0 to 255. This is used as |
684 | an index into a 256 bit field. If the bit at that index is set, | |
685 | the primary is responsible. If the bit at that index is not set, | |
686 | the secondary is responsible. The \fBsplit\fR value determines | |
687 | how many of the leading bits are set to one. So, in practice, higher | |
688 | split values will cause the primary to serve more clients than the | |
689 | secondary. Lower split values, the converse. Legal values are between | |
2a537542 TM |
690 | 0 and 256 inclusive, of which the most reasonable is 128. Note that |
691 | a value of 0 makes the secondary responsible for all clients and a value | |
692 | of 256 makes the primary responsible for all clients. | |
3c807354 | 693 | .RE |
59d36179 | 694 | .PP |
417b7b4a | 695 | The |
59d36179 | 696 | .I hba |
3c807354 TL |
697 | statement |
698 | .RS 0.25i | |
59d36179 | 699 | .PP |
98311e4b | 700 | .B hba \fIcolon-separated-hex-list\fB;\fR |
59d36179 TL |
701 | .PP |
702 | The hba statement specifies the split between the primary and | |
703 | secondary as a bitmap rather than a cutoff, which theoretically allows | |
a0497ac5 SR |
704 | for finer-grained control. In practice, there is probably no need |
705 | for such fine-grained control, however. An example hba statement: | |
59d36179 TL |
706 | .PP |
707 | .nf | |
708 | hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff: | |
709 | 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00; | |
710 | .fi | |
98311e4b | 711 | .PP |
2426234f | 712 | This is equivalent to a \fBsplit 128;\fR statement, and identical. The |
417b7b4a | 713 | following two examples are also equivalent to a \fBsplit\fR of 128, but |
2426234f DH |
714 | are not identical: |
715 | .PP | |
716 | .nf | |
717 | hba aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa: | |
718 | aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa; | |
719 | ||
720 | hba 55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55: | |
721 | 55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55; | |
722 | .fi | |
723 | .PP | |
724 | They are equivalent, because half the bits are set to 0, half are set to | |
725 | 1 (0xa and 0x5 are 1010 and 0101 binary respectively) and consequently this | |
726 | would roughly divide the clients equally between the servers. They are not | |
727 | identical, because the actual peers this would load balance to each server | |
728 | are different for each example. | |
729 | .PP | |
730 | You must only have \fBsplit\fR or \fBhba\fR defined, never both. For most | |
731 | cases, the fine-grained control that \fBhba\fR offers isn't necessary, and | |
732 | \fBsplit\fR should be used. | |
3c807354 | 733 | .RE |
59d36179 | 734 | .PP |
417b7b4a | 735 | The |
59d36179 | 736 | .I load balance max seconds |
3c807354 TL |
737 | statement |
738 | .RS 0.25i | |
59d36179 | 739 | .PP |
3c807354 | 740 | .B load balance max seconds \fIseconds\fR\fB;\fR |
59d36179 TL |
741 | .PP |
742 | This statement allows you to configure a cutoff after which load | |
743 | balancing is disabled. The cutoff is based on the number of seconds | |
744 | since the client sent its first DHCPDISCOVER or DHCPREQUEST message, | |
745 | and only works with clients that correctly implement the \fIsecs\fR | |
746 | field - fortunately most clients do. We recommend setting this to | |
747 | something like 3 or 5. The effect of this is that if one of the | |
748 | failover peers gets into a state where it is responding to failover | |
749 | messages but not responding to some client requests, the other | |
750 | failover peer will take over its client load automatically as the | |
751 | clients retry. | |
3e985dbf TM |
752 | .PP |
753 | It is possible to disable load balancing between peers by setting this | |
754 | value to 0 on both peers. Bear in mind that this means both peers will | |
755 | respond to all DHCPDISCOVERs or DHCPREQUESTs. | |
3c807354 | 756 | .RE |
99aa7f38 | 757 | .PP |
9e3eb22a DH |
758 | The |
759 | .I auto-partner-down | |
760 | statement | |
761 | .RS 0.25i | |
762 | .PP | |
763 | .B auto-partner-down \fIseconds\fR\fB;\fR | |
764 | .PP | |
765 | This statement instructs the server to initiate a timed delay upon entering | |
766 | the communications-interrupted state (any situation of being out-of-contact | |
767 | with the remote failover peer). At the conclusion of the timer, the server | |
768 | will automatically enter the partner-down state. This permits the server | |
769 | to allocate leases from the partner's free lease pool after an STOS+MCLT | |
770 | timer expires, which can be dangerous if the partner is in fact operating | |
771 | at the time (the two servers will give conflicting bindings). | |
772 | .PP | |
773 | Think very carefully before enabling this feature. The partner-down and | |
774 | communications-interrupted states are intentionally segregated because | |
775 | there do exist situations where a failover server can fail to communicate | |
776 | with its peer, but still has the ability to receive and reply to requests | |
777 | from DHCP clients. In general, this feature should only be used in those | |
778 | deployments where the failover servers are directly connected to one | |
779 | another, such as by a dedicated hardwired link ("a heartbeat cable"). | |
780 | .PP | |
781 | A zero value disables the auto-partner-down feature (also the default), and | |
782 | any positive value indicates the time in seconds to wait before automatically | |
783 | entering partner-down. | |
784 | .RE | |
785 | .PP | |
99aa7f38 DH |
786 | The Failover pool balance statements. |
787 | .RS 0.25i | |
788 | .PP | |
789 | \fBmax-lease-misbalance \fIpercentage\fR\fB;\fR | |
790 | \fBmax-lease-ownership \fIpercentage\fR\fB;\fR | |
791 | \fBmin-balance \fIseconds\fR\fB;\fR | |
792 | \fBmax-balance \fIseconds\fR\fB;\fR | |
793 | .PP | |
794 | This version of the DHCP Server evaluates pool balance on a schedule, | |
795 | rather than on demand as leases are allocated. The latter approach | |
796 | proved to be slightly klunky when pool misbalanced reach total | |
8e112e2b | 797 | saturation \(em when any server ran out of leases to assign, it also lost |
99aa7f38 DH |
798 | its ability to notice it had run dry. |
799 | .PP | |
800 | In order to understand pool balance, some elements of its operation | |
5a38e43f SR |
801 | first need to be defined. First, there are \'free\' and \'backup\' leases. |
802 | Both of these are referred to as \'free state leases\'. \'free\' and | |
803 | \'backup\' | |
804 | are \'the free states\' for the purpose of this document. The difference | |
805 | is that only the primary may allocate from \'free\' leases unless under | |
806 | special circumstances, and only the secondary may allocate \'backup\' leases. | |
99aa7f38 DH |
807 | .PP |
808 | When pool balance is performed, the only plausible expectation is to | |
809 | provide a 50/50 split of the free state leases between the two servers. | |
810 | This is because no one can predict which server will fail, regardless | |
811 | of the relative load placed upon the two servers, so giving each server | |
5a38e43f | 812 | half the leases gives both servers the same amount of \'failure endurance\'. |
99aa7f38 DH |
813 | Therefore, there is no way to configure any different behaviour, outside of |
814 | some very small windows we will describe shortly. | |
815 | .PP | |
816 | The first thing calculated on any pool balance run is a value referred to | |
5a38e43f | 817 | as \'lts\', or "Leases To Send". This, simply, is the difference in the |
99aa7f38 DH |
818 | count of free and backup leases, divided by two. For the secondary, |
819 | it is the difference in the backup and free leases, divided by two. | |
820 | The resulting value is signed: if it is positive, the local server is | |
821 | expected to hand out leases to retain a 50/50 balance. If it is negative, | |
822 | the remote server would need to send leases to balance the pool. Once | |
823 | the lts value reaches zero, the pool is perfectly balanced (give or take | |
824 | one lease in the case of an odd number of total free state leases). | |
825 | .PP | |
826 | The current approach is still something of a hybrid of the old approach, | |
827 | marked by the presence of the \fBmax-lease-misbalance\fR statement. This | |
828 | parameter configures what used to be a 10% fixed value in previous versions: | |
829 | if lts is less than free+backup * \fBmax-lease-misbalance\fR percent, then | |
830 | the server will skip balancing a given pool (it won't bother moving any | |
831 | leases, even if some leases "should" be moved). The meaning of this value | |
832 | is also somewhat overloaded, however, in that it also governs the estimation | |
833 | of when to attempt to balance the pool (which may then also be skipped over). | |
834 | The oldest leases in the free and backup states are examined. The time | |
835 | they have resided in their respective queues is used as an estimate to | |
836 | indicate how much time it is probable it would take before the leases at | |
837 | the top of the list would be consumed (and thus, how long it would take | |
838 | to use all leases in that state). This percentage is directly multiplied | |
839 | by this time, and fit into the schedule if it falls within | |
840 | the \fBmin-balance\fR and \fBmax-balance\fR configured values. The | |
841 | scheduled pool check time is only moved in a downwards direction, it is | |
842 | never increased. Lastly, if the lts is more than double this number in | |
5a38e43f | 843 | the negative direction, the local server will \'panic\' and transmit a |
99aa7f38 DH |
844 | Failover protocol POOLREQ message, in the hopes that the remote system |
845 | will be woken up into action. | |
846 | .PP | |
847 | Once the lts value exceeds the \fBmax-lease-misbalance\fR percentage of | |
848 | total free state leases as described above, leases are moved to the remote | |
849 | server. This is done in two passes. | |
850 | .PP | |
851 | In the first pass, only leases whose most recent bound client would have | |
852 | been served by the remote server - according to the Load Balance Algorithm | |
853 | (see above \fBsplit\fR and \fBhba\fR configuration statements) - are given | |
854 | away to the peer. This first pass will happily continue to give away leases, | |
855 | decrementing the lts value by one for each, until the lts value has reached | |
856 | the negative of the total number of leases multiplied by | |
857 | the \fBmax-lease-ownership\fR percentage. So it is through this value that | |
858 | you can permit a small misbalance of the lease pools - for the purpose of | |
859 | giving the peer more than a 50/50 share of leases in the hopes that their | |
860 | clients might some day return and be allocated by the peer (operating | |
5a38e43f | 861 | normally). This process is referred to as \'MAC Address Affinity\', but this |
99aa7f38 DH |
862 | is somewhat misnamed: it applies equally to DHCP Client Identifier options. |
863 | Note also that affinity is applied to leases when they enter the state | |
5a38e43f | 864 | \'free\' from \'expired\' or \'released\'. In this case also, leases will not |
99aa7f38 DH |
865 | be moved from free to backup if the secondary already has more than its |
866 | share. | |
867 | .PP | |
868 | The second pass is only entered into if the first pass fails to reduce | |
869 | the lts underneath the total number of free state leases multiplied by | |
870 | the \fBmax-lease-ownership\fR percentage. In this pass, the oldest | |
871 | leases are given over to the peer without second thought about the Load | |
872 | Balance Algorithm, and this continues until the lts falls under this | |
873 | value. In this way, the local server will also happily keep a small | |
874 | percentage of the leases that would normally load balance to itself. | |
875 | .PP | |
876 | So, the \fBmax-lease-misbalance\fR value acts as a behavioural gate. | |
877 | Smaller values will cause more leases to transition states to balance | |
878 | the pools over time, higher values will decrease the amount of change | |
879 | (but may lead to pool starvation if there's a run on leases). | |
880 | .PP | |
4408ba61 | 881 | The \fBmax-lease-ownership\fR value permits a small (percentage) skew |
99aa7f38 DH |
882 | in the lease balance of a percentage of the total number of free state |
883 | leases. | |
884 | .PP | |
885 | Finally, the \fBmin-balance\fR and \fBmax-balance\fR make certain that a | |
886 | scheduled rebalance event happens within a reasonable timeframe (not | |
887 | to be thrown off by, for example, a 7 year old free lease). | |
888 | .PP | |
889 | Plausible values for the percentages lie between 0 and 100, inclusive, but | |
890 | values over 50 are indistinguishable from one another (once lts exceeds | |
891 | 50% of the free state leases, one server must therefore have 100% of the | |
892 | leases in its respective free state). It is recommended to select | |
893 | a \fBmax-lease-ownership\fR value that is lower than the value selected | |
894 | for the \fBmax-lease-misbalance\fR value. \fBmax-lease-ownership\fR | |
895 | defaults to 10, and \fBmax-lease-misbalance\fR defaults to 15. | |
896 | .PP | |
897 | Plausible values for the \fBmin-balance\fR and \fBmax-balance\fR times also | |
898 | range from 0 to (2^32)-1 (or the limit of your local time_t value), but | |
899 | default to values 60 and 3600 respectively (to place balance events between | |
900 | 1 minute and 1 hour). | |
901 | .RE | |
d9dc2726 | 902 | .SH CLIENT CLASSING |
98311e4b | 903 | Clients can be separated into classes, and treated differently |
a0497ac5 | 904 | depending on what class they are in. This separation can be done |
d9dc2726 | 905 | either with a conditional statement, or with a match statement within |
a0497ac5 | 906 | the class declaration. It is possible to specify a limit on the |
d9dc2726 TL |
907 | total number of clients within a particular class or subclass that may |
908 | hold leases at one time, and it is possible to specify automatic | |
909 | subclassing based on the contents of the client packet. | |
910 | .PP | |
4dd0eb18 | 911 | Classing support for DHCPv6 clients was added in 4.3.0. It follows |
01fa619f SR |
912 | the same rules as for DHCPv4 except that support for billing classes |
913 | has not been added yet. | |
914 | .PP | |
d758ad8c TL |
915 | To add clients to classes based on conditional evaluation, you can |
916 | specify a matching expression in the class statement: | |
d9dc2726 TL |
917 | .PP |
918 | .nf | |
e9bb983c | 919 | class "ras-clients" { |
d83e416e | 920 | match if substring (option dhcp-client-identifier, 1, 3) = "RAS"; |
d9dc2726 TL |
921 | } |
922 | .fi | |
98311e4b | 923 | .PP |
d638452e TM |
924 | Please note that the values used in match expressions may only come from |
925 | data or options that are part of the client packet. It is not possible to | |
926 | use values constructed through one or more executable statements. This | |
927 | stems from the fact that client classification occurs before any statements | |
928 | are executed. Attempting to do so will yield indeterminate results. | |
929 | .PP | |
e9bb983c TL |
930 | Note that whether you use matching expressions or add statements (or |
931 | both) to classify clients, you must always write a class declaration | |
a0497ac5 | 932 | for any class that you use. If there will be no match statement and |
e9bb983c TL |
933 | no in-scope statements for a class, the declaration should look like |
934 | this: | |
98311e4b | 935 | .PP |
e9bb983c TL |
936 | .nf |
937 | class "ras-clients" { | |
938 | } | |
939 | .fi | |
2cd60a52 | 940 | .SH SUBCLASSES |
d9dc2726 | 941 | .PP |
a0497ac5 | 942 | In addition to classes, it is possible to declare subclasses. A |
d9dc2726 TL |
943 | subclass is a class with the same name as a regular class, but with a |
944 | specific submatch expression which is hashed for quick matching. | |
945 | This is essentially a speed hack - the main difference between five | |
946 | classes with match expressions and one class with five subclasses is | |
a0497ac5 | 947 | that it will be quicker to find the subclasses. Subclasses work as |
d9dc2726 TL |
948 | follows: |
949 | .PP | |
950 | .nf | |
2cd60a52 TL |
951 | class "allocation-class-1" { |
952 | match pick-first-value (option dhcp-client-identifier, hardware); | |
d9dc2726 TL |
953 | } |
954 | ||
2cd60a52 TL |
955 | class "allocation-class-2" { |
956 | match pick-first-value (option dhcp-client-identifier, hardware); | |
d9dc2726 TL |
957 | } |
958 | ||
2cd60a52 TL |
959 | subclass "allocation-class-1" 1:8:0:2b:4c:39:ad; |
960 | subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3; | |
961 | subclass "allocation-class-1" 1:0:0:c4:aa:29:44; | |
962 | ||
963 | subnet 10.0.0.0 netmask 255.255.255.0 { | |
964 | pool { | |
7b9767ea | 965 | allow members of "allocation-class-1"; |
2cd60a52 TL |
966 | range 10.0.0.11 10.0.0.50; |
967 | } | |
968 | pool { | |
7b9767ea | 969 | allow members of "allocation-class-2"; |
2cd60a52 TL |
970 | range 10.0.0.51 10.0.0.100; |
971 | } | |
972 | } | |
973 | .fi | |
974 | .PP | |
975 | The data following the class name in the subclass declaration is a | |
976 | constant value to use in matching the match expression for the class. | |
977 | When class matching is done, the server will evaluate the match | |
a0497ac5 | 978 | expression and then look the result up in the hash table. If it |
2cd60a52 TL |
979 | finds a match, the client is considered a member of both the class and |
980 | the subclass. | |
981 | .PP | |
a0497ac5 | 982 | Subclasses can be declared with or without scope. In the above |
2cd60a52 TL |
983 | example, the sole purpose of the subclass is to allow some clients |
984 | access to one address pool, while other clients are given access to | |
a0497ac5 | 985 | the other pool, so these subclasses are declared without scopes. If |
2cd60a52 TL |
986 | part of the purpose of the subclass were to define different parameter |
987 | values for some clients, you might want to declare some subclasses | |
988 | with scopes. | |
989 | .PP | |
990 | In the above example, if you had a single client that needed some | |
991 | configuration parameters, while most didn't, you might write the | |
992 | following subclass declaration for that client: | |
993 | .PP | |
994 | .nf | |
605a8b6d | 995 | subclass "allocation-class-2" 1:08:00:2b:a1:11:31 { |
2cd60a52 TL |
996 | option root-path "samsara:/var/diskless/alphapc"; |
997 | filename "/tftpboot/netbsd.alphapc-diskless"; | |
d9dc2726 TL |
998 | } |
999 | .fi | |
1000 | .PP | |
2cd60a52 TL |
1001 | In this example, we've used subclassing as a way to control address |
1002 | allocation on a per-client basis. However, it's also possible to use | |
1003 | subclassing in ways that are not specific to clients - for example, to | |
1004 | use the value of the vendor-class-identifier option to determine what | |
1005 | values to send in the vendor-encapsulated-options option. An example | |
5cc21fb3 TL |
1006 | of this is shown under the VENDOR ENCAPSULATED OPTIONS head in the |
1007 | .B dhcp-options(5) | |
1008 | manual page. | |
66ecafef | 1009 | .SH PER-CLASS LIMITS ON DYNAMIC ADDRESS ALLOCATION |
d9dc2726 TL |
1010 | .PP |
1011 | You may specify a limit to the number of clients in a class that can | |
a0497ac5 SR |
1012 | be assigned leases. The effect of this will be to make it difficult |
1013 | for a new client in a class to get an address. Once a class with | |
d9dc2726 TL |
1014 | such a limit has reached its limit, the only way a new client in that |
1015 | class can get a lease is for an existing client to relinquish its | |
1016 | lease, either by letting it expire, or by sending a DHCPRELEASE | |
a0497ac5 | 1017 | packet. Classes with lease limits are specified as follows: |
d9dc2726 TL |
1018 | .PP |
1019 | .nf | |
e9bb983c | 1020 | class "limited-1" { |
d9dc2726 TL |
1021 | lease limit 4; |
1022 | } | |
1023 | .fi | |
1024 | .PP | |
1025 | This will produce a class in which a maximum of four members may hold | |
1026 | a lease at one time. | |
2cd60a52 | 1027 | .SH SPAWNING CLASSES |
d9dc2726 TL |
1028 | .PP |
1029 | It is possible to declare a | |
1030 | .I spawning class\fR. | |
1031 | A spawning class is a class that automatically produces subclasses | |
a0497ac5 | 1032 | based on what the client sends. The reason that spawning classes |
d9dc2726 | 1033 | were created was to make it possible to create lease-limited classes |
a0497ac5 | 1034 | on the fly. The envisioned application is a cable-modem environment |
d9dc2726 TL |
1035 | where the ISP wishes to provide clients at a particular site with more |
1036 | than one IP address, but does not wish to provide such clients with | |
1037 | their own subnet, nor give them an unlimited number of IP addresses | |
1038 | from the network segment to which they are connected. | |
1039 | .PP | |
1040 | Many cable modem head-end systems can be configured to add a Relay | |
1041 | Agent Information option to DHCP packets when relaying them to the | |
a0497ac5 SR |
1042 | DHCP server. These systems typically add a circuit ID or remote ID |
1043 | option that uniquely identifies the customer site. To take advantage | |
d9dc2726 | 1044 | of this, you can write a class declaration as follows: |
2cd60a52 | 1045 | .PP |
d9dc2726 | 1046 | .nf |
e9bb983c | 1047 | class "customer" { |
b1c231ba | 1048 | spawn with option agent.circuit-id; |
d9dc2726 TL |
1049 | lease limit 4; |
1050 | } | |
1051 | .fi | |
1052 | .PP | |
1053 | Now whenever a request comes in from a customer site, the circuit ID | |
d7d9c0c7 | 1054 | option will be checked against the class\'s hash table. If a subclass |
d9dc2726 | 1055 | is found that matches the circuit ID, the client will be classified in |
a0497ac5 | 1056 | that subclass and treated accordingly. If no subclass is found |
d9dc2726 TL |
1057 | matching the circuit ID, a new one will be created and logged in the |
1058 | .B dhcpd.leases | |
a0497ac5 | 1059 | file, and the client will be classified in this new class. Once the |
d9dc2726 TL |
1060 | client has been classified, it will be treated according to the rules |
1061 | of the class, including, in this case, being subject to the per-site | |
1062 | limit of four leases. | |
1063 | .PP | |
1064 | The use of the subclass spawning mechanism is not restricted to relay | |
1065 | agent options - this particular example is given only because it is a | |
1066 | fairly straightforward one. | |
874031aa TL |
1067 | .SH COMBINING MATCH, MATCH IF AND SPAWN WITH |
1068 | .PP | |
1069 | In some cases, it may be useful to use one expression to assign a | |
1070 | client to a particular class, and a second expression to put it into a | |
a0497ac5 | 1071 | subclass of that class. This can be done by combining the \fBmatch |
874031aa | 1072 | if\fR and \fBspawn with\fR statements, or the \fBmatch if\fR and |
a0497ac5 | 1073 | \fBmatch\fR statements. For example: |
874031aa TL |
1074 | .PP |
1075 | .nf | |
1076 | class "jr-cable-modems" { | |
1077 | match if option dhcp-vendor-identifier = "jrcm"; | |
1078 | spawn with option agent.circuit-id; | |
1079 | lease limit 4; | |
1080 | } | |
1081 | ||
1082 | class "dv-dsl-modems" { | |
e6b3a140 | 1083 | match if option dhcp-vendor-identifier = "dvdsl"; |
874031aa TL |
1084 | spawn with option agent.circuit-id; |
1085 | lease limit 16; | |
1086 | } | |
1087 | .fi | |
1088 | .PP | |
1089 | This allows you to have two classes that both have the same \fBspawn | |
1090 | with\fR expression without getting the clients in the two classes | |
1091 | confused with each other. | |
66ecafef TL |
1092 | .SH DYNAMIC DNS UPDATES |
1093 | .PP | |
1094 | The DHCP server has the ability to dynamically update the Domain Name | |
1095 | System. Within the configuration files, you can define how you want | |
1096 | the Domain Name System to be updated. These updates are RFC 2136 | |
1097 | compliant so any DNS server supporting RFC 2136 should be able to | |
59d36179 | 1098 | accept updates from the DHCP server. |
66ecafef | 1099 | .PP |
d7d9c0c7 SR |
1100 | There are two DNS schemes implemented. The interim option is |
1101 | based on draft revisions of the DDNS documents while the standard | |
1102 | option is based on the RFCs for DHCP-DNS interaction and DHCIDs. | |
1103 | A third option, ad-hoc, was deprecated and has now been removed | |
1104 | from the code base. The DHCP server must be configured to use | |
1105 | one of the two currently-supported methods, or not to do DNS updates. | |
1106 | .PP | |
1107 | New installations should use the standard option. Older | |
1108 | installations may want to continue using the interim option for | |
1109 | backwards compatibility with the DNS database until the database | |
1110 | can be updated. This can be done with the | |
3c807354 TL |
1111 | .I ddns-update-style |
1112 | configuration parameter. | |
d7d9c0c7 SR |
1113 | .SH THE DNS UPDATE SCHEME |
1114 | the interim and standard DNS update schemes operate mostly according | |
1115 | to work from the IETF. The interim version was based on the drafts | |
1116 | in progress at the time while the standard is based on the completed | |
1117 | RFCs. The standard RFCs are: | |
fc06ee4f SR |
1118 | .PP |
1119 | .nf | |
1120 | .ce 3 | |
1121 | RFC 4701 (updated by RF5494) | |
1122 | RFC 4702 | |
1123 | RFC 4703 | |
1124 | .fi | |
1125 | .PP | |
1126 | And the corresponding drafts were: | |
3031654a TL |
1127 | .PP |
1128 | .nf | |
1129 | .ce 3 | |
3031654a | 1130 | draft-ietf-dnsext-dhcid-rr-??.txt |
fc06ee4f SR |
1131 | draft-ietf-dhc-fqdn-option-??.txt |
1132 | draft-ietf-dhc-ddns-resolution-??.txt | |
3031654a TL |
1133 | .fi |
1134 | .PP | |
d7d9c0c7 SR |
1135 | The basic framework for the two schemes is similar with the main |
1136 | material difference being that a DHCID RR is used in the standard | |
1137 | version while the interim versions uses a TXT RR. The format | |
1138 | of the TXT record bears a resemblance to the DHCID RR but it is not | |
1139 | equivalent (MD5 vs SHA2, field length differences etc). | |
3031654a | 1140 | .PP |
d7d9c0c7 | 1141 | In these two schemes the DHCP server does not necessarily |
a0497ac5 | 1142 | always update both the A and the PTR records. The FQDN option |
0e74ff1f | 1143 | includes a flag which, when sent by the client, indicates that the |
a0497ac5 | 1144 | client wishes to update its own A record. In that case, the server |
d7d9c0c7 | 1145 | can be configured either to honor the client\'s intentions or ignore |
a0497ac5 SR |
1146 | them. This is done with the statement \fIallow client-updates;\fR or |
1147 | the statement \fIignore client-updates;\fR. By default, client | |
3031654a TL |
1148 | updates are allowed. |
1149 | .PP | |
0e74ff1f TL |
1150 | If the server is configured to allow client updates, then if the |
1151 | client sends a fully-qualified domain name in the FQDN option, the | |
1152 | server will use that name the client sent in the FQDN option to update | |
a0497ac5 SR |
1153 | the PTR record. For example, let us say that the client is a visitor |
1154 | from the "radish.org" domain, whose hostname is "jschmoe". The | |
1155 | server is for the "example.org" domain. The DHCP client indicates in | |
1156 | the FQDN option that its FQDN is "jschmoe.radish.org.". It also | |
1157 | indicates that it wants to update its own A record. The DHCP server | |
0e74ff1f TL |
1158 | therefore does not attempt to set up an A record for the client, but |
1159 | does set up a PTR record for the IP address that it assigns the | |
a0497ac5 | 1160 | client, pointing at jschmoe.radish.org. Once the DHCP client has an |
0e74ff1f TL |
1161 | IP address, it can update its own A record, assuming that the |
1162 | "radish.org" DNS server will allow it to do so. | |
3031654a TL |
1163 | .PP |
1164 | If the server is configured not to allow client updates, or if the | |
d7d9c0c7 | 1165 | client doesn\'t want to do its own update, the server will simply |
d9b2a590 TM |
1166 | choose a name for the client. By default, the server will choose |
1167 | from the following three values: | |
1168 | .PP | |
1169 | 1. \fBfqdn\fR option (if present) | |
1170 | 2. hostname option (if present) | |
1171 | 3. Configured hostname option (if defined). | |
1172 | .PP | |
1173 | If these defaults for choosing the host name are not appropriate | |
7fffbde1 | 1174 | you can write your own statement to set the ddns-hostname variable |
d9b2a590 TM |
1175 | as you wish. If none of the above are found the server will use |
1176 | the host declaration name (if one) and use-host-decl-names is on. | |
1177 | .PP | |
1178 | It will use its own domain name for the client. It will then update | |
1179 | both the A and PTR record, using the name that it chose for the client. | |
1180 | If the client sends a fully-qualified domain name in the \fBfqdn\fR option, | |
1181 | the server uses only the leftmost part of the domain name - in the example | |
1182 | above, "jschmoe" instead of "jschmoe.radish.org". | |
7fffbde1 | 1183 | .PP |
a396d25f DH |
1184 | Further, if the \fIignore client-updates;\fR directive is used, then |
1185 | the server will in addition send a response in the DHCP packet, using | |
1186 | the FQDN Option, that implies to the client that it should perform its | |
1187 | own updates if it chooses to do so. With \fIdeny client-updates;\fR, a | |
1188 | response is sent which indicates the client may not perform updates. | |
1189 | .PP | |
417b7b4a | 1190 | Both the standard and interim options also include a method to |
d7d9c0c7 SR |
1191 | allow more than one DHCP server to update the DNS database without |
1192 | accidentally deleting A records that shouldn\'t be deleted nor failing | |
1193 | to add A records that should be added. For the standard option the | |
1194 | method works as follows: | |
3031654a TL |
1195 | .PP |
1196 | When the DHCP server issues a client a new lease, it creates a text | |
d7d9c0c7 SR |
1197 | string that is an SHA hash over the DHCP client\'s identification (see |
1198 | RFCs 4701 & 4702 for details). The update attempts to add an A | |
1199 | record with the name the server chose and a DHCID record containing the | |
a0497ac5 | 1200 | hashed identifier string (hashid). If this update succeeds, the |
3031654a TL |
1201 | server is done. |
1202 | .PP | |
1203 | If the update fails because the A record already exists, then the DHCP | |
1204 | server attempts to add the A record with the prerequisite that there | |
d7d9c0c7 SR |
1205 | must be a DHCID record in the same name as the new A record, and that |
1206 | DHCID record\'s contents must be equal to hashid. If this update | |
a0497ac5 | 1207 | succeeds, then the client has its A record and PTR record. If it |
3031654a | 1208 | fails, then the name the client has been assigned (or requested) is in |
d7d9c0c7 | 1209 | use, and can\'t be used by the client. At this point the DHCP server |
9f8b2a7f | 1210 | gives up trying to do a DNS update for the client until the client |
3031654a TL |
1211 | chooses a new name. |
1212 | .PP | |
d7d9c0c7 SR |
1213 | The server also does not update very aggressively. Because each |
1214 | DNS update involves a round trip to the DNS server, there is a cost | |
1215 | associated with doing updates even if they do not actually modify | |
1216 | the DNS database. So the DHCP server tracks whether or not it has | |
1217 | updated the record in the past (this information is stored on the | |
1218 | lease) and does not attempt to update records that it | |
3031654a TL |
1219 | thinks it has already updated. |
1220 | .PP | |
1221 | This can lead to cases where the DHCP server adds a record, and then | |
1222 | the record is deleted through some other mechanism, but the server | |
1223 | never again updates the DNS because it thinks the data is already | |
a0497ac5 | 1224 | there. In this case the data can be removed from the lease through |
3031654a TL |
1225 | operator intervention, and once this has been done, the DNS will be |
1226 | updated the next time the client renews. | |
d7d9c0c7 SR |
1227 | .PP |
1228 | The interim DNS update scheme was written before the RFCs were finalized | |
1229 | and does not quite follow them. The RFCs call for a new DHCID RRtype | |
e1634c24 | 1230 | while the interim DNS update scheme uses a TXT record. In addition |
d7d9c0c7 SR |
1231 | the ddns-resolution draft called for the DHCP server to put a DHCID RR |
1232 | on the PTR record, but the \fIinterim\fR update method does not do this. | |
1233 | In the final RFC this requirement was relaxed such that a server may | |
1234 | add a DHCID RR to the PTR record. | |
1235 | .PP | |
905c58b9 TM |
1236 | .SH DDNS IN DUAL STACK ENVIRONMENTS |
1237 | As described in RFC 4703, section 5.2, in order to perform DDNS in dual | |
1238 | stack environments, both IPv4 and IPv6 servers would need to be configured | |
1239 | to use the standard update style and participating IPv4 clients MUST | |
1240 | convey DUIDs as described in RFC 4361, section 6.1., in their | |
1241 | dhcp-client-identifiers. | |
1242 | .PP | |
1243 | In a nutshell, this mechanism is intended to use globally unique DUIDs | |
1244 | to idenfity both IPv4 and IPv6 clients, and where a device has both | |
1245 | IPv4 and IPv6 leases it is identified by the same DUID. This allows | |
1246 | a dual stack client to use the same FQDN for both mappings, while | |
1247 | being protected from updates for other clients by the rules of conflict | |
1248 | detection. | |
1249 | .PP | |
1250 | However, not all IPv4 clients implement this behavior which makes | |
1251 | supporting them dual stack environments problematic. In order to | |
1252 | address this issue ISC DHCP (as of 4.4.0) supports a new mode of | |
1253 | DDNS conflict resolution referred to as Dual Stack Mixed Mode (DSMM). | |
1254 | .PP | |
1255 | The concept behind DSMM is relatively simple. All dhcp servers of one | |
1256 | protocol (IPv4 or v6) use one ddns-update-style (interim or standard) | |
1257 | while all servers of the "other" protocol will use the "other" | |
1258 | ddns-udpate-style. In this way, all servers of a given protocol are | |
1259 | using the same record type (TXT or DHCID) for their DHCID RR entries. | |
1260 | This allows conflict detection to be enforced within each protocol | |
1261 | without interferring with the other's entries. | |
1262 | .PP | |
1263 | DSMM modifications now ensure that IPv4 DSMM servers only ever modify | |
1264 | A records, their associated PTR records and DHCID records, while DSMM | |
1265 | IPv6 severs only modify AAAA records, their associated PTR records, | |
1266 | and DHCID records. | |
1267 | .PP | |
1268 | Note that DSMM is not a perfect solution, it is a compromise that can | |
1269 | work well provided all participating DNS updaters play by DSMM rules. | |
1270 | As with anything else in life, it only works as well as those who | |
1271 | particpate behave. | |
1272 | .PP | |
1273 | While conflict detection is enabled by default, DSMM is not. To enable | |
1274 | DSMM, both update-conflict-detection and ddns-dual-stack-mixed-mode must | |
1275 | be true. | |
1276 | .PP | |
1277 | .SH PROTECTING DNS ENTRIES FOR STATIC CLIENTS | |
1278 | Built into conflict resolution is the protection of manually made entries | |
1279 | for static clients. Per the rules of conflict resolution, a DNS updater | |
1280 | may not alter forward DNS entries unless there is a DHCID RR which matches | |
1281 | for whom the update is being made. Therefore, any forward DNS entries | |
1282 | without a corresponding DHCID RR cannot be altered by such an updater. | |
1283 | .PP | |
1284 | In some environments, it may be desirable to use only this aspect of conflict | |
1285 | resolution and allow DNS updaters to overwrite entries for dynamic clients | |
1286 | regardless of what client owns them. In other words, the presence or lack | |
1287 | of a DHCID RR is used to determine whether entries may or may not be | |
1288 | overwritten. Whether or not the client matches the data value of the DHCID | |
1289 | RR is irrelevant. This behavior, off by default, can be configured through | |
1290 | the parameter, ddns-guard-id-must-match. As with DSMM, this behavior is | |
1291 | can only be enabled if conflict resolution is enabled. This behavior should | |
1292 | be considered carefully before electing to use it. | |
1293 | .PP | |
1294 | There is an additional parameter that can be used with DSMM | |
1295 | ddns-other-guard-is-dynamic. When enabled along with DSMM, a server will | |
1296 | regard the presence of a DHCID RR of the other style type as indicating that | |
1297 | the forward DNS entries for that FQDN should be dynamic and may be overwritten. | |
1298 | For example, such a server using interim style could overwrite the DNS entries | |
1299 | for an FQDN if there is only a DHDID type DHDID RR for the FQDN. Essentially, | |
1300 | if there are dynamic entries for one protocol, that is enough to overcome the | |
1301 | static protection of entries for the other protocol. This behavior warrants | |
1302 | careful consideration before electing to use it. | |
1303 | .PP | |
66ecafef TL |
1304 | .SH DYNAMIC DNS UPDATE SECURITY |
1305 | .PP | |
59d36179 TL |
1306 | When you set your DNS server up to allow updates from the DHCP server, |
1307 | you may be exposing it to unauthorized updates. To avoid this, you | |
1308 | should use TSIG signatures - a method of cryptographically signing | |
a0497ac5 SR |
1309 | updates using a shared secret key. As long as you protect the |
1310 | secrecy of this key, your updates should also be secure. Note, | |
59d36179 TL |
1311 | however, that the DHCP protocol itself provides no security, and that |
1312 | clients can therefore provide information to the DHCP server which the | |
1313 | DHCP server will then use in its updates, with the constraints | |
1314 | described previously. | |
66ecafef TL |
1315 | .PP |
1316 | The DNS server must be configured to allow updates for any zone that | |
1317 | the DHCP server will be updating. For example, let us say that | |
1318 | clients in the sneedville.edu domain will be assigned addresses on the | |
59d36179 TL |
1319 | 10.10.17.0/24 subnet. In that case, you will need a key declaration |
1320 | for the TSIG key you will be using, and also two zone declarations - | |
1321 | one for the zone containing A records that will be updates and one for | |
1322 | the zone containing PTR records - for ISC BIND, something like this: | |
66ecafef TL |
1323 | .PP |
1324 | .nf | |
59d36179 TL |
1325 | key DHCP_UPDATER { |
1326 | algorithm HMAC-MD5.SIG-ALG.REG.INT; | |
1327 | secret pRP5FapFoJ95JEL06sv4PQ==; | |
1328 | }; | |
1329 | ||
1330 | zone "example.org" { | |
66ecafef | 1331 | type master; |
59d36179 TL |
1332 | file "example.org.db"; |
1333 | allow-update { key DHCP_UPDATER; }; | |
66ecafef TL |
1334 | }; |
1335 | ||
1336 | zone "17.10.10.in-addr.arpa" { | |
1337 | type master; | |
1338 | file "10.10.17.db"; | |
59d36179 | 1339 | allow-update { key DHCP_UPDATER; }; |
66ecafef TL |
1340 | }; |
1341 | .fi | |
1342 | .PP | |
59d36179 | 1343 | You will also have to configure your DHCP server to do updates to |
a0497ac5 | 1344 | these zones. To do so, you need to add something like this to your |
59d36179 TL |
1345 | dhcpd.conf file: |
1346 | .PP | |
1347 | .nf | |
1348 | key DHCP_UPDATER { | |
1349 | algorithm HMAC-MD5.SIG-ALG.REG.INT; | |
1350 | secret pRP5FapFoJ95JEL06sv4PQ==; | |
1351 | }; | |
1352 | ||
1353 | zone EXAMPLE.ORG. { | |
1354 | primary 127.0.0.1; | |
1355 | key DHCP_UPDATER; | |
1356 | } | |
1357 | ||
1358 | zone 17.127.10.in-addr.arpa. { | |
1359 | primary 127.0.0.1; | |
1360 | key DHCP_UPDATER; | |
1361 | } | |
1362 | .fi | |
1363 | .PP | |
98311e4b | 1364 | The \fIprimary\fR statement specifies the IP address of the name |
d424157d SR |
1365 | server whose zone information is to be updated. In addition to |
1366 | the \fIprimary\fR statement there are also the \fIprimary6\fR , | |
1367 | \fIsecondary\fR and \fIsecondary6\fR statements. The \fIprimary6\fR | |
1368 | statement specifies an IPv6 address for the name server. The | |
1369 | secondaries provide for additional addresses for name servers | |
1370 | to be used if the primary does not respond. The number of name | |
1371 | servers the DDNS code will attempt to use before giving up | |
1372 | is limited and is currently set to three. | |
98311e4b | 1373 | .PP |
0e74ff1f TL |
1374 | Note that the zone declarations have to correspond to authority |
1375 | records in your name server - in the above example, there must be an | |
a0497ac5 | 1376 | SOA record for "example.org." and for "17.10.10.in-addr.arpa.". For |
98311e4b | 1377 | example, if there were a subdomain "foo.example.org" with no separate |
417b7b4a | 1378 | SOA, you could not write a zone declaration for "foo.example.org." |
d758ad8c TL |
1379 | Also keep in mind that zone names in your DHCP configuration should end in a |
1380 | "."; this is the preferred syntax. If you do not end your zone name in a | |
1381 | ".", the DHCP server will figure it out. Also note that in the DHCP | |
1382 | configuration, zone names are not encapsulated in quotes where there are in | |
1383 | the DNS configuration. | |
0e74ff1f | 1384 | .PP |
d7d9c0c7 SR |
1385 | You should choose your own secret key, of course. The ISC BIND 9 |
1386 | distribution comes with a program for generating secret keys called | |
1387 | dnssec-keygen. If you are using BIND 9\'s | |
d758ad8c | 1388 | dnssec-keygen, the above key would be created as follows: |
98311e4b | 1389 | .PP |
d758ad8c TL |
1390 | .nf |
1391 | dnssec-keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER | |
98311e4b DH |
1392 | .fi |
1393 | .PP | |
3ffc07de TM |
1394 | The key name, algorithm, and secret must match that being used by the DNS |
1395 | server. The DHCP server currently supports the following algorithms: | |
1396 | .nf | |
1397 | ||
1398 | HMAC-MD5 | |
1399 | HMAC-SHA1 | |
1400 | HMAC-SHA224 | |
1401 | HMAC-SHA256 | |
1402 | HMAC-SHA384 | |
1403 | HMAC-SHA512 | |
1404 | .fi | |
1405 | .PP | |
9f8b2a7f | 1406 | You may wish to enable logging of DNS updates on your DNS server. |
66ecafef TL |
1407 | To do so, you might write a logging statement like the following: |
1408 | .PP | |
1409 | .nf | |
1410 | logging { | |
1411 | channel update_debug { | |
1412 | file "/var/log/update-debug.log"; | |
1413 | severity debug 3; | |
1414 | print-category yes; | |
1415 | print-severity yes; | |
1416 | print-time yes; | |
1417 | }; | |
1418 | channel security_info { | |
1419 | file "/var/log/named-auth.info"; | |
1420 | severity info; | |
1421 | print-category yes; | |
1422 | print-severity yes; | |
1423 | print-time yes; | |
1424 | }; | |
1425 | ||
1426 | category update { update_debug; }; | |
1427 | category security { security_info; }; | |
1428 | }; | |
1429 | .fi | |
1430 | .PP | |
1431 | You must create the /var/log/named-auth.info and | |
a0497ac5 | 1432 | /var/log/update-debug.log files before starting the name server. For |
66ecafef TL |
1433 | more information on configuring ISC BIND, consult the documentation |
1434 | that accompanies it. | |
0f7099d7 TL |
1435 | .SH REFERENCE: EVENTS |
1436 | .PP | |
1437 | There are three kinds of events that can happen regarding a lease, and | |
1438 | it is possible to declare statements that occur when any of these | |
a0497ac5 | 1439 | events happen. These events are the commit event, when the server |
0f7099d7 TL |
1440 | has made a commitment of a certain lease to a client, the release |
1441 | event, when the client has released the server from its commitment, | |
1442 | and the expiry event, when the commitment expires. | |
1443 | .PP | |
0f7099d7 | 1444 | To declare a set of statements to execute when an event happens, you |
2cd60a52 | 1445 | must use the \fBon\fR statement, followed by the name of the event, |
0f7099d7 | 1446 | followed by a series of statements to execute when the event happens, |
d7d9c0c7 | 1447 | enclosed in braces. |
5e6b52dc | 1448 | .SH REFERENCE: DECLARATIONS |
d250c5b9 | 1449 | .PP |
98311e4b DH |
1450 | .B The |
1451 | .I include | |
1452 | .B statement | |
1453 | .PP | |
1454 | .nf | |
1455 | \fBinclude\fR \fI"filename"\fR\fB;\fR | |
1456 | .fi | |
1457 | .PP | |
1458 | The \fIinclude\fR statement is used to read in a named file, and process | |
1459 | the contents of that file as though it were entered in place of the | |
1460 | include statement. | |
1461 | .PP | |
417b7b4a | 1462 | .B The |
5e6b52dc TL |
1463 | .I shared-network |
1464 | .B statement | |
1465 | .PP | |
1466 | .nf | |
1467 | \fBshared-network\fR \fIname\fR \fB{\fR | |
1468 | [ \fIparameters\fR ] | |
1469 | [ \fIdeclarations\fR ] | |
1470 | \fB}\fR | |
1471 | .fi | |
1472 | .PP | |
1473 | The \fIshared-network\fR statement is used to inform the DHCP server | |
1474 | that some IP subnets actually share the same physical network. Any | |
1475 | subnets in a shared network should be declared within a | |
1476 | \fIshared-network\fR statement. Parameters specified in the | |
1477 | \fIshared-network\fR statement will be used when booting clients on | |
1478 | those subnets unless parameters provided at the subnet or host level | |
1479 | override them. If any subnet in a shared network has addresses | |
1480 | available for dynamic allocation, those addresses are collected into a | |
1481 | common pool for that shared network and assigned to clients as needed. | |
1482 | There is no way to distinguish on which subnet of a shared network a | |
1483 | client should boot. | |
1484 | .PP | |
1485 | .I Name | |
a0497ac5 | 1486 | should be the name of the shared network. This name is used when |
5e6b52dc | 1487 | printing debugging messages, so it should be descriptive for the |
a0497ac5 | 1488 | shared network. The name may have the syntax of a valid domain name |
5e6b52dc TL |
1489 | (although it will never be used as such), or it may be any arbitrary |
1490 | name, enclosed in quotes. | |
1491 | .PP | |
417b7b4a | 1492 | .B The |
5e6b52dc TL |
1493 | .I subnet |
1494 | .B statement | |
1495 | .PP | |
1496 | .nf | |
1497 | \fBsubnet\fR \fIsubnet-number\fR \fBnetmask\fR \fInetmask\fR \fB{\fR | |
1498 | [ \fIparameters\fR ] | |
1499 | [ \fIdeclarations\fR ] | |
1500 | \fB}\fR | |
1501 | .fi | |
1502 | .PP | |
1503 | The \fIsubnet\fR statement is used to provide dhcpd with enough | |
1504 | information to tell whether or not an IP address is on that subnet. | |
1505 | It may also be used to provide subnet-specific parameters and to | |
1506 | specify what addresses may be dynamically allocated to clients booting | |
a0497ac5 | 1507 | on that subnet. Such addresses are specified using the \fIrange\fR |
5e6b52dc TL |
1508 | declaration. |
1509 | .PP | |
1510 | The | |
1511 | .I subnet-number | |
1512 | should be an IP address or domain name which resolves to the subnet | |
417b7b4a | 1513 | number of the subnet being described. The |
5e6b52dc TL |
1514 | .I netmask |
1515 | should be an IP address or domain name which resolves to the subnet mask | |
a0497ac5 | 1516 | of the subnet being described. The subnet number, together with the |
5e6b52dc TL |
1517 | netmask, are sufficient to determine whether any given IP address is |
1518 | on the specified subnet. | |
1519 | .PP | |
73eaf823 TL |
1520 | Although a netmask must be given with every subnet declaration, it is |
1521 | recommended that if there is any variance in subnet masks at a site, a | |
1522 | subnet-mask option statement be used in each subnet declaration to set | |
1523 | the desired subnet mask, since any subnet-mask option statement will | |
1524 | override the subnet mask declared in the subnet statement. | |
1525 | .PP | |
417b7b4a | 1526 | .B The |
98bd7ca0 DH |
1527 | .I subnet6 |
1528 | .B statement | |
1529 | .PP | |
1530 | .nf | |
1531 | \fBsubnet6\fR \fIsubnet6-number\fR \fB{\fR | |
1532 | [ \fIparameters\fR ] | |
1533 | [ \fIdeclarations\fR ] | |
1534 | \fB}\fR | |
1535 | .fi | |
1536 | .PP | |
1537 | The \fIsubnet6\fR statement is used to provide dhcpd with enough | |
1538 | information to tell whether or not an IPv6 address is on that subnet6. | |
1539 | It may also be used to provide subnet-specific parameters and to | |
1540 | specify what addresses may be dynamically allocated to clients booting | |
417b7b4a | 1541 | on that subnet. |
98bd7ca0 DH |
1542 | .PP |
1543 | The | |
1544 | .I subnet6-number | |
4408ba61 | 1545 | should be an IPv6 network identifier, specified as ip6-address/bits. |
98bd7ca0 | 1546 | .PP |
5e6b52dc TL |
1547 | .B The |
1548 | .I range | |
1549 | .B statement | |
1550 | .PP | |
1551 | .nf | |
d9dc2726 | 1552 | .B range\fR [ \fBdynamic-bootp\fR ] \fIlow-address\fR [ \fIhigh-address\fR]\fB;\fR |
5e6b52dc TL |
1553 | .fi |
1554 | .PP | |
1555 | For any subnet on which addresses will be assigned dynamically, there | |
a0497ac5 SR |
1556 | must be at least one \fIrange\fR statement. The range statement |
1557 | gives the lowest and highest IP addresses in a range. All IP | |
5e6b52dc | 1558 | addresses in the range should be in the subnet in which the |
a0497ac5 | 1559 | \fIrange\fR statement is declared. The \fIdynamic-bootp\fR flag may |
5e6b52dc | 1560 | be specified if addresses in the specified range may be dynamically |
a0497ac5 | 1561 | assigned to BOOTP clients as well as DHCP clients. When specifying a |
5e6b52dc TL |
1562 | single address, \fIhigh-address\fR can be omitted. |
1563 | .PP | |
1564 | .B The | |
98bd7ca0 DH |
1565 | .I range6 |
1566 | .B statement | |
1567 | .PP | |
1568 | .nf | |
1569 | .B range6\fR \fIlow-address\fR \fIhigh-address\fR\fB;\fR | |
1570 | .B range6\fR \fIsubnet6-number\fR\fB;\fR | |
783259b1 | 1571 | .B range6\fR \fIsubnet6-number\fR \fBtemporary\fR\fB;\fR |
80c9fdb0 | 1572 | .B range6\fR \fIaddress\fR \fBtemporary\fR\fB;\fR |
98bd7ca0 DH |
1573 | .fi |
1574 | .PP | |
1575 | For any IPv6 subnet6 on which addresses will be assigned dynamically, there | |
1576 | must be at least one \fIrange6\fR statement. The \fIrange6\fR statement | |
417b7b4a TM |
1577 | can either be the lowest and highest IPv6 addresses in a \fIrange6\fR, or |
1578 | use CIDR notation, specified as ip6-address/bits. All IP addresses | |
98bd7ca0 DH |
1579 | in the \fIrange6\fR should be in the subnet6 in which the |
1580 | \fIrange6\fR statement is declared. | |
1581 | .PP | |
532c031e | 1582 | The \fItemporary\fR variant makes the prefix (by default on 64 bits) available |
80c9fdb0 FD |
1583 | for temporary (RFC 4941) addresses. A new address per prefix in the shared |
1584 | network is computed at each request with an IA_TA option. Release and Confirm | |
783259b1 | 1585 | ignores temporary addresses. |
80c9fdb0 | 1586 | .PP |
417b7b4a | 1587 | Any IPv6 addresses given to hosts with \fIfixed-address6\fR are excluded |
98bd7ca0 DH |
1588 | from the \fIrange6\fR, as are IPv6 addresses on the server itself. |
1589 | .PP | |
80c9fdb0 FD |
1590 | .PP |
1591 | .B The | |
1592 | .I prefix6 | |
1593 | .B statement | |
1594 | .PP | |
1595 | .nf | |
1596 | .B prefix6\fR \fIlow-address\fR \fIhigh-address\fR \fB/\fR \fIbits\fR\fB;\fR | |
1597 | .fi | |
1598 | .PP | |
1599 | The \fIprefix6\fR is the \fIrange6\fR equivalent for Prefix Delegation | |
1600 | (RFC 3633). Prefixes of \fIbits\fR length are assigned between | |
1601 | \fIlow-address\fR and \fIhigh-address\fR. | |
1602 | .PP | |
1603 | Any IPv6 prefixes given to static entries (hosts) with \fIfixed-prefix6\fR | |
1604 | are excluded from the \fIprefix6\fR. | |
1605 | .PP | |
1606 | This statement is currently global but it should have a shared-network scope. | |
1607 | .PP | |
98bd7ca0 | 1608 | .B The |
5e6b52dc TL |
1609 | .I host |
1610 | .B statement | |
1611 | .PP | |
1612 | .nf | |
1613 | \fBhost\fR \fIhostname\fR { | |
1614 | [ \fIparameters\fR ] | |
1615 | [ \fIdeclarations\fR ] | |
1616 | \fB}\fR | |
1617 | .fi | |
d250c5b9 | 1618 | .PP |
98311e4b | 1619 | The |
d250c5b9 | 1620 | .B host |
34711bb7 SR |
1621 | declaration provides a way for the DHCP server to identify a DHCP or |
1622 | BOOTP client. This allows the server to provide configuration | |
1623 | information including fixed addresses or, in DHCPv6, fixed prefixes | |
1624 | for a specific client. | |
47c9ea95 | 1625 | .PP |
c75473d8 | 1626 | If it is desirable to be able to boot a DHCP or BOOTP client on more than one |
34711bb7 | 1627 | subnet with fixed v4 addresses, more than one address may be specified in the |
5e6b52dc | 1628 | .I fixed-address |
98311e4b | 1629 | declaration, or more than one |
d250c5b9 | 1630 | .B host |
c75473d8 | 1631 | statement may be specified matching the same client. |
47c9ea95 | 1632 | .PP |
34711bb7 SR |
1633 | The |
1634 | .I fixed-address6 | |
4dd0eb18 | 1635 | declaration is used for v6 addresses. At this time it only works with a single |
34711bb7 SR |
1636 | address. For multiple addresses specify multiple |
1637 | .B host | |
1638 | statements. | |
1639 | .PP | |
5e6b52dc | 1640 | If client-specific boot parameters must change based on the network |
417b7b4a | 1641 | to which the client is attached, then multiple |
d250c5b9 | 1642 | .B host |
c75473d8 | 1643 | declarations should be used. The |
d250c5b9 | 1644 | .B host |
c75473d8 DH |
1645 | declarations will only match a client if one of their |
1646 | .I fixed-address | |
1647 | statements is viable on the subnet (or shared network) where the client is | |
1648 | attached. Conversely, for a | |
1649 | .B host | |
1650 | declaration to match a client being allocated a dynamic address, it must not | |
1651 | have any | |
1652 | .I fixed-address | |
1653 | statements. You may therefore need a mixture of | |
1654 | .B host | |
1655 | declarations for any given client...some having | |
1656 | .I fixed-address | |
1657 | statements, others without. | |
1658 | .PP | |
d250c5b9 | 1659 | .I hostname |
5e6b52dc TL |
1660 | should be a name identifying the host. If a \fIhostname\fR option is |
1661 | not specified for the host, \fIhostname\fR is used. | |
1662 | .PP | |
1663 | \fIHost\fR declarations are matched to actual DHCP or BOOTP clients | |
1664 | by matching the \fRdhcp-client-identifier\fR option specified in the | |
1665 | \fIhost\fR declaration to the one supplied by the client, or, if the | |
1666 | \fIhost\fR declaration or the client does not provide a | |
1667 | \fRdhcp-client-identifier\fR option, by matching the \fIhardware\fR | |
1668 | parameter in the \fIhost\fR declaration to the network hardware | |
a0497ac5 | 1669 | address supplied by the client. BOOTP clients do not normally |
5e6b52dc TL |
1670 | provide a \fIdhcp-client-identifier\fR, so the hardware address must |
1671 | be used for all clients that may boot using the BOOTP protocol. | |
1672 | .PP | |
98bd7ca0 DH |
1673 | DHCPv6 servers can use the \fIhost-identifier option\fR parameter in |
1674 | the \fIhost\fR declaration, and specify any option with a fixed value | |
1675 | to identify hosts. | |
1676 | .PP | |
98311e4b DH |
1677 | Please be aware that |
1678 | .B only | |
1679 | the \fIdhcp-client-identifier\fR option and the hardware address can be | |
4408ba61 | 1680 | used to match a host declaration, or the \fIhost-identifier option\fR |
a0497ac5 SR |
1681 | parameter for DHCPv6 servers. For example, it is not possible to |
1682 | match a host declaration to a \fIhost-name\fR option. This is | |
98bd7ca0 DH |
1683 | because the host-name option cannot be guaranteed to be unique for any |
1684 | given client, whereas both the hardware address and | |
1685 | \fIdhcp-client-identifier\fR option are at least theoretically | |
1686 | guaranteed to be unique to a given client. | |
98311e4b | 1687 | .PP |
5e6b52dc TL |
1688 | .B The |
1689 | .I group | |
1690 | .B statement | |
d250c5b9 | 1691 | .PP |
5e6b52dc TL |
1692 | .nf |
1693 | \fBgroup\fR { | |
1694 | [ \fIparameters\fR ] | |
1695 | [ \fIdeclarations\fR ] | |
1696 | \fB}\fR | |
1697 | .fi | |
1698 | .PP | |
1699 | The group statement is used simply to apply one or more parameters to | |
a0497ac5 | 1700 | a group of declarations. It can be used to group hosts, shared |
5e6b52dc | 1701 | networks, subnets, or even other groups. |
1a67a4d7 | 1702 | .SH REFERENCE: ALLOW AND DENY |
66b01364 TL |
1703 | The |
1704 | .I allow | |
1705 | and | |
1706 | .I deny | |
605a8b6d TL |
1707 | statements can be used to control the response of the DHCP server to |
1708 | various sorts of requests. The allow and deny keywords actually have | |
1709 | different meanings depending on the context. In a pool context, these | |
1710 | keywords can be used to set up access lists for address allocation | |
1711 | pools. In other contexts, the keywords simply control general server | |
a0497ac5 | 1712 | behavior with respect to clients based on scope. In a non-pool |
605a8b6d TL |
1713 | context, the |
1714 | .I ignore | |
1715 | keyword can be used in place of the | |
1716 | .I deny | |
1717 | keyword to prevent logging of denied requests. | |
1718 | .PP | |
1719 | .SH ALLOW DENY AND IGNORE IN SCOPE | |
1a67a4d7 TL |
1720 | The following usages of allow and deny will work in any scope, |
1721 | although it is not recommended that they be used in pool | |
1722 | declarations. | |
66b01364 TL |
1723 | .PP |
1724 | .B The | |
1725 | .I unknown-clients | |
1726 | .B keyword | |
1727 | .PP | |
1728 | \fBallow unknown-clients;\fR | |
1729 | \fBdeny unknown-clients;\fR | |
605a8b6d | 1730 | \fBignore unknown-clients;\fR |
66b01364 TL |
1731 | .PP |
1732 | The \fBunknown-clients\fR flag is used to tell dhcpd whether | |
a0497ac5 | 1733 | or not to dynamically assign addresses to unknown clients. Dynamic |
66b01364 | 1734 | address assignment to unknown clients is \fBallow\fRed by default. |
0e74ff1f | 1735 | An unknown client is simply a client that has no host declaration. |
66b01364 | 1736 | .PP |
98311e4b DH |
1737 | The use of this option is now \fIdeprecated\fR. If you are trying to |
1738 | restrict access on your network to known clients, you should use \fBdeny | |
1739 | unknown-clients;\fR inside of your address pool, as described under the | |
4408ba61 | 1740 | heading ALLOW AND DENY WITHIN POOL DECLARATIONS. |
98311e4b | 1741 | .PP |
66b01364 TL |
1742 | .B The |
1743 | .I bootp | |
1744 | .B keyword | |
1745 | .PP | |
1746 | \fBallow bootp;\fR | |
1747 | \fBdeny bootp;\fR | |
605a8b6d | 1748 | \fBignore bootp;\fR |
66b01364 | 1749 | .PP |
ba7ed239 | 1750 | The \fBbootp\fR flag is used to tell dhcpd whether |
66b01364 TL |
1751 | or not to respond to bootp queries. Bootp queries are \fBallow\fRed |
1752 | by default. | |
1753 | .PP | |
1754 | .B The | |
1755 | .I booting | |
1756 | .B keyword | |
1757 | .PP | |
1758 | \fBallow booting;\fR | |
1759 | \fBdeny booting;\fR | |
605a8b6d | 1760 | \fBignore booting;\fR |
66b01364 TL |
1761 | .PP |
1762 | The \fBbooting\fR flag is used to tell dhcpd whether or not to respond | |
1763 | to queries from a particular client. This keyword only has meaning | |
a0497ac5 | 1764 | when it appears in a host declaration. By default, booting is |
66b01364 | 1765 | \fBallow\fRed, but if it is disabled for a particular client, then |
98311e4b DH |
1766 | that client will not be able to get an address from the DHCP server. |
1767 | .PP | |
605a8b6d TL |
1768 | .B The |
1769 | .I duplicates | |
1770 | .B keyword | |
1771 | .PP | |
1772 | \fBallow duplicates;\fR | |
1773 | \fBdeny duplicates;\fR | |
1774 | .PP | |
1775 | Host declarations can match client messages based on the DHCP Client | |
c759db75 | 1776 | Identifier option or based on the client's network hardware type and |
a0497ac5 | 1777 | MAC address. If the MAC address is used, the host declaration will |
605a8b6d | 1778 | match any client with that MAC address - even clients with different |
a0497ac5 | 1779 | client identifiers. This doesn't normally happen, but is possible |
605a8b6d TL |
1780 | when one computer has more than one operating system installed on it - |
1781 | for example, Microsoft Windows and NetBSD or Linux. | |
1782 | .PP | |
1783 | The \fBduplicates\fR flag tells the DHCP server that if a request is | |
1784 | received from a client that matches the MAC address of a host | |
1785 | declaration, any other leases matching that MAC address should be | |
a0497ac5 | 1786 | discarded by the server, even if the UID is not the same. This is a |
605a8b6d TL |
1787 | violation of the DHCP protocol, but can prevent clients whose client |
1788 | identifiers change regularly from holding many leases at the same time. | |
1789 | By default, duplicates are \fBallow\fRed. | |
98311e4b | 1790 | .PP |
605a8b6d TL |
1791 | .B The |
1792 | .I declines | |
1793 | .B keyword | |
1794 | .PP | |
1795 | \fBallow declines;\fR | |
1796 | \fBdeny declines;\fR | |
1797 | \fBignore declines;\fR | |
1798 | .PP | |
1799 | The DHCPDECLINE message is used by DHCP clients to indicate that the | |
a0497ac5 | 1800 | lease the server has offered is not valid. When the server receives |
605a8b6d TL |
1801 | a DHCPDECLINE for a particular address, it normally abandons that |
1802 | address, assuming that some unauthorized system is using it. | |
1803 | Unfortunately, a malicious or buggy client can, using DHCPDECLINE | |
e690fa7c | 1804 | messages, completely exhaust the DHCP server's allocation pool. The |
fb98e02e TM |
1805 | server will eventually reclaim these leases, but not while the client |
1806 | is running through the pool. This may cause serious thrashing in the DNS, | |
1807 | and it will also cause the DHCP server to forget old DHCP client address | |
605a8b6d TL |
1808 | allocations. |
1809 | .PP | |
e690fa7c SR |
1810 | The \fBdeclines\fR flag tells the DHCP server whether or not to honor |
1811 | DHCPDECLINE messages. If it is set to \fBdeny\fR or \fBignore\fR in | |
1812 | a particular scope, the DHCP server will not respond to DHCPDECLINE | |
1813 | messages. | |
1814 | .PP | |
1815 | The \fBdeclines\fR flag is only supported by DHCPv4 servers. Given the large | |
1816 | IPv6 address space and the internal limits imposed by the server's | |
1817 | address generation mechanism we don't think it is necessary for DHCPv6 | |
1818 | servers at this time. | |
1819 | .PP | |
fb98e02e TM |
1820 | Currently, abandoned IPv6 addresses are reclaimed in one of two ways: |
1821 | a) Client renews a specific address: | |
34711bb7 SR |
1822 | If a client using a given DUID submits a DHCP REQUEST containing |
1823 | the last address abandoned by that DUID, the address will be | |
1824 | reassigned to that client. | |
fb98e02e | 1825 | |
34711bb7 SR |
1826 | b) Upon the second restart following an address abandonment. When |
1827 | an address is abandoned it is both recorded as such in the lease | |
1828 | file and retained as abandoned in server memory until the server | |
1829 | is restarted. Upon restart, the server will process the lease file | |
1830 | and all addresses whose last known state is abandoned will be | |
1831 | retained as such in memory but not rewritten to the lease file. | |
1832 | This means that a subsequent restart of the server will not see the | |
1833 | abandoned addresses in the lease file and therefore have no record | |
1834 | of them as abandoned in memory and as such perceive them as free | |
1835 | for assignment. | |
fb98e02e TM |
1836 | .PP |
1837 | The total number addresses in a pool, available for a given DUID value, | |
1838 | is internally limited by the server's address generation mechanism. If | |
1839 | through mistaken configuration, multiple clients are using the same | |
1840 | DUID they will competing for the same addresses causing the server to reach | |
1841 | this internal limit rather quickly. The internal limit isolates this type | |
1842 | of activity such that address range is not exhausted for other DUID values. | |
1843 | The appearance of the following error log, can be an indication of this | |
1844 | condition: | |
1845 | ||
34711bb7 SR |
1846 | "Best match for DUID <XX> is an abandoned address, This may be a |
1847 | result of multiple clients attempting to use this DUID" | |
fb98e02e | 1848 | |
34711bb7 SR |
1849 | where <XX> is an actual DUID value depicted as colon separated |
1850 | string of bytes in hexadecimal values. | |
fb98e02e | 1851 | .PP |
3031654a TL |
1852 | .B The |
1853 | .I client-updates | |
1854 | .B keyword | |
1855 | .PP | |
1856 | \fBallow client-updates;\fR | |
1857 | \fBdeny client-updates;\fR | |
1858 | .PP | |
1859 | The \fBclient-updates\fR flag tells the DHCP server whether or not to | |
e1634c24 SR |
1860 | honor the client's intention to do its own update of its A record. See |
1861 | the documentation under the heading THE DNS UPDATE SCHEME for details. | |
6d103865 SK |
1862 | .PP |
1863 | .B The | |
1864 | .I leasequery | |
1865 | .B keyword | |
1866 | .PP | |
1867 | \fBallow leasequery;\fR | |
1868 | \fBdeny leasequery;\fR | |
1869 | .PP | |
1870 | The \fBleasequery\fR flag tells the DHCP server whether or not to | |
1871 | answer DHCPLEASEQUERY packets. The answer to a DHCPLEASEQUERY packet | |
417b7b4a TM |
1872 | includes information about a specific lease, such as when it was |
1873 | issued and when it will expire. By default, the server will not | |
6d103865 | 1874 | respond to these packets. |
1a67a4d7 TL |
1875 | .SH ALLOW AND DENY WITHIN POOL DECLARATIONS |
1876 | .PP | |
9f8b2a7f | 1877 | The uses of the allow and deny keywords shown in the previous section |
1a67a4d7 TL |
1878 | work pretty much the same way whether the client is sending a |
1879 | DHCPDISCOVER or a DHCPREQUEST message - an address will be allocated | |
1880 | to the client (either the old address it's requesting, or a new | |
1881 | address) and then that address will be tested to see if it's okay to | |
a0497ac5 SR |
1882 | let the client have it. If the client requested it, and it's not |
1883 | okay, the server will send a DHCPNAK message. Otherwise, the server | |
1884 | will simply not respond to the client. If it is okay to give the | |
1a67a4d7 TL |
1885 | address to the client, the server will send a DHCPACK message. |
1886 | .PP | |
1887 | The primary motivation behind pool declarations is to have address | |
a0497ac5 | 1888 | allocation pools whose allocation policies are different. A client |
1a67a4d7 | 1889 | may be denied access to one pool, but allowed access to another pool |
a0497ac5 | 1890 | on the same network segment. In order for this to work, access |
1a67a4d7 TL |
1891 | control has to be done during address allocation, not after address |
1892 | allocation is done. | |
1893 | .PP | |
1894 | When a DHCPREQUEST message is processed, address allocation simply | |
1895 | consists of looking up the address the client is requesting and seeing | |
1896 | if it's still available for the client. If it is, then the DHCP | |
1897 | server checks both the address pool permit lists and the relevant | |
1898 | in-scope allow and deny statements to see if it's okay to give the | |
1899 | lease to the client. In the case of a DHCPDISCOVER message, the | |
1900 | allocation process is done as described previously in the ADDRESS | |
1901 | ALLOCATION section. | |
1902 | .PP | |
1903 | When declaring permit lists for address allocation pools, the | |
9f8b2a7f | 1904 | following syntaxes are recognized following the allow or deny keywords: |
1a67a4d7 | 1905 | .PP |
98311e4b | 1906 | \fBknown-clients;\fR |
1a67a4d7 TL |
1907 | .PP |
1908 | If specified, this statement either allows or prevents allocation from | |
1909 | this pool to any client that has a host declaration (i.e., is known). | |
66ecafef TL |
1910 | A client is known if it has a host declaration in \fIany\fR scope, not |
1911 | just the current scope. | |
1a67a4d7 | 1912 | .PP |
98311e4b | 1913 | \fBunknown-clients;\fR |
1a67a4d7 TL |
1914 | .PP |
1915 | If specified, this statement either allows or prevents allocation from | |
1916 | this pool to any client that has no host declaration (i.e., is not | |
1917 | known). | |
1918 | .PP | |
1919 | \fBmembers of "\fRclass\fB";\fR | |
1920 | .PP | |
1921 | If specified, this statement either allows or prevents allocation from | |
1922 | this pool to any client that is a member of the named class. | |
1923 | .PP | |
1924 | \fBdynamic bootp clients;\fR | |
1925 | .PP | |
1926 | If specified, this statement either allows or prevents allocation from | |
1927 | this pool to any bootp client. | |
1928 | .PP | |
1929 | \fBauthenticated clients;\fR | |
1930 | .PP | |
1931 | If specified, this statement either allows or prevents allocation from | |
1932 | this pool to any client that has been authenticated using the DHCP | |
a0497ac5 | 1933 | authentication protocol. This is not yet supported. |
1a67a4d7 TL |
1934 | .PP |
1935 | \fBunauthenticated clients;\fR | |
1936 | .PP | |
1937 | If specified, this statement either allows or prevents allocation from | |
1938 | this pool to any client that has not been authenticated using the DHCP | |
a0497ac5 | 1939 | authentication protocol. This is not yet supported. |
1a67a4d7 TL |
1940 | .PP |
1941 | \fBall clients;\fR | |
1942 | .PP | |
1943 | If specified, this statement either allows or prevents allocation from | |
a0497ac5 | 1944 | this pool to all clients. This can be used when you want to write a |
1a67a4d7 TL |
1945 | pool declaration for some reason, but hold it in reserve, or when you |
1946 | want to renumber your network quickly, and thus want the server to | |
1947 | force all clients that have been allocated addresses from this pool to | |
1948 | obtain new addresses immediately when they next renew. | |
b1d3778c DH |
1949 | .PP |
1950 | \fBafter \fItime\fR\fB;\fR | |
1951 | .PP | |
1952 | If specified, this statement either allows or prevents allocation from | |
1953 | this pool after a given date. This can be used when you want to move | |
1954 | clients from one pool to another. The server adjusts the regular lease | |
1955 | time so that the latest expiry time is at the given time+min-lease-time. | |
1956 | A short min-lease-time enforces a step change, whereas a longer | |
1957 | min-lease-time allows for a gradual change. | |
1958 | \fItime\fR is either second since epoch, or a UTC time string e.g. | |
1959 | 4 2007/08/24 09:14:32 or a string with time zone offset in seconds | |
1960 | e.g. 4 2007/08/24 11:14:32 -7200 | |
5e6b52dc | 1961 | .SH REFERENCE: PARAMETERS |
3c807354 | 1962 | The |
a5252220 TM |
1963 | .I abandon-lease-time |
1964 | statement | |
1965 | .RS 0.25i | |
1966 | .PP | |
f883cc90 | 1967 | .B abandon-lease-time \fItime\fR\fB;\fR |
a5252220 TM |
1968 | .PP |
1969 | .I Time | |
1970 | should be the maximum amount of time (in seconds) that an abandoned IPv4 lease | |
1971 | remains unavailable for assignment to a client. Abandoned leases will only be | |
1972 | offered to clients if there are no free leases. If not defined, the default | |
1973 | abandon lease time is 86400 seconds (24 hours). Note the abandoned lease time | |
1974 | for a given lease is preserved across server restarts. The parameter may only | |
1975 | be set at the global scope and is evaluated only once during server startup. | |
1976 | .PP | |
1977 | Values less than sixty seconds are not recommended as this is below the ping | |
1978 | check threshold and can cause leases once abandoned but since returned to the | |
1979 | free state to not be pinged before being offered. If the requested time is | |
1980 | larger than 0x7FFFFFFF - 1 or the sum of the current time plus the abandoned time isgreater than 0x7FFFFFFF it is treated as infinite. | |
1981 | .RE | |
1982 | .PP | |
1983 | The | |
b22de500 DH |
1984 | .I adaptive-lease-time-threshold |
1985 | statement | |
1986 | .RS 0.25i | |
1987 | .PP | |
1988 | .B adaptive-lease-time-threshold \fIpercentage\fR\fB;\fR | |
1989 | .PP | |
1990 | When the number of allocated leases within a pool rises above | |
1991 | the \fIpercentage\fR given in this statement, the DHCP server decreases | |
1992 | the lease length for new clients within this pool to \fImin-lease-time\fR | |
1993 | seconds. Clients renewing an already valid (long) leases get at least the | |
1994 | remaining time from the current lease. Since the leases expire faster, | |
1995 | the server may either recover more quickly or avoid pool exhaustion | |
1996 | entirely. Once the number of allocated leases drop below the threshold, | |
1997 | the server reverts back to normal lease times. Valid percentages are | |
1998 | between 1 and 99. | |
1999 | .RE | |
2000 | .PP | |
2001 | The | |
5cc21fb3 | 2002 | .I always-broadcast |
3c807354 TL |
2003 | statement |
2004 | .RS 0.25i | |
0a1c1f11 | 2005 | .PP |
5cc21fb3 | 2006 | .B always-broadcast \fIflag\fR\fB;\fR |
0a1c1f11 | 2007 | .PP |
5cc21fb3 TL |
2008 | The DHCP and BOOTP protocols both require DHCP and BOOTP clients to |
2009 | set the broadcast bit in the flags field of the BOOTP message header. | |
2010 | Unfortunately, some DHCP and BOOTP clients do not do this, and | |
a0497ac5 | 2011 | therefore may not receive responses from the DHCP server. The DHCP |
5cc21fb3 | 2012 | server can be made to always broadcast its responses to clients by |
5a38e43f | 2013 | setting this flag to \'on\' for the relevant scope; relevant scopes would be |
98311e4b | 2014 | inside a conditional statement, as a parameter for a class, or as a parameter |
a0497ac5 | 2015 | for a host declaration. To avoid creating excess broadcast traffic on your |
98311e4b | 2016 | network, we recommend that you restrict the use of this option to as few |
a0497ac5 | 2017 | clients as possible. For example, the Microsoft DHCP client is known not |
98311e4b | 2018 | to have this problem, as are the OpenTransport and ISC DHCP clients. |
3c807354 | 2019 | .RE |
0a1c1f11 | 2020 | .PP |
3c807354 | 2021 | The |
5cc21fb3 | 2022 | .I always-reply-rfc1048 |
3c807354 TL |
2023 | statement |
2024 | .RS 0.25i | |
5e6b52dc | 2025 | .PP |
5cc21fb3 | 2026 | .B always-reply-rfc1048 \fIflag\fR\fB;\fR |
5e6b52dc | 2027 | .PP |
5cc21fb3 | 2028 | Some BOOTP clients expect RFC1048-style responses, but do not follow |
a0497ac5 | 2029 | RFC1048 when sending their requests. You can tell that a client is |
5cc21fb3 TL |
2030 | having this problem if it is not getting the options you have |
2031 | configured for it and if you see in the server log the message | |
2032 | "(non-rfc1048)" printed with each BOOTREQUEST that is logged. | |
5e6b52dc | 2033 | .PP |
5cc21fb3 TL |
2034 | If you want to send rfc1048 options to such a client, you can set the |
2035 | .B always-reply-rfc1048 | |
2036 | option in that client's host declaration, and the DHCP server will | |
a0497ac5 | 2037 | respond with an RFC-1048-style vendor options field. This flag can |
5cc21fb3 TL |
2038 | be set in any scope, and will affect all clients covered by that |
2039 | scope. | |
3c807354 | 2040 | .RE |
5e6b52dc | 2041 | .PP |
3c807354 | 2042 | The |
5cc21fb3 | 2043 | .I authoritative |
3c807354 TL |
2044 | statement |
2045 | .RS 0.25i | |
cdd70b87 | 2046 | .PP |
5cc21fb3 | 2047 | .B authoritative; |
cdd70b87 | 2048 | .PP |
5cc21fb3 | 2049 | .B not authoritative; |
cdd70b87 | 2050 | .PP |
5cc21fb3 TL |
2051 | The DHCP server will normally assume that the configuration |
2052 | information about a given network segment is not known to be correct | |
2053 | and is not authoritative. This is so that if a naive user installs a | |
2054 | DHCP server not fully understanding how to configure it, it does not | |
2055 | send spurious DHCPNAK messages to clients that have obtained addresses | |
2056 | from a legitimate DHCP server on the network. | |
cdd70b87 | 2057 | .PP |
5cc21fb3 TL |
2058 | Network administrators setting up authoritative DHCP servers for their |
2059 | networks should always write \fBauthoritative;\fR at the top of their | |
2060 | configuration file to indicate that the DHCP server \fIshould\fR send | |
a0497ac5 | 2061 | DHCPNAK messages to misconfigured clients. If this is not done, |
5cc21fb3 TL |
2062 | clients will be unable to get a correct IP address after changing |
2063 | subnets until their old lease has expired, which could take quite a | |
2064 | long time. | |
cdd70b87 | 2065 | .PP |
5cc21fb3 | 2066 | Usually, writing \fBauthoritative;\fR at the top level of the file |
a0497ac5 | 2067 | should be sufficient. However, if a DHCP server is to be set up so |
5cc21fb3 TL |
2068 | that it is aware of some networks for which it is authoritative and |
2069 | some networks for which it is not, it may be more appropriate to | |
2070 | declare authority on a per-network-segment basis. | |
cdd70b87 | 2071 | .PP |
5cc21fb3 TL |
2072 | Note that the most specific scope for which the concept of authority |
2073 | makes any sense is the physical network segment - either a | |
2074 | shared-network statement or a subnet statement that is not contained | |
2075 | within a shared-network statement. It is not meaningful to specify | |
2076 | that the server is authoritative for some subnets within a shared | |
2077 | network, but not authoritative for others, nor is it meaningful to | |
2078 | specify that the server is authoritative for some host declarations | |
2079 | and not others. | |
e4b6b033 TM |
2080 | .PP |
2081 | In order for DHCPINFORMs to be responded to by the server, | |
2082 | they must match to subnets over which the server has authority; | |
2083 | otherwise they will be ignored and logged. To minimize the | |
2084 | impact on logging volume, only the first and every subsequent 100th | |
2085 | occurrence of an ignored DHCPINFORM is logged. | |
3c807354 | 2086 | .RE |
cdd70b87 | 2087 | .PP |
5cc21fb3 | 2088 | The \fIboot-unknown-clients\fR statement |
3c807354 TL |
2089 | .RS 0.25i |
2090 | .PP | |
98311e4b | 2091 | .B boot-unknown-clients \fIflag\fB;\fR |
3c807354 | 2092 | .PP |
5cc21fb3 TL |
2093 | If the \fIboot-unknown-clients\fR statement is present and has a value |
2094 | of \fIfalse\fR or \fIoff\fR, then clients for which there is no | |
2095 | .I host | |
a0497ac5 | 2096 | declaration will not be allowed to obtain IP addresses. If this |
5cc21fb3 TL |
2097 | statement is not present or has a value of \fItrue\fR or \fIon\fR, |
2098 | then clients without host declarations will be allowed to obtain IP | |
2099 | addresses, as long as those addresses are not restricted by | |
2100 | .I allow | |
2101 | and \fIdeny\fR statements within their \fIpool\fR declarations. | |
3c807354 TL |
2102 | .RE |
2103 | .PP | |
30593241 TM |
2104 | The \fIcheck-secs-byte-order\fR statement |
2105 | .RS 0.25i | |
2106 | .PP | |
2107 | .B check-secs-byte-order \fIflag\fB;\fR | |
2108 | .PP | |
3bb1978f | 2109 | When \fIcheck-secs-byte-order\fR is enabled, the server will check for DHCPv4 |
30593241 TM |
2110 | clients that do the byte ordering on the secs field incorrectly. This field |
2111 | should be in network byte order but some clients get it wrong. When this | |
2112 | parameter is enabled the server will examine the secs field and if it looks | |
2113 | wrong (high byte non zero and low byte zero) swap the bytes. The default | |
2114 | is disabled. This parameter is only useful when doing load balancing within | |
2115 | failover. (Formerly, this behavior had to be enabled during compilation | |
2116 | configuration via --enable-secs-byteorder). | |
2117 | .PP | |
64e1823d DH |
2118 | The \fIdb-time-format\fR statement |
2119 | .RS 0.25i | |
2120 | .PP | |
2121 | .B db-time-format \fR[ \fIdefault\fR | \fIlocal\fR ] \fB;\fR | |
2122 | .PP | |
2123 | The DHCP server software outputs several timestamps when writing leases to | |
2124 | persistent storage. This configuration parameter selects one of two output | |
2125 | formats. The \fIdefault\fR format prints the day, date, and time in UTC, | |
2126 | while the \fIlocal\fR format prints the system seconds-since-epoch, and | |
2127 | helpfully provides the day and time in the system timezone in a comment. | |
2128 | The time formats are described in detail in the dhcpd.leases(5) manpage. | |
2129 | .RE | |
2130 | .PP | |
5cc21fb3 | 2131 | The \fIddns-hostname\fR statement |
3c807354 TL |
2132 | .RS 0.25i |
2133 | .PP | |
5cc21fb3 | 2134 | .B ddns-hostname \fIname\fB;\fR |
3c807354 | 2135 | .PP |
5cc21fb3 | 2136 | The \fIname\fR parameter should be the hostname that will be used in |
8e112e2b | 2137 | setting up the client's A and PTR records. If no \fIddns-hostname\fR is |
5cc21fb3 | 2138 | specified in scope, then the server will derive the hostname |
9f8b2a7f | 2139 | automatically, using an algorithm that varies for each of the |
5cc21fb3 | 2140 | different update methods. |
3c807354 TL |
2141 | .RE |
2142 | .PP | |
2143 | The \fIddns-domainname\fR statement | |
2144 | .RS 0.25i | |
2145 | .PP | |
2146 | .B ddns-domainname \fIname\fB;\fR | |
2147 | .PP | |
2148 | The \fIname\fR parameter should be the domain name that will be | |
2149 | appended to the client's hostname to form a fully-qualified | |
2150 | domain-name (FQDN). | |
2151 | .RE | |
2152 | .PP | |
905c58b9 TM |
2153 | The \fIddns-dual-stack-mixed-mode\fR statement |
2154 | .RS 0.25i | |
2155 | .PP | |
2156 | .B ddns-dual-stack-mixed-mode \fIflag\fB;\fR | |
2157 | .PP | |
2158 | The \fIddns-dual-stack-mixed-mode\fR parameter controls whether or not the | |
2159 | server applies Dual Stack Mixed Mode rules during DDNS conflict resolution. | |
2160 | This parameter is off by default, has no effect unless | |
2161 | update-conflict-detection is enabled, and may only be specified at the | |
2162 | global scope. | |
2163 | .RE | |
2164 | .PP | |
2165 | The \fIddns-guard-id-must-match\fR statement | |
2166 | .RS 0.25i | |
2167 | .PP | |
2168 | .B ddns-guard-id-must-match \fIflag\fB;\fR | |
2169 | .PP | |
2170 | The \fIddns-guard-id-must-match\fR parameter controls whether or not a | |
2171 | the client id within a DHCID RR must match that of the DNS update's client | |
2172 | to permit DNS entries associated with that DHCID RR to be ovewritten. | |
2173 | Proper conflict resolution requires ID matching and should only be disabled | |
2174 | after careful consideration. When disabled, it is allows any DNS updater to | |
2175 | replace DNS entries that have an associated DHCID RR, regardless of client | |
2176 | identity. This parameter is on by default, has no effect unless | |
2177 | update-conflict-detection is enabled, and may only be specified at the global | |
2178 | scope. | |
2179 | .RE | |
2180 | .PP | |
61ef216b SR |
2181 | The \fddns-local-address4\fR and \fddns-local-address6\fR statements |
2182 | .RS 0.25i | |
2183 | .PP | |
2184 | .B ddns-local-address4 \fIaddress\fB;\fR | |
2185 | .PP | |
2186 | .B ddns-local-address6 \fIaddress\fB;\fR | |
2187 | .PP | |
2188 | The \fIaddress\fR parameter should be the local IPv4 or IPv6 address | |
2189 | the server should use as the from address when sending DDNS update | |
2190 | requests. | |
2191 | .RE | |
2192 | .PP | |
905c58b9 TM |
2193 | The \fIddns-other-guard-is-dynamic\fR statement |
2194 | .RS 0.25i | |
2195 | .PP | |
2196 | .B ddns-other-guard-is-dynamic \fIflag\fB;\fR | |
2197 | .PP | |
2198 | The \fIddns-other-guard-is-dynamic\fR parameter controls whether or not a | |
2199 | a server running DSMM will consider the presence of the other update style | |
2200 | DHCID RR as an indcation that a DNS entries may be overwritten. It should | |
2201 | only be enabled after careful study as it allows DNS entries that would | |
2202 | otherwise be protected as static, to be overwritten in certain cases. This | |
2203 | paramater is off by default, has no effect unless ddns-dual-stack-mixed-mode | |
2204 | is enabled, and may only be specified at the global scope. | |
2205 | .RE | |
2206 | .PP | |
3c807354 TL |
2207 | The \fIddns-rev-domainname\fR statement |
2208 | .RS 0.25i | |
2209 | .PP | |
2210 | .B ddns-rev-domainname \fIname\fB;\fR | |
61ef216b | 2211 | .PP |
3c807354 TL |
2212 | The \fIname\fR parameter should be the domain name that will be |
2213 | appended to the client's reversed IP address to produce a name for use | |
a0497ac5 | 2214 | in the client's PTR record. By default, this is "in-addr.arpa.", but |
3c807354 TL |
2215 | the default can be overridden here. |
2216 | .PP | |
2217 | The reversed IP address to which this domain name is appended is | |
2218 | always the IP address of the client, in dotted quad notation, reversed | |
2219 | - for example, if the IP address assigned to the client is | |
a0497ac5 | 2220 | 10.17.92.74, then the reversed IP address is 74.92.17.10. So a |
3c807354 TL |
2221 | client with that IP address would, by default, be given a PTR record |
2222 | of 10.17.92.74.in-addr.arpa. | |
2223 | .RE | |
2224 | .PP | |
5cc21fb3 | 2225 | The \fIddns-update-style\fR parameter |
3c807354 | 2226 | .RS 0.25i |
d250c5b9 | 2227 | .PP |
5cc21fb3 | 2228 | .B ddns-update-style \fIstyle\fB;\fR |
d250c5b9 | 2229 | .PP |
3c807354 | 2230 | The |
5cc21fb3 | 2231 | .I style |
d7d9c0c7 | 2232 | parameter must be one of \fBstandard\fR, \fBinterim\fR or \fBnone\fR. |
5cc21fb3 TL |
2233 | The \fIddns-update-style\fR statement is only meaningful in the outer |
2234 | scope - it is evaluated once after reading the dhcpd.conf file, rather | |
2235 | than each time a client is assigned an IP address, so there is no way | |
884a458f SK |
2236 | to use different DNS update styles for different clients. The default |
2237 | is \fBnone\fR. | |
3c807354 | 2238 | .RE |
5e6b52dc | 2239 | .PP |
417b7b4a | 2240 | .B The |
5cc21fb3 TL |
2241 | .I ddns-updates |
2242 | .B statement | |
3c807354 | 2243 | .RS 0.25i |
5e6b52dc | 2244 | .PP |
5cc21fb3 | 2245 | \fBddns-updates \fIflag\fR\fB;\fR |
5e6b52dc | 2246 | .PP |
5cc21fb3 | 2247 | The \fIddns-updates\fR parameter controls whether or not the server will |
a0497ac5 | 2248 | attempt to do a DNS update when a lease is confirmed. Set this to \fIoff\fR |
5cc21fb3 | 2249 | if the server should not attempt to do updates within a certain scope. |
a0497ac5 | 2250 | The \fIddns-updates\fR parameter is on by default. To disable DNS |
5cc21fb3 TL |
2251 | updates in all scopes, it is preferable to use the |
2252 | \fIddns-update-style\fR statement, setting the style to \fInone\fR. | |
3c807354 | 2253 | .RE |
5e6b52dc | 2254 | .PP |
3c807354 | 2255 | The |
5cc21fb3 | 2256 | .I default-lease-time |
3c807354 TL |
2257 | statement |
2258 | .RS 0.25i | |
5e6b52dc | 2259 | .PP |
5cc21fb3 | 2260 | .B default-lease-time \fItime\fR\fB;\fR |
5e6b52dc | 2261 | .PP |
5cc21fb3 TL |
2262 | .I Time |
2263 | should be the length in seconds that will be assigned to a lease if | |
2264 | the client requesting the lease does not ask for a specific expiration | |
98bd7ca0 DH |
2265 | time. This is used for both DHCPv4 and DHCPv6 leases (it is also known |
2266 | as the "valid lifetime" in DHCPv6). | |
5a38e43f | 2267 | The default is 43200 seconds. |
3c807354 | 2268 | .RE |
5e6b52dc | 2269 | .PP |
3c807354 | 2270 | The |
6368a1bd | 2271 | .I delayed-ack |
f8cbf390 DH |
2272 | and |
2273 | .I max-ack-delay | |
2274 | statements | |
6368a1bd DH |
2275 | .RS 0.25i |
2276 | .PP | |
f8cbf390 | 2277 | .B delayed-ack \fIcount\fR\fB;\fR |
61ef216b | 2278 | .PP |
f8cbf390 | 2279 | .B max-ack-delay \fImicroseconds\fR\fB;\fR |
6368a1bd | 2280 | .PP |
f8cbf390 | 2281 | .I Count |
4406f9b0 TM |
2282 | should be an integer value from zero to 2^16-1 and defaults to 0, which means |
2283 | that the feature is disabled. Otherwise, 28 may be a sensible starting point | |
2284 | for many configurations (SO_SNDBUF size / 576 bytes.) The count represents how | |
2285 | many DHCPv4 replies maximum will be queued pending transmission until after a | |
2286 | database commit event. If this number is reached, a database commit event | |
2287 | (commonly resulting in fsync() and representing a performance penalty) will be | |
2288 | made, and the reply packets will be transmitted in a batch afterwards. This | |
2289 | preserves the RFC2131 direction that "stable storage" be updated prior to | |
2290 | replying to clients. Should the DHCPv4 sockets "go dry" (select() returns | |
2291 | immediately with no read sockets), the commit is made and any queued packets | |
2292 | are transmitted. | |
f8cbf390 DH |
2293 | .PP |
2294 | Similarly, \fImicroseconds\fR indicates how many microseconds are permitted | |
2295 | to pass inbetween queuing a packet pending an fsync, and performing the | |
2296 | fsync. Valid values range from 0 to 2^32-1, and defaults to 250,000 (1/4 of | |
2297 | a second). | |
fbcee149 | 2298 | .PP |
4406f9b0 TM |
2299 | The delayed-ack feature is compiled in by default, but can be disabled |
2300 | at compile time with \'./configure --disable-delayed-ack\'. Please note | |
2301 | that the delayed-ack feature is not currently compatible with support for | |
700e3fca TM |
2302 | DHPCv4-over-DHCPv6 so when a 4to6 port ommand line argument enables this |
2303 | in the server the delayed-ack value is reset to 0. | |
6368a1bd DH |
2304 | .RE |
2305 | .PP | |
417b7b4a TM |
2306 | The |
2307 | .I dhcp-cache-threshold | |
929a2364 TM |
2308 | statement |
2309 | .RS 0.25i | |
2310 | .PP | |
2311 | .B dhcp-cache-threshold \fIpercentage\fB;\fR | |
2312 | .PP | |
2313 | The \fIdhcp-cache-threshold\fR statement takes one integer parameter | |
2314 | with allowed values between 0 and 100. The default value is 25 (25% of | |
2315 | the lease time). This parameter expresses the percentage of the total | |
2316 | lease time, measured from the beginning, during which a | |
2317 | client's attempt to renew its lease will result in getting | |
bbdac71d TM |
2318 | the already assigned lease, rather than an extended lease. This feature |
2319 | is supported for both IPv4 and IPv6 and down to the pool level and for | |
2320 | IPv6 all three pool types: NA, TA and PD. | |
929a2364 TM |
2321 | .PP |
2322 | Clients that attempt renewal frequently can cause the server to | |
2323 | update and write the database frequently resulting in a performance | |
2324 | impact on the server. The \fIdhcp-cache-threshold\fR | |
2325 | statement instructs the DHCP server to avoid updating leases too | |
bbdac71d | 2326 | frequently thus avoiding this behavior. Instead the server replies with the |
f3a44c10 | 2327 | same lease (i.e. reuses it) with no modifications except for CLTT (Client Last |
bbdac71d TM |
2328 | Transmission Time) and for IPv4: |
2329 | ||
2330 | the lease time sent to the client is shortened by the age of | |
2331 | the lease | |
2332 | ||
2333 | while for IPv6: | |
2334 | ||
2335 | the preferred and valid lifetimes sent to the client are | |
2336 | shortened by the age of the lease. | |
2337 | ||
2338 | None of these changes require writing the lease to disk. | |
2339 | ||
f3a44c10 TM |
2340 | .PP |
2341 | When an existing lease is matched to a renewing client, it will be reused | |
2342 | if all of the following conditions are true: | |
2343 | .nf | |
2344 | 1. The dhcp-cache-threshold is larger than zero | |
2345 | 2. The current lease is active | |
2346 | 3. The percentage of the lease time that has elapsed is less than | |
2347 | dhcp-cache-threshold | |
2348 | 4. The client information provided in the renewal does not alter | |
2349 | any of the following: | |
2350 | a. DNS information and DNS updates are enabled | |
bbdac71d TM |
2351 | b. Billing class to which the lease is associated (IPv4 only) |
2352 | c. The host declaration associated with the lease (IPv4 only) | |
3abc5708 | 2353 | d. The client id - this may happen if a client boots without |
bbdac71d TM |
2354 | a client id and then starts using one in subsequent |
2355 | requests. (IPv4 only) | |
f3a44c10 | 2356 | .fi |
3abc5708 | 2357 | .PP |
bbdac71d TM |
2358 | While lease data is not written to disk when a lease is reused, the server |
2359 | will still execute any on-commit statements. | |
2360 | .PP | |
3abc5708 SR |
2361 | Note that the lease can be reused if the options the client or relay agent |
2362 | sends are changed. These changes will not be recorded in the in-memory or | |
2363 | on-disk databases until the client renews after the threshold time is reached. | |
929a2364 TM |
2364 | .RE |
2365 | .PP | |
6368a1bd | 2366 | The |
98311e4b DH |
2367 | .I do-forward-updates |
2368 | statement | |
2369 | .RS 0.25i | |
2370 | .PP | |
2371 | .B do-forward-updates \fIflag\fB;\fR | |
2372 | .PP | |
2373 | The \fIdo-forward-updates\fR statement instructs the DHCP server as | |
d7d9c0c7 | 2374 | to whether it should attempt to update a DHCP client\'s A record |
a0497ac5 | 2375 | when the client acquires or renews a lease. This statement has no |
d7d9c0c7 SR |
2376 | effect unless DNS updates are enabled. Forward updates are enabled |
2377 | by default. If this statement is used to disable forward updates, | |
2378 | the DHCP server will never attempt to update the client\'s A record, | |
2379 | and will only ever attempt to update the client\'s PTR record if the | |
2380 | client supplies an FQDN that should be placed in the PTR record using | |
2381 | the \fBfqdn\fR option. If forward updates are enabled, the DHCP server | |
2382 | will still honor the setting of the \fBclient-updates\fR flag. | |
98311e4b DH |
2383 | .RE |
2384 | .PP | |
2385 | The | |
624d5a03 | 2386 | .I dont-use-fsync |
cde11a4c SR |
2387 | statement |
2388 | .RS 0.25i | |
2389 | .PP | |
624d5a03 | 2390 | .B dont-use-fsync \fIflag\fB;\fR |
cde11a4c | 2391 | .PP |
624d5a03 | 2392 | The \fIdont-use-fsync\fR statement instructs the DHCP server if |
cde11a4c SR |
2393 | it should call fsync() when writing leases to the lease file. By |
2394 | default and if the flag is set to false the server \fBwill\fR call | |
2395 | fsync(). Suppressing the call to fsync() may increase the performance | |
2396 | of the server but it also adds a risk that a lease will not be | |
2397 | properly written to the disk after it has been issued to a client | |
2398 | and before the server stops. This can lead to duplicate leases | |
2399 | being issued to different clients. Using this option is \fBnot | |
2400 | recommended\FR. | |
2401 | .RE | |
2402 | .PP | |
2403 | The | |
5e6b52dc | 2404 | .I dynamic-bootp-lease-cutoff |
3c807354 TL |
2405 | statement |
2406 | .RS 0.25i | |
5e6b52dc | 2407 | .PP |
3c807354 | 2408 | .B dynamic-bootp-lease-cutoff \fIdate\fB;\fR |
5e6b52dc TL |
2409 | .PP |
2410 | The \fIdynamic-bootp-lease-cutoff\fR statement sets the ending time | |
2411 | for all leases assigned dynamically to BOOTP clients. Because BOOTP | |
2412 | clients do not have any way of renewing leases, and don't know that | |
c759db75 | 2413 | their leases could expire, by default dhcpd assigns infinite leases |
5e6b52dc TL |
2414 | to all BOOTP clients. However, it may make sense in some situations |
2415 | to set a cutoff date for all BOOTP leases - for example, the end of a | |
2416 | school term, or the time at night when a facility is closed and all | |
2417 | machines are required to be powered off. | |
2418 | .PP | |
2419 | .I Date | |
2420 | should be the date on which all assigned BOOTP leases will end. The | |
2421 | date is specified in the form: | |
2422 | .PP | |
2423 | .ce 1 | |
2424 | W YYYY/MM/DD HH:MM:SS | |
2425 | .PP | |
2426 | W is the day of the week expressed as a number | |
2427 | from zero (Sunday) to six (Saturday). YYYY is the year, including the | |
2428 | century. MM is the month expressed as a number from 1 to 12. DD is | |
2429 | the day of the month, counting from 1. HH is the hour, from zero to | |
2430 | 23. MM is the minute and SS is the second. The time is always in | |
6ceb9118 | 2431 | Coordinated Universal Time (UTC), not local time. |
3c807354 | 2432 | .RE |
5e6b52dc | 2433 | .PP |
3c807354 | 2434 | The |
5e6b52dc | 2435 | .I dynamic-bootp-lease-length |
3c807354 TL |
2436 | statement |
2437 | .RS 0.25i | |
5e6b52dc | 2438 | .PP |
3c807354 | 2439 | .B dynamic-bootp-lease-length\fR \fIlength\fR\fB;\fR |
5e6b52dc TL |
2440 | .PP |
2441 | The \fIdynamic-bootp-lease-length\fR statement is used to set the | |
a0497ac5 | 2442 | length of leases dynamically assigned to BOOTP clients. At some |
5e6b52dc TL |
2443 | sites, it may be possible to assume that a lease is no longer in |
2444 | use if its holder has not used BOOTP or DHCP to get its address within | |
a0497ac5 SR |
2445 | a certain time period. The period is specified in \fIlength\fR as a |
2446 | number of seconds. If a client reboots using BOOTP during the | |
5e6b52dc TL |
2447 | timeout period, the lease duration is reset to \fIlength\fR, so a |
2448 | BOOTP client that boots frequently enough will never lose its lease. | |
2449 | Needless to say, this parameter should be adjusted with extreme | |
2450 | caution. | |
3c807354 | 2451 | .RE |
5e6b52dc | 2452 | .PP |
3c807354 | 2453 | The |
e046c826 TM |
2454 | .I echo-client-id |
2455 | statement | |
2456 | .RS 0.25i | |
2457 | .PP | |
2458 | .B echo-client-id\fR \fIflag\fR\fB;\fR | |
2459 | .PP | |
2460 | The \fIecho-client-id\fR statement is used to enable or disable RFC 6842 | |
2461 | compliant behavior. If the echo-client-id statement is present and has a | |
2462 | value of true or on, and a DHCP DISCOVER or REQUEST is received which contains | |
2463 | the client identifier option (Option code 61), the server will copy the option | |
2464 | into its response (DHCP ACK or NAK) per RFC 6842. In other words if the | |
2465 | client sends the option it will receive it back. By default, this flag is off | |
2466 | and client identifiers will not echoed back to the client. | |
2467 | .RE | |
2468 | .PP | |
2469 | The | |
5cc21fb3 TL |
2470 | .I filename |
2471 | statement | |
2472 | .RS 0.25i | |
2473 | .PP | |
2474 | .B filename\fR \fB"\fR\fIfilename\fR\fB";\fR | |
2475 | .PP | |
2476 | The \fIfilename\fR statement can be used to specify the name of the | |
2477 | initial boot file which is to be loaded by a client. The | |
2478 | .I filename | |
2479 | should be a filename recognizable to whatever file transfer protocol | |
2480 | the client can be expected to use to load the file. | |
2481 | .RE | |
2482 | .PP | |
2483 | The | |
2484 | .I fixed-address | |
98311e4b | 2485 | declaration |
5cc21fb3 TL |
2486 | .RS 0.25i |
2487 | .PP | |
2488 | .B fixed-address address\fR [\fB,\fR \fIaddress\fR ... ]\fB;\fR | |
2489 | .PP | |
98311e4b | 2490 | The \fIfixed-address\fR declaration is used to assign one or more fixed |
5cc21fb3 TL |
2491 | IP addresses to a client. It should only appear in a \fIhost\fR |
2492 | declaration. If more than one address is supplied, then when the | |
98311e4b | 2493 | client boots, it will be assigned the address that corresponds to the |
5cc21fb3 | 2494 | network on which it is booting. If none of the addresses in the |
98311e4b DH |
2495 | \fIfixed-address\fR statement are valid for the network to which the client |
2496 | is connected, that client will not match the \fIhost\fR declaration | |
2497 | containing that \fIfixed-address\fR declaration. Each \fIaddress\fR | |
2498 | in the \fIfixed-address\fR declaration should be either an IP address or | |
2499 | a domain name that resolves to one or more IP addresses. | |
5cc21fb3 TL |
2500 | .RE |
2501 | .PP | |
2502 | The | |
98bd7ca0 DH |
2503 | .I fixed-address6 |
2504 | declaration | |
2505 | .RS 0.25i | |
2506 | .PP | |
2507 | .B fixed-address6 ip6-address\fR ;\fR | |
2508 | .PP | |
2509 | The \fIfixed-address6\fR declaration is used to assign a fixed | |
2510 | IPv6 addresses to a client. It should only appear in a \fIhost\fR | |
2511 | declaration. | |
2512 | .RE | |
2513 | .PP | |
2514 | The | |
34711bb7 SR |
2515 | .I fixed-prefix6 |
2516 | declaration | |
2517 | .RS 0.25i | |
2518 | .PP | |
2519 | .B fixed-prefix6\fR \fIlow-address\fR \fB/\fR \fIbits\fR\fB;\fR | |
2520 | .PP | |
2521 | The \fIfixed-prefix6\fR declaration is used to assign a fixed | |
2522 | IPv6 prefix to a client. It should only appear in a \fIhost\fR | |
2523 | declaration, but multiple \fIfixed-prefix6\fR statements may appear | |
2524 | in a single \fIhost\fR declaration. | |
2525 | .PP | |
2526 | The \fIlow-address\fR specifies the start of the prefix and the \fIbits\fR | |
2527 | specifies the size of the prefix in bits. | |
2528 | .PP | |
2529 | If there are multiple prefixes for a given host entry the server will | |
2530 | choose one that matches the requested prefix size or, if none match, | |
2531 | the first one. | |
2532 | .PP | |
4dd0eb18 | 2533 | If there are multiple \fIhost\fR declarations the server will try to |
34711bb7 SR |
2534 | choose a declaration where the \fIfixed-address6\fR matches the client's |
2535 | subnet. If none match it will choose one that doesn't have a \fIfixed-address6\fR | |
2536 | statement. | |
2537 | .PP | |
2538 | Note Well: Unlike the fixed address the fixed prefix does not need to match | |
2539 | a subnet in order to be served. This allows you to provide a prefix to | |
2540 | a client that is outside of the subnet on which the client makes the request | |
2541 | to the the server. | |
2542 | .RE | |
2543 | .PP | |
2544 | The | |
5cc21fb3 | 2545 | .I get-lease-hostnames |
3c807354 TL |
2546 | statement |
2547 | .RS 0.25i | |
5fea7b10 | 2548 | .PP |
3c807354 | 2549 | .B get-lease-hostnames\fR \fIflag\fR\fB;\fR |
5fea7b10 TL |
2550 | .PP |
2551 | The \fIget-lease-hostnames\fR statement is used to tell dhcpd whether | |
2552 | or not to look up the domain name corresponding to the IP address of | |
2553 | each address in the lease pool and use that address for the DHCP | |
2554 | \fIhostname\fR option. If \fIflag\fR is true, then this lookup is | |
a0497ac5 | 2555 | done for all addresses in the current scope. By default, or if |
5fea7b10 | 2556 | \fIflag\fR is false, no lookups are done. |
3c807354 | 2557 | .RE |
c256bae9 | 2558 | .PP |
417b7b4a | 2559 | The |
5cc21fb3 | 2560 | .I hardware |
3c807354 TL |
2561 | statement |
2562 | .RS 0.25i | |
c256bae9 | 2563 | .PP |
5cc21fb3 | 2564 | .B hardware \fIhardware-type hardware-address\fB;\fR |
c256bae9 | 2565 | .PP |
5cc21fb3 TL |
2566 | In order for a BOOTP client to be recognized, its network hardware |
2567 | address must be declared using a \fIhardware\fR clause in the | |
2568 | .I host | |
2569 | statement. | |
2570 | .I hardware-type | |
a0497ac5 | 2571 | must be the name of a physical hardware interface type. Currently, |
5cc21fb3 TL |
2572 | only the |
2573 | .B ethernet | |
2574 | and | |
2575 | .B token-ring | |
2576 | types are recognized, although support for a | |
2577 | .B fddi | |
2578 | hardware type (and others) would also be desirable. | |
2579 | The | |
2580 | .I hardware-address | |
2581 | should be a set of hexadecimal octets (numbers from 0 through ff) | |
a0497ac5 | 2582 | separated by colons. The \fIhardware\fR statement may also be used |
5cc21fb3 TL |
2583 | for DHCP clients. |
2584 | .RE | |
c256bae9 | 2585 | .PP |
417b7b4a | 2586 | The |
98bd7ca0 DH |
2587 | .I host-identifier option |
2588 | statement | |
2589 | .RS 0.25i | |
2590 | .PP | |
2591 | .B host-identifier option \fIoption-name option-data\fB;\fR | |
2592 | .PP | |
619304cd SR |
2593 | or |
2594 | .PP | |
2595 | .B host-identifier v6relopt \fInumber option-name option-data\fB;\fR | |
2596 | .PP | |
98bd7ca0 DH |
2597 | This identifies a DHCPv6 client in a |
2598 | .I host | |
2599 | statement. | |
2600 | .I option-name | |
417b7b4a | 2601 | is any option, and |
98bd7ca0 | 2602 | .I option-data |
417b7b4a | 2603 | is the value for the option that the client will send. The |
98bd7ca0 | 2604 | .I option-data |
619304cd SR |
2605 | must be a constant value. In the v6relopts case the additional number |
2606 | is the relay to examine for the specified option name and value. The | |
2607 | values are the same as for the v6relay option. 0 is a no-op, 1 is the | |
2608 | relay closest to the client, 2 the next one in and so on. Values that | |
2609 | are larger than the maximum number of relays (currently 32) indicate the | |
2610 | relay closest to the server independent of number. | |
98bd7ca0 DH |
2611 | .RE |
2612 | .PP | |
417b7b4a | 2613 | The |
38ee81bd SR |
2614 | .I ignore-client-uids |
2615 | statement | |
2616 | .RS 0.25i | |
2617 | .PP | |
2618 | .B ignore-client-uids \fIflag\fB;\fR | |
2619 | .PP | |
2620 | If the \fIignore-client-uids\fR statement is present and has a value of | |
2621 | \fItrue\fR or \fIon\fR, the UID for clients will not be recorded. | |
2622 | If this statement is not present or has a value of \fIfalse\fR or | |
417b7b4a | 2623 | \fIoff\fR, then client UIDs will be recorded. |
38ee81bd SR |
2624 | .RE |
2625 | .PP | |
5cc21fb3 | 2626 | The |
1db5e2c0 DH |
2627 | .I infinite-is-reserved |
2628 | statement | |
2629 | .RS 0.25i | |
2630 | .PP | |
2631 | .B infinite-is-reserved \fIflag\fB;\fR | |
2632 | .PP | |
5a38e43f | 2633 | ISC DHCP now supports \'reserved\' leases. See the section on RESERVED LEASES |
1db5e2c0 DH |
2634 | below. If this \fIflag\fR is on, the server will automatically reserve leases |
2635 | allocated to clients which requested an infinite (0xffffffff) lease-time. | |
2636 | .PP | |
2637 | The default is off. | |
2638 | .RE | |
2639 | .PP | |
2640 | The | |
5cc21fb3 TL |
2641 | .I lease-file-name |
2642 | statement | |
2643 | .RS 0.25i | |
c256bae9 | 2644 | .PP |
5cc21fb3 | 2645 | .B lease-file-name \fIname\fB;\fR |
d250c5b9 | 2646 | .PP |
5cc21fb3 | 2647 | .I Name |
ab77c8b8 TM |
2648 | Where \fIname\fR is the name of the DHCP server's lease file. By default, |
2649 | this is DBDIR/dhcpd.leases. This statement \fBmust\fR appear in the outer | |
2650 | scope of the configuration file - if it appears in some other scope, it will | |
2651 | have no effect. The value must be the absolute path of the file to use. | |
2652 | The order of precedence the server uses for the lease file name | |
2653 | is: | |
2654 | .PP | |
2655 | 1. \fBlease-file-name\fR configuration file statement. | |
2656 | 2. \fB-lf\fR command line flag. | |
2657 | 3. \fBPATH_DHCPD_DB\fR environment variable. | |
b024480e DH |
2658 | .RE |
2659 | .PP | |
2660 | The | |
75135a3f EH |
2661 | .I dhcpv6-lease-file-name |
2662 | statement | |
2663 | .RS 0.25i | |
2664 | .PP | |
2665 | .B dhcpv6-lease-file-name \fIname\fB;\fR | |
2666 | .PP | |
ab77c8b8 TM |
2667 | Where \fIname\fR is the name of the DHCP server's lease file when the server |
2668 | is running DHCPv6. By default, this is DBDIR/dhcpd6.leases. This statement | |
2669 | \fBmust\fR appear in the outer scope of the configuration file - if it appears | |
2670 | in some other scope, it will have no effect. The value must be the absolute | |
2671 | path of the file to use. The order of precedence the server uses | |
2672 | for the lease file name is: | |
2673 | .PP | |
2674 | 1. \fBdhcpv6-lease-file-name\fR configuration file statement. | |
2675 | 2. \fB-lf\fR command line flag. | |
2676 | 3. \fBPATH_DHCPD6_DB\fR environment variable. | |
3c807354 TL |
2677 | .RE |
2678 | .PP | |
2679 | The | |
cc1bd34e TM |
2680 | .I lease-id-format |
2681 | parameter | |
2682 | .RS 0.25i | |
2683 | .PP | |
2684 | .B lease-id-format \fIformat\fB;\fR | |
2685 | .PP | |
2686 | The \fIformat\fR parameter must be either \fBoctal\fR or \fBhex\fR. | |
2687 | This parameter governs the format used to write certain values to lease | |
2688 | files. With the default format, octal, values are written as quoted strings in | |
2689 | which non-printable characters are represented as octal escapes - | |
2690 | a backslash character followed by three octal digits. When the hex format | |
2691 | is specified, values are written as an unquoted series of pairs of | |
2692 | hexadecimal digits, separated by colons. | |
2693 | ||
2694 | Currently, the values written out based on lease-id-format are the server-duid, | |
2695 | the uid (DHCPv4 leases), and the IAID_DUID (DHCPv6 leases). Note the server | |
2696 | automatically reads the values in either format. | |
2697 | .RE | |
2698 | .PP | |
2699 | The | |
ab77c8b8 TM |
2700 | .I limit-addrs-per-ia |
2701 | statement | |
2702 | .RS 0.25i | |
2703 | .PP | |
2704 | .B limit-addrs-per-ia \fInumber\fB;\fR | |
2705 | .PP | |
2706 | By default, the DHCPv6 server will limit clients to one IAADDR per IA | |
2707 | option, meaning one address. If you wish to permit clients to hang onto | |
2708 | multiple addresses at a time, configure a larger \fInumber\fR here. | |
2709 | .PP | |
2710 | Note that there is no present method to configure the server to forcibly | |
2711 | configure the client with one IP address per each subnet on a shared network. | |
2712 | This is left to future work. | |
2713 | .RE | |
2714 | .PP | |
2715 | The | |
5cc21fb3 | 2716 | .I local-port |
3c807354 TL |
2717 | statement |
2718 | .RS 0.25i | |
c43fe218 | 2719 | .PP |
5cc21fb3 | 2720 | .B local-port \fIport\fB;\fR |
c43fe218 | 2721 | .PP |
5cc21fb3 TL |
2722 | This statement causes the DHCP server to listen for DHCP requests on |
2723 | the UDP port specified in \fIport\fR, rather than on port 67. | |
2724 | .RE | |
c43fe218 | 2725 | .PP |
5cc21fb3 | 2726 | The |
98311e4b DH |
2727 | .I local-address |
2728 | statement | |
2729 | .RS 0.25i | |
2730 | .PP | |
2731 | .B local-address \fIaddress\fB;\fR | |
2732 | .PP | |
2733 | This statement causes the DHCP server to listen for DHCP requests sent | |
2734 | to the specified \fIaddress\fR, rather than requests sent to all addresses. | |
2735 | Since serving directly attached DHCP clients implies that the server must | |
2736 | respond to requests sent to the all-ones IP address, this option cannot be | |
8e112e2b | 2737 | used if clients are on directly attached networks; it is only realistically |
98311e4b DH |
2738 | useful for a server whose only clients are reached via unicasts, such as via |
2739 | DHCP relay agents. | |
2740 | .PP | |
2741 | Note: This statement is only effective if the server was compiled using | |
2742 | the USE_SOCKETS #define statement, which is default on a small number of | |
2743 | operating systems, and must be explicitly chosen at compile-time for all | |
2744 | others. You can be sure if your server is compiled with USE_SOCKETS if | |
2745 | you see lines of this format at startup: | |
2746 | .PP | |
2747 | Listening on Socket/eth0 | |
2748 | .PP | |
2749 | Note also that since this bind()s all DHCP sockets to the specified | |
2750 | address, that only one address may be supported in a daemon at a given | |
2751 | time. | |
2752 | .RE | |
2753 | .PP | |
2754 | The | |
a2a0f98c FD |
2755 | .I local-address6 |
2756 | and | |
2757 | .I bind-local-address6 | |
2758 | statements | |
2759 | .RS 0.25i | |
2760 | .PP | |
2761 | .B local-address6 \fIaddress\fB;\fR | |
2762 | .PP | |
2763 | .B bind-local-address6 \fIflag\fB;\fR | |
2764 | .PP | |
2765 | The \fIlocal-address6\fR statement causes the DHCP server to send IPv6 | |
2766 | packets as originating from the specified IPv6 \fIaddress\fR, rather than | |
2767 | leaving the kernel to fill in the source address field. | |
2768 | .PP | |
2769 | When \fIbind-local-address6\fR is present and has a value of true or on, | |
2770 | service sockets are bound to \fIaddress\fR too. | |
2771 | .PP | |
2772 | By default \fIaddress\fR is the undefined address and the | |
2773 | \fIbind-local-address6\fR is disabled, both may only be set at the global | |
2774 | scope. | |
2775 | .RE | |
2776 | .PP | |
2777 | The | |
d83e416e TL |
2778 | .I log-facility |
2779 | statement | |
2780 | .RS 0.25i | |
2781 | .PP | |
2782 | .B log-facility \fIfacility\fB;\fR | |
2783 | .PP | |
2784 | This statement causes the DHCP server to do all of its logging on the | |
a0497ac5 SR |
2785 | specified log facility once the dhcpd.conf file has been read. By |
2786 | default the DHCP server logs to the daemon facility. Possible log | |
d83e416e TL |
2787 | facilities include auth, authpriv, cron, daemon, ftp, kern, lpr, mail, |
2788 | mark, news, ntp, security, syslog, user, uucp, and local0 through | |
a0497ac5 | 2789 | local7. Not all of these facilities are available on all systems, |
d83e416e TL |
2790 | and there may be other facilities available on other systems. |
2791 | .PP | |
2792 | In addition to setting this value, you may need to modify your | |
2793 | .I syslog.conf | |
a0497ac5 | 2794 | file to configure logging of the DHCP server. For example, you might |
d83e416e TL |
2795 | add a line like this: |
2796 | .PP | |
2797 | .nf | |
2798 | local7.debug /var/log/dhcpd.log | |
2799 | .fi | |
2800 | .PP | |
2801 | The syntax of the \fIsyslog.conf\fR file may be different on some | |
2802 | operating systems - consult the \fIsyslog.conf\fR manual page to be | |
2803 | sure. To get syslog to start logging to the new file, you must first | |
2804 | create the file with correct ownership and permissions (usually, the | |
2805 | same owner and permissions of your /var/log/messages or | |
2806 | /usr/adm/messages file should be fine) and send a SIGHUP to syslogd. | |
2807 | Some systems support log rollover using a shell script or program | |
0e74ff1f TL |
2808 | called newsyslog or logrotate, and you may be able to configure this |
2809 | as well so that your log file doesn't grow uncontrollably. | |
d83e416e TL |
2810 | .PP |
2811 | Because the \fIlog-facility\fR setting is controlled by the dhcpd.conf | |
2812 | file, log messages printed while parsing the dhcpd.conf file or before | |
2813 | parsing it are logged to the default log facility. To prevent this, | |
2814 | see the README file included with this distribution, which describes | |
8e112e2b | 2815 | BUG: where is that mentioned in README? |
d83e416e TL |
2816 | how to change the default log facility. When this parameter is used, |
2817 | the DHCP server prints its startup message a second time after parsing | |
2818 | the configuration file, so that the log will be as complete as | |
2819 | possible. | |
2820 | .RE | |
2821 | .PP | |
2822 | The | |
250f7134 | 2823 | .I log-threshold-high |
417b7b4a | 2824 | and |
250f7134 SR |
2825 | .I log-threshold-low |
2826 | statements | |
2827 | .RS 0.25i | |
2828 | .PP | |
2829 | .B log-threshold-high \fIpercentage\fB;\fR | |
2830 | .PP | |
2831 | .B log-threshold-low \fIpercentage\fB;\fR | |
2832 | .PP | |
2833 | The \fIlog-threshold-low\fR and \fIlog-threshold-high\fR statements | |
2834 | are used to control when a message is output about pool usage. The | |
2835 | value for both of them is the percentage of the pool in use. If the | |
2836 | high threshold is 0 or has not been specified, no messages will be | |
2837 | produced. If a high threshold is given, a message is output once the | |
2838 | pool usage passes that level. After that, no more messages will be | |
2839 | output until the pool usage falls below the low threshold. If the low | |
2840 | threshold is not given, it default to a value of zero. | |
2841 | .PP | |
2842 | A special case occurs when the low threshold is set to be higer than | |
2843 | the high threshold. In this case, a message will be generated each time | |
2844 | a lease is acknowledged when the pool usage is above the high threshold. | |
fb98e02e TM |
2845 | .PP |
2846 | Note that threshold logging will be automatically disabled for shared | |
2847 | subnets whose total number of addresses is larger than (2^64)-1. The server | |
2848 | will emit a log statement at startup when threshold logging is disabled as | |
2849 | shown below: | |
2850 | ||
2851 | "Threshold logging disabled for shared subnet of ranges: <addresses>" | |
2852 | ||
2853 | This is likely to have no practical runtime effect as CPUs are unlikely | |
2854 | to support a server actually reaching such a large number of leases. | |
250f7134 SR |
2855 | .RE |
2856 | .PP | |
2857 | The | |
5cc21fb3 TL |
2858 | .I max-lease-time |
2859 | statement | |
2860 | .RS 0.25i | |
007e3ee4 | 2861 | .PP |
5cc21fb3 | 2862 | .B max-lease-time \fItime\fR\fB;\fR |
007e3ee4 | 2863 | .PP |
5cc21fb3 TL |
2864 | .I Time |
2865 | should be the maximum length in seconds that will be assigned to a | |
5a38e43f SR |
2866 | lease. |
2867 | If not defined, the default maximum lease time is 86400. | |
2868 | The only exception to this is that Dynamic BOOTP lease | |
5cc21fb3 TL |
2869 | lengths, which are not specified by the client, are not limited by |
2870 | this maximum. | |
2871 | .RE | |
c43fe218 | 2872 | .PP |
5cc21fb3 TL |
2873 | The |
2874 | .I min-lease-time | |
2875 | statement | |
2876 | .RS 0.25i | |
2877 | .PP | |
2878 | .B min-lease-time \fItime\fR\fB;\fR | |
2879 | .PP | |
2880 | .I Time | |
2881 | should be the minimum length in seconds that will be assigned to a | |
2882 | lease. | |
417b7b4a | 2883 | The default is the minimum of 300 seconds or |
5a38e43f | 2884 | \fBmax-lease-time\fR. |
3c807354 | 2885 | .RE |
c43fe218 | 2886 | .PP |
3c807354 | 2887 | The |
5cc21fb3 | 2888 | .I min-secs |
3c807354 TL |
2889 | statement |
2890 | .RS 0.25i | |
41885489 | 2891 | .PP |
5cc21fb3 | 2892 | .B min-secs \fIseconds\fR\fB;\fR |
41885489 | 2893 | .PP |
5cc21fb3 TL |
2894 | .I Seconds |
2895 | should be the minimum number of seconds since a client began trying to | |
2896 | acquire a new lease before the DHCP server will respond to its request. | |
2897 | The number of seconds is based on what the client reports, and the maximum | |
a0497ac5 | 2898 | value that the client can report is 255 seconds. Generally, setting this |
5cc21fb3 TL |
2899 | to one will result in the DHCP server not responding to the client's first |
2900 | request, but always responding to its second request. | |
41885489 | 2901 | .PP |
5cc21fb3 TL |
2902 | This can be used |
2903 | to set up a secondary DHCP server which never offers an address to a client | |
a0497ac5 | 2904 | until the primary server has been given a chance to do so. If the primary |
5cc21fb3 | 2905 | server is down, the client will bind to the secondary server, but otherwise |
a0497ac5 | 2906 | clients should always bind to the primary. Note that this does not, by |
5cc21fb3 TL |
2907 | itself, permit a primary server and a secondary server to share a pool of |
2908 | dynamically-allocatable addresses. | |
3c807354 | 2909 | .RE |
41885489 | 2910 | .PP |
3c807354 | 2911 | The |
5cc21fb3 | 2912 | .I next-server |
3c807354 TL |
2913 | statement |
2914 | .RS 0.25i | |
b1c231ba | 2915 | .PP |
5cc21fb3 | 2916 | .B next-server\fR \fIserver-name\fR\fB;\fR |
b1c231ba | 2917 | .PP |
5cc21fb3 TL |
2918 | The \fInext-server\fR statement is used to specify the host address of |
2919 | the server from which the initial boot file (specified in the | |
a0497ac5 | 2920 | \fIfilename\fR statement) is to be loaded. \fIServer-name\fR should |
88cd8aca | 2921 | be a numeric IP address or a domain name. |
5cc21fb3 TL |
2922 | .RE |
2923 | .PP | |
2924 | The | |
2925 | .I omapi-port | |
2926 | statement | |
2927 | .RS 0.25i | |
2928 | .PP | |
2929 | .B omapi-port\fR \fIport\fR\fB;\fR | |
2930 | .PP | |
2931 | The \fIomapi-port\fR statement causes the DHCP server to listen for | |
a0497ac5 | 2932 | OMAPI connections on the specified port. This statement is required |
5cc21fb3 TL |
2933 | to enable the OMAPI protocol, which is used to examine and modify the |
2934 | state of the DHCP server as it is running. | |
3c807354 | 2935 | .RE |
b1c231ba | 2936 | .PP |
3c807354 | 2937 | The |
600d4b35 | 2938 | .I one-lease-per-client |
3c807354 TL |
2939 | statement |
2940 | .RS 0.25i | |
600d4b35 | 2941 | .PP |
3c807354 | 2942 | .B one-lease-per-client \fIflag\fR\fB;\fR |
600d4b35 TL |
2943 | .PP |
2944 | If this flag is enabled, whenever a client sends a DHCPREQUEST for a | |
2945 | particular lease, the server will automatically free any other leases | |
a0497ac5 | 2946 | the client holds. This presumes that when the client sends a |
600d4b35 TL |
2947 | DHCPREQUEST, it has forgotten any lease not mentioned in the |
2948 | DHCPREQUEST - i.e., the client has only a single network interface | |
2949 | .I and | |
2950 | it does not remember leases it's holding on networks to which it is | |
a0497ac5 | 2951 | not currently attached. Neither of these assumptions are guaranteed |
600d4b35 | 2952 | or provable, so we urge caution in the use of this statement. |
3c807354 | 2953 | .RE |
600d4b35 | 2954 | .PP |
3c807354 | 2955 | The |
c2e5ee28 TM |
2956 | .I persist-eui-64-leases |
2957 | statement | |
2958 | .RS 0.25i | |
2959 | .PP | |
2960 | .B persist-eui-64-leases \fIflag\fR\fB;\fR | |
2961 | .PP | |
2962 | When this flag is enabled, the server will write EUI-64 based leases to the | |
2963 | leases file. Since such leases can only, ever be valid for a single DUID value | |
2964 | it can be argued that writing them to the leases file isn't essential and not | |
2965 | doing so may have perfomance advantages. See \fIuse-eui-64\fR statement for | |
2966 | more details on EUI-64 based address allocation. The flag is enabled by | |
2967 | default and may only be set at the global scope. | |
2968 | .RE | |
2969 | .PP | |
2970 | The | |
5cc21fb3 | 2971 | .I pid-file-name |
3c807354 TL |
2972 | statement |
2973 | .RS 0.25i | |
cdd70b87 | 2974 | .PP |
5cc21fb3 TL |
2975 | .B pid-file-name |
2976 | .I name\fR\fB;\fR | |
cdd70b87 | 2977 | .PP |
5cc21fb3 | 2978 | .I Name |
a0497ac5 | 2979 | should be the name of the DHCP server's process ID file. This is the |
5cc21fb3 | 2980 | file in which the DHCP server's process ID is stored when the server |
ab77c8b8 TM |
2981 | starts. By default, this is RUNDIR/dhcpd.pid. Like the \fIlease-file-name\fR |
2982 | statement, this statement must appear in the outer scope of the configuration | |
2983 | file. The order of precedence used by the server is: | |
2984 | .PP | |
2985 | 1. \fBpid-file-name\fR configuration file statement. | |
2986 | 2. \fB-lf\fR command line flag. | |
2987 | 3. \fBPATH_DHCPD_PID\fR environment variable. | |
75135a3f EH |
2988 | .PP |
2989 | The | |
2990 | .I dhcpv6-pid-file-name | |
2991 | statement | |
2992 | .RS 0.25i | |
2993 | .PP | |
2994 | .B dhcpv6-pid-file-name \fIname\fB;\fR | |
2995 | .PP | |
2996 | .I Name | |
2997 | is the name of the pid file to use if and only if the server is running | |
2998 | in DHCPv6 mode. By default, this is DBDIR/dhcpd6.pid. This statement, | |
ab77c8b8 TM |
2999 | like \fIpid-file-name\fr, \fBmust\fR appear in the outer scope of the |
3000 | configuration file. The order of precedence used by the server is: | |
3001 | .PP | |
3002 | 1. \fBdhcpv6-pid-file-name\fR configuration file statement. | |
3003 | 2. \fB-lf\fR command line flag. | |
3004 | 3. \fBPATH_DHCPD6_PID\fR environment variable. | |
3005 | .PP | |
3c807354 | 3006 | .RE |
cdd70b87 | 3007 | .PP |
3c807354 | 3008 | The |
252bb0e4 | 3009 | .I ping-check |
abf0a2ab TL |
3010 | statement |
3011 | .RS 0.25i | |
3012 | .PP | |
252bb0e4 | 3013 | .B ping-check |
abf0a2ab TL |
3014 | .I flag\fR\fB;\fR |
3015 | .PP | |
3016 | When the DHCP server is considering dynamically allocating an IP | |
3017 | address to a client, it first sends an ICMP Echo request (a \fIping\fR) | |
a0497ac5 SR |
3018 | to the address being assigned. It waits for a second, and if no |
3019 | ICMP Echo response has been heard, it assigns the address. If a | |
abf0a2ab | 3020 | response \fIis\fR heard, the lease is abandoned, and the server does |
a5252220 TM |
3021 | not respond to the client. The lease will remain abandoned for a minimum |
3022 | of abandon-lease-time seconds. | |
3023 | .PP | |
3024 | If a there are no free addressses but there are abandoned IP addresses, the | |
3025 | DHCP server will attempt to reclaim an abandoned IP address regardless of the | |
3026 | value of abandon-lease-time. | |
abf0a2ab | 3027 | .PP |
98311e4b | 3028 | This \fIping check\fR introduces a default one-second delay in responding |
a0497ac5 | 3029 | to DHCPDISCOVER messages, which can be a problem for some clients. The |
98311e4b DH |
3030 | default delay of one second may be configured using the ping-timeout |
3031 | parameter. The ping-check configuration parameter can be used to control | |
3032 | checking - if its value is false, no ping check is done. | |
3033 | .RE | |
3034 | .PP | |
3035 | The | |
a5b21e16 TM |
3036 | .I ping-cltt-secs |
3037 | statement | |
3038 | .RS 0.25i | |
3039 | .PP | |
3040 | .B ping-cltt-secs | |
3041 | .I seconds\fR\fB;\fR | |
3042 | .PP | |
3043 | The server will conduct a ping check if all the following conditions are true: | |
3044 | .PP | |
3045 | 1. Ping checking is enabled. | |
3046 | .PP | |
3047 | 2. The server is responding to a DISCOVER. | |
3048 | .PP | |
3049 | 3. The lease to be offered is neither static nor active (i.e. still a valid | |
3050 | lease). | |
3051 | .PP | |
3052 | 4. And any of the following are true: | |
3053 | a. This will be the first offer of this lease (CLTT is 0). | |
3054 | b. The lease is being offered to a client other than its previous owner | |
3055 | c. The lease is being offered to its previous owner and more than | |
3056 | \fBping-cltt-secs\fR have elapsed since CLTT of the original lease. | |
3057 | d. The lease was abandoned and the server is attempting to reclaim it. | |
3058 | ||
3059 | .PP | |
3060 | The \fBping-cltt-secs\fR statement allows the user to specify the amount of | |
3061 | time that must elaspe after CLTT before a ping check will be conducted. | |
3062 | The default value is sixty seconds. | |
3063 | .RE | |
3064 | .PP | |
3065 | The | |
98311e4b DH |
3066 | .I ping-timeout |
3067 | statement | |
3068 | .RS 0.25i | |
3069 | .PP | |
3070 | .B ping-timeout | |
3071 | .I seconds\fR\fB;\fR | |
3072 | .PP | |
3073 | If the DHCP server determined it should send an ICMP echo request (a | |
3074 | \fIping\fR) because the ping-check statement is true, ping-timeout allows | |
3075 | you to configure how many seconds the DHCP server should wait for an | |
3076 | ICMP Echo response to be heard, if no ICMP Echo response has been received | |
3077 | before the timeout expires, it assigns the address. If a response \fIis\fR | |
3078 | heard, the lease is abandoned, and the server does not respond to the client. | |
e6eccd10 TM |
3079 | If no value is set, ping-timeout defaults to 1 second. (See also ping-timeout-ms |
3080 | below) | |
3081 | .RE | |
5918b493 | 3082 | .PP |
e6eccd10 TM |
3083 | The |
3084 | .I ping-timeout-ms | |
3085 | statement | |
3086 | .RS 0.25i | |
3087 | .PP | |
3088 | .B ping-timeout-ms | |
3089 | .I milliseconds\fR\fB;\fR | |
3090 | .PP | |
3091 | Allows you to specify the ping timeout in milliseconds rather than | |
3092 | seconds. If this value is greater than zero, the server will use it | |
3093 | in place of ping-timeout. The default value is zero. | |
abf0a2ab TL |
3094 | .RE |
3095 | .PP | |
3096 | The | |
98bd7ca0 DH |
3097 | .I preferred-lifetime |
3098 | statement | |
3099 | .RS 0.25i | |
3100 | .PP | |
3101 | .B preferred-lifetime | |
3102 | .I seconds\fR\fB;\fR | |
3103 | .PP | |
5a38e43f | 3104 | IPv6 addresses have \'valid\' and \'preferred\' lifetimes. The valid lifetime |
98bd7ca0 DH |
3105 | determines at what point at lease might be said to have expired, and is no |
3106 | longer useable. A preferred lifetime is an advisory condition to help | |
3107 | applications move off of the address and onto currently valid addresses | |
3108 | (should there still be any open TCP sockets or similar). | |
3109 | .PP | |
dce576b8 | 3110 | The preferred lifetime defaults to 5/8 the default lease time. |
98bd7ca0 DH |
3111 | .RE |
3112 | .PP | |
3113 | The | |
1a006ff6 TM |
3114 | .I prefix-length-mode |
3115 | statement | |
3116 | .RS 0.25i | |
3117 | .PP | |
3118 | .B prefix-length-mode | |
3119 | .I mode\fR\fB;\fR | |
3120 | .PP | |
3121 | According to RFC 3633, DHCPv6 clients may specify preferences when soliciting | |
3122 | prefixes by including an IA_PD Prefix option within the IA_PD option. Among | |
3123 | the preferences that may be conveyed is the "prefix-length". When non-zero it | |
3124 | indicates a client's desired length for offered prefixes. The RFC states that | |
3125 | servers "MAY choose to use the information...to select prefix(es)" but does | |
3126 | not specify any particular rules for doing so. The prefix-length-mode statement | |
3127 | can be used to set the prefix selection rules employed by the server, | |
3128 | when clients send a non-zero prefix-length value. The mode parameter must | |
3129 | be one of \fBignore\fR, \fBprefer\fR, \fBexact\fR, \fBminimum\fR, or | |
3130 | \fBmaximum\fR where: | |
3131 | .PP | |
3132 | 1. ignore - The requested length is ignored. The server will offer the first | |
3133 | available prefix. | |
3134 | .PP | |
3135 | 2. prefer - The server will offer the first available prefix with the same | |
3136 | length as the requested length. If none are found then it will offer the | |
b53ba157 | 3137 | first available prefix of any length. This is the default behavior. |
1a006ff6 TM |
3138 | .PP |
3139 | 3. exact - The server will offer the first available prefix with the same | |
3140 | length as the requested length. If none are found, it will return a status | |
b53ba157 | 3141 | indicating no prefixes available. |
1a006ff6 TM |
3142 | .PP |
3143 | 4. minimum - The server will offer the first available prefix with the same | |
3144 | length as the requested length. If none are found, it will return the first | |
3145 | available prefix whose length is greater than (e.g. longer than), the | |
3146 | requested value. If none of those are found, it will return a status | |
3147 | indicating no prefixes available. For example, if client requests a length | |
3148 | of /60, and the server has available prefixes of lengths /56 and /64, it will | |
3149 | offer prefix of length /64. | |
3150 | .PP | |
3151 | 5. maximum - The server will offer the first available prefix with the same | |
3152 | length as the requested length. If none are found, it will return the first | |
3153 | available prefix whose length is less than (e.g. shorter than), the | |
3154 | requested value. If none of those are found, it will return a status | |
3155 | indicating no prefixes available. For example, if client requests a length | |
3156 | of /60, and the server has available prefixes of lengths /56 and /64, it will | |
3157 | offer a prefix of length /56. | |
3158 | .PP | |
3159 | In general "first available" is determined by the order in which pools are | |
3160 | defined in the server's configuration. For example, if a subnet is defined | |
3161 | with three prefix pools A,B, and C: | |
3162 | .PP | |
3163 | .nf | |
3164 | subnet 3000::/64 { | |
3165 | # pool A | |
3166 | pool6 { | |
3167 | : | |
3168 | } | |
3169 | # pool B | |
3170 | pool6 { | |
3171 | : | |
3172 | } | |
417b7b4a | 3173 | # pool C |
1a006ff6 TM |
3174 | pool6 { |
3175 | : | |
3176 | } | |
3177 | } | |
3178 | .fi | |
3179 | .PP | |
3180 | then the pools will be checked in the order A, B, C. For modes \fBprefer\fR, | |
3181 | \fBminimum\fR, and \fBmaximum\fR this may mean checking the pools in that order | |
3182 | twice. A first pass through is made looking for an available prefix of exactly | |
3183 | the preferred length. If none are found, then a second pass is performed | |
3184 | starting with pool A but with appropriately adjusted length criteria. | |
3185 | .RE | |
3186 | .PP | |
3187 | The | |
bafa7b74 TM |
3188 | .I release-on-roam |
3189 | statement | |
3190 | .RS 0.25i | |
3191 | .PP | |
3192 | .B release-on-roam \fIflag\fB;\fR | |
3193 | .PP | |
3194 | When enabled and the dhcpd server detects that a DHCPv6 client (IAID+DUID) | |
3195 | has roamed to a new network, it will release the pre-existing leases on the | |
3196 | old network and emit a log statement similiar to the following: | |
3197 | ||
3198 | "Client: <id> roamed to new network, releasing lease: <address>" | |
3199 | ||
3200 | The server will carry out all of the same steps that would normally occur | |
3201 | when a client explicitly releases a lease. When release-on-roam is disabled | |
3202 | (the default) the server makes such leases unavailable until they expire or | |
3203 | the server is restarted. Clients that need leases in multiple networks must | |
3204 | supply a unique IAID in each IA. This parameter may only be specified at | |
3205 | the global level. | |
3206 | .RE | |
3207 | .PP | |
3208 | The | |
3a16098f DH |
3209 | .I remote-port |
3210 | statement | |
3211 | .RS 0.25i | |
3212 | .PP | |
3213 | .B remote-port \fIport\fB;\fR | |
3214 | .PP | |
3215 | This statement causes the DHCP server to transmit DHCP responses to DHCP | |
3216 | clients upon the UDP port specified in \fIport\fR, rather than on port 68. | |
3217 | In the event that the UDP response is transmitted to a DHCP Relay, the | |
3218 | server generally uses the \fBlocal-port\fR configuration value. Should the | |
3219 | DHCP Relay happen to be addressed as 127.0.0.1, however, the DHCP Server | |
3220 | transmits its response to the \fBremote-port\fR configuration value. This | |
c759db75 | 3221 | is generally only useful for testing purposes, and this configuration value |
3a16098f DH |
3222 | should generally not be used. |
3223 | .RE | |
3224 | .PP | |
3225 | The | |
612bc350 | 3226 | .I server-identifier |
3c807354 TL |
3227 | statement |
3228 | .RS 0.25i | |
d250c5b9 | 3229 | .PP |
3c807354 | 3230 | .B server-identifier \fIhostname\fR\fB;\fR |
d250c5b9 | 3231 | .PP |
b13b05da | 3232 | The server-identifier statement can be used to define the value that |
a0497ac5 | 3233 | is sent in the DHCP Server Identifier option for a given scope. The |
b13b05da TL |
3234 | value specified \fBmust\fR be an IP address for the DHCP server, and |
3235 | must be reachable by all clients served by a particular scope. | |
3236 | .PP | |
3237 | The use of the server-identifier statement is not recommended - the only | |
3238 | reason to use it is to force a value other than the default value to be | |
a0497ac5 | 3239 | sent on occasions where the default value would be incorrect. The default |
b13b05da | 3240 | value is the first IP address associated with the physical network interface |
74f45f96 TL |
3241 | on which the request arrived. |
3242 | .PP | |
3243 | The usual case where the | |
b13b05da TL |
3244 | \fIserver-identifier\fR statement needs to be sent is when a physical |
3245 | interface has more than one IP address, and the one being sent by default | |
3246 | isn't appropriate for some or all clients served by that interface. | |
74f45f96 TL |
3247 | Another common case is when an alias is defined for the purpose of |
3248 | having a consistent IP address for the DHCP server, and it is desired | |
3249 | that the clients use this IP address when contacting the server. | |
3250 | .PP | |
3251 | Supplying a value for the dhcp-server-identifier option is equivalent | |
3252 | to using the server-identifier statement. | |
3c807354 | 3253 | .RE |
5cc21fb3 TL |
3254 | .PP |
3255 | The | |
7116a34f TM |
3256 | .I server-id-check |
3257 | statement | |
3258 | .RS 0.25i | |
3259 | .PP | |
3260 | .B server-id-check \fIflag\fR\fB;\fR | |
3261 | .PP | |
3262 | The server-id-check statement is used to control whether or not a server, | |
3263 | participating in failover, verifies that the value of the | |
3264 | dhcp-server-identifier option in received DHCP REQUESTs match the server's | |
3265 | id before processing the request. Server id checking is disabled by default. | |
3266 | Setting this flag enables id checking and thereafter the server will only | |
3267 | process requests that match. Note the flag setting should be consistent | |
3268 | between failover partners. | |
3269 | .PP | |
3270 | Unless overridden by use of the server-identifier statement, the value the | |
3271 | server uses as its id will be the first IP address associated with the | |
3272 | physical network interface on which the request arrived. | |
3273 | .PP | |
3274 | In order to reduce runtime overhead the server only checks for a server id | |
3275 | option in the global and subnet scopes. Complicated configurations | |
adb95d23 | 3276 | may result in different server ids for this check and when the server id for |
7116a34f TM |
3277 | a reply packet is determined, which would prohibit the server from responding. |
3278 | .PP | |
3279 | The primary use for this option is when a client broadcasts a request | |
3280 | but requires that the response come from a specific failover peer. | |
3281 | An example of this would be when a client reboots while its lease is still | |
3282 | active - in this case both servers will normally respond. Most of the | |
3283 | time the client won't check the server id and can use either of the responses. | |
3284 | However if the client does check the server id it may reject the response | |
3285 | if it came from the wrong peer. If the timing is such that the "wrong" | |
3286 | peer responds first most of the time the client may not get an address for | |
3287 | some time. | |
3288 | .PP | |
3289 | Care should be taken before enabling this option. | |
3290 | .PP | |
3291 | .RE | |
3292 | .PP | |
3293 | The | |
98bd7ca0 DH |
3294 | .I server-duid |
3295 | statement | |
3296 | .RS 0.25i | |
3297 | .PP | |
3298 | .B server-duid \fILLT\fR [ \fIhardware-type\fR \fItimestamp\fR \fIhardware-address\fR ] \fB;\fR | |
3299 | ||
3300 | .B server-duid \fIEN\fR \fIenterprise-number\fR \fIenterprise-identifier\fR \fB;\fR | |
3301 | ||
3302 | .B server-duid \fILL\fR [ \fIhardware-type\fR \fIhardware-address\fR ] \fB;\fR | |
3303 | .PP | |
3304 | The server-duid statement configures the server DUID. You may pick either | |
3305 | LLT (link local address plus time), EN (enterprise), or LL (link local). | |
3306 | .PP | |
3307 | If you choose LLT or LL, you may specify the exact contents of the DUID. | |
3308 | Otherwise the server will generate a DUID of the specified type. | |
3309 | .PP | |
3310 | If you choose EN, you must include the enterprise number and the | |
3311 | enterprise-identifier. | |
3312 | .PP | |
90a062fb SR |
3313 | If there is a server-duid statement in the lease file it will take precedence |
3314 | over the server-duid statement from the config file and a | |
3315 | dhcp6.server-id option in the config file will override both. | |
3316 | .PP | |
98bd7ca0 DH |
3317 | The default server-duid type is LLT. |
3318 | .RE | |
3319 | .PP | |
3320 | The | |
5cc21fb3 TL |
3321 | .I server-name |
3322 | statement | |
3323 | .RS 0.25i | |
3324 | .PP | |
3325 | .B server-name "\fIname\fB";\fR | |
3326 | .PP | |
3327 | The \fIserver-name\fR statement can be used to inform the client of | |
a0497ac5 | 3328 | the name of the server from which it is booting. \fIName\fR should |
5cc21fb3 TL |
3329 | be the name that will be provided to the client. |
3330 | .RE | |
3331 | .PP | |
3332 | The | |
dce576b8 TM |
3333 | .I dhcpv6-set-tee-times |
3334 | statement | |
3335 | .RS 0.25i | |
3336 | .PP | |
3337 | .B dhcpv6-set-tee-times\fR \fIflag\fR\fB;\fR | |
3338 | .PP | |
3339 | The \fIdhcpv6-set-tee-times\fR statement enables setting T1 and T2 to the | |
3340 | values recommended in RFC 3315 (Section 22.4). When setting T1 and T2, the | |
3341 | server will use dhcp-renewal-time and dhcp-rebinding-time, respectively. | |
3342 | A value of zero tells the client it may choose its own value. | |
3343 | ||
3344 | When those options are not defined then values will be set to zero unless the | |
905c58b9 | 3345 | global \fIdhcpv6-set-tee-times\fR is enabled. When this option is enabled the |
dce576b8 TM |
3346 | times are calculated as recommended by RFC 3315, Section 22.4: |
3347 | ||
3348 | T1 will be set to 0.5 times the shortest preferred lifetime | |
3349 | in the reply. If the "shortest" preferred lifetime is | |
3350 | 0xFFFFFFFF, T1 will set to 0xFFFFFFFF. | |
3351 | ||
3352 | T2 will be set to 0.8 times the shortest preferred lifetime | |
3353 | in the reply. If the "shortest" preferred lifetime is | |
3354 | 0xFFFFFFFF, T2 will set to 0xFFFFFFFF. | |
3355 | ||
3356 | Keep in mind that given sufficiently small lease lifetimes, the above | |
3357 | calculations will result in the two values being equal. For example, a 9 second | |
3358 | lease lifetime would yield T1 = T2 = 4 seconds, which would cause clients to | |
3359 | issue rebinds only. In such a case it would likely be better to explicitly | |
3360 | define the values. | |
3361 | ||
3362 | Note that dhcpv6-set-tee-times is intended to be transitional and will likely | |
3363 | be removed in a future release. Once removed the behavior will be to use | |
3364 | the configured values when present or calculate them per the RFC. If you want | |
3365 | zeros, define them as zeros. | |
3366 | .RE | |
3367 | .PP | |
3368 | The | |
5cc21fb3 TL |
3369 | .I site-option-space |
3370 | statement | |
3371 | .RS 0.25i | |
3372 | .PP | |
3373 | .B site-option-space "\fIname\fB";\fR | |
3374 | .PP | |
3375 | The \fIsite-option-space\fR statement can be used to determine from | |
a0497ac5 | 3376 | what option space site-local options will be taken. This can be used |
5cc21fb3 TL |
3377 | in much the same way as the \fIvendor-option-space\fR statement. |
3378 | Site-local options in DHCP are those options whose numeric codes are | |
a0497ac5 | 3379 | greater than 224. These options are intended for site-specific |
5cc21fb3 | 3380 | uses, but are frequently used by vendors of embedded hardware that |
a0497ac5 | 3381 | contains DHCP clients. Because site-specific options are allocated |
9f8b2a7f | 3382 | on an ad hoc basis, it is quite possible that one vendor's DHCP client |
5cc21fb3 | 3383 | might use the same option code that another vendor's client uses, for |
a0497ac5 | 3384 | different purposes. The \fIsite-option-space\fR option can be used |
5cc21fb3 | 3385 | to assign a different set of site-specific options for each such |
98311e4b | 3386 | vendor, using conditional evaluation (see \fBdhcp-eval (5)\fR for |
5cc21fb3 TL |
3387 | details). |
3388 | .RE | |
3389 | .PP | |
3390 | The | |
297c659c TL |
3391 | .I stash-agent-options |
3392 | statement | |
3393 | .RS 0.25i | |
3394 | .PP | |
3395 | .B stash-agent-options \fIflag\fB;\fR | |
3396 | .PP | |
3397 | If the \fIstash-agent-options\fR parameter is true for a given client, | |
3398 | the server will record the relay agent information options sent during | |
3399 | the client's initial DHCPREQUEST message when the client was in the | |
3400 | SELECTING state and behave as if those options are included in all | |
a0497ac5 | 3401 | subsequent DHCPREQUEST messages sent in the RENEWING state. This |
297c659c TL |
3402 | works around a problem with relay agent information options, which is |
3403 | that they usually not appear in DHCPREQUEST messages sent by the | |
3404 | client in the RENEWING state, because such messages are unicast | |
3405 | directly to the server and not sent through a relay agent. | |
90e0ef94 | 3406 | .RE |
297c659c TL |
3407 | .PP |
3408 | The | |
3004bebf DH |
3409 | .I update-conflict-detection |
3410 | statement | |
3411 | .RS 0.25i | |
3412 | .PP | |
3413 | .B update-conflict-detection \fIflag\fB;\fR | |
3414 | .PP | |
3415 | If the \fIupdate-conflict-detection\fR parameter is true, the server will | |
3416 | perform standard DHCID multiple-client, one-name conflict detection. If | |
3417 | the parameter has been set false, the server will skip this check and | |
3418 | instead simply tear down any previous bindings to install the new | |
905c58b9 TM |
3419 | binding without question. The default is true and this parameter may only |
3420 | be specified at the global scope. | |
68287bde | 3421 | .RE |
3004bebf DH |
3422 | .PP |
3423 | The | |
5ee63c60 TL |
3424 | .I update-optimization |
3425 | statement | |
3426 | .RS 0.25i | |
3427 | .PP | |
3428 | .B update-optimization \fIflag\fB;\fR | |
3429 | .PP | |
0e74ff1f | 3430 | If the \fIupdate-optimization\fR parameter is false for a given client, |
9f8b2a7f | 3431 | the server will attempt a DNS update for that client each time the |
5ee63c60 | 3432 | client renews its lease, rather than only attempting an update when it |
a0497ac5 | 3433 | appears to be necessary. This will allow the DNS to heal from |
5ee63c60 | 3434 | database inconsistencies more easily, but the cost is that the DHCP |
a0497ac5 | 3435 | server must do many more DNS updates. We recommend leaving this option |
e1634c24 SR |
3436 | enabled, which is the default. If this parameter is not specified, |
3437 | or is true, the DHCP server | |
98311e4b | 3438 | will only update when the client information changes, the client gets a |
0e74ff1f | 3439 | different lease, or the client's lease expires. |
90e0ef94 | 3440 | .RE |
5ee63c60 TL |
3441 | .PP |
3442 | The | |
abf0a2ab TL |
3443 | .I update-static-leases |
3444 | statement | |
3445 | .RS 0.25i | |
3446 | .PP | |
3447 | .B update-static-leases \fIflag\fB;\fR | |
3448 | .PP | |
3449 | The \fIupdate-static-leases\fR flag, if enabled, causes the DHCP | |
9f8b2a7f | 3450 | server to do DNS updates for clients even if those clients are being |
f1208e79 TM |
3451 | assigned their IP address using a \fIfixed-address\fR or |
3452 | \fIfixed-address6\fR statement - that is, the client is being given a | |
3453 | static assignment. It is not recommended because the DHCP server has | |
3454 | no way to tell that the update has been done, and therefore will not | |
3455 | delete the record when it is not in use. Also, the server must attempt | |
3456 | the update each time the client renews its lease, which could have a | |
3457 | significant performance impact in environments that place heavy demands | |
3458 | on the DHCP server. This feature is supported for both DHCPv4 and DHCPv6, | |
3459 | and update modes standard or interim. It is disabled by default. | |
90e0ef94 | 3460 | .RE |
417b7b4a TM |
3461 | .PP |
3462 | The | |
3463 | .I use-eui-64 | |
3464 | statement | |
3465 | .RS 0.25i | |
3466 | .PP | |
3467 | .B use-eui-64 \fIflag\fB;\fR | |
3468 | .PP | |
3469 | ||
3470 | (Support for this must be enabled at compile time, see EUI_64 in | |
3471 | includes/site.h) | |
3472 | ||
3473 | The \fIuse-eui-64\fR flag, if enabled, instructs the server to construct an | |
3474 | address using the client's EUI-64 DUID (Type 3, HW Type EUI-64), rather than | |
3475 | creating an address using the dynamic algorithm. This means that a given DUID | |
3476 | will always generate the same address for a given pool and further that the | |
3477 | address is guaranteed to be unique to that DUID. The IPv6 address will be | |
3478 | calculated from the EUI-64 link layer address, conforming to RFC 2373, unless | |
3479 | there is a host declaration for the client-id. | |
3480 | ||
3481 | The range6 statement for EUI-64 must define full /64 bit ranges. Invalid ranges | |
3482 | will be flagged during configuration parsing as errors. See the following | |
3483 | example: | |
3484 | ||
3485 | subnet6 fc00:e4::/64 { | |
3486 | use-eui-64 true; | |
3487 | range6 fc00:e4::/64; | |
3488 | } | |
3489 | ||
3490 | The statement may be specified down to the pool level, allowing a mixture of | |
3491 | dynamic and EUI-64 based pools. | |
3492 | ||
3493 | During lease file parsing, any leases which map to an EUI-64 pool, that have a | |
3494 | non-EUI-64 DUID or for which the lease address is not the EUI-64 address for | |
3495 | that DUID in that pool, will be discarded. | |
3496 | ||
3497 | If a host declaration exists for the DUID, the server grants the address | |
3498 | (fixed-prefix6, fixed-address6) according to the host declaration, regardless | |
3499 | of the DUID type of the client (even for EUI-64 DUIDs). | |
3500 | ||
3501 | If a client request's an EUI-64 lease for a given network, and the resultant | |
3502 | address conflicts with a fixed address reservation, the server will send the | |
3503 | client a "no addresses available" response. | |
3504 | ||
3505 | Any client with a non-conforming DUID (not type 3 or not hw type EUI-64) that | |
3506 | is not linked to a host declaration, which requests an address from an EUI-64 | |
3507 | enabled pool will be ignored and the event will be logged. | |
3508 | ||
3509 | Pools that are configured for EUI-64 will be skipped for dynamic allocation. | |
3510 | If there are no pools in the shared network from which to allocate, the client | |
3511 | will get back a no addresses available status. | |
3512 | ||
3513 | On an EUI-64 enabled pool, any client with a DUID 3, HW Type EUI-64, requesting | |
3514 | a solicit/renew and including IA_NA that do not match the EUI-64 policy, they | |
3515 | will be treated as though they are "outside" the subnet for a given client | |
3516 | message: | |
3517 | ||
3518 | Solicit - Server will advertise with EUI-64 ia suboption, but with rapid | |
3519 | commit off | |
3520 | Request - Server will send "an address not on link status", and no ia | |
3521 | suboption Renew/Rebind - Server will send the requested address ia | |
3522 | suboption with lifetimes of 0, plus an EUI-64 ia | |
c2e5ee28 TM |
3523 | |
3524 | Whether or not EUI-64 based leases are written out to the lease database | |
3525 | may be controlled by \fIpersist-eui-64-leases\fR statement. | |
417b7b4a | 3526 | .RE |
abf0a2ab TL |
3527 | .PP |
3528 | The | |
5cc21fb3 TL |
3529 | .I use-host-decl-names |
3530 | statement | |
3531 | .RS 0.25i | |
3532 | .PP | |
3533 | .B use-host-decl-names \fIflag\fB;\fR | |
3534 | .PP | |
3535 | If the \fIuse-host-decl-names\fR parameter is true in a given scope, | |
3536 | then for every host declaration within that scope, the name provided | |
3537 | for the host declaration will be supplied to the client as its | |
a0497ac5 | 3538 | hostname. So, for example, |
5cc21fb3 TL |
3539 | .PP |
3540 | .nf | |
3541 | group { | |
3542 | use-host-decl-names on; | |
3543 | ||
3544 | host joe { | |
98311e4b | 3545 | hardware ethernet 08:00:2b:4c:29:32; |
60bba434 | 3546 | fixed-address joe.example.com; |
5cc21fb3 TL |
3547 | } |
3548 | } | |
3549 | ||
3550 | is equivalent to | |
3551 | ||
3552 | host joe { | |
98311e4b | 3553 | hardware ethernet 08:00:2b:4c:29:32; |
60bba434 | 3554 | fixed-address joe.example.com; |
5cc21fb3 TL |
3555 | option host-name "joe"; |
3556 | } | |
3557 | .fi | |
3558 | .PP | |
d9b2a590 TM |
3559 | Additionally, enabling use-host-decl-names instructs the server to use |
3560 | the host declaration name in the the forward DNS name, if no other values | |
3561 | are available. This value selection process is discussed in more detail | |
3562 | under DNS updates. | |
3563 | .PP | |
5cc21fb3 TL |
3564 | An \fIoption host-name\fR statement within a host declaration will |
3565 | override the use of the name in the host declaration. | |
3566 | .PP | |
3567 | It should be noted here that most DHCP clients completely ignore the | |
3568 | host-name option sent by the DHCP server, and there is no way to | |
a0497ac5 | 3569 | configure them not to do this. So you generally have a choice of |
5cc21fb3 | 3570 | either not having any hostname to client IP address mapping that the |
a0497ac5 | 3571 | client will recognize, or doing DNS updates. It is beyond |
5cc21fb3 TL |
3572 | the scope of this document to describe how to make this |
3573 | determination. | |
3574 | .RE | |
3575 | .PP | |
3576 | The | |
3577 | .I use-lease-addr-for-default-route | |
3578 | statement | |
3579 | .RS 0.25i | |
3580 | .PP | |
3581 | .B use-lease-addr-for-default-route \fIflag\fR\fB;\fR | |
3582 | .PP | |
3583 | If the \fIuse-lease-addr-for-default-route\fR parameter is true in a | |
3584 | given scope, then instead of sending the value specified in the | |
3585 | routers option (or sending no value at all), the IP address of the | |
a0497ac5 | 3586 | lease being assigned is sent to the client. This supposedly causes |
5cc21fb3 | 3587 | Win95 machines to ARP for all IP addresses, which can be helpful if |
a0497ac5 | 3588 | your router is configured for proxy ARP. The use of this feature is |
5cc21fb3 TL |
3589 | not recommended, because it won't work for many DHCP clients. |
3590 | .RE | |
3591 | .PP | |
3592 | The | |
3593 | .I vendor-option-space | |
3594 | statement | |
3595 | .RS 0.25i | |
3596 | .PP | |
3597 | .B vendor-option-space \fIstring\fR\fB;\fR | |
3598 | .PP | |
3599 | The \fIvendor-option-space\fR parameter determines from what option | |
a0497ac5 | 3600 | space vendor options are taken. The use of this configuration |
98311e4b | 3601 | parameter is illustrated in the \fBdhcp-options(5)\fR manual page, in |
5cc21fb3 TL |
3602 | the \fIVENDOR ENCAPSULATED OPTIONS\fR section. |
3603 | .RE | |
e501cb07 TL |
3604 | .SH SETTING PARAMETER VALUES USING EXPRESSIONS |
3605 | Sometimes it's helpful to be able to set the value of a DHCP server | |
a0497ac5 | 3606 | parameter based on some value that the client has sent. To do this, |
417b7b4a | 3607 | you can use expression evaluation. The |
e501cb07 | 3608 | .B dhcp-eval(5) |
a0497ac5 | 3609 | manual page describes how to write expressions. To assign the result |
e501cb07 TL |
3610 | of an evaluation to an option, define the option as follows: |
3611 | .nf | |
3612 | .sp 1 | |
3613 | \fImy-parameter \fB= \fIexpression \fB;\fR | |
3614 | .fi | |
3615 | .PP | |
3616 | For example: | |
3617 | .nf | |
3618 | .sp 1 | |
3619 | ddns-hostname = binary-to-ascii (16, 8, "-", | |
3620 | substring (hardware, 1, 6)); | |
3621 | .fi | |
1db5e2c0 DH |
3622 | .RE |
3623 | .SH RESERVED LEASES | |
3624 | It's often useful to allocate a single address to a single client, in | |
3625 | approximate perpetuity. Host statements with \fBfixed-address\fR clauses | |
3626 | exist to a certain extent to serve this purpose, but because host statements | |
417b7b4a | 3627 | are intended to approximate \'static configuration\', they suffer from not |
5a38e43f SR |
3628 | being referenced in a littany of other Server Services, such as dynamic DNS, |
3629 | failover, \'on events\' and so forth. | |
1db5e2c0 | 3630 | .PP |
5a38e43f SR |
3631 | If a standard dynamic lease, as from any range statement, is marked |
3632 | \'reserved\', then the server will only allocate this lease to the client it | |
3633 | is identified by (be that by client identifier or hardware address). | |
1db5e2c0 DH |
3634 | .PP |
3635 | In practice, this means that the lease follows the normal state engine, enters | |
3636 | ACTIVE state when the client is bound to it, expires, or is released, and any | |
3637 | events or services that would normally be supplied during these events are | |
3638 | processed normally, as with any other dynamic lease. The only difference | |
3639 | is that failover servers treat reserved leases as special when they enter | |
3640 | the FREE or BACKUP states - each server applies the lease into the state it | |
3641 | may allocate from - and the leases are not placed on the queue for allocation | |
5a38e43f | 3642 | to other clients. Instead they may only be \'found\' by client identity. The |
1db5e2c0 DH |
3643 | result is that the lease is only offered to the returning client. |
3644 | .PP | |
3645 | Care should probably be taken to ensure that the client only has one lease | |
3646 | within a given subnet that it is identified by. | |
3647 | .PP | |
5a38e43f SR |
3648 | Leases may be set \'reserved\' either through OMAPI, or through the |
3649 | \'infinite-is-reserved\' configuration option (if this is applicable to your | |
1db5e2c0 DH |
3650 | environment and mixture of clients). |
3651 | .PP | |
5a38e43f SR |
3652 | It should also be noted that leases marked \'reserved\' are effectively treated |
3653 | the same as leases marked \'bootp\'. | |
1db5e2c0 | 3654 | .RE |
612bc350 | 3655 | .SH REFERENCE: OPTION STATEMENTS |
612bc350 TL |
3656 | DHCP option statements are documented in the |
3657 | .B dhcp-options(5) | |
3658 | manual page. | |
95848a1f TL |
3659 | .SH REFERENCE: EXPRESSIONS |
3660 | Expressions used in DHCP option statements and elsewhere are | |
3661 | documented in the | |
3662 | .B dhcp-eval(5) | |
3663 | manual page. | |
d250c5b9 | 3664 | .SH SEE ALSO |
95848a1f | 3665 | dhcpd(8), dhcpd.leases(5), dhcp-options(5), dhcp-eval(5), RFC2132, RFC2131. |
d250c5b9 | 3666 | .SH AUTHOR |
95848a1f | 3667 | .B dhcpd.conf(5) |
edad9be5 | 3668 | is maintained by ISC. |
98311e4b | 3669 | Information about Internet Systems Consortium can be found at |
2c85ac9b | 3670 | .B https://www.isc.org. |