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