1dhcpd.conf(5) File Formats Manual dhcpd.conf(5)
2
6 dhcpd.conf - dhcpd configuration file
7
9 The dhcpd.conf file contains configuration information for dhcpd, the
10 Internet Systems Consortium DHCP Server.
11 The dhcpd.conf file is a free-form ASCII text file. It is parsed by
13 the recursive-descent parser built into dhcpd. The file may contain
14 extra tabs and newlines for formatting purposes. Keywords in the file
15 are case-insensitive. Comments may be placed anywhere within the file
16 (except within quotes). Comments begin with the # character and end at
17 the end of the line.
18 The file essentially consists of a list of statements. Statements fall
20 into two broad categories - parameters and declarations.
21 Parameter statements either say how to do something (e.g., how long a
23 lease to offer), whether to do something (e.g., should dhcpd provide
24 addresses to unknown clients), or what parameters to provide to the
25 client (e.g., use gateway 220.177.244.7).
26 Declarations are used to describe the topology of the network, to de‐
28 scribe clients on the network, to provide addresses that can be as‐
29 signed to clients, or to apply a group of parameters to a group of dec‐
30 larations. In any group of parameters and declarations, all parameters
31 must be specified before any declarations which depend on those parame‐
32 ters may be specified.
33 Declarations about network topology include the shared-network and the
35 subnet declarations. If clients on a subnet are to be assigned ad‐
36 dresses dynamically, a range declaration must appear within the subnet
37 declaration. For clients with statically assigned addresses, or for
38 installations where only known clients will be served, each such client
39 must have a host declaration. If parameters are to be applied to a
40 group of declarations which are not related strictly on a per-subnet
41 basis, the group declaration can be used.
42 For every subnet which will be served, and for every subnet to which
44 the dhcp server is connected, there must be one subnet declaration,
45 which tells dhcpd how to recognize that an address is on that subnet.
46 A subnet declaration is required for each subnet even if no addresses
47 will be dynamically allocated on that subnet.
48 Some installations have physical networks on which more than one IP
50 subnet operates. For example, if there is a site-wide requirement that
51 8-bit subnet masks be used, but a department with a single physical
52 ethernet network expands to the point where it has more than 254 nodes,
53 it may be necessary to run two 8-bit subnets on the same ethernet until
54 such time as a new physical network can be added. In this case, the
55 subnet declarations for these two networks must be enclosed in a
56 shared-network declaration.
57 Note that even when the shared-network declaration is absent, an empty
59 one is created by the server to contain the subnet (and any scoped pa‐
60 rameters included in the subnet). For practical purposes, this means
61 that "stateless" DHCP clients, which are not tied to addresses (and
62 therefore subnets) will receive the same configuration as stateful
63 ones.
64 Some sites may have departments which have clients on more than one
66 subnet, but it may be desirable to offer those clients a uniform set of
67 parameters which are different than what would be offered to clients
68 from other departments on the same subnet. For clients which will be
69 declared explicitly with host declarations, these declarations can be
70 enclosed in a group declaration along with the parameters which are
71 common to that department. For clients whose addresses will be dynami‐
72 cally assigned, class declarations and conditional declarations may be
73 used to group parameter assignments based on information the client
74 sends.
75 When a client is to be booted, its boot parameters are determined by
77 consulting that client's host declaration (if any), and then consulting
78 any class declarations matching the client, followed by the pool, sub‐
79 net and shared-network declarations for the IP address assigned to the
80 client. Each of these declarations itself appears within a lexical
81 scope, and all declarations at less specific lexical scopes are also
82 consulted for client option declarations. Scopes are never considered
83 twice, and if parameters are declared in more than one scope, the pa‐
84 rameter declared in the most specific scope is the one that is used.
85 When dhcpd tries to find a host declaration for a client, it first
87 looks for a host declaration which has a fixed-address declaration that
88 lists an IP address that is valid for the subnet or shared network on
89 which the client is booting. If it doesn't find any such entry, it
90 tries to find an entry which has no fixed-address declaration.
91
93 A typical dhcpd.conf file will look something like this:
94 global parameters...
96 subnet 204.254.239.0 netmask 255.255.255.224 {
98 subnet-specific parameters...
99 range 204.254.239.10 204.254.239.30;
100 }
101 subnet 204.254.239.32 netmask 255.255.255.224 {
103 subnet-specific parameters...
104 range 204.254.239.42 204.254.239.62;
105 }
106 subnet 204.254.239.64 netmask 255.255.255.224 {
108 subnet-specific parameters...
109 range 204.254.239.74 204.254.239.94;
110 }
111 group {
113 group-specific parameters...
114 host zappo.test.isc.org {
115 host-specific parameters...
116 }
117 host beppo.test.isc.org {
118 host-specific parameters...
119 }
120 host harpo.test.isc.org {
121 host-specific parameters...
122 }
123 }
124 Figure 1
126 Notice that at the beginning of the file, there's a place for global
129 parameters. These might be things like the organization's domain name,
130 the addresses of the name servers (if they are common to the entire or‐
131 ganization), and so on. So, for example:
132 option domain-name "isc.org";
134 option domain-name-servers ns1.isc.org, ns2.isc.org;
135 Figure 2
137 As you can see in Figure 2, you can specify host addresses in parame‐
139 ters using their domain names rather than their numeric IP addresses.
140 If a given hostname resolves to more than one IP address (for example,
141 if that host has two ethernet interfaces), then where possible, both
142 addresses are supplied to the client.
143 The most obvious reason for having subnet-specific parameters as shown
145 in Figure 1 is that each subnet, of necessity, has its own router. So
146 for the first subnet, for example, there should be something like:
147 option routers 204.254.239.1;
149 Note that the address here is specified numerically. This is not re‐
151 quired - if you have a different domain name for each interface on your
152 router, it's perfectly legitimate to use the domain name for that in‐
153 terface instead of the numeric address. However, in many cases there
154 may be only one domain name for all of a router's IP addresses, and it
155 would not be appropriate to use that name here.
156 In Figure 1 there is also a group statement, which provides common pa‐
158 rameters for a set of three hosts - zappo, beppo and harpo. As you can
159 see, these hosts are all in the test.isc.org domain, so it might make
160 sense for a group-specific parameter to override the domain name sup‐
161 plied to these hosts:
162 option domain-name "test.isc.org";
164 Also, given the domain they're in, these are probably test machines.
166 If we wanted to test the DHCP leasing mechanism, we might set the lease
167 timeout somewhat shorter than the default:
168 max-lease-time 120;
170 default-lease-time 120;
171 You may have noticed that while some parameters start with the option
173 keyword, some do not. Parameters starting with the option keyword cor‐
174 respond to actual DHCP options, while parameters that do not start with
175 the option keyword either control the behavior of the DHCP server
176 (e.g., how long a lease dhcpd will give out), or specify client parame‐
177 ters that are not optional in the DHCP protocol (for example, server-
178 name and filename).
179 In Figure 1, each host had host-specific parameters. These could in‐
181 clude such things as the hostname option, the name of a file to upload
182 (the filename parameter) and the address of the server from which to
183 upload the file (the next-server parameter). In general, any parameter
184 can appear anywhere that parameters are allowed, and will be applied
185 according to the scope in which the parameter appears.
186 Imagine that you have a site with a lot of NCD X-Terminals. These ter‐
188 minals come in a variety of models, and you want to specify the boot
189 files for each model. One way to do this would be to have host decla‐
190 rations for each server and group them by model:
191 group {
193 filename "Xncd19r";
194 next-server ncd-booter;
195 host ncd1 { hardware ethernet 0:c0:c3:49:2b:57; }
197 host ncd4 { hardware ethernet 0:c0:c3:80:fc:32; }
198 host ncd8 { hardware ethernet 0:c0:c3:22:46:81; }
199 }
200 group {
202 filename "Xncd19c";
203 next-server ncd-booter;
204 host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; }
206 host ncd3 { hardware ethernet 0:c0:c3:00:14:11; }
207 }
208 group {
210 filename "XncdHMX";
211 next-server ncd-booter;
212 host ncd1 { hardware ethernet 0:c0:c3:11:90:23; }
214 host ncd4 { hardware ethernet 0:c0:c3:91:a7:8; }
215 host ncd8 { hardware ethernet 0:c0:c3:cc:a:8f; }
216 }
217
219 The pool and pool6 declarations can be used to specify a pool of ad‐
220 dresses that will be treated differently than another pool of ad‐
221 dresses, even on the same network segment or subnet. For example, you
222 may want to provide a large set of addresses that can be assigned to
223 DHCP clients that are registered to your DHCP server, while providing a
224 smaller set of addresses, possibly with short lease times, that are
225 available for unknown clients. If you have a firewall, you may be able
226 to arrange for addresses from one pool to be allowed access to the In‐
227 ternet, while addresses in another pool are not, thus encouraging users
228 to register their DHCP clients. To do this, you would set up a pair of
229 pool declarations:
230 subnet 10.0.0.0 netmask 255.255.255.0 {
232 option routers 10.0.0.254;
233 # Unknown clients get this pool.
235 pool {
236 option domain-name-servers bogus.example.com;
237 max-lease-time 300;
238 range 10.0.0.200 10.0.0.253;
239 allow unknown-clients;
240 }
241 # Known clients get this pool.
243 pool {
244 option domain-name-servers ns1.example.com, ns2.example.com;
245 max-lease-time 28800;
246 range 10.0.0.5 10.0.0.199;
247 deny unknown-clients;
248 }
249 }
250 It is also possible to set up entirely different subnets for known and
252 unknown clients - address pools exist at the level of shared networks,
253 so address ranges within pool declarations can be on different subnets.
254 As you can see in the preceding example, pools can have permit lists
256 that control which clients are allowed access to the pool and which
257 aren't. Each entry in a pool's permit list is introduced with the al‐
258 low or deny keyword. If a pool has a permit list, then only those
259 clients that match specific entries on the permit list will be eligible
260 to be assigned addresses from the pool. If a pool has a deny list,
261 then only those clients that do not match any entries on the deny list
262 will be eligible. If both permit and deny lists exist for a pool,
263 then only clients that match the permit list and do not match the deny
264 list will be allowed access.
265 The pool6 declaration is similar to the pool declaration. Currently it
267 is only allowed within a subnet6 declaration, and may not be included
268 directly in a shared network declaration. In addition to the range6
269 statement it allows the prefix6 statement to be included. You may in‐
270 clude range6 statements for both NA and TA and prefix6 statements in a
271 single pool6 statement.
272
274 Address allocation is actually only done when a client is in the INIT
275 state and has sent a DHCPDISCOVER message. If the client thinks it has
276 a valid lease and sends a DHCPREQUEST to initiate or renew that lease,
277 the server has only three choices - it can ignore the DHCPREQUEST, send
278 a DHCPNAK to tell the client it should stop using the address, or send
279 a DHCPACK, telling the client to go ahead and use the address for a
280 while.
281 If the server finds the address the client is requesting, and that ad‐
283 dress is available to the client, the server will send a DHCPACK. If
284 the address is no longer available, or the client isn't permitted to
285 have it, the server will send a DHCPNAK. If the server knows nothing
286 about the address, it will remain silent, unless the address is incor‐
287 rect for the network segment to which the client has been attached and
288 the server is authoritative for that network segment, in which case the
289 server will send a DHCPNAK even though it doesn't know about the ad‐
290 dress.
291 There may be a host declaration matching the client's identification.
293 If that host declaration contains a fixed-address declaration that
294 lists an IP address that is valid for the network segment to which the
295 client is connected, the DHCP server will never do dynamic address al‐
296 location. In this case, the client is required to take the address
297 specified in the host declaration. If the client sends a DHCPREQUEST
298 for some other address, the server will respond with a DHCPNAK.
299 When the DHCP server allocates a new address for a client (remember,
301 this only happens if the client has sent a DHCPDISCOVER), it first
302 looks to see if the client already has a valid lease on an IP address,
303 or if there is an old IP address the client had before that hasn't yet
304 been reassigned. In that case, the server will take that address and
305 check it to see if the client is still permitted to use it. If the
306 client is no longer permitted to use it, the lease is freed if the
307 server thought it was still in use - the fact that the client has sent
308 a DHCPDISCOVER proves to the server that the client is no longer using
309 the lease.
310 If no existing lease is found, or if the client is forbidden to receive
312 the existing lease, then the server will look in the list of address
313 pools for the network segment to which the client is attached for a
314 lease that is not in use and that the client is permitted to have. It
315 looks through each pool declaration in sequence (all range declarations
316 that appear outside of pool declarations are grouped into a single pool
317 with no permit list). If the permit list for the pool allows the
318 client to be allocated an address from that pool, the pool is examined
319 to see if there is an address available. If so, then the client is
320 tentatively assigned that address. Otherwise, the next pool is tested.
321 If no addresses are found that can be assigned to the client, no re‐
322 sponse is sent to the client.
323 If an address is found that the client is permitted to have, and that
325 has never been assigned to any client before, the address is immedi‐
326 ately allocated to the client. If the address is available for alloca‐
327 tion but has been previously assigned to a different client, the server
328 will keep looking in hopes of finding an address that has never before
329 been assigned to a client.
330 The DHCP server generates the list of available IP addresses from a
332 hash table. This means that the addresses are not sorted in any par‐
333 ticular order, and so it is not possible to predict the order in which
334 the DHCP server will allocate IP addresses. Users of previous versions
335 of the ISC DHCP server may have become accustomed to the DHCP server
336 allocating IP addresses in ascending order, but this is no longer pos‐
337 sible, and there is no way to configure this behavior with version 3 of
338 the ISC DHCP server.
339
341 The DHCP server checks IP addresses to see if they are in use before
342 allocating them to clients. It does this by sending an ICMP Echo re‐
343 quest message to the IP address being allocated. If no ICMP Echo reply
344 is received within a second, the address is assumed to be free. This
345 is only done for leases that have been specified in range statements,
346 and only when the lease is thought by the DHCP server to be free -
347 i.e., the DHCP server or its failover peer has not listed the lease as
348 in use.
349 If a response is received to an ICMP Echo request, the DHCP server as‐
351 sumes that there is a configuration error - the IP address is in use by
352 some host on the network that is not a DHCP client. It marks the ad‐
353 dress as abandoned, and will not assign it to clients. The lease will
354 remain abandoned for a minimum of abandon-lease-time seconds.
355 If a DHCP client tries to get an IP address, but none are available,
357 but there are abandoned IP addresses, then the DHCP server will attempt
358 to reclaim an abandoned IP address. It marks one IP address as free,
359 and then does the same ICMP Echo request check described previously.
360 If there is no answer to the ICMP Echo request, the address is assigned
361 to the client.
362 The DHCP server does not cycle through abandoned IP addresses if the
364 first IP address it tries to reclaim is free. Rather, when the next
365 DHCPDISCOVER comes in from the client, it will attempt a new allocation
366 using the same method described here, and will typically try a new IP
367 address.
368
370 This version of the ISC DHCP server supports the DHCP failover protocol
371 as documented in draft-ietf-dhc-failover-12.txt. This is not a final
372 protocol document, and we have not done interoperability testing with
373 other vendors' implementations of this protocol, so you must not assume
374 that this implementation conforms to the standard. If you wish to use
375 the failover protocol, make sure that both failover peers are running
376 the same version of the ISC DHCP server.
377 The failover protocol allows two DHCP servers (and no more than two) to
379 share a common address pool. Each server will have about half of the
380 available IP addresses in the pool at any given time for allocation.
381 If one server fails, the other server will continue to renew leases out
382 of the pool, and will allocate new addresses out of the roughly half of
383 available addresses that it had when communications with the other
384 server were lost.
385 It is possible during a prolonged failure to tell the remaining server
387 that the other server is down, in which case the remaining server will
388 (over time) reclaim all the addresses the other server had available
389 for allocation, and begin to reuse them. This is called putting the
390 server into the PARTNER-DOWN state.
391 You can put the server into the PARTNER-DOWN state either by using the
393 omshell (1) command or by stopping the server, editing the last
394 failover state declaration in the lease file, and restarting the
395 server. If you use this last method, change the "my state" line to:
396 failover peer name state {
398 my state partner-down;.
399 peer state state at date;
400 }
401 It is only required to change "my state" as shown above.
403 When the other server comes back online, it should automatically detect
405 that it has been offline and request a complete update from the server
406 that was running in the PARTNER-DOWN state, and then both servers will
407 resume processing together.
408 It is possible to get into a dangerous situation: if you put one server
410 into the PARTNER-DOWN state, and then *that* server goes down, and the
411 other server comes back up, the other server will not know that the
412 first server was in the PARTNER-DOWN state, and may issue addresses
413 previously issued by the other server to different clients, resulting
414 in IP address conflicts. Before putting a server into PARTNER-DOWN
415 state, therefore, make sure that the other server will not restart au‐
416 tomatically.
417 The failover protocol defines a primary server role and a secondary
419 server role. There are some differences in how primaries and secon‐
420 daries act, but most of the differences simply have to do with provid‐
421 ing a way for each peer to behave in the opposite way from the other.
422 So one server must be configured as primary, and the other must be con‐
423 figured as secondary, and it doesn't matter too much which one is
424 which.
425
427 When a server starts that has not previously communicated with its
428 failover peer, it must establish communications with its failover peer
429 and synchronize with it before it can serve clients. This can happen
430 either because you have just configured your DHCP servers to perform
431 failover for the first time, or because one of your failover servers
432 has failed catastrophically and lost its database.
433 The initial recovery process is designed to ensure that when one
435 failover peer loses its database and then resynchronizes, any leases
436 that the failed server gave out before it failed will be honored. When
437 the failed server starts up, it notices that it has no saved failover
438 state, and attempts to contact its peer.
439 When it has established contact, it asks the peer for a complete copy
441 its peer's lease database. The peer then sends its complete database,
442 and sends a message indicating that it is done. The failed server then
443 waits until MCLT has passed, and once MCLT has passed both servers make
444 the transition back into normal operation. This waiting period ensures
445 that any leases the failed server may have given out while out of con‐
446 tact with its partner will have expired.
447 While the failed server is recovering, its partner remains in the part‐
449 ner-down state, which means that it is serving all clients. The failed
450 server provides no service at all to DHCP clients until it has made the
451 transition into normal operation.
452 In the case where both servers detect that they have never before com‐
454 municated with their partner, they both come up in this recovery state
455 and follow the procedure we have just described. In this case, no ser‐
456 vice will be provided to DHCP clients until MCLT has expired.
457
459 In order to configure failover, you need to write a peer declaration
460 that configures the failover protocol, and you need to write peer ref‐
461 erences in each pool declaration for which you want to do failover.
462 You do not have to do failover for all pools on a given network seg‐
463 ment. You must not tell one server it's doing failover on a particu‐
464 lar address pool and tell the other it is not. You must not have any
465 common address pools on which you are not doing failover. A pool dec‐
466 laration that utilizes failover would look like this:
467 pool {
469 failover peer "foo";
470 pool specific parameters
471 };
472 Dynamic BOOTP leases are not compatible with failover, and, as such,
474 you need to disallow BOOTP in pools that you are using failover for.
475 The server currently does very little sanity checking, so if you
477 configure it wrong, it will just fail in odd ways. I would recommend
478 therefore that you either do failover or don't do failover, but don't
479 do any mixed pools. Also, use the same master configuration file for
480 both servers, and have a separate file that contains the peer
481 declaration and includes the master file. This will help you to avoid
482 configuration mismatches. As our implementation evolves, this will
483 become less of a problem. A basic sample dhcpd.conf file for a
484 primary server might look like this:
485 failover peer "foo" {
487 primary;
488 address anthrax.rc.example.com;
489 port 647;
490 peer address trantor.rc.example.com;
491 peer port 847;
492 max-response-delay 60;
493 max-unacked-updates 10;
494 mclt 3600;
495 split 128;
496 load balance max seconds 3;
497 }
498 include "/etc/dhcpd.master";
500 The statements in the peer declaration are as follows:
502 The primary and secondary statements
504 [ primary | secondary ];
506 This determines whether the server is primary or secondary, as de‐
508 scribed earlier under DHCP FAILOVER.
509 The address statement
511 address address;
513 The address statement declares the IP address or DNS name on which
515 the server should listen for connections from its failover peer, and
516 also the value to use for the DHCP Failover Protocol server identi‐
517 fier. Because this value is used as an identifier, it may not be
518 omitted.
519 The peer address statement
521 peer address address;
523 The peer address statement declares the IP address or DNS name to
525 which the server should connect to reach its failover peer for
526 failover messages.
527 The port statement
529 port port-number;
531 The port statement declares the TCP port on which the server should
533 listen for connections from its failover peer. This statement may be
534 omitted, in which case the IANA assigned port number 647 will be used
535 by default.
536 The peer port statement
538 peer port port-number;
540 The peer port statement declares the TCP port to which the server
542 should connect to reach its failover peer for failover messages.
543 This statement may be omitted, in which case the IANA assigned port
544 number 647 will be used by default.
545 The max-response-delay statement
547 max-response-delay seconds;
549 The max-response-delay statement tells the DHCP server how many sec‐
551 onds may pass without receiving a message from its failover peer be‐
552 fore it assumes that connection has failed. This number should be
553 small enough that a transient network failure that breaks the connec‐
554 tion will not result in the servers being out of communication for a
555 long time, but large enough that the server isn't constantly making
556 and breaking connections. This parameter must be specified.
557 The max-unacked-updates statement
559 max-unacked-updates count;
561 The max-unacked-updates statement tells the remote DHCP server how
563 many BNDUPD messages it can send before it receives a BNDACK from the
564 local system. We don't have enough operational experience to say
565 what a good value for this is, but 10 seems to work. This parameter
566 must be specified.
567 The mclt statement
569 mclt seconds;
571 The mclt statement defines the Maximum Client Lead Time. It must be
573 specified on the primary, and may not be specified on the secondary.
574 This is the length of time for which a lease may be renewed by either
575 failover peer without contacting the other. The longer you set this,
576 the longer it will take for the running server to recover IP ad‐
577 dresses after moving into PARTNER-DOWN state. The shorter you set
578 it, the more load your servers will experience when they are not com‐
579 municating. A value of something like 3600 is probably reasonable,
580 but again bear in mind that we have no real operational experience
581 with this.
582 The split statement
584 split bits;
586 The split statement specifies the split between the primary and sec‐
588 ondary for the purposes of load balancing. Whenever a client makes a
589 DHCP request, the DHCP server runs a hash on the client identifica‐
590 tion, resulting in value from 0 to 255. This is used as an index
591 into a 256 bit field. If the bit at that index is set, the primary
592 is responsible. If the bit at that index is not set, the secondary
593 is responsible. The split value determines how many of the leading
594 bits are set to one. So, in practice, higher split values will cause
595 the primary to serve more clients than the secondary. Lower split
596 values, the converse. Legal values are between 0 and 256 inclusive,
597 of which the most reasonable is 128. Note that a value of 0 makes
598 the secondary responsible for all clients and a value of 256 makes
599 the primary responsible for all clients.
600 The hba statement
602 hba colon-separated-hex-list;
604 The hba statement specifies the split between the primary and sec‐
606 ondary as a bitmap rather than a cutoff, which theoretically allows
607 for finer-grained control. In practice, there is probably no need
608 for such fine-grained control, however. An example hba statement:
609 hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:
611 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00;
612 This is equivalent to a split 128; statement, and identical. The
614 following two examples are also equivalent to a split of 128, but are
615 not identical:
616 hba aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:
618 aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa;
619 hba 55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:
621 55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55;
622 They are equivalent, because half the bits are set to 0, half are set
624 to 1 (0xa and 0x5 are 1010 and 0101 binary respectively) and conse‐
625 quently this would roughly divide the clients equally between the
626 servers. They are not identical, because the actual peers this would
627 load balance to each server are different for each example.
628 You must only have split or hba defined, never both. For most cases,
630 the fine-grained control that hba offers isn't necessary, and split
631 should be used.
632 The load balance max seconds statement
634 load balance max seconds seconds;
636 This statement allows you to configure a cutoff after which load bal‐
638 ancing is disabled. The cutoff is based on the number of seconds
639 since the client sent its first DHCPDISCOVER or DHCPREQUEST message,
640 and only works with clients that correctly implement the secs field -
641 fortunately most clients do. We recommend setting this to something
642 like 3 or 5. The effect of this is that if one of the failover peers
643 gets into a state where it is responding to failover messages but not
644 responding to some client requests, the other failover peer will take
645 over its client load automatically as the clients retry.
646 It is possible to disable load balancing between peers by setting
648 this value to 0 on both peers. Bear in mind that this means both
649 peers will respond to all DHCPDISCOVERs or DHCPREQUESTs.
650 The auto-partner-down statement
652 auto-partner-down seconds;
654 This statement instructs the server to initiate a timed delay upon
656 entering the communications-interrupted state (any situation of being
657 out-of-contact with the remote failover peer). At the conclusion of
658 the timer, the server will automatically enter the partner-down
659 state. This permits the server to allocate leases from the partner's
660 free lease pool after an STOS+MCLT timer expires, which can be dan‐
661 gerous if the partner is in fact operating at the time (the two
662 servers will give conflicting bindings).
663 Think very carefully before enabling this feature. The partner-down
665 and communications-interrupted states are intentionally segregated
666 because there do exist situations where a failover server can fail to
667 communicate with its peer, but still has the ability to receive and
668 reply to requests from DHCP clients. In general, this feature should
669 only be used in those deployments where the failover servers are di‐
670 rectly connected to one another, such as by a dedicated hardwired
671 link ("a heartbeat cable").
672 A zero value disables the auto-partner-down feature (also the de‐
674 fault), and any positive value indicates the time in seconds to wait
675 before automatically entering partner-down.
676 The Failover pool balance statements.
678 max-lease-misbalance percentage;
680 max-lease-ownership percentage;
681 min-balance seconds;
682 max-balance seconds;
683 This version of the DHCP Server evaluates pool balance on a schedule,
685 rather than on demand as leases are allocated. The latter approach
686 proved to be slightly klunky when pool misbalanced reach total satu‐
687 ration — when any server ran out of leases to assign, it also lost
688 its ability to notice it had run dry.
689 In order to understand pool balance, some elements of its operation
691 first need to be defined. First, there are ´free´ and ´backup´
692 leases. Both of these are referred to as ´free state leases´.
693 ´free´ and ´backup´ are ´the free states´ for the purpose of this
694 document. The difference is that only the primary may allocate from
695 ´free´ leases unless under special circumstances, and only the sec‐
696 ondary may allocate ´backup´ leases.
697 When pool balance is performed, the only plausible expectation is to
699 provide a 50/50 split of the free state leases between the two
700 servers. This is because no one can predict which server will fail,
701 regardless of the relative load placed upon the two servers, so giv‐
702 ing each server half the leases gives both servers the same amount of
703 ´failure endurance´. Therefore, there is no way to configure any
704 different behaviour, outside of some very small windows we will de‐
705 scribe shortly.
706 The first thing calculated on any pool balance run is a value re‐
708 ferred to as ´lts´, or "Leases To Send". This, simply, is the dif‐
709 ference in the count of free and backup leases, divided by two. For
710 the secondary, it is the difference in the backup and free leases,
711 divided by two. The resulting value is signed: if it is positive,
712 the local server is expected to hand out leases to retain a 50/50
713 balance. If it is negative, the remote server would need to send
714 leases to balance the pool. Once the lts value reaches zero, the
715 pool is perfectly balanced (give or take one lease in the case of an
716 odd number of total free state leases).
717 The current approach is still something of a hybrid of the old ap‐
719 proach, marked by the presence of the max-lease-misbalance statement.
720 This parameter configures what used to be a 10% fixed value in previ‐
721 ous versions: if lts is less than free+backup * max-lease-misbalance
722 percent, then the server will skip balancing a given pool (it won't
723 bother moving any leases, even if some leases "should" be moved).
724 The meaning of this value is also somewhat overloaded, however, in
725 that it also governs the estimation of when to attempt to balance the
726 pool (which may then also be skipped over). The oldest leases in the
727 free and backup states are examined. The time they have resided in
728 their respective queues is used as an estimate to indicate how much
729 time it is probable it would take before the leases at the top of the
730 list would be consumed (and thus, how long it would take to use all
731 leases in that state). This percentage is directly multiplied by
732 this time, and fit into the schedule if it falls within the min-bal‐
733 ance and max-balance configured values. The scheduled pool check
734 time is only moved in a downwards direction, it is never increased.
735 Lastly, if the lts is more than double this number in the negative
736 direction, the local server will ´panic´ and transmit a Failover pro‐
737 tocol POOLREQ message, in the hopes that the remote system will be
738 woken up into action.
739 Once the lts value exceeds the max-lease-misbalance percentage of to‐
741 tal free state leases as described above, leases are moved to the re‐
742 mote server. This is done in two passes.
743 In the first pass, only leases whose most recent bound client would
745 have been served by the remote server - according to the Load Balance
746 Algorithm (see above split and hba configuration statements) - are
747 given away to the peer. This first pass will happily continue to
748 give away leases, decrementing the lts value by one for each, until
749 the lts value has reached the negative of the total number of leases
750 multiplied by the max-lease-ownership percentage. So it is through
751 this value that you can permit a small misbalance of the lease pools
752 - for the purpose of giving the peer more than a 50/50 share of
753 leases in the hopes that their clients might some day return and be
754 allocated by the peer (operating normally). This process is referred
755 to as ´MAC Address Affinity´, but this is somewhat misnamed: it ap‐
756 plies equally to DHCP Client Identifier options. Note also that
757 affinity is applied to leases when they enter the state ´free´ from
758 ´expired´ or ´released´. In this case also, leases will not be moved
759 from free to backup if the secondary already has more than its share.
760 The second pass is only entered into if the first pass fails to re‐
762 duce the lts underneath the total number of free state leases multi‐
763 plied by the max-lease-ownership percentage. In this pass, the old‐
764 est leases are given over to the peer without second thought about
765 the Load Balance Algorithm, and this continues until the lts falls
766 under this value. In this way, the local server will also happily
767 keep a small percentage of the leases that would normally load bal‐
768 ance to itself.
769 So, the max-lease-misbalance value acts as a behavioural gate.
771 Smaller values will cause more leases to transition states to balance
772 the pools over time, higher values will decrease the amount of change
773 (but may lead to pool starvation if there's a run on leases).
774 The max-lease-ownership value permits a small (percentage) skew in
776 the lease balance of a percentage of the total number of free state
777 leases.
778 Finally, the min-balance and max-balance make certain that a sched‐
780 uled rebalance event happens within a reasonable timeframe (not to be
781 thrown off by, for example, a 7 year old free lease).
782 Plausible values for the percentages lie between 0 and 100, inclu‐
784 sive, but values over 50 are indistinguishable from one another (once
785 lts exceeds 50% of the free state leases, one server must therefore
786 have 100% of the leases in its respective free state). It is recom‐
787 mended to select a max-lease-ownership value that is lower than the
788 value selected for the max-lease-misbalance value. max-lease-owner‐
789 ship defaults to 10, and max-lease-misbalance defaults to 15.
790 Plausible values for the min-balance and max-balance times also range
792 from 0 to (2^32)-1 (or the limit of your local time_t value), but de‐
793 fault to values 60 and 3600 respectively (to place balance events be‐
794 tween 1 minute and 1 hour).
795
797 Clients can be separated into classes, and treated differently depend‐
798 ing on what class they are in. This separation can be done either with
799 a conditional statement, or with a match statement within the class
800 declaration. It is possible to specify a limit on the total number of
801 clients within a particular class or subclass that may hold leases at
802 one time, and it is possible to specify automatic subclassing based on
803 the contents of the client packet.
804 Classing support for DHCPv6 clients was added in 4.3.0. It follows the
806 same rules as for DHCPv4 except that support for billing classes has
807 not been added yet.
808 To add clients to classes based on conditional evaluation, you can
810 specify a matching expression in the class statement:
811 class "ras-clients" {
813 match if substring (option dhcp-client-identifier, 1, 3) = "RAS";
814 }
815 Please note that the values used in match expressions may only come
817 from data or options that are part of the client packet. It is not pos‐
818 sible to use values constructed through one or more executable state‐
819 ments. This stems from the fact that client classification occurs be‐
820 fore any statements are executed. Attempting to do so will yield inde‐
821 terminate results.
822 Note that whether you use matching expressions or add statements (or
824 both) to classify clients, you must always write a class declaration
825 for any class that you use. If there will be no match statement and no
826 in-scope statements for a class, the declaration should look like this:
827 class "ras-clients" {
829 }
830
832 In addition to classes, it is possible to declare subclasses. A sub‐
833 class is a class with the same name as a regular class, but with a spe‐
834 cific submatch expression which is hashed for quick matching. This is
835 essentially a speed hack - the main difference between five classes
836 with match expressions and one class with five subclasses is that it
837 will be quicker to find the subclasses. Subclasses work as follows:
838 class "allocation-class-1" {
840 match pick-first-value (option dhcp-client-identifier, hardware);
841 }
842 class "allocation-class-2" {
844 match pick-first-value (option dhcp-client-identifier, hardware);
845 }
846 subclass "allocation-class-1" 1:8:0:2b:4c:39:ad;
848 subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3;
849 subclass "allocation-class-1" 1:0:0:c4:aa:29:44;
850 subnet 10.0.0.0 netmask 255.255.255.0 {
852 pool {
853 allow members of "allocation-class-1";
854 range 10.0.0.11 10.0.0.50;
855 }
856 pool {
857 allow members of "allocation-class-2";
858 range 10.0.0.51 10.0.0.100;
859 }
860 }
861 The data following the class name in the subclass declaration is a con‐
863 stant value to use in matching the match expression for the class.
864 When class matching is done, the server will evaluate the match expres‐
865 sion and then look the result up in the hash table. If it finds a
866 match, the client is considered a member of both the class and the sub‐
867 class.
868 Subclasses can be declared with or without scope. In the above exam‐
870 ple, the sole purpose of the subclass is to allow some clients access
871 to one address pool, while other clients are given access to the other
872 pool, so these subclasses are declared without scopes. If part of the
873 purpose of the subclass were to define different parameter values for
874 some clients, you might want to declare some subclasses with scopes.
875 In the above example, if you had a single client that needed some con‐
877 figuration parameters, while most didn't, you might write the following
878 subclass declaration for that client:
879 subclass "allocation-class-2" 1:08:00:2b:a1:11:31 {
881 option root-path "samsara:/var/diskless/alphapc";
882 filename "/tftpboot/netbsd.alphapc-diskless";
883 }
884 In this example, we've used subclassing as a way to control address al‐
886 location on a per-client basis. However, it's also possible to use
887 subclassing in ways that are not specific to clients - for example, to
888 use the value of the vendor-class-identifier option to determine what
889 values to send in the vendor-encapsulated-options option. An example
890 of this is shown under the VENDOR ENCAPSULATED OPTIONS head in the
891 dhcp-options(5) manual page.
892
894 You may specify a limit to the number of clients in a class that can be
895 assigned leases. The effect of this will be to make it difficult for a
896 new client in a class to get an address. Once a class with such a
897 limit has reached its limit, the only way a new client in that class
898 can get a lease is for an existing client to relinquish its lease, ei‐
899 ther by letting it expire, or by sending a DHCPRELEASE packet. Classes
900 with lease limits are specified as follows:
901 class "limited-1" {
903 lease limit 4;
904 }
905 This will produce a class in which a maximum of four members may hold a
907 lease at one time.
908
910 It is possible to declare a spawning class. A spawning class is a
911 class that automatically produces subclasses based on what the client
912 sends. The reason that spawning classes were created was to make it
913 possible to create lease-limited classes on the fly. The envisioned
914 application is a cable-modem environment where the ISP wishes to pro‐
915 vide clients at a particular site with more than one IP address, but
916 does not wish to provide such clients with their own subnet, nor give
917 them an unlimited number of IP addresses from the network segment to
918 which they are connected.
919 Many cable modem head-end systems can be configured to add a Relay
921 Agent Information option to DHCP packets when relaying them to the DHCP
922 server. These systems typically add a circuit ID or remote ID option
923 that uniquely identifies the customer site. To take advantage of this,
924 you can write a class declaration as follows:
925 class "customer" {
927 spawn with option agent.circuit-id;
928 lease limit 4;
929 }
930 Now whenever a request comes in from a customer site, the circuit ID
932 option will be checked against the class´s hash table. If a subclass
933 is found that matches the circuit ID, the client will be classified in
934 that subclass and treated accordingly. If no subclass is found match‐
935 ing the circuit ID, a new one will be created and logged in the
936 dhcpd.leases file, and the client will be classified in this new class.
937 Once the client has been classified, it will be treated according to
938 the rules of the class, including, in this case, being subject to the
939 per-site limit of four leases.
940 The use of the subclass spawning mechanism is not restricted to relay
942 agent options - this particular example is given only because it is a
943 fairly straightforward one.
944
946 In some cases, it may be useful to use one expression to assign a
947 client to a particular class, and a second expression to put it into a
948 subclass of that class. This can be done by combining the match if and
949 spawn with statements, or the match if and match statements. For exam‐
950 ple:
951 class "jr-cable-modems" {
953 match if option dhcp-vendor-identifier = "jrcm";
954 spawn with option agent.circuit-id;
955 lease limit 4;
956 }
957 class "dv-dsl-modems" {
959 match if option dhcp-vendor-identifier = "dvdsl";
960 spawn with option agent.circuit-id;
961 lease limit 16;
962 }
963 This allows you to have two classes that both have the same spawn with
965 expression without getting the clients in the two classes confused with
966 each other.
967
969 The DHCP server has the ability to dynamically update the Domain Name
970 System. Within the configuration files, you can define how you want
971 the Domain Name System to be updated. These updates are RFC 2136 com‐
972 pliant so any DNS server supporting RFC 2136 should be able to accept
973 updates from the DHCP server.
974 There are two DNS schemes implemented. The interim option is based on
976 draft revisions of the DDNS documents while the standard option is
977 based on the RFCs for DHCP-DNS interaction and DHCIDs. A third option,
978 ad-hoc, was deprecated and has now been removed from the code base.
979 The DHCP server must be configured to use one of the two currently-sup‐
980 ported methods, or not to do DNS updates.
981 New installations should use the standard option. Older installations
983 may want to continue using the interim option for backwards compatibil‐
984 ity with the DNS database until the database can be updated. This can
985 be done with the ddns-update-style configuration parameter.
986
988 the interim and standard DNS update schemes operate mostly according to
989 work from the IETF. The interim version was based on the drafts in
990 progress at the time while the standard is based on the completed RFCs.
991 The standard RFCs are:
992 RFC 4701 (updated by RF5494)
994 RFC 4702
995 RFC 4703
996 And the corresponding drafts were:
998 draft-ietf-dnsext-dhcid-rr-??.txt
1000 draft-ietf-dhc-fqdn-option-??.txt
1001 draft-ietf-dhc-ddns-resolution-??.txt
1002 The basic framework for the two schemes is similar with the main mate‐
1004 rial difference being that a DHCID RR is used in the standard version
1005 while the interim versions uses a TXT RR. The format of the TXT record
1006 bears a resemblance to the DHCID RR but it is not equivalent (MD5 vs
1007 SHA2, field length differences etc).
1008 In these two schemes the DHCP server does not necessarily always update
1010 both the A and the PTR records. The FQDN option includes a flag which,
1011 when sent by the client, indicates that the client wishes to update its
1012 own A record. In that case, the server can be configured either to
1013 honor the client´s intentions or ignore them. This is done with the
1014 statement allow client-updates; or the statement ignore client-up‐
1015 dates;. By default, client updates are allowed.
1016 If the server is configured to allow client updates, then if the client
1018 sends a fully-qualified domain name in the FQDN option, the server will
1019 use that name the client sent in the FQDN option to update the PTR
1020 record. For example, let us say that the client is a visitor from the
1021 "radish.org" domain, whose hostname is "jschmoe". The server is for
1022 the "example.org" domain. The DHCP client indicates in the FQDN option
1023 that its FQDN is "jschmoe.radish.org.". It also indicates that it
1024 wants to update its own A record. The DHCP server therefore does not
1025 attempt to set up an A record for the client, but does set up a PTR
1026 record for the IP address that it assigns the client, pointing at
1027 jschmoe.radish.org. Once the DHCP client has an IP address, it can up‐
1028 date its own A record, assuming that the "radish.org" DNS server will
1029 allow it to do so.
1030 If the server is configured not to allow client updates, or if the
1032 client doesn´t want to do its own update, the server will simply choose
1033 a name for the client. By default, the server will choose from the fol‐
1034 lowing three values:
1035 1. fqdn option (if present)
1037 2. hostname option (if present)
1038 3. Configured hostname option (if defined).
1039 If these defaults for choosing the host name are not appropriate you
1041 can write your own statement to set the ddns-hostname variable as you
1042 wish. If none of the above are found the server will use the host dec‐
1043 laration name (if one) and use-host-decl-names is on.
1044 It will use its own domain name for the client. It will then update
1046 both the A and PTR record, using the name that it chose for the client.
1047 If the client sends a fully-qualified domain name in the fqdn option,
1048 the server uses only the leftmost part of the domain name - in the ex‐
1049 ample above, "jschmoe" instead of "jschmoe.radish.org".
1050 Further, if the ignore client-updates; directive is used, then the
1052 server will in addition send a response in the DHCP packet, using the
1053 FQDN Option, that implies to the client that it should perform its own
1054 updates if it chooses to do so. With deny client-updates;, a response
1055 is sent which indicates the client may not perform updates.
1056 Both the standard and interim options also include a method to allow
1058 more than one DHCP server to update the DNS database without acciden‐
1059 tally deleting A records that shouldn´t be deleted nor failing to add A
1060 records that should be added. For the standard option the method works
1061 as follows:
1062 When the DHCP server issues a client a new lease, it creates a text
1064 string that is an SHA hash over the DHCP client´s identification (see
1065 RFCs 4701 & 4702 for details). The update attempts to add an A record
1066 with the name the server chose and a DHCID record containing the hashed
1067 identifier string (hashid). If this update succeeds, the server is
1068 done.
1069 If the update fails because the A record already exists, then the DHCP
1071 server attempts to add the A record with the prerequisite that there
1072 must be a DHCID record in the same name as the new A record, and that
1073 DHCID record´s contents must be equal to hashid. If this update suc‐
1074 ceeds, then the client has its A record and PTR record. If it fails,
1075 then the name the client has been assigned (or requested) is in use,
1076 and can´t be used by the client. At this point the DHCP server gives
1077 up trying to do a DNS update for the client until the client chooses a
1078 new name.
1079 The server also does not update very aggressively. Because each DNS
1081 update involves a round trip to the DNS server, there is a cost associ‐
1082 ated with doing updates even if they do not actually modify the DNS
1083 database. So the DHCP server tracks whether or not it has updated the
1084 record in the past (this information is stored on the lease) and does
1085 not attempt to update records that it thinks it has already updated.
1086 This can lead to cases where the DHCP server adds a record, and then
1088 the record is deleted through some other mechanism, but the server
1089 never again updates the DNS because it thinks the data is already
1090 there. In this case the data can be removed from the lease through op‐
1091 erator intervention, and once this has been done, the DNS will be up‐
1092 dated the next time the client renews.
1093 The interim DNS update scheme was written before the RFCs were final‐
1095 ized and does not quite follow them. The RFCs call for a new DHCID
1096 RRtype while the interim DNS update scheme uses a TXT record. In addi‐
1097 tion the ddns-resolution draft called for the DHCP server to put a
1098 DHCID RR on the PTR record, but the interim update method does not do
1099 this. In the final RFC this requirement was relaxed such that a server
1100 may add a DHCID RR to the PTR record.
1101
1103 As described in RFC 4703, section 5.2, in order to perform DDNS in dual
1104 stack environments, both IPv4 and IPv6 servers would need to be config‐
1105 ured to use the standard update style and participating IPv4 clients
1106 MUST convey DUIDs as described in RFC 4361, section 6.1., in their
1107 dhcp-client-identifiers.
1108 In a nutshell, this mechanism is intended to use globally unique DUIDs
1110 to idenfity both IPv4 and IPv6 clients, and where a device has both
1111 IPv4 and IPv6 leases it is identified by the same DUID. This allows a
1112 dual stack client to use the same FQDN for both mappings, while being
1113 protected from updates for other clients by the rules of conflict de‐
1114 tection.
1115 However, not all IPv4 clients implement this behavior which makes sup‐
1117 porting them dual stack environments problematic. In order to address
1118 this issue ISC DHCP (as of 4.4.0) supports a new mode of DDNS conflict
1119 resolution referred to as Dual Stack Mixed Mode (DSMM).
1120 The concept behind DSMM is relatively simple. All dhcp servers of one
1122 protocol (IPv4 or v6) use one ddns-update-style (interim or standard)
1123 while all servers of the "other" protocol will use the "other" ddns-ud‐
1124 pate-style. In this way, all servers of a given protocol are using the
1125 same record type (TXT or DHCID) for their DHCID RR entries. This al‐
1126 lows conflict detection to be enforced within each protocol without in‐
1127 terferring with the other's entries.
1128 DSMM modifications now ensure that IPv4 DSMM servers only ever modify A
1130 records, their associated PTR records and DHCID records, while DSMM
1131 IPv6 severs only modify AAAA records, their associated PTR records, and
1132 DHCID records.
1133 Note that DSMM is not a perfect solution, it is a compromise that can
1135 work well provided all participating DNS updaters play by DSMM rules.
1136 As with anything else in life, it only works as well as those who par‐
1137 ticpate behave.
1138 While conflict detection is enabled by default, DSMM is not. To enable
1140 DSMM, both update-conflict-detection and ddns-dual-stack-mixed-mode
1141 must be true.
1142
1144 Built into conflict resolution is the protection of manually made en‐
1145 tries for static clients. Per the rules of conflict resolution, a DNS
1146 updater may not alter forward DNS entries unless there is a DHCID RR
1147 which matches for whom the update is being made. Therefore, any for‐
1148 ward DNS entries without a corresponding DHCID RR cannot be altered by
1149 such an updater.
1150 In some environments, it may be desirable to use only this aspect of
1152 conflict resolution and allow DNS updaters to overwrite entries for dy‐
1153 namic clients regardless of what client owns them. In other words, the
1154 presence or lack of a DHCID RR is used to determine whether entries may
1155 or may not be overwritten. Whether or not the client matches the data
1156 value of the DHCID RR is irrelevant. This behavior, off by default,
1157 can be configured through the parameter, ddns-guard-id-must-match. As
1158 with DSMM, this behavior is can only be enabled if conflict resolution
1159 is enabled. This behavior should be considered carefully before
1160 electing to use it.
1161 There is an additional parameter that can be used with DSMM ddns-other-
1163 guard-is-dynamic. When enabled along with DSMM, a server will regard
1164 the presence of a DHCID RR of the other style type as indicating that
1165 the forward DNS entries for that FQDN should be dynamic and may be
1166 overwritten. For example, such a server using interim style could
1167 overwrite the DNS entries for an FQDN if there is only a DHDID type DH‐
1168 DID RR for the FQDN. Essentially, if there are dynamic entries for one
1169 protocol, that is enough to overcome the static protection of entries
1170 for the other protocol. This behavior warrants careful consideration
1171 before electing to use it.
1172
1174 When you set your DNS server up to allow updates from the DHCP server,
1175 you may be exposing it to unauthorized updates. To avoid this, you
1176 should use TSIG signatures - a method of cryptographically signing up‐
1177 dates using a shared secret key. As long as you protect the secrecy of
1178 this key, your updates should also be secure. Note, however, that the
1179 DHCP protocol itself provides no security, and that clients can there‐
1180 fore provide information to the DHCP server which the DHCP server will
1181 then use in its updates, with the constraints described previously.
1182 The DNS server must be configured to allow updates for any zone that
1184 the DHCP server will be updating. For example, let us say that clients
1185 in the sneedville.edu domain will be assigned addresses on the
1186 10.10.17.0/24 subnet. In that case, you will need a key declaration
1187 for the TSIG key you will be using, and also two zone declarations -
1188 one for the zone containing A records that will be updates and one for
1189 the zone containing PTR records - for ISC BIND, something like this:
1190 key DHCP_UPDATER {
1192 algorithm hmac-md5;
1193 secret pRP5FapFoJ95JEL06sv4PQ==;
1194 };
1195 zone "example.org" {
1197 type master;
1198 file "example.org.db";
1199 allow-update { key DHCP_UPDATER; };
1200 };
1201 zone "17.10.10.in-addr.arpa" {
1203 type master;
1204 file "10.10.17.db";
1205 allow-update { key DHCP_UPDATER; };
1206 };
1207 You will also have to configure your DHCP server to do updates to these
1209 zones. To do so, you need to add something like this to your
1210 dhcpd.conf file:
1211 key DHCP_UPDATER {
1213 algorithm hmac-md5;
1214 secret pRP5FapFoJ95JEL06sv4PQ==;
1215 };
1216 zone EXAMPLE.ORG. {
1218 primary 127.0.0.1;
1219 key DHCP_UPDATER;
1220 }
1221 zone 17.127.10.in-addr.arpa. {
1223 primary 127.0.0.1;
1224 key DHCP_UPDATER;
1225 }
1226 The primary statement specifies the IP address of the name server whose
1228 zone information is to be updated. In addition to the primary state‐
1229 ment there are also the primary6 , secondary and secondary6 statements.
1230 The primary6 statement specifies an IPv6 address for the name server.
1231 The secondaries provide for additional addresses for name servers to be
1232 used if the primary does not respond. The number of name servers the
1233 DDNS code will attempt to use before giving up is limited and is cur‐
1234 rently set to three.
1235 Note that the zone declarations have to correspond to authority records
1237 in your name server - in the above example, there must be an SOA record
1238 for "example.org." and for "17.10.10.in-addr.arpa.". For example, if
1239 there were a subdomain "foo.example.org" with no separate SOA, you
1240 could not write a zone declaration for "foo.example.org." Also keep in
1241 mind that zone names in your DHCP configuration should end in a ".";
1242 this is the preferred syntax. If you do not end your zone name in a
1243 ".", the DHCP server will figure it out. Also note that in the DHCP
1244 configuration, zone names are not encapsulated in quotes where there
1245 are in the DNS configuration.
1246 You should choose your own secret key, of course. The ISC BIND 9 dis‐
1248 tribution comes with a program for generating secret keys called
1249 dnssec-keygen. If you are using BIND 9´s dnssec-keygen, the above key
1250 would be created as follows:
1251 dnssec-keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER
1253 The key name, algorithm, and secret must match that being used by the
1255 DNS server. The DHCP server currently supports the following algo‐
1256 rithms:
1257 HMAC-MD5
1259 HMAC-SHA1
1260 HMAC-SHA224
1261 HMAC-SHA256
1262 HMAC-SHA384
1263 HMAC-SHA512
1264 You may wish to enable logging of DNS updates on your DNS server. To
1266 do so, you might write a logging statement like the following:
1267 logging {
1269 channel update_debug {
1270 file "/var/log/update-debug.log";
1271 severity debug 3;
1272 print-category yes;
1273 print-severity yes;
1274 print-time yes;
1275 };
1276 channel security_info {
1277 file "/var/log/named-auth.info";
1278 severity info;
1279 print-category yes;
1280 print-severity yes;
1281 print-time yes;
1282 };
1283 category update { update_debug; };
1285 category security { security_info; };
1286 };
1287 You must create the /var/log/named-auth.info and /var/log/update-de‐
1289 bug.log files before starting the name server. For more information on
1290 configuring ISC BIND, consult the documentation that accompanies it.
1291
1293 There are three kinds of events that can happen regarding a lease, and
1294 it is possible to declare statements that occur when any of these
1295 events happen. These events are the commit event, when the server has
1296 made a commitment of a certain lease to a client, the release event,
1297 when the client has released the server from its commitment, and the
1298 expiry event, when the commitment expires.
1299 To declare a set of statements to execute when an event happens, you
1301 must use the on statement, followed by the name of the event, followed
1302 by a series of statements to execute when the event happens, enclosed
1303 in braces.
1304
1306 The include statement
1307 include "filename";
1309 The include statement is used to read in a named file, and process the
1311 contents of that file as though it were entered in place of the include
1312 statement.
1313 The shared-network statement
1315 shared-network name {
1317 [ parameters ]
1318 [ declarations ]
1319 }
1320 The shared-network statement is used to inform the DHCP server that
1322 some IP subnets actually share the same physical network. Any subnets
1323 in a shared network should be declared within a shared-network state‐
1324 ment. Parameters specified in the shared-network statement will be
1325 used when booting clients on those subnets unless parameters provided
1326 at the subnet or host level override them. If any subnet in a shared
1327 network has addresses available for dynamic allocation, those addresses
1328 are collected into a common pool for that shared network and assigned
1329 to clients as needed. There is no way to distinguish on which subnet
1330 of a shared network a client should boot.
1331 Name should be the name of the shared network. This name is used when
1333 printing debugging messages, so it should be descriptive for the shared
1334 network. The name may have the syntax of a valid domain name (although
1335 it will never be used as such), or it may be any arbitrary name, en‐
1336 closed in quotes.
1337 The subnet statement
1339 subnet subnet-number netmask netmask {
1341 [ parameters ]
1342 [ declarations ]
1343 }
1344 The subnet statement is used to provide dhcpd with enough information
1346 to tell whether or not an IP address is on that subnet. It may also be
1347 used to provide subnet-specific parameters and to specify what ad‐
1348 dresses may be dynamically allocated to clients booting on that subnet.
1349 Such addresses are specified using the range declaration.
1350 The subnet-number should be an IP address or domain name which resolves
1352 to the subnet number of the subnet being described. The netmask should
1353 be an IP address or domain name which resolves to the subnet mask of
1354 the subnet being described. The subnet number, together with the net‐
1355 mask, are sufficient to determine whether any given IP address is on
1356 the specified subnet.
1357 Although a netmask must be given with every subnet declaration, it is
1359 recommended that if there is any variance in subnet masks at a site, a
1360 subnet-mask option statement be used in each subnet declaration to set
1361 the desired subnet mask, since any subnet-mask option statement will
1362 override the subnet mask declared in the subnet statement.
1363 The subnet6 statement
1365 subnet6 subnet6-number {
1367 [ parameters ]
1368 [ declarations ]
1369 }
1370 The subnet6 statement is used to provide dhcpd with enough information
1372 to tell whether or not an IPv6 address is on that subnet6. It may also
1373 be used to provide subnet-specific parameters and to specify what ad‐
1374 dresses may be dynamically allocated to clients booting on that subnet.
1375 The subnet6-number should be an IPv6 network identifier, specified as
1377 ip6-address/bits.
1378 The range statement
1380 range [ dynamic-bootp ] low-address [ high-address];
1382 For any subnet on which addresses will be assigned dynamically, there
1384 must be at least one range statement. The range statement gives the
1385 lowest and highest IP addresses in a range. All IP addresses in the
1386 range should be in the subnet in which the range statement is declared.
1387 The dynamic-bootp flag may be specified if addresses in the specified
1388 range may be dynamically assigned to BOOTP clients as well as DHCP
1389 clients. When specifying a single address, high-address can be omit‐
1390 ted.
1391 The range6 statement
1393 range6 low-address high-address;
1395 range6 subnet6-number;
1396 range6 subnet6-number temporary;
1397 range6 address temporary;
1398 For any IPv6 subnet6 on which addresses will be assigned dynamically,
1400 there must be at least one range6 statement. The range6 statement can
1401 either be the lowest and highest IPv6 addresses in a range6, or use
1402 CIDR notation, specified as ip6-address/bits. All IP addresses in the
1403 range6 should be in the subnet6 in which the range6 statement is de‐
1404 clared.
1405 The temporary variant makes the prefix (by default on 64 bits) avail‐
1407 able for temporary (RFC 4941) addresses. A new address per prefix in
1408 the shared network is computed at each request with an IA_TA option.
1409 Release and Confirm ignores temporary addresses.
1410 Any IPv6 addresses given to hosts with fixed-address6 are excluded from
1412 the range6, as are IPv6 addresses on the server itself.
1413 The prefix6 statement
1415 prefix6 low-address high-address / bits;
1417 The prefix6 is the range6 equivalent for Prefix Delegation (RFC 3633).
1419 Prefixes of bits length are assigned between low-address and high-ad‐
1420 dress.
1421 Any IPv6 prefixes given to static entries (hosts) with fixed-prefix6
1423 are excluded from the prefix6.
1424 This statement is currently global but it should have a shared-network
1426 scope.
1427 The host statement
1429 host hostname {
1431 [ parameters ]
1432 [ declarations ]
1433 }
1434 The host declaration provides a way for the DHCP server to identify a
1436 DHCP or BOOTP client. This allows the server to provide configuration
1437 information including fixed addresses or, in DHCPv6, fixed prefixes for
1438 a specific client.
1439 If it is desirable to be able to boot a DHCP or BOOTP client on more
1441 than one subnet with fixed v4 addresses, more than one address may be
1442 specified in the fixed-address declaration, or more than one host
1443 statement may be specified matching the same client.
1444 The fixed-address6 declaration is used for v6 addresses. At this time
1446 it only works with a single address. For multiple addresses specify
1447 multiple host statements.
1448 If client-specific boot parameters must change based on the network to
1450 which the client is attached, then multiple host declarations should be
1451 used. The host declarations will only match a client if one of their
1452 fixed-address statements is viable on the subnet (or shared network)
1453 where the client is attached. Conversely, for a host declaration to
1454 match a client being allocated a dynamic address, it must not have any
1455 fixed-address statements. You may therefore need a mixture of host
1456 declarations for any given client...some having fixed-address state‐
1457 ments, others without.
1458 hostname should be a name identifying the host. If a hostname option
1460 is not specified for the host, hostname is used.
1461 Host declarations are matched to actual DHCP or BOOTP clients by match‐
1463 ing the dhcp-client-identifier or pxe-client-id options specified in
1464 the host declaration to the one supplied by the client, or, if the host
1465 declaration or the client does not provide a dhcp-client-identifier or
1466 pxe-client-id options, by matching the hardware parameter in the host
1467 declaration to the network hardware address supplied by the client.
1468 BOOTP clients do not normally provide a dhcp-client-identifier, so the
1469 hardware address must be used for all clients that may boot using the
1470 BOOTP protocol.
1471 DHCPv6 servers can use the host-identifier option parameter in the host
1473 declaration, and specify any option with a fixed value to identify
1474 hosts.
1475 Please be aware that only the dhcp-client-identifier and pxe-client-id
1477 options and the hardware address can be used to match a host declara‐
1478 tion, or the host-identifier option parameter for DHCPv6 servers. For
1479 example, it is not possible to match a host declaration to a host-name
1480 option. This is because the host-name option cannot be guaranteed to
1481 be unique for any given client, whereas both the hardware address and
1482 dhcp-client-identifier option are at least theoretically guaranteed to
1483 be unique to a given client.
1484 The group statement
1486 group {
1488 [ parameters ]
1489 [ declarations ]
1490 }
1491 The group statement is used simply to apply one or more parameters to a
1493 group of declarations. It can be used to group hosts, shared networks,
1494 subnets, or even other groups.
1495
1497 The allow and deny statements can be used to control the response of
1498 the DHCP server to various sorts of requests. The allow and deny key‐
1499 words actually have different meanings depending on the context. In a
1500 pool context, these keywords can be used to set up access lists for ad‐
1501 dress allocation pools. In other contexts, the keywords simply control
1502 general server behavior with respect to clients based on scope. In a
1503 non-pool context, the ignore keyword can be used in place of the deny
1504 keyword to prevent logging of denied requests.
1505
1507 The following usages of allow and deny will work in any scope, although
1508 it is not recommended that they be used in pool declarations.
1509 The unknown-clients keyword
1511 allow unknown-clients;
1513 deny unknown-clients;
1514 ignore unknown-clients;
1515 The unknown-clients flag is used to tell dhcpd whether or not to dynam‐
1517 ically assign addresses to unknown clients. Dynamic address assignment
1518 to unknown clients is allowed by default. An unknown client is simply
1519 a client that has no host declaration.
1520 The use of this option is now deprecated. If you are trying to re‐
1522 strict access on your network to known clients, you should use deny un‐
1523 known-clients; inside of your address pool, as described under the
1524 heading ALLOW AND DENY WITHIN POOL DECLARATIONS.
1525 The bootp keyword
1527 allow bootp;
1529 deny bootp;
1530 ignore bootp;
1531 The bootp flag is used to tell dhcpd whether or not to respond to bootp
1533 queries. Bootp queries are allowed by default.
1534 The booting keyword
1536 allow booting;
1538 deny booting;
1539 ignore booting;
1540 The booting flag is used to tell dhcpd whether or not to respond to
1542 queries from a particular client. This keyword only has meaning when
1543 it appears in a host declaration. By default, booting is allowed, but
1544 if it is disabled for a particular client, then that client will not be
1545 able to get an address from the DHCP server.
1546 The duplicates keyword
1548 allow duplicates;
1550 deny duplicates;
1551 Host declarations can match client messages based on the DHCP Client
1553 Identifier option or based on the client's network hardware type and
1554 MAC address. If the MAC address is used, the host declaration will
1555 match any client with that MAC address - even clients with different
1556 client identifiers. This doesn't normally happen, but is possible when
1557 one computer has more than one operating system installed on it - for
1558 example, Microsoft Windows and NetBSD or Linux.
1559 The duplicates flag tells the DHCP server that if a request is received
1561 from a client that matches the MAC address of a host declaration, any
1562 other leases matching that MAC address should be discarded by the
1563 server, even if the UID is not the same. This is a violation of the
1564 DHCP protocol, but can prevent clients whose client identifiers change
1565 regularly from holding many leases at the same time. By default, du‐
1566 plicates are allowed.
1567 The declines keyword
1569 allow declines;
1571 deny declines;
1572 ignore declines;
1573 The DHCPDECLINE message is used by DHCP clients to indicate that the
1575 lease the server has offered is not valid. When the server receives a
1576 DHCPDECLINE for a particular address, it normally abandons that ad‐
1577 dress, assuming that some unauthorized system is using it. Unfortu‐
1578 nately, a malicious or buggy client can, using DHCPDECLINE messages,
1579 completely exhaust the DHCP server's allocation pool. The server will
1580 eventually reclaim these leases, but not while the client is running
1581 through the pool. This may cause serious thrashing in the DNS, and it
1582 will also cause the DHCP server to forget old DHCP client address allo‐
1583 cations.
1584 The declines flag tells the DHCP server whether or not to honor DHCPDE‐
1586 CLINE messages. If it is set to deny or ignore in a particular scope,
1587 the DHCP server will not respond to DHCPDECLINE messages.
1588 The declines flag is only supported by DHCPv4 servers. Given the large
1590 IPv6 address space and the internal limits imposed by the server's ad‐
1591 dress generation mechanism we don't think it is necessary for DHCPv6
1592 servers at this time.
1593 Currently, abandoned IPv6 addresses are reclaimed in one of two ways:
1595 a) Client renews a specific address:
1596 If a client using a given DUID submits a DHCP REQUEST containing
1597 the last address abandoned by that DUID, the address will be
1598 reassigned to that client.
1599 b) Upon the second restart following an address abandonment. When
1601 an address is abandoned it is both recorded as such in the lease
1602 file and retained as abandoned in server memory until the server
1603 is restarted. Upon restart, the server will process the lease file
1604 and all addresses whose last known state is abandoned will be
1605 retained as such in memory but not rewritten to the lease file.
1606 This means that a subsequent restart of the server will not see the
1607 abandoned addresses in the lease file and therefore have no record
1608 of them as abandoned in memory and as such perceive them as free
1609 for assignment.
1610 The total number addresses in a pool, available for a given DUID value,
1612 is internally limited by the server's address generation mechanism. If
1613 through mistaken configuration, multiple clients are using the same
1614 DUID they will competing for the same addresses causing the server to
1615 reach this internal limit rather quickly. The internal limit isolates
1616 this type of activity such that address range is not exhausted for
1617 other DUID values. The appearance of the following error log, can be
1618 an indication of this condition:
1619 "Best match for DUID <XX> is an abandoned address, This may be a
1621 result of multiple clients attempting to use this DUID"
1622 where <XX> is an actual DUID value depicted as colon separated
1624 string of bytes in hexadecimal values.
1625 The client-updates keyword
1627 allow client-updates;
1629 deny client-updates;
1630 The client-updates flag tells the DHCP server whether or not to honor
1632 the client's intention to do its own update of its A record. See the
1633 documentation under the heading THE DNS UPDATE SCHEME for details.
1634 The leasequery keyword
1636 allow leasequery;
1638 deny leasequery;
1639 The leasequery flag tells the DHCP server whether or not to answer DHC‐
1641 PLEASEQUERY packets. The answer to a DHCPLEASEQUERY packet includes in‐
1642 formation about a specific lease, such as when it was issued and when
1643 it will expire. By default, the server will not respond to these pack‐
1644 ets.
1645
1647 The uses of the allow and deny keywords shown in the previous section
1648 work pretty much the same way whether the client is sending a DHCPDIS‐
1649 COVER or a DHCPREQUEST message - an address will be allocated to the
1650 client (either the old address it's requesting, or a new address) and
1651 then that address will be tested to see if it's okay to let the client
1652 have it. If the client requested it, and it's not okay, the server
1653 will send a DHCPNAK message. Otherwise, the server will simply not re‐
1654 spond to the client. If it is okay to give the address to the client,
1655 the server will send a DHCPACK message.
1656 The primary motivation behind pool declarations is to have address al‐
1658 location pools whose allocation policies are different. A client may
1659 be denied access to one pool, but allowed access to another pool on the
1660 same network segment. In order for this to work, access control has to
1661 be done during address allocation, not after address allocation is
1662 done.
1663 When a DHCPREQUEST message is processed, address allocation simply con‐
1665 sists of looking up the address the client is requesting and seeing if
1666 it's still available for the client. If it is, then the DHCP server
1667 checks both the address pool permit lists and the relevant in-scope al‐
1668 low and deny statements to see if it's okay to give the lease to the
1669 client. In the case of a DHCPDISCOVER message, the allocation process
1670 is done as described previously in the ADDRESS ALLOCATION section.
1671 When declaring permit lists for address allocation pools, the following
1673 syntaxes are recognized following the allow or deny keywords:
1674 known-clients;
1676 If specified, this statement either allows or prevents allocation from
1678 this pool to any client that has a host declaration (i.e., is known).
1679 A client is known if it has a host declaration in any scope, not just
1680 the current scope.
1681 unknown-clients;
1683 If specified, this statement either allows or prevents allocation from
1685 this pool to any client that has no host declaration (i.e., is not
1686 known).
1687 members of "class";
1689 If specified, this statement either allows or prevents allocation from
1691 this pool to any client that is a member of the named class.
1692 dynamic bootp clients;
1694 If specified, this statement either allows or prevents allocation from
1696 this pool to any bootp client.
1697 authenticated clients;
1699 If specified, this statement either allows or prevents allocation from
1701 this pool to any client that has been authenticated using the DHCP au‐
1702 thentication protocol. This is not yet supported.
1703 unauthenticated clients;
1705 If specified, this statement either allows or prevents allocation from
1707 this pool to any client that has not been authenticated using the DHCP
1708 authentication protocol. This is not yet supported.
1709 all clients;
1711 If specified, this statement either allows or prevents allocation from
1713 this pool to all clients. This can be used when you want to write a
1714 pool declaration for some reason, but hold it in reserve, or when you
1715 want to renumber your network quickly, and thus want the server to
1716 force all clients that have been allocated addresses from this pool to
1717 obtain new addresses immediately when they next renew.
1718 after time;
1720 If specified, this statement either allows or prevents allocation from
1722 this pool after a given date. This can be used when you want to move
1723 clients from one pool to another. The server adjusts the regular lease
1724 time so that the latest expiry time is at the given time+min-lease-
1725 time. A short min-lease-time enforces a step change, whereas a longer
1726 min-lease-time allows for a gradual change. time is either second
1727 since epoch, or a UTC time string e.g. 4 2007/08/24 09:14:32 or a
1728 string with time zone offset in seconds e.g. 4 2007/08/24 11:14:32
1729 -7200
1730
1732 The abandon-lease-time statement
1733 abandon-lease-time time;
1735 Time should be the maximum amount of time (in seconds) that an aban‐
1737 doned IPv4 lease remains unavailable for assignment to a client.
1738 Abandoned leases will only be offered to clients if there are no free
1739 leases. If not defined, the default abandon lease time is 86400 sec‐
1740 onds (24 hours). Note the abandoned lease time for a given lease is
1741 preserved across server restarts. The parameter may only be set at
1742 the global scope and is evaluated only once during server startup.
1743 Values less than sixty seconds are not recommended as this is below
1745 the ping check threshold and can cause leases once abandoned but
1746 since returned to the free state to not be pinged before being of‐
1747 fered. If the requested time is larger than 0x7FFFFFFF - 1 or the
1748 sum of the current time plus the abandoned time isgreater than
1749 0x7FFFFFFF it is treated as infinite.
1750 The adaptive-lease-time-threshold statement
1752 adaptive-lease-time-threshold percentage;
1754 When the number of allocated leases within a pool rises above the
1756 percentage given in this statement, the DHCP server decreases the
1757 lease length for new clients within this pool to min-lease-time sec‐
1758 onds. Clients renewing an already valid (long) leases get at least
1759 the remaining time from the current lease. Since the leases expire
1760 faster, the server may either recover more quickly or avoid pool ex‐
1761 haustion entirely. Once the number of allocated leases drop below
1762 the threshold, the server reverts back to normal lease times. Valid
1763 percentages are between 1 and 99.
1764 The always-broadcast statement
1766 always-broadcast flag;
1768 The DHCP and BOOTP protocols both require DHCP and BOOTP clients to
1770 set the broadcast bit in the flags field of the BOOTP message header.
1771 Unfortunately, some DHCP and BOOTP clients do not do this, and there‐
1772 fore may not receive responses from the DHCP server. The DHCP server
1773 can be made to always broadcast its responses to clients by setting
1774 this flag to ´on´ for the relevant scope; relevant scopes would be
1775 inside a conditional statement, as a parameter for a class, or as a
1776 parameter for a host declaration. To avoid creating excess broadcast
1777 traffic on your network, we recommend that you restrict the use of
1778 this option to as few clients as possible. For example, the Micro‐
1779 soft DHCP client is known not to have this problem, as are the Open‐
1780 Transport and ISC DHCP clients.
1781 The always-reply-rfc1048 statement
1783 always-reply-rfc1048 flag;
1785 Some BOOTP clients expect RFC1048-style responses, but do not follow
1787 RFC1048 when sending their requests. You can tell that a client is
1788 having this problem if it is not getting the options you have config‐
1789 ured for it and if you see in the server log the message "(non-
1790 rfc1048)" printed with each BOOTREQUEST that is logged.
1791 If you want to send rfc1048 options to such a client, you can set the
1793 always-reply-rfc1048 option in that client's host declaration, and
1794 the DHCP server will respond with an RFC-1048-style vendor options
1795 field. This flag can be set in any scope, and will affect all
1796 clients covered by that scope.
1797 The authoritative statement
1799 authoritative;
1801 not authoritative;
1803 The DHCP server will normally assume that the configuration informa‐
1805 tion about a given network segment is not known to be correct and is
1806 not authoritative. This is so that if a naive user installs a DHCP
1807 server not fully understanding how to configure it, it does not send
1808 spurious DHCPNAK messages to clients that have obtained addresses
1809 from a legitimate DHCP server on the network.
1810 Network administrators setting up authoritative DHCP servers for
1812 their networks should always write authoritative; at the top of their
1813 configuration file to indicate that the DHCP server should send DHCP‐
1814 NAK messages to misconfigured clients. If this is not done, clients
1815 will be unable to get a correct IP address after changing subnets un‐
1816 til their old lease has expired, which could take quite a long time.
1817 Usually, writing authoritative; at the top level of the file should
1819 be sufficient. However, if a DHCP server is to be set up so that it
1820 is aware of some networks for which it is authoritative and some net‐
1821 works for which it is not, it may be more appropriate to declare au‐
1822 thority on a per-network-segment basis.
1823 Note that the most specific scope for which the concept of authority
1825 makes any sense is the physical network segment - either a shared-
1826 network statement or a subnet statement that is not contained within
1827 a shared-network statement. It is not meaningful to specify that the
1828 server is authoritative for some subnets within a shared network, but
1829 not authoritative for others, nor is it meaningful to specify that
1830 the server is authoritative for some host declarations and not oth‐
1831 ers.
1832 In order for DHCPINFORMs to be responded to by the server, they must
1834 match to subnets over which the server has authority; otherwise they
1835 will be ignored and logged. To minimize the impact on logging vol‐
1836 ume, only the first and every subsequent 100th occurrence of an ig‐
1837 nored DHCPINFORM is logged.
1838 The boot-unknown-clients statement
1840 boot-unknown-clients flag;
1842 If the boot-unknown-clients statement is present and has a value of
1844 false or off, then clients for which there is no host declaration
1845 will not be allowed to obtain IP addresses. If this statement is not
1846 present or has a value of true or on, then clients without host dec‐
1847 larations will be allowed to obtain IP addresses, as long as those
1848 addresses are not restricted by allow and deny statements within
1849 their pool declarations.
1850 The check-secs-byte-order statement
1852 check-secs-byte-order flag;
1854 When check-secs-byte-order is enabled, the server will check for
1856 DHCPv4 clients that do the byte ordering on the secs field incor‐
1857 rectly. This field should be in network byte order but some clients
1858 get it wrong. When this parameter is enabled the server will examine
1859 the secs field and if it looks wrong (high byte non zero and low byte
1860 zero) swap the bytes. The default is disabled. This parameter is
1861 only useful when doing load balancing within failover. (Formerly,
1862 this behavior had to be enabled during compilation configuration via
1863 --enable-secs-byteorder).
1864 The db-time-format statement
1866 db-time-format [ default | local ] ;
1868 The DHCP server software outputs several timestamps when writing
1870 leases to persistent storage. This configuration parameter se‐
1871 lects one of two output formats. The default format prints the
1872 day, date, and time in UTC, while the local format prints the sys‐
1873 tem seconds-since-epoch, and helpfully provides the day and time
1874 in the system timezone in a comment. The time formats are de‐
1875 scribed in detail in the dhcpd.leases(5) manpage.
1876 The ddns-hostname statement
1878 ddns-hostname name;
1880 The name parameter should be the hostname that will be used in
1882 setting up the client's A and PTR records. If no ddns-hostname is
1883 specified in scope, then the server will derive the hostname auto‐
1884 matically, using an algorithm that varies for each of the differ‐
1885 ent update methods.
1886 The ddns-domainname statement
1888 ddns-domainname name;
1890 The name parameter should be the domain name that will be appended
1892 to the client's hostname to form a fully-qualified domain-name
1893 (FQDN).
1894 The ddns-dual-stack-mixed-mode statement
1896 ddns-dual-stack-mixed-mode flag;
1898 The ddns-dual-stack-mixed-mode parameter controls whether or not
1900 the server applies Dual Stack Mixed Mode rules during DDNS con‐
1901 flict resolution. This parameter is off by default, has no effect
1902 unless update-conflict-detection is enabled, and may only be spec‐
1903 ified at the global scope.
1904 The ddns-guard-id-must-match statement
1906 ddns-guard-id-must-match flag;
1908 The ddns-guard-id-must-match parameter controls whether or not a
1910 the client id within a DHCID RR must match that of the DNS up‐
1911 date's client to permit DNS entries associated with that DHCID RR
1912 to be ovewritten. Proper conflict resolution requires ID matching
1913 and should only be disabled after careful consideration. When
1914 disabled, it is allows any DNS updater to replace DNS entries that
1915 have an associated DHCID RR, regardless of client identity. This
1916 parameter is on by default, has no effect unless update-conflict-
1917 detection is enabled, and may only be specified at the global
1918 scope.
1919 The dns-local-address4 and dns-local-address6 statements
1921 ddns-local-address4 address;
1923 ddns-local-address6 address;
1925 The address parameter should be the local IPv4 or IPv6 address the
1927 server should use as the from address when sending DDNS update re‐
1928 quests.
1929 The ddns-other-guard-is-dynamic statement
1931 ddns-other-guard-is-dynamic flag;
1933 The ddns-other-guard-is-dynamic parameter controls whether or not
1935 a a server running DSMM will consider the presence of the other
1936 update style DHCID RR as an indcation that a DNS entries may be
1937 overwritten. It should only be enabled after careful study as it
1938 allows DNS entries that would otherwise be protected as static, to
1939 be overwritten in certain cases. This paramater is off by default,
1940 has no effect unless ddns-dual-stack-mixed-mode is enabled, and
1941 may only be specified at the global scope.
1942 The ddns-rev-domainname statement
1944 ddns-rev-domainname name;
1946 The name parameter should be the domain name that will be appended
1948 to the client's reversed IP address to produce a name for use in
1949 the client's PTR record. By default, this is "in-addr.arpa.", but
1950 the default can be overridden here.
1951 The reversed IP address to which this domain name is appended is
1953 always the IP address of the client, in dotted quad notation, re‐
1954 versed - for example, if the IP address assigned to the client is
1955 10.17.92.74, then the reversed IP address is 74.92.17.10. So a
1956 client with that IP address would, by default, be given a PTR
1957 record of 10.17.92.74.in-addr.arpa.
1958 The ddns-update-style parameter
1960 ddns-update-style style;
1962 The style parameter must be one of standard, interim or none. The
1964 ddns-update-style statement is only meaningful in the outer scope
1965 - it is evaluated once after reading the dhcpd.conf file, rather
1966 than each time a client is assigned an IP address, so there is no
1967 way to use different DNS update styles for different clients. The
1968 default is none.
1969 The ddns-updates statement
1971 ddns-updates flag;
1973 The ddns-updates parameter controls whether or not the server will
1975 attempt to do a DNS update when a lease is confirmed. Set this to
1976 off if the server should not attempt to do updates within a cer‐
1977 tain scope. The ddns-updates parameter is on by default. To dis‐
1978 able DNS updates in all scopes, it is preferable to use the ddns-
1979 update-style statement, setting the style to none.
1980 The default-lease-time statement
1982 default-lease-time time;
1984 Time should be the length in seconds that will be assigned to a
1986 lease if the client requesting the lease does not ask for a spe‐
1987 cific expiration time. This is used for both DHCPv4 and DHCPv6
1988 leases (it is also known as the "valid lifetime" in DHCPv6). The
1989 default is 43200 seconds.
1990 The delayed-ack and max-ack-delay statements
1992 delayed-ack count;
1994 max-ack-delay microseconds;
1996 Count should be an integer value from zero to 2^16-1 and defaults
1998 to 0, which means that the feature is disabled. Otherwise, 28 may
1999 be a sensible starting point for many configurations (SO_SNDBUF
2000 size / 576 bytes.) The count represents how many DHCPv4 replies
2001 maximum will be queued pending transmission until after a database
2002 commit event. If this number is reached, a database commit event
2003 (commonly resulting in fsync() and representing a performance pen‐
2004 alty) will be made, and the reply packets will be transmitted in a
2005 batch afterwards. This preserves the RFC2131 direction that "sta‐
2006 ble storage" be updated prior to replying to clients. Should the
2007 DHCPv4 sockets "go dry" (select() returns immediately with no read
2008 sockets), the commit is made and any queued packets are transmit‐
2009 ted.
2010 Similarly, microseconds indicates how many microseconds are per‐
2012 mitted to pass inbetween queuing a packet pending an fsync, and
2013 performing the fsync. Valid values range from 0 to 2^32-1, and
2014 defaults to 250,000 (1/4 of a second).
2015 The delayed-ack feature is compiled in by default, but can be dis‐
2017 abled at compile time with ´./configure --disable-delayed-ack´.
2018 Please note that the delayed-ack feature is not currently compati‐
2019 ble with support for DHPCv4-over-DHCPv6 so when a 4to6 port ommand
2020 line argument enables this in the server the delayed-ack value is
2021 reset to 0.
2022 The dhcp-cache-threshold statement
2024 dhcp-cache-threshold percentage;
2026 The dhcp-cache-threshold statement takes one integer parameter
2028 with allowed values between 0 and 100. The default value is 25
2029 (25% of the lease time). This parameter expresses the percentage
2030 of the total lease time, measured from the beginning, during which
2031 a client's attempt to renew its lease will result in getting the
2032 already assigned lease, rather than an extended lease. This fea‐
2033 ture is supported for both IPv4 and IPv6 and down to the pool
2034 level and for IPv6 all three pool types: NA, TA and PD.
2035 Clients that attempt renewal frequently can cause the server to
2037 update and write the database frequently resulting in a perfor‐
2038 mance impact on the server. The dhcp-cache-threshold statement
2039 instructs the DHCP server to avoid updating leases too frequently
2040 thus avoiding this behavior. Instead the server replies with the
2041 same lease (i.e. reuses it) with no modifications except for CLTT
2042 (Client Last Transmission Time) and for IPv4:
2043 the lease time sent to the client is shortened by the age of
2045 the lease
2046 while for IPv6:
2048 the preferred and valid lifetimes sent to the client are
2050 shortened by the age of the lease.
2051 None of these changes require writing the lease to disk.
2053 When an existing lease is matched to a renewing client, it will be
2056 reused if all of the following conditions are true:
2057 1. The dhcp-cache-threshold is larger than zero
2058 2. The current lease is active
2059 3. The percentage of the lease time that has elapsed is less than
2060 dhcp-cache-threshold
2061 4. The client information provided in the renewal does not alter
2062 any of the following:
2063 a. DNS information and DNS updates are enabled
2064 b. Billing class to which the lease is associated (IPv4 only)
2065 c. The host declaration associated with the lease (IPv4 only)
2066 d. The client id - this may happen if a client boots without
2067 a client id and then starts using one in subsequent
2068 requests. (IPv4 only)
2069 While lease data is not written to disk when a lease is reused,
2071 the server will still execute any on-commit statements.
2072 Note that the lease can be reused if the options the client or re‐
2074 lay agent sends are changed. These changes will not be recorded
2075 in the in-memory or on-disk databases until the client renews af‐
2076 ter the threshold time is reached.
2077 The do-forward-updates statement
2079 do-forward-updates flag;
2081 The do-forward-updates statement instructs the DHCP server as to
2083 whether it should attempt to update a DHCP client´s A record when
2084 the client acquires or renews a lease. This statement has no ef‐
2085 fect unless DNS updates are enabled. Forward updates are enabled
2086 by default. If this statement is used to disable forward updates,
2087 the DHCP server will never attempt to update the client´s A
2088 record, and will only ever attempt to update the client´s PTR
2089 record if the client supplies an FQDN that should be placed in the
2090 PTR record using the fqdn option. If forward updates are enabled,
2091 the DHCP server will still honor the setting of the client-updates
2092 flag.
2093 The dont-use-fsync statement
2095 dont-use-fsync flag;
2097 The dont-use-fsync statement instructs the DHCP server if it
2099 should call fsync() when writing leases to the lease file. By de‐
2100 fault and if the flag is set to false the server will call
2101 fsync(). Suppressing the call to fsync() may increase the perfor‐
2102 mance of the server but it also adds a risk that a lease will not
2103 be properly written to the disk after it has been issued to a
2104 client and before the server stops. This can lead to duplicate
2105 leases being issued to different clients. Using this option is
2106 not recommended.
2107 The dynamic-bootp-lease-cutoff statement
2109 dynamic-bootp-lease-cutoff date;
2111 The dynamic-bootp-lease-cutoff statement sets the ending time for
2113 all leases assigned dynamically to BOOTP clients. Because BOOTP
2114 clients do not have any way of renewing leases, and don't know
2115 that their leases could expire, by default dhcpd assigns infinite
2116 leases to all BOOTP clients. However, it may make sense in some
2117 situations to set a cutoff date for all BOOTP leases - for exam‐
2118 ple, the end of a school term, or the time at night when a facil‐
2119 ity is closed and all machines are required to be powered off.
2120 Date should be the date on which all assigned BOOTP leases will
2122 end. The date is specified in the form:
2123 W YYYY/MM/DD HH:MM:SS
2125 W is the day of the week expressed as a number from zero (Sunday)
2127 to six (Saturday). YYYY is the year, including the century. MM
2128 is the month expressed as a number from 1 to 12. DD is the day of
2129 the month, counting from 1. HH is the hour, from zero to 23. MM
2130 is the minute and SS is the second. The time is always in Coordi‐
2131 nated Universal Time (UTC), not local time.
2132 The dynamic-bootp-lease-length statement
2134 dynamic-bootp-lease-length length;
2136 The dynamic-bootp-lease-length statement is used to set the length
2138 of leases dynamically assigned to BOOTP clients. At some sites,
2139 it may be possible to assume that a lease is no longer in use if
2140 its holder has not used BOOTP or DHCP to get its address within a
2141 certain time period. The period is specified in length as a num‐
2142 ber of seconds. If a client reboots using BOOTP during the time‐
2143 out period, the lease duration is reset to length, so a BOOTP
2144 client that boots frequently enough will never lose its lease.
2145 Needless to say, this parameter should be adjusted with extreme
2146 caution.
2147 The echo-client-id statement
2149 echo-client-id flag;
2151 The echo-client-id statement is used to enable or disable RFC 6842
2153 compliant behavior. If the echo-client-id statement is present
2154 and has a value of true or on, and a DHCP DISCOVER or REQUEST is
2155 received which contains the client identifier option (Option code
2156 61), the server will copy the option into its response (DHCP ACK
2157 or NAK) per RFC 6842. In other words if the client sends the op‐
2158 tion it will receive it back. By default, this flag is off and
2159 client identifiers will not echoed back to the client.
2160 The filename statement
2162 filename "filename";
2164 The filename statement can be used to specify the name of the ini‐
2166 tial boot file which is to be loaded by a client. The filename
2167 should be a filename recognizable to whatever file transfer proto‐
2168 col the client can be expected to use to load the file.
2169 The fixed-address declaration
2171 fixed-address address [, address ... ];
2173 The fixed-address declaration is used to assign one or more fixed
2175 IP addresses to a client. It should only appear in a host decla‐
2176 ration. If more than one address is supplied, then when the
2177 client boots, it will be assigned the address that corresponds to
2178 the network on which it is booting. If none of the addresses in
2179 the fixed-address statement are valid for the network to which the
2180 client is connected, that client will not match the host declara‐
2181 tion containing that fixed-address declaration. Each address in
2182 the fixed-address declaration should be either an IP address or a
2183 domain name that resolves to one or more IP addresses.
2184 The fixed-address6 declaration
2186 fixed-address6 ip6-address ;
2188 The fixed-address6 declaration is used to assign a fixed IPv6 ad‐
2190 dresses to a client. It should only appear in a host declaration.
2191 The fixed-prefix6 declaration
2193 fixed-prefix6 low-address / bits;
2195 The fixed-prefix6 declaration is used to assign a fixed IPv6 pre‐
2197 fix to a client. It should only appear in a host declaration, but
2198 multiple fixed-prefix6 statements may appear in a single host dec‐
2199 laration.
2200 The low-address specifies the start of the prefix and the bits
2202 specifies the size of the prefix in bits.
2203 If there are multiple prefixes for a given host entry the server
2205 will choose one that matches the requested prefix size or, if none
2206 match, the first one.
2207 If there are multiple host declarations the server will try to
2209 choose a declaration where the fixed-address6 matches the client's
2210 subnet. If none match it will choose one that doesn't have a
2211 fixed-address6 statement.
2212 Note Well: Unlike the fixed address the fixed prefix does not need
2214 to match a subnet in order to be served. This allows you to pro‐
2215 vide a prefix to a client that is outside of the subnet on which
2216 the client makes the request to the the server.
2217 The get-lease-hostnames statement
2219 get-lease-hostnames flag;
2221 The get-lease-hostnames statement is used to tell dhcpd whether or
2223 not to look up the domain name corresponding to the IP address of
2224 each address in the lease pool and use that address for the DHCP
2225 hostname option. If flag is true, then this lookup is done for
2226 all addresses in the current scope. By default, or if flag is
2227 false, no lookups are done.
2228 The hardware statement
2230 hardware hardware-type hardware-address;
2232 In order for a BOOTP client to be recognized, its network hardware
2234 address must be declared using a hardware clause in the host
2235 statement. hardware-type must be the name of a physical hardware
2236 interface type. Currently, only the ethernet and token-ring types
2237 are recognized, although support for a fddi hardware type (and
2238 others) would also be desirable. The hardware-address should be a
2239 set of hexadecimal octets (numbers from 0 through ff) separated by
2240 colons. The hardware statement may also be used for DHCP clients.
2241 The host-identifier option statement
2243 host-identifier option option-name option-data;
2245 or
2247 host-identifier v6relopt number option-name option-data;
2249 This identifies a DHCPv6 client in a host statement. option-name
2251 is any option, and option-data is the value for the option that
2252 the client will send. The option-data must be a constant value.
2253 In the v6relopts case the additional number is the relay to exam‐
2254 ine for the specified option name and value. The values are the
2255 same as for the v6relay option. 0 is a no-op, 1 is the relay
2256 closest to the client, 2 the next one in and so on. Values that
2257 are larger than the maximum number of relays (currently 32) indi‐
2258 cate the relay closest to the server independent of number.
2259 The ignore-client-uids statement
2261 ignore-client-uids flag;
2263 If the ignore-client-uids statement is present and has a value of
2265 true or on, the UID for clients will not be recorded. If this
2266 statement is not present or has a value of false or off, then
2267 client UIDs will be recorded.
2268 The infinite-is-reserved statement
2270 infinite-is-reserved flag;
2272 ISC DHCP now supports ´reserved´ leases. See the section on RE‐
2274 SERVED LEASES below. If this flag is on, the server will automat‐
2275 ically reserve leases allocated to clients which requested an in‐
2276 finite (0xffffffff) lease-time.
2277 The default is off.
2279 The lease-file-name statement
2281 lease-file-name name;
2283 Name Where name is the name of the DHCP server's lease file. By
2285 default, this is /var/lib/dhcpd/dhcpd.leases. This statement must
2286 appear in the outer scope of the configuration file - if it ap‐
2287 pears in some other scope, it will have no effect. The value must
2288 be the absolute path of the file to use. The order of precedence
2289 the server uses for the lease file name is:
2290 1. lease-file-name configuration file statement.
2292 2. -lf command line flag.
2293 3. PATH_DHCPD_DB environment variable.
2294 The dhcpv6-lease-file-name statement
2296 dhcpv6-lease-file-name name;
2298 Where name is the name of the DHCP server's lease file when the
2300 server is running DHCPv6. By default, this is
2301 /var/lib/dhcpd/dhcpd6.leases. This statement must appear in the
2302 outer scope of the configuration file - if it appears in some
2303 other scope, it will have no effect. The value must be the abso‐
2304 lute path of the file to use. The order of precedence the server
2305 uses for the lease file name is:
2306 1. dhcpv6-lease-file-name configuration file statement.
2308 2. -lf command line flag.
2309 3. PATH_DHCPD6_DB environment variable.
2310 The lease-id-format parameter
2312 lease-id-format format;
2314 The format parameter must be either octal or hex. This parameter
2316 governs the format used to write certain values to lease files.
2317 With the default format, octal, values are written as quoted
2318 strings in which non-printable characters are represented as octal
2319 escapes - a backslash character followed by three octal digits.
2320 When the hex format is specified, values are written as an un‐
2321 quoted series of pairs of hexadecimal digits, separated by colons.
2322 Currently, the values written out based on lease-id-format are the
2324 server-duid, the uid (DHCPv4 leases), and the IAID_DUID (DHCPv6
2325 leases). Note the server automatically reads the values in either
2326 format.
2327 The limit-addrs-per-ia statement
2329 limit-addrs-per-ia number;
2331 By default, the DHCPv6 server will limit clients to one IAADDR per
2333 IA option, meaning one address. If you wish to permit clients to
2334 hang onto multiple addresses at a time, configure a larger number
2335 here.
2336 Note that there is no present method to configure the server to
2338 forcibly configure the client with one IP address per each subnet
2339 on a shared network. This is left to future work.
2340 The local-port statement
2342 local-port port;
2344 This statement causes the DHCP server to listen for DHCP requests
2346 on the UDP port specified in port, rather than on port 67.
2347 The local-address statement
2349 local-address address;
2351 This statement causes the DHCP server to listen for DHCP requests
2353 sent to the specified address, rather than requests sent to all
2354 addresses. Since serving directly attached DHCP clients implies
2355 that the server must respond to requests sent to the all-ones IP
2356 address, this option cannot be used if clients are on directly at‐
2357 tached networks; it is only realistically useful for a server
2358 whose only clients are reached via unicasts, such as via DHCP re‐
2359 lay agents.
2360 Note: This statement is only effective if the server was compiled
2362 using the USE_SOCKETS #define statement, which is default on a
2363 small number of operating systems, and must be explicitly chosen
2364 at compile-time for all others. You can be sure if your server is
2365 compiled with USE_SOCKETS if you see lines of this format at
2366 startup:
2367 Listening on Socket/eth0
2369 Note also that since this bind()s all DHCP sockets to the speci‐
2371 fied address, that only one address may be supported in a daemon
2372 at a given time.
2373 The local-address6 and bind-local-address6 statements
2375 local-address6 address;
2377 bind-local-address6 flag;
2379 The local-address6 statement causes the DHCP server to send IPv6
2381 packets as originating from the specified IPv6 address, rather
2382 than leaving the kernel to fill in the source address field.
2383 When bind-local-address6 is present and has a value of true or on,
2385 service sockets are bound to address too.
2386 By default address is the undefined address and the bind-local-ad‐
2388 dress6 is disabled, both may only be set at the global scope.
2389 The log-facility statement
2391 log-facility facility;
2393 This statement causes the DHCP server to do all of its logging on
2395 the specified log facility once the dhcpd.conf file has been read.
2396 By default the DHCP server logs to the daemon facility. Possible
2397 log facilities include auth, authpriv, cron, daemon, ftp, kern,
2398 lpr, mail, mark, news, ntp, security, syslog, user, uucp, and lo‐
2399 cal0 through local7. Not all of these facilities are available on
2400 all systems, and there may be other facilities available on other
2401 systems.
2402 In addition to setting this value, you may need to modify your
2404 syslog.conf file to configure logging of the DHCP server. For ex‐
2405 ample, you might add a line like this:
2406 local7.debug /var/log/dhcpd.log
2408 The syntax of the syslog.conf file may be different on some oper‐
2410 ating systems - consult the syslog.conf manual page to be sure.
2411 To get syslog to start logging to the new file, you must first
2412 create the file with correct ownership and permissions (usually,
2413 the same owner and permissions of your /var/log/messages or
2414 /usr/adm/messages file should be fine) and send a SIGHUP to sys‐
2415 logd. Some systems support log rollover using a shell script or
2416 program called newsyslog or logrotate, and you may be able to con‐
2417 figure this as well so that your log file doesn't grow uncontrol‐
2418 lably.
2419 Because the log-facility setting is controlled by the dhcpd.conf
2421 file, log messages printed while parsing the dhcpd.conf file or
2422 before parsing it are logged to the default log facility. To pre‐
2423 vent this, see the README file included with this distribution,
2424 which describes BUG: where is that mentioned in README? how to
2425 change the default log facility. When this parameter is used, the
2426 DHCP server prints its startup message a second time after parsing
2427 the configuration file, so that the log will be as complete as
2428 possible.
2429 The log-threshold-high and log-threshold-low statements
2431 log-threshold-high percentage;
2433 log-threshold-low percentage;
2435 The log-threshold-low and log-threshold-high statements are used
2437 to control when a message is output about pool usage. The value
2438 for both of them is the percentage of the pool in use. If the
2439 high threshold is 0 or has not been specified, no messages will be
2440 produced. If a high threshold is given, a message is output once
2441 the pool usage passes that level. After that, no more messages
2442 will be output until the pool usage falls below the low threshold.
2443 If the low threshold is not given, it default to a value of zero.
2444 A special case occurs when the low threshold is set to be higer
2446 than the high threshold. In this case, a message will be gener‐
2447 ated each time a lease is acknowledged when the pool usage is
2448 above the high threshold.
2449 Note that threshold logging will be automatically disabled for
2451 shared subnets whose total number of addresses is larger than
2452 (2^64)-1. The server will emit a log statement at startup when
2453 threshold logging is disabled as shown below:
2454 "Threshold logging disabled for shared subnet of ranges: <ad‐
2456 dresses>"
2457 This is likely to have no practical runtime effect as CPUs are un‐
2459 likely to support a server actually reaching such a large number
2460 of leases.
2461 The max-lease-time statement
2463 max-lease-time time;
2465 Time should be the maximum length in seconds that will be assigned
2467 to a lease. If not defined, the default maximum lease time is
2468 86400. The only exception to this is that Dynamic BOOTP lease
2469 lengths, which are not specified by the client, are not limited by
2470 this maximum.
2471 The min-lease-time statement
2473 min-lease-time time;
2475 Time should be the minimum length in seconds that will be assigned
2477 to a lease. The default is the minimum of 300 seconds or max-
2478 lease-time.
2479 The min-secs statement
2481 min-secs seconds;
2483 Seconds should be the minimum number of seconds since a client be‐
2485 gan trying to acquire a new lease before the DHCP server will re‐
2486 spond to its request. The number of seconds is based on what the
2487 client reports, and the maximum value that the client can report
2488 is 255 seconds. Generally, setting this to one will result in the
2489 DHCP server not responding to the client's first request, but al‐
2490 ways responding to its second request.
2491 This can be used to set up a secondary DHCP server which never of‐
2493 fers an address to a client until the primary server has been
2494 given a chance to do so. If the primary server is down, the
2495 client will bind to the secondary server, but otherwise clients
2496 should always bind to the primary. Note that this does not, by
2497 itself, permit a primary server and a secondary server to share a
2498 pool of dynamically-allocatable addresses.
2499 The next-server statement
2501 next-server server-name;
2503 The next-server statement is used to specify the host address of
2505 the server from which the initial boot file (specified in the
2506 filename statement) is to be loaded. Server-name should be a nu‐
2507 meric IP address or a domain name. If no next-server statement
2508 applies to a given client, the address 0.0.0.0 is used.
2509 The omapi-port statement
2511 omapi-port port;
2513 The omapi-port statement causes the DHCP server to listen for
2515 OMAPI connections on the specified port. This statement is re‐
2516 quired to enable the OMAPI protocol, which is used to examine and
2517 modify the state of the DHCP server as it is running.
2518 The one-lease-per-client statement
2520 one-lease-per-client flag;
2522 If this flag is enabled, whenever a client sends a DHCPREQUEST for
2524 a particular lease, the server will automatically free any other
2525 leases the client holds. This presumes that when the client sends
2526 a DHCPREQUEST, it has forgotten any lease not mentioned in the
2527 DHCPREQUEST - i.e., the client has only a single network interface
2528 and it does not remember leases it's holding on networks to which
2529 it is not currently attached. Neither of these assumptions are
2530 guaranteed or provable, so we urge caution in the use of this
2531 statement.
2532 The persist-eui-64-leases statement
2534 persist-eui-64-leases flag;
2536 When this flag is enabled, the server will write EUI-64 based
2538 leases to the leases file. Since such leases can only, ever be
2539 valid for a single DUID value it can be argued that writing them
2540 to the leases file isn't essential and not doing so may have per‐
2541 fomance advantages. See use-eui-64 statement for more details on
2542 EUI-64 based address allocation. The flag is enabled by default
2543 and may only be set at the global scope.
2544 The pid-file-name statement
2546 pid-file-name name;
2548 Name should be the name of the DHCP server's process ID file.
2550 This is the file in which the DHCP server's process ID is stored
2551 when the server starts. By default, this is /var/run/dhcpd.pid.
2552 Like the lease-file-name statement, this statement must appear in
2553 the outer scope of the configuration file. The order of precedence
2554 used by the server is:
2555 1. pid-file-name configuration file statement.
2557 2. -lf command line flag.
2558 3. PATH_DHCPD_PID environment variable.
2559 The dhcpv6-pid-file-name statement
2561 dhcpv6-pid-file-name name;
2563 Name is the name of the pid file to use if and only if the
2565 server is running in DHCPv6 mode. By default, this is
2566 /var/lib/dhcpd/dhcpd6.pid. This statement, like pid-file-name,
2567 must appear in the outer scope of the configuration file. The
2568 order of precedence used by the server is:
2569 1. dhcpv6-pid-file-name configuration file statement.
2571 2. -lf command line flag.
2572 3. PATH_DHCPD6_PID environment variable.
2573 The ping-check statement
2575 ping-check flag;
2577 When the DHCP server is considering dynamically allocating an IP
2579 address to a client, it first sends an ICMP Echo request (a
2580 ping) to the address being assigned. It waits for a second, and
2581 if no ICMP Echo response has been heard, it assigns the address.
2582 If a response is heard, the lease is abandoned, and the server
2583 does not respond to the client. The lease will remain abandoned
2584 for a minimum of abandon-lease-time seconds.
2585 If a there are no free addressses but there are abandoned IP ad‐
2587 dresses, the DHCP server will attempt to reclaim an abandoned IP
2588 address regardless of the value of abandon-lease-time.
2589 This ping check introduces a default one-second delay in re‐
2591 sponding to DHCPDISCOVER messages, which can be a problem for
2592 some clients. The default delay of one second may be configured
2593 using the ping-timeout parameter. The ping-check configuration
2594 parameter can be used to control checking - if its value is
2595 false, no ping check is done.
2596 The ping-cltt-secs statement
2598 ping-cltt-secs seconds;
2600 The server will conduct a ping check if all the following condi‐
2602 tions are true:
2603 1. Ping checking is enabled.
2605 2. The server is responding to a DISCOVER.
2607 3. The lease to be offered is neither static nor active (i.e.
2609 still a valid lease).
2610 4. And any of the following are true:
2612 a. This will be the first offer of this lease (CLTT is 0).
2613 b. The lease is being offered to a client other than its
2614 previous owner
2615 c. The lease is being offered to its previous owner and more
2616 than
2617 ping-cltt-secs have elapsed since CLTT of the original
2618 lease.
2619 d. The lease was abandoned and the server is attempting to
2620 reclaim it.
2621 The ping-cltt-secs statement allows the user to specify the
2624 amount of time that must elaspe after CLTT before a ping check
2625 will be conducted. The default value is sixty seconds.
2626 The ping-timeout statement
2628 ping-timeout seconds;
2630 If the DHCP server determined it should send an ICMP echo re‐
2632 quest (a ping) because the ping-check statement is true, ping-
2633 timeout allows you to configure how many seconds the DHCP server
2634 should wait for an ICMP Echo response to be heard, if no ICMP
2635 Echo response has been received before the timeout expires, it
2636 assigns the address. If a response is heard, the lease is aban‐
2637 doned, and the server does not respond to the client. If no
2638 value is set, ping-timeout defaults to 1 second. (See also ping-
2639 timeout-ms below)
2640 The ping-timeout-ms statement
2642 ping-timeout-ms milliseconds;
2644 Allows you to specify the ping timeout in milliseconds rather
2646 than seconds. If this value is greater than zero, the server
2647 will use it in place of ping-timeout. The default value is
2648 zero.
2649 The preferred-lifetime statement
2651 preferred-lifetime seconds;
2653 IPv6 addresses have ´valid´ and ´preferred´ lifetimes. The
2655 valid lifetime determines at what point a lease might be said to
2656 have expired, and is no longer useable. A preferred lifetime is
2657 an advisory condition to help applications move off of the ad‐
2658 dress and onto currently valid addresses (should there still be
2659 any open TCP sockets or similar).
2660 The preferred lifetime defaults to 5/8 the default lease time.
2662 The prefix-length-mode statement
2664 prefix-length-mode mode;
2666 According to RFC 3633, DHCPv6 clients may specify preferences
2668 when soliciting prefixes by including an IA_PD Prefix option
2669 within the IA_PD option. Among the preferences that may be con‐
2670 veyed is the "prefix-length". When non-zero it indicates a
2671 client's desired length for offered prefixes. The RFC states
2672 that servers "MAY choose to use the information...to select pre‐
2673 fix(es)" but does not specify any particular rules for doing so.
2674 The prefix-length-mode statement can be used to set the prefix
2675 selection rules employed by the server, when clients send a non-
2676 zero prefix-length value. The mode parameter must be one of ig‐
2677 nore, prefer, exact, minimum, or maximum where:
2678 1. ignore - The requested length is ignored. The server will of‐
2680 fer the first available prefix.
2681 2. prefer - The server will offer the first available prefix
2683 with the same length as the requested length. If none are found
2684 then it will offer the first available prefix of any length.
2685 This is the default behavior.
2686 3. exact - The server will offer the first available prefix with
2688 the same length as the requested length. If none are found, it
2689 will return a status indicating no prefixes available.
2690 4. minimum - The server will offer the first available prefix
2692 with the same length as the requested length. If none are
2693 found, it will return the first available prefix whose length is
2694 greater than (e.g. longer than), the requested value. If none
2695 of those are found, it will return a status indicating no pre‐
2696 fixes available. For example, if client requests a length of
2697 /60, and the server has available prefixes of lengths /56 and
2698 /64, it will offer prefix of length /64.
2699 5. maximum - The server will offer the first available prefix
2701 with the same length as the requested length. If none are
2702 found, it will return the first available prefix whose length is
2703 less than (e.g. shorter than), the requested value. If none of
2704 those are found, it will return a status indicating no prefixes
2705 available. For example, if client requests a length of /60, and
2706 the server has available prefixes of lengths /56 and /64, it
2707 will offer a prefix of length /56.
2708 In general "first available" is determined by the order in which
2710 pools are defined in the server's configuration. For example,
2711 if a subnet is defined with three prefix pools A,B, and C:
2712 subnet 3000::/64 {
2714 # pool A
2715 pool6 {
2716 :
2717 }
2718 # pool B
2719 pool6 {
2720 :
2721 }
2722 # pool C
2723 pool6 {
2724 :
2725 }
2726 }
2727 then the pools will be checked in the order A, B, C. For modes
2729 prefer, minimum, and maximum this may mean checking the pools in
2730 that order twice. A first pass through is made looking for an
2731 available prefix of exactly the preferred length. If none are
2732 found, then a second pass is performed starting with pool A but
2733 with appropriately adjusted length criteria.
2734 The release-on-roam statement
2736 release-on-roam flag;
2738 When enabled and the dhcpd server detects that a DHCPv6 client
2740 (IAID+DUID) has roamed to a new network, it will release the
2741 pre-existing leases on the old network and emit a log statement
2742 similiar to the following:
2743 "Client: <id> roamed to new network, releasing lease: <ad‐
2745 dress>"
2746 The server will carry out all of the same steps that would nor‐
2748 mally occur when a client explicitly releases a lease. When re‐
2749 lease-on-roam is disabled (the default) the server makes such
2750 leases unavailable until they expire or the server is restarted.
2751 Clients that need leases in multiple networks must supply a
2752 unique IAID in each IA. This parameter may only be specified at
2753 the global level.
2754 The remote-port statement
2756 remote-port port;
2758 This statement causes the DHCP server to transmit DHCP responses
2760 to DHCP clients upon the UDP port specified in port, rather than
2761 on port 68. In the event that the UDP response is transmitted
2762 to a DHCP Relay, the server generally uses the local-port con‐
2763 figuration value. Should the DHCP Relay happen to be addressed
2764 as 127.0.0.1, however, the DHCP Server transmits its response to
2765 the remote-port configuration value. This is generally only
2766 useful for testing purposes, and this configuration value should
2767 generally not be used.
2768 The server-identifier statement
2770 server-identifier hostname;
2772 The server-identifier statement can be used to define the value
2774 that is sent in the DHCP Server Identifier option for a given
2775 scope. The value specified must be an IP address for the DHCP
2776 server, and must be reachable by all clients served by a partic‐
2777 ular scope.
2778 The use of the server-identifier statement is not recommended -
2780 the only reason to use it is to force a value other than the de‐
2781 fault value to be sent on occasions where the default value
2782 would be incorrect. The default value is the first IP address
2783 associated with the physical network interface on which the re‐
2784 quest arrived.
2785 The usual case where the server-identifier statement needs to be
2787 sent is when a physical interface has more than one IP address,
2788 and the one being sent by default isn't appropriate for some or
2789 all clients served by that interface. Another common case is
2790 when an alias is defined for the purpose of having a consistent
2791 IP address for the DHCP server, and it is desired that the
2792 clients use this IP address when contacting the server.
2793 Supplying a value for the dhcp-server-identifier option is
2795 equivalent to using the server-identifier statement.
2796 The server-id-check statement
2798 server-id-check flag;
2800 The server-id-check statement is used to control whether or not
2802 a server, participating in failover, verifies that the value of
2803 the dhcp-server-identifier option in received DHCP REQUESTs
2804 match the server's id before processing the request. Server id
2805 checking is disabled by default. Setting this flag enables id
2806 checking and thereafter the server will only process requests
2807 that match. Note the flag setting should be consistent between
2808 failover partners.
2809 Unless overridden by use of the server-identifier statement, the
2811 value the server uses as its id will be the first IP address as‐
2812 sociated with the physical network interface on which the re‐
2813 quest arrived.
2814 In order to reduce runtime overhead the server only checks for a
2816 server id option in the global and subnet scopes. Complicated
2817 configurations may result in different server ids for this check
2818 and when the server id for a reply packet is determined, which
2819 would prohibit the server from responding.
2820 The primary use for this option is when a client broadcasts a
2822 request but requires that the response come from a specific
2823 failover peer. An example of this would be when a client re‐
2824 boots while its lease is still active - in this case both
2825 servers will normally respond. Most of the time the client
2826 won't check the server id and can use either of the responses.
2827 However if the client does check the server id it may reject the
2828 response if it came from the wrong peer. If the timing is such
2829 that the "wrong" peer responds first most of the time the client
2830 may not get an address for some time.
2831 Care should be taken before enabling this option.
2833 The server-duid statement
2835 server-duid LLT [ hardware-type timestamp hardware-address ] ;
2837 server-duid EN enterprise-number enterprise-identifier ;
2839 server-duid LL [ hardware-type hardware-address ] ;
2841 The server-duid statement configures the server DUID. You may
2843 pick either LLT (link local address plus time), EN (enterprise),
2844 or LL (link local).
2845 If you choose LLT or LL, you may specify the exact contents of
2847 the DUID. Otherwise the server will generate a DUID of the
2848 specified type.
2849 If you choose EN, you must include the enterprise number and the
2851 enterprise-identifier.
2852 If there is a server-duid statement in the lease file it will
2854 take precedence over the server-duid statement from the config
2855 file and a dhcp6.server-id option in the config file will over‐
2856 ride both.
2857 The default server-duid type is LLT.
2859 The server-name statement
2861 server-name name ;
2863 The server-name statement can be used to inform the client of
2865 the name of the server from which it is booting. Name should be
2866 the name that will be provided to the client.
2867 The dhcpv6-set-tee-times statement
2869 dhcpv6-set-tee-times flag;
2871 The dhcpv6-set-tee-times statement enables setting T1 and T2 to
2873 the values recommended in RFC 3315 (Section 22.4). When setting
2874 T1 and T2, the server will use dhcp-renewal-time and dhcp-re‐
2875 binding-time, respectively. A value of zero tells the client it
2876 may choose its own value.
2877 When those options are not defined then values will be set to
2879 zero unless the global dhcpv6-set-tee-times is enabled. When
2880 this option is enabled the times are calculated as recommended
2881 by RFC 3315, Section 22.4:
2882 T1 will be set to 0.5 times the shortest preferred life‐
2884 time
2885 in the reply. If the "shortest" preferred lifetime is
2886 0xFFFFFFFF, T1 will set to 0xFFFFFFFF.
2887 T2 will be set to 0.8 times the shortest preferred life‐
2889 time
2890 in the reply. If the "shortest" preferred lifetime is
2891 0xFFFFFFFF, T2 will set to 0xFFFFFFFF.
2892 Keep in mind that given sufficiently small lease lifetimes, the
2894 above calculations will result in the two values being equal.
2895 For example, a 9 second lease lifetime would yield T1 = T2 = 4
2896 seconds, which would cause clients to issue rebinds only. In
2897 such a case it would likely be better to explicitly define the
2898 values.
2899 Note that dhcpv6-set-tee-times is intended to be transitional
2901 and will likely be removed in a future release. Once removed the
2902 behavior will be to use the configured values when present or
2903 calculate them per the RFC. If you want zeros, define them as
2904 zeros.
2905 The site-option-space statement
2907 site-option-space name ;
2909 The site-option-space statement can be used to determine from
2911 what option space site-local options will be taken. This can be
2912 used in much the same way as the vendor-option-space statement.
2913 Site-local options in DHCP are those options whose numeric codes
2914 are greater than 224. These options are intended for site-spe‐
2915 cific uses, but are frequently used by vendors of embedded hard‐
2916 ware that contains DHCP clients. Because site-specific options
2917 are allocated on an ad hoc basis, it is quite possible that one
2918 vendor's DHCP client might use the same option code that another
2919 vendor's client uses, for different purposes. The site-option-
2920 space option can be used to assign a different set of site-spe‐
2921 cific options for each such vendor, using conditional evaluation
2922 (see dhcp-eval (5) for details).
2923 The stash-agent-options statement
2925 stash-agent-options flag;
2927 If the stash-agent-options parameter is true for a given client,
2929 the server will record the relay agent information options sent
2930 during the client's initial DHCPREQUEST message when the client
2931 was in the SELECTING state and behave as if those options are
2932 included in all subsequent DHCPREQUEST messages sent in the RE‐
2933 NEWING state. This works around a problem with relay agent in‐
2934 formation options, which is that they usually not appear in
2935 DHCPREQUEST messages sent by the client in the RENEWING state,
2936 because such messages are unicast directly to the server and not
2937 sent through a relay agent.
2938 The update-conflict-detection statement
2940 update-conflict-detection flag;
2942 If the update-conflict-detection parameter is true, the server
2944 will perform standard DHCID multiple-client, one-name conflict
2945 detection. If the parameter has been set false, the server will
2946 skip this check and instead simply tear down any previous bind‐
2947 ings to install the new binding without question. The default
2948 is true and this parameter may only be specified at the global
2949 scope.
2950 The update-optimization statement
2952 update-optimization flag;
2954 If the update-optimization parameter is false for a given
2956 client, the server will attempt a DNS update for that client
2957 each time the client renews its lease, rather than only attempt‐
2958 ing an update when it appears to be necessary. This will allow
2959 the DNS to heal from database inconsistencies more easily, but
2960 the cost is that the DHCP server must do many more DNS updates.
2961 We recommend leaving this option enabled, which is the default.
2962 If this parameter is not specified, or is true, the DHCP server
2963 will only update when the client information changes, the client
2964 gets a different lease, or the client's lease expires.
2965 The update-static-leases statement
2967 update-static-leases flag;
2969 The update-static-leases flag, if enabled, causes the DHCP
2971 server to do DNS updates for clients even if those clients are
2972 being assigned their IP address using a fixed-address or fixed-
2973 address6 statement - that is, the client is being given a static
2974 assignment. It is not recommended because the DHCP server has
2975 no way to tell that the update has been done, and therefore will
2976 not delete the record when it is not in use. Also, the server
2977 must attempt the update each time the client renews its lease,
2978 which could have a significant performance impact in environ‐
2979 ments that place heavy demands on the DHCP server. This feature
2980 is supported for both DHCPv4 and DHCPv6, and update modes stan‐
2981 dard or interim. It is disabled by default.
2982 The use-eui-64 statement
2984 use-eui-64 flag;
2986 (Support for this must be enabled at compile time, see EUI_64 in
2988 includes/site.h)
2989 The use-eui-64 flag, if enabled, instructs the server to con‐
2991 struct an address using the client's EUI-64 DUID (Type 3, HW
2992 Type EUI-64), rather than creating an address using the dynamic
2993 algorithm. This means that a given DUID will always generate
2994 the same address for a given pool and further that the address
2995 is guaranteed to be unique to that DUID. The IPv6 address will
2996 be calculated from the EUI-64 link layer address, conforming to
2997 RFC 2373, unless there is a host declaration for the client-id.
2998 The range6 statement for EUI-64 must define full /64 bit ranges.
3000 Invalid ranges will be flagged during configuration parsing as
3001 errors. See the following example:
3002 subnet6 fc00:e4::/64 {
3004 use-eui-64 true;
3005 range6 fc00:e4::/64;
3006 }
3007 The statement may be specified down to the pool level, allowing
3009 a mixture of dynamic and EUI-64 based pools.
3010 During lease file parsing, any leases which map to an EUI-64
3012 pool, that have a non-EUI-64 DUID or for which the lease address
3013 is not the EUI-64 address for that DUID in that pool, will be
3014 discarded.
3015 If a host declaration exists for the DUID, the server grants the
3017 address (fixed-prefix6, fixed-address6) according to the host
3018 declaration, regardless of the DUID type of the client (even for
3019 EUI-64 DUIDs).
3020 If a client request's an EUI-64 lease for a given network, and
3022 the resultant address conflicts with a fixed address reserva‐
3023 tion, the server will send the client a "no addresses available"
3024 response.
3025 Any client with a non-conforming DUID (not type 3 or not hw type
3027 EUI-64) that is not linked to a host declaration, which requests
3028 an address from an EUI-64 enabled pool will be ignored and the
3029 event will be logged.
3030 Pools that are configured for EUI-64 will be skipped for dynamic
3032 allocation. If there are no pools in the shared network from
3033 which to allocate, the client will get back a no addresses
3034 available status.
3035 On an EUI-64 enabled pool, any client with a DUID 3, HW Type
3037 EUI-64, requesting a solicit/renew and including IA_NA that do
3038 not match the EUI-64 policy, they will be treated as though they
3039 are "outside" the subnet for a given client message:
3040 Solicit - Server will advertise with EUI-64 ia suboption,
3042 but with rapid
3043 commit off
3044 Request - Server will send "an address not on link status",
3045 and no ia
3046 suboption Renew/Rebind - Server will send the requested ad‐
3047 dress ia
3048 suboption with lifetimes of 0, plus an EUI-64 ia
3049 Whether or not EUI-64 based leases are written out to the lease
3051 database may be controlled by persist-eui-64-leases statement.
3052 The use-host-decl-names statement
3054 use-host-decl-names flag;
3056 If the use-host-decl-names parameter is true in a given scope,
3058 then for every host declaration within that scope, the name pro‐
3059 vided for the host declaration will be supplied to the client as
3060 its hostname. So, for example,
3061 group {
3063 use-host-decl-names on;
3064 host joe {
3066 hardware ethernet 08:00:2b:4c:29:32;
3067 fixed-address joe.example.com;
3068 }
3069 }
3070 is equivalent to
3072 host joe {
3074 hardware ethernet 08:00:2b:4c:29:32;
3075 fixed-address joe.example.com;
3076 option host-name "joe";
3077 }
3078 Additionally, enabling use-host-decl-names instructs the server
3080 to use the host declaration name in the the forward DNS name, if
3081 no other values are available. This value selection process is
3082 discussed in more detail under DNS updates.
3083 An option host-name statement within a host declaration will
3085 override the use of the name in the host declaration.
3086 It should be noted here that most DHCP clients completely ignore
3088 the host-name option sent by the DHCP server, and there is no
3089 way to configure them not to do this. So you generally have a
3090 choice of either not having any hostname to client IP address
3091 mapping that the client will recognize, or doing DNS updates.
3092 It is beyond the scope of this document to describe how to make
3093 this determination.
3094 The use-lease-addr-for-default-route statement
3096 use-lease-addr-for-default-route flag;
3098 If the use-lease-addr-for-default-route parameter is true in a
3100 given scope, then instead of sending the value specified in the
3101 routers option (or sending no value at all), the IP address of
3102 the lease being assigned is sent to the client. This supposedly
3103 causes Win95 machines to ARP for all IP addresses, which can be
3104 helpful if your router is configured for proxy ARP. The use of
3105 this feature is not recommended, because it won't work for many
3106 DHCP clients.
3107 The vendor-option-space statement
3109 vendor-option-space string;
3111 The vendor-option-space parameter determines from what option
3113 space vendor options are taken. The use of this configuration
3114 parameter is illustrated in the dhcp-options(5) manual page, in
3115 the VENDOR ENCAPSULATED OPTIONS section.
3116
3118 Sometimes it's helpful to be able to set the value of a DHCP server pa‐
3119 rameter based on some value that the client has sent. To do this, you
3120 can use expression evaluation. The dhcp-eval(5) manual page describes
3121 how to write expressions. To assign the result of an evaluation to an
3122 option, define the option as follows:
3123 my-parameter = expression ;
3125 For example:
3127 ddns-hostname = binary-to-ascii (16, 8, "-",
3129 substring (hardware, 1, 6));
3130
3132 It's often useful to allocate a single address to a single client, in
3133 approximate perpetuity. Host statements with fixed-address clauses ex‐
3134 ist to a certain extent to serve this purpose, but because host state‐
3135 ments are intended to approximate ´static configuration´, they suffer
3136 from not being referenced in a littany of other Server Services, such
3137 as dynamic DNS, failover, ´on events´ and so forth.
3138 If a standard dynamic lease, as from any range statement, is marked
3140 ´reserved´, then the server will only allocate this lease to the client
3141 it is identified by (be that by client identifier or hardware address).
3142 In practice, this means that the lease follows the normal state engine,
3144 enters ACTIVE state when the client is bound to it, expires, or is re‐
3145 leased, and any events or services that would normally be supplied dur‐
3146 ing these events are processed normally, as with any other dynamic
3147 lease. The only difference is that failover servers treat reserved
3148 leases as special when they enter the FREE or BACKUP states - each
3149 server applies the lease into the state it may allocate from - and the
3150 leases are not placed on the queue for allocation to other clients.
3151 Instead they may only be ´found´ by client identity. The result is
3152 that the lease is only offered to the returning client.
3153 Care should probably be taken to ensure that the client only has one
3155 lease within a given subnet that it is identified by.
3156 Leases may be set ´reserved´ either through OMAPI, or through the ´in‐
3158 finite-is-reserved´ configuration option (if this is applicable to your
3159 environment and mixture of clients).
3160 It should also be noted that leases marked ´reserved´ are effectively
3162 treated the same as leases marked ´bootp´.
3163
3165 DHCP option statements are documented in the dhcp-options(5) manual
3166 page.
3167
3169 Expressions used in DHCP option statements and elsewhere are documented
3170 in the dhcp-eval(5) manual page.
3171
3173 dhcpd(8), dhcpd.leases(5), dhcp-options(5), dhcp-eval(5), RFC2132,
3174 RFC2131.
3175
3177 dhcpd.conf(5) is maintained by ISC. Information about Internet Systems
3178 Consortium can be found at https://www.isc.org.
3179 dhcpd.conf(5)