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