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
28 describe clients on the network, to provide addresses that can be
29 assigned to clients, or to apply a group of parameters to a group of
30 declarations. In any group of parameters and declarations, all parame‐
31 ters must be specified before any declarations which depend on those
32 parameters 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
36 addresses dynamically, a range declaration must appear within the sub‐
37 net declaration. For clients with statically assigned addresses, or
38 for installations where only known clients will be served, each such
39 client must have a host declaration. If parameters are to be applied
40 to a group of declarations which are not related strictly on a per-sub‐
41 net 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
60 parameters 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
84 parameter 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
131 organization), 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
151 required - if you have a different domain name for each interface on
152 your router, it's perfectly legitimate to use the domain name for that
153 interface 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
158 parameters for a set of three hosts - zappo, beppo and harpo. As you
159 can see, these hosts are all in the test.isc.org domain, so it might
160 make sense for a group-specific parameter to override the domain name
161 supplied 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
181 include such things as the hostname option, the name of a file to
182 upload (the filename parameter) and the address of the server from
183 which to upload the file (the next-server parameter). In general, any
184 parameter can appear anywhere that parameters are allowed, and will be
185 applied 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
220 addresses that will be treated differently than another pool of
221 addresses, even on the same network segment or subnet. For example,
222 you may want to provide a large set of addresses that can be assigned
223 to DHCP clients that are registered to your DHCP server, while provid‐
224 ing a smaller set of addresses, possibly with short lease times, that
225 are available for unknown clients. If you have a firewall, you may be
226 able to arrange for addresses from one pool to be allowed access to the
227 Internet, while addresses in another pool are not, thus encouraging
228 users to register their DHCP clients. To do this, you would set up a
229 pair of 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
258 allow 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
270 include range6 statements for both NA and TA and prefixy6 statements in
271 a 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
283 address 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
290 address.
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
296 allocation. 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
322 response 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
343 request message to the IP address being allocated. If no ICMP Echo
344 reply is received within a second, the address is assumed to be free.
345 This is only done for leases that have been specified in range state‐
346 ments, 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
348 as in use.
349 If a response is received to an ICMP Echo request, the DHCP server
351 assumes that there is a configuration error - the IP address is in use
352 by some host on the network that is not a DHCP client. It marks the
353 address 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
416 automatically.
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
508 described 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
552 before 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
577 addresses 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
670 directly 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
674 default), and any positive value indicates the time in seconds to
675 wait 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
705 describe shortly.
706 The first thing calculated on any pool balance run is a value
708 referred 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
719 approach, marked by the presence of the max-lease-misbalance state‐
720 ment. This parameter configures what used to be a 10% fixed value in
721 previous versions: if lts is less than free+backup * max-lease-mis‐
722 balance percent, then the server will skip balancing a given pool (it
723 won't bother moving any leases, even if some leases "should" be
724 moved). The meaning of this value is also somewhat overloaded, how‐
725 ever, in that it also governs the estimation of when to attempt to
726 balance the pool (which may then also be skipped over). The oldest
727 leases in the free and backup states are examined. The time they
728 have resided in their respective queues is used as an estimate to
729 indicate how much time it is probable it would take before the leases
730 at the top of the list would be consumed (and thus, how long it would
731 take to use all leases in that state). This percentage is directly
732 multiplied by this time, and fit into the schedule if it falls within
733 the min-balance and max-balance configured values. The scheduled
734 pool check time is only moved in a downwards direction, it is never
735 increased. Lastly, if the lts is more than double this number in the
736 negative direction, the local server will ´panic´ and transmit a
737 Failover protocol POOLREQ message, in the hopes that the remote sys‐
738 tem will be woken up into action.
739 Once the lts value exceeds the max-lease-misbalance percentage of
741 total free state leases as described above, leases are moved to the
742 remote 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
756 applies 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
762 reduce the lts underneath the total number of free state leases mul‐
763 tiplied by the max-lease-ownership percentage. In this pass, the
764 oldest 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
793 default to values 60 and 3600 respectively (to place balance events
794 between 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
820 before any statements are executed. Attempting to do so will yield
821 indeterminate 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
886 allocation 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,
899 either by letting it expire, or by sending a DHCPRELEASE packet.
900 Classes 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-
1015 updates;. 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
1028 update 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
1049 example 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
1091 operator intervention, and once this has been done, the DNS will be
1092 updated 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
1114 detection.
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-
1124 udpate-style. In this way, all servers of a given protocol are using
1125 the same record type (TXT or DHCID) for their DHCID RR entries. This
1126 allows conflict detection to be enforced within each protocol without
1127 interferring 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
1145 entries for static clients. Per the rules of conflict resolution, a
1146 DNS updater may not alter forward DNS entries unless there is a DHCID
1147 RR which matches for whom the update is being made. Therefore, any
1148 forward DNS entries without a corresponding DHCID RR cannot be altered
1149 by 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
1153 dynamic clients regardless of what client owns them. In other words,
1154 the presence or lack of a DHCID RR is used to determine whether entries
1155 may or may not be overwritten. Whether or not the client matches the
1156 data value of the DHCID RR is irrelevant. This behavior, off by
1157 default, can be configured through the parameter, ddns-guard-id-must-
1158 match. As with DSMM, this behavior is can only be enabled if conflict
1159 resolution is enabled. This behavior should be considered carefully
1160 before 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
1168 DHDID RR for the FQDN. Essentially, if there are dynamic entries for
1169 one protocol, that is enough to overcome the static protection of
1170 entries for the other protocol. This behavior warrants careful consid‐
1171 eration 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
1177 updates using a shared secret key. As long as you protect the secrecy
1178 of this key, your updates should also be secure. Note, however, that
1179 the DHCP protocol itself provides no security, and that clients can
1180 therefore provide information to the DHCP server which the DHCP server
1181 will then use in its updates, with the constraints described previ‐
1182 ously.
1183 The DNS server must be configured to allow updates for any zone that
1185 the DHCP server will be updating. For example, let us say that clients
1186 in the sneedville.edu domain will be assigned addresses on the
1187 10.10.17.0/24 subnet. In that case, you will need a key declaration
1188 for the TSIG key you will be using, and also two zone declarations -
1189 one for the zone containing A records that will be updates and one for
1190 the zone containing PTR records - for ISC BIND, something like this:
1191 key DHCP_UPDATER {
1193 algorithm hmac-md5;
1194 secret pRP5FapFoJ95JEL06sv4PQ==;
1195 };
1196 zone "example.org" {
1198 type master;
1199 file "example.org.db";
1200 allow-update { key DHCP_UPDATER; };
1201 };
1202 zone "17.10.10.in-addr.arpa" {
1204 type master;
1205 file "10.10.17.db";
1206 allow-update { key DHCP_UPDATER; };
1207 };
1208 You will also have to configure your DHCP server to do updates to these
1210 zones. To do so, you need to add something like this to your
1211 dhcpd.conf file:
1212 key DHCP_UPDATER {
1214 algorithm hmac-md5;
1215 secret pRP5FapFoJ95JEL06sv4PQ==;
1216 };
1217 zone EXAMPLE.ORG. {
1219 primary 127.0.0.1;
1220 key DHCP_UPDATER;
1221 }
1222 zone 17.127.10.in-addr.arpa. {
1224 primary 127.0.0.1;
1225 key DHCP_UPDATER;
1226 }
1227 The primary statement specifies the IP address of the name server whose
1229 zone information is to be updated. In addition to the primary state‐
1230 ment there are also the primary6 , secondary and secondary6 statements.
1231 The primary6 statement specifies an IPv6 address for the name server.
1232 The secondaries provide for additional addresses for name servers to be
1233 used if the primary does not respond. The number of name servers the
1234 DDNS code will attempt to use before giving up is limited and is cur‐
1235 rently set to three.
1236 Note that the zone declarations have to correspond to authority records
1238 in your name server - in the above example, there must be an SOA record
1239 for "example.org." and for "17.10.10.in-addr.arpa.". For example, if
1240 there were a subdomain "foo.example.org" with no separate SOA, you
1241 could not write a zone declaration for "foo.example.org." Also keep in
1242 mind that zone names in your DHCP configuration should end in a ".";
1243 this is the preferred syntax. If you do not end your zone name in a
1244 ".", the DHCP server will figure it out. Also note that in the DHCP
1245 configuration, zone names are not encapsulated in quotes where there
1246 are in the DNS configuration.
1247 You should choose your own secret key, of course. The ISC BIND 9 dis‐
1249 tribution comes with a program for generating secret keys called
1250 dnssec-keygen. If you are using BIND 9´s dnssec-keygen, the above key
1251 would be created as follows:
1252 dnssec-keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER
1254 The key name, algorithm, and secret must match that being used by the
1256 DNS server. The DHCP server currently supports the following algo‐
1257 rithms:
1258 HMAC-MD5
1260 HMAC-SHA1
1261 HMAC-SHA224
1262 HMAC-SHA256
1263 HMAC-SHA384
1264 HMAC-SHA512
1265 You may wish to enable logging of DNS updates on your DNS server. To
1267 do so, you might write a logging statement like the following:
1268 logging {
1270 channel update_debug {
1271 file "/var/log/update-debug.log";
1272 severity debug 3;
1273 print-category yes;
1274 print-severity yes;
1275 print-time yes;
1276 };
1277 channel security_info {
1278 file "/var/log/named-auth.info";
1279 severity info;
1280 print-category yes;
1281 print-severity yes;
1282 print-time yes;
1283 };
1284 category update { update_debug; };
1286 category security { security_info; };
1287 };
1288 You must create the /var/log/named-auth.info and /var/log/update-
1290 debug.log files before starting the name server. For more information
1291 on configuring ISC BIND, consult the documentation that accompanies it.
1292
1294 There are three kinds of events that can happen regarding a lease, and
1295 it is possible to declare statements that occur when any of these
1296 events happen. These events are the commit event, when the server has
1297 made a commitment of a certain lease to a client, the release event,
1298 when the client has released the server from its commitment, and the
1299 expiry event, when the commitment expires.
1300 To declare a set of statements to execute when an event happens, you
1302 must use the on statement, followed by the name of the event, followed
1303 by a series of statements to execute when the event happens, enclosed
1304 in braces.
1305
1307 The include statement
1308 include "filename";
1310 The include statement is used to read in a named file, and process the
1312 contents of that file as though it were entered in place of the include
1313 statement.
1314 The shared-network statement
1316 shared-network name {
1318 [ parameters ]
1319 [ declarations ]
1320 }
1321 The shared-network statement is used to inform the DHCP server that
1323 some IP subnets actually share the same physical network. Any subnets
1324 in a shared network should be declared within a shared-network state‐
1325 ment. Parameters specified in the shared-network statement will be
1326 used when booting clients on those subnets unless parameters provided
1327 at the subnet or host level override them. If any subnet in a shared
1328 network has addresses available for dynamic allocation, those addresses
1329 are collected into a common pool for that shared network and assigned
1330 to clients as needed. There is no way to distinguish on which subnet
1331 of a shared network a client should boot.
1332 Name should be the name of the shared network. This name is used when
1334 printing debugging messages, so it should be descriptive for the shared
1335 network. The name may have the syntax of a valid domain name (although
1336 it will never be used as such), or it may be any arbitrary name,
1337 enclosed in quotes.
1338 The subnet statement
1340 subnet subnet-number netmask netmask {
1342 [ parameters ]
1343 [ declarations ]
1344 }
1345 The subnet statement is used to provide dhcpd with enough information
1347 to tell whether or not an IP address is on that subnet. It may also be
1348 used to provide subnet-specific parameters and to specify what
1349 addresses may be dynamically allocated to clients booting on that sub‐
1350 net. Such addresses are specified using the range declaration.
1351 The subnet-number should be an IP address or domain name which resolves
1353 to the subnet number of the subnet being described. The netmask should
1354 be an IP address or domain name which resolves to the subnet mask of
1355 the subnet being described. The subnet number, together with the net‐
1356 mask, are sufficient to determine whether any given IP address is on
1357 the specified subnet.
1358 Although a netmask must be given with every subnet declaration, it is
1360 recommended that if there is any variance in subnet masks at a site, a
1361 subnet-mask option statement be used in each subnet declaration to set
1362 the desired subnet mask, since any subnet-mask option statement will
1363 override the subnet mask declared in the subnet statement.
1364 The subnet6 statement
1366 subnet6 subnet6-number {
1368 [ parameters ]
1369 [ declarations ]
1370 }
1371 The subnet6 statement is used to provide dhcpd with enough information
1373 to tell whether or not an IPv6 address is on that subnet6. It may also
1374 be used to provide subnet-specific parameters and to specify what
1375 addresses may be dynamically allocated to clients booting on that sub‐
1376 net.
1377 The subnet6-number should be an IPv6 network identifier, specified as
1379 ip6-address/bits.
1380 The range statement
1382 range [ dynamic-bootp ] low-address [ high-address];
1384 For any subnet on which addresses will be assigned dynamically, there
1386 must be at least one range statement. The range statement gives the
1387 lowest and highest IP addresses in a range. All IP addresses in the
1388 range should be in the subnet in which the range statement is declared.
1389 The dynamic-bootp flag may be specified if addresses in the specified
1390 range may be dynamically assigned to BOOTP clients as well as DHCP
1391 clients. When specifying a single address, high-address can be omit‐
1392 ted.
1393 The range6 statement
1395 range6 low-address high-address;
1397 range6 subnet6-number;
1398 range6 subnet6-number temporary;
1399 range6 address temporary;
1400 For any IPv6 subnet6 on which addresses will be assigned dynamically,
1402 there must be at least one range6 statement. The range6 statement can
1403 either be the lowest and highest IPv6 addresses in a range6, or use
1404 CIDR notation, specified as ip6-address/bits. All IP addresses in the
1405 range6 should be in the subnet6 in which the range6 statement is
1406 declared.
1407 The temporary variant makes the prefix (by default on 64 bits) avail‐
1409 able for temporary (RFC 4941) addresses. A new address per prefix in
1410 the shared network is computed at each request with an IA_TA option.
1411 Release and Confirm ignores temporary addresses.
1412 Any IPv6 addresses given to hosts with fixed-address6 are excluded from
1414 the range6, as are IPv6 addresses on the server itself.
1415 The prefix6 statement
1417 prefix6 low-address high-address / bits;
1419 The prefix6 is the range6 equivalent for Prefix Delegation (RFC 3633).
1421 Prefixes of bits length are assigned between low-address and high-
1422 address.
1423 Any IPv6 prefixes given to static entries (hosts) with fixed-prefix6
1425 are excluded from the prefix6.
1426 This statement is currently global but it should have a shared-network
1428 scope.
1429 The host statement
1431 host hostname {
1433 [ parameters ]
1434 [ declarations ]
1435 }
1436 The host declaration provides a way for the DHCP server to identify a
1438 DHCP or BOOTP client. This allows the server to provide configuration
1439 information including fixed addresses or, in DHCPv6, fixed prefixes for
1440 a specific client.
1441 If it is desirable to be able to boot a DHCP or BOOTP client on more
1443 than one subnet with fixed v4 addresses, more than one address may be
1444 specified in the fixed-address declaration, or more than one host
1445 statement may be specified matching the same client.
1446 The fixed-address6 declaration is used for v6 addresses. At this time
1448 it only works with a single address. For multiple addresses specify
1449 multiple host statements.
1450 If client-specific boot parameters must change based on the network to
1452 which the client is attached, then multiple host declarations should be
1453 used. The host declarations will only match a client if one of their
1454 fixed-address statements is viable on the subnet (or shared network)
1455 where the client is attached. Conversely, for a host declaration to
1456 match a client being allocated a dynamic address, it must not have any
1457 fixed-address statements. You may therefore need a mixture of host
1458 declarations for any given client...some having fixed-address state‐
1459 ments, others without.
1460 hostname should be a name identifying the host. If a hostname option
1462 is not specified for the host, hostname is used.
1463 Host declarations are matched to actual DHCP or BOOTP clients by match‐
1465 ing the dhcp-client-identifier or pxe-client-id options specified in
1466 the host declaration to the one supplied by the client, or, if the host
1467 declaration or the client does not provide a dhcp-client-identifier or
1468 pxe-client-id options, by matching the hardware parameter in the host
1469 declaration to the network hardware address supplied by the client.
1470 BOOTP clients do not normally provide a dhcp-client-identifier, so the
1471 hardware address must be used for all clients that may boot using the
1472 BOOTP protocol.
1473 DHCPv6 servers can use the host-identifier option parameter in the host
1475 declaration, and specify any option with a fixed value to identify
1476 hosts.
1477 Please be aware that only the dhcp-client-identifier and pxe-client-id
1479 options and the hardware address can be used to match a host declara‐
1480 tion, or the host-identifier option parameter for DHCPv6 servers. For
1481 example, it is not possible to match a host declaration to a host-name
1482 option. This is because the host-name option cannot be guaranteed to
1483 be unique for any given client, whereas both the hardware address and
1484 dhcp-client-identifier option are at least theoretically guaranteed to
1485 be unique to a given client.
1486 The group statement
1488 group {
1490 [ parameters ]
1491 [ declarations ]
1492 }
1493 The group statement is used simply to apply one or more parameters to a
1495 group of declarations. It can be used to group hosts, shared networks,
1496 subnets, or even other groups.
1497
1499 The allow and deny statements can be used to control the response of
1500 the DHCP server to various sorts of requests. The allow and deny key‐
1501 words actually have different meanings depending on the context. In a
1502 pool context, these keywords can be used to set up access lists for
1503 address allocation pools. In other contexts, the keywords simply con‐
1504 trol general server behavior with respect to clients based on scope.
1505 In a non-pool context, the ignore keyword can be used in place of the
1506 deny keyword to prevent logging of denied requests.
1507
1509 The following usages of allow and deny will work in any scope, although
1510 it is not recommended that they be used in pool declarations.
1511 The unknown-clients keyword
1513 allow unknown-clients;
1515 deny unknown-clients;
1516 ignore unknown-clients;
1517 The unknown-clients flag is used to tell dhcpd whether or not to dynam‐
1519 ically assign addresses to unknown clients. Dynamic address assignment
1520 to unknown clients is allowed by default. An unknown client is simply
1521 a client that has no host declaration.
1522 The use of this option is now deprecated. If you are trying to
1524 restrict access on your network to known clients, you should use deny
1525 unknown-clients; inside of your address pool, as described under the
1526 heading ALLOW AND DENY WITHIN POOL DECLARATIONS.
1527 The bootp keyword
1529 allow bootp;
1531 deny bootp;
1532 ignore bootp;
1533 The bootp flag is used to tell dhcpd whether or not to respond to bootp
1535 queries. Bootp queries are allowed by default.
1536 The booting keyword
1538 allow booting;
1540 deny booting;
1541 ignore booting;
1542 The booting flag is used to tell dhcpd whether or not to respond to
1544 queries from a particular client. This keyword only has meaning when
1545 it appears in a host declaration. By default, booting is allowed, but
1546 if it is disabled for a particular client, then that client will not be
1547 able to get an address from the DHCP server.
1548 The duplicates keyword
1550 allow duplicates;
1552 deny duplicates;
1553 Host declarations can match client messages based on the DHCP Client
1555 Identifier option or based on the client's network hardware type and
1556 MAC address. If the MAC address is used, the host declaration will
1557 match any client with that MAC address - even clients with different
1558 client identifiers. This doesn't normally happen, but is possible when
1559 one computer has more than one operating system installed on it - for
1560 example, Microsoft Windows and NetBSD or Linux.
1561 The duplicates flag tells the DHCP server that if a request is received
1563 from a client that matches the MAC address of a host declaration, any
1564 other leases matching that MAC address should be discarded by the
1565 server, even if the UID is not the same. This is a violation of the
1566 DHCP protocol, but can prevent clients whose client identifiers change
1567 regularly from holding many leases at the same time. By default,
1568 duplicates are allowed.
1569 The declines keyword
1571 allow declines;
1573 deny declines;
1574 ignore declines;
1575 The DHCPDECLINE message is used by DHCP clients to indicate that the
1577 lease the server has offered is not valid. When the server receives a
1578 DHCPDECLINE for a particular address, it normally abandons that
1579 address, assuming that some unauthorized system is using it. Unfortu‐
1580 nately, a malicious or buggy client can, using DHCPDECLINE messages,
1581 completely exhaust the DHCP server's allocation pool. The server will
1582 eventually reclaim these leases, but not while the client is running
1583 through the pool. This may cause serious thrashing in the DNS, and it
1584 will also cause the DHCP server to forget old DHCP client address allo‐
1585 cations.
1586 The declines flag tells the DHCP server whether or not to honor DHCPDE‐
1588 CLINE messages. If it is set to deny or ignore in a particular scope,
1589 the DHCP server will not respond to DHCPDECLINE messages.
1590 The declines flag is only supported by DHCPv4 servers. Given the large
1592 IPv6 address space and the internal limits imposed by the server's
1593 address generation mechanism we don't think it is necessary for DHCPv6
1594 servers at this time.
1595 Currently, abandoned IPv6 addresses are reclaimed in one of two ways:
1597 a) Client renews a specific address:
1598 If a client using a given DUID submits a DHCP REQUEST containing
1599 the last address abandoned by that DUID, the address will be
1600 reassigned to that client.
1601 b) Upon the second restart following an address abandonment. When
1603 an address is abandoned it is both recorded as such in the lease
1604 file and retained as abandoned in server memory until the server
1605 is restarted. Upon restart, the server will process the lease file
1606 and all addresses whose last known state is abandoned will be
1607 retained as such in memory but not rewritten to the lease file.
1608 This means that a subsequent restart of the server will not see the
1609 abandoned addresses in the lease file and therefore have no record
1610 of them as abandoned in memory and as such perceive them as free
1611 for assignment.
1612 The total number addresses in a pool, available for a given DUID value,
1614 is internally limited by the server's address generation mechanism. If
1615 through mistaken configuration, multiple clients are using the same
1616 DUID they will competing for the same addresses causing the server to
1617 reach this internal limit rather quickly. The internal limit isolates
1618 this type of activity such that address range is not exhausted for
1619 other DUID values. The appearance of the following error log, can be
1620 an indication of this condition:
1621 "Best match for DUID <XX> is an abandoned address, This may be a
1623 result of multiple clients attempting to use this DUID"
1624 where <XX> is an actual DUID value depicted as colon separated
1626 string of bytes in hexadecimal values.
1627 The client-updates keyword
1629 allow client-updates;
1631 deny client-updates;
1632 The client-updates flag tells the DHCP server whether or not to honor
1634 the client's intention to do its own update of its A record. See the
1635 documentation under the heading THE DNS UPDATE SCHEME for details.
1636 The leasequery keyword
1638 allow leasequery;
1640 deny leasequery;
1641 The leasequery flag tells the DHCP server whether or not to answer DHC‐
1643 PLEASEQUERY packets. The answer to a DHCPLEASEQUERY packet includes
1644 information about a specific lease, such as when it was issued and when
1645 it will expire. By default, the server will not respond to these pack‐
1646 ets.
1647
1649 The uses of the allow and deny keywords shown in the previous section
1650 work pretty much the same way whether the client is sending a DHCPDIS‐
1651 COVER or a DHCPREQUEST message - an address will be allocated to the
1652 client (either the old address it's requesting, or a new address) and
1653 then that address will be tested to see if it's okay to let the client
1654 have it. If the client requested it, and it's not okay, the server
1655 will send a DHCPNAK message. Otherwise, the server will simply not
1656 respond to the client. If it is okay to give the address to the
1657 client, the server will send a DHCPACK message.
1658 The primary motivation behind pool declarations is to have address
1660 allocation pools whose allocation policies are different. A client may
1661 be denied access to one pool, but allowed access to another pool on the
1662 same network segment. In order for this to work, access control has to
1663 be done during address allocation, not after address allocation is
1664 done.
1665 When a DHCPREQUEST message is processed, address allocation simply con‐
1667 sists of looking up the address the client is requesting and seeing if
1668 it's still available for the client. If it is, then the DHCP server
1669 checks both the address pool permit lists and the relevant in-scope
1670 allow and deny statements to see if it's okay to give the lease to the
1671 client. In the case of a DHCPDISCOVER message, the allocation process
1672 is done as described previously in the ADDRESS ALLOCATION section.
1673 When declaring permit lists for address allocation pools, the following
1675 syntaxes are recognized following the allow or deny keywords:
1676 known-clients;
1678 If specified, this statement either allows or prevents allocation from
1680 this pool to any client that has a host declaration (i.e., is known).
1681 A client is known if it has a host declaration in any scope, not just
1682 the current scope.
1683 unknown-clients;
1685 If specified, this statement either allows or prevents allocation from
1687 this pool to any client that has no host declaration (i.e., is not
1688 known).
1689 members of "class";
1691 If specified, this statement either allows or prevents allocation from
1693 this pool to any client that is a member of the named class.
1694 dynamic bootp clients;
1696 If specified, this statement either allows or prevents allocation from
1698 this pool to any bootp client.
1699 authenticated clients;
1701 If specified, this statement either allows or prevents allocation from
1703 this pool to any client that has been authenticated using the DHCP
1704 authentication protocol. This is not yet supported.
1705 unauthenticated clients;
1707 If specified, this statement either allows or prevents allocation from
1709 this pool to any client that has not been authenticated using the DHCP
1710 authentication protocol. This is not yet supported.
1711 all clients;
1713 If specified, this statement either allows or prevents allocation from
1715 this pool to all clients. This can be used when you want to write a
1716 pool declaration for some reason, but hold it in reserve, or when you
1717 want to renumber your network quickly, and thus want the server to
1718 force all clients that have been allocated addresses from this pool to
1719 obtain new addresses immediately when they next renew.
1720 after time;
1722 If specified, this statement either allows or prevents allocation from
1724 this pool after a given date. This can be used when you want to move
1725 clients from one pool to another. The server adjusts the regular lease
1726 time so that the latest expiry time is at the given time+min-lease-
1727 time. A short min-lease-time enforces a step change, whereas a longer
1728 min-lease-time allows for a gradual change. time is either second
1729 since epoch, or a UTC time string e.g. 4 2007/08/24 09:14:32 or a
1730 string with time zone offset in seconds e.g. 4 2007/08/24 11:14:32
1731 -7200
1732
1734 The abandon-lease-time statement
1735 abandon-lease-time time;
1737 Time should be the maximum amount of time (in seconds) that an aban‐
1739 doned IPv4 lease remains unavailable for assignment to a client.
1740 Abandoned leases will only be offered to clients if there are no free
1741 leases. If not defined, the default abandon lease time is 86400 sec‐
1742 onds (24 hours). Note the abandoned lease time for a given lease is
1743 preserved across server restarts. The parameter may only be set at
1744 the global scope and is evaluated only once during server startup.
1745 Values less than sixty seconds are not recommended as this is below
1747 the ping check threshold and can cause leases once abandoned but
1748 since returned to the free state to not be pinged before being
1749 offered. If the requested time is larger than 0x7FFFFFFF - 1 or the
1750 sum of the current time plus the abandoned time isgreater than
1751 0x7FFFFFFF it is treated as infinite.
1752 The adaptive-lease-time-threshold statement
1754 adaptive-lease-time-threshold percentage;
1756 When the number of allocated leases within a pool rises above the
1758 percentage given in this statement, the DHCP server decreases the
1759 lease length for new clients within this pool to min-lease-time sec‐
1760 onds. Clients renewing an already valid (long) leases get at least
1761 the remaining time from the current lease. Since the leases expire
1762 faster, the server may either recover more quickly or avoid pool
1763 exhaustion entirely. Once the number of allocated leases drop below
1764 the threshold, the server reverts back to normal lease times. Valid
1765 percentages are between 1 and 99.
1766 The always-broadcast statement
1768 always-broadcast flag;
1770 The DHCP and BOOTP protocols both require DHCP and BOOTP clients to
1772 set the broadcast bit in the flags field of the BOOTP message header.
1773 Unfortunately, some DHCP and BOOTP clients do not do this, and there‐
1774 fore may not receive responses from the DHCP server. The DHCP server
1775 can be made to always broadcast its responses to clients by setting
1776 this flag to ´on´ for the relevant scope; relevant scopes would be
1777 inside a conditional statement, as a parameter for a class, or as a
1778 parameter for a host declaration. To avoid creating excess broadcast
1779 traffic on your network, we recommend that you restrict the use of
1780 this option to as few clients as possible. For example, the Micro‐
1781 soft DHCP client is known not to have this problem, as are the Open‐
1782 Transport and ISC DHCP clients.
1783 The always-reply-rfc1048 statement
1785 always-reply-rfc1048 flag;
1787 Some BOOTP clients expect RFC1048-style responses, but do not follow
1789 RFC1048 when sending their requests. You can tell that a client is
1790 having this problem if it is not getting the options you have config‐
1791 ured for it and if you see in the server log the message "(non-
1792 rfc1048)" printed with each BOOTREQUEST that is logged.
1793 If you want to send rfc1048 options to such a client, you can set the
1795 always-reply-rfc1048 option in that client's host declaration, and
1796 the DHCP server will respond with an RFC-1048-style vendor options
1797 field. This flag can be set in any scope, and will affect all
1798 clients covered by that scope.
1799 The authoritative statement
1801 authoritative;
1803 not authoritative;
1805 The DHCP server will normally assume that the configuration informa‐
1807 tion about a given network segment is not known to be correct and is
1808 not authoritative. This is so that if a naive user installs a DHCP
1809 server not fully understanding how to configure it, it does not send
1810 spurious DHCPNAK messages to clients that have obtained addresses
1811 from a legitimate DHCP server on the network.
1812 Network administrators setting up authoritative DHCP servers for
1814 their networks should always write authoritative; at the top of their
1815 configuration file to indicate that the DHCP server should send DHCP‐
1816 NAK messages to misconfigured clients. If this is not done, clients
1817 will be unable to get a correct IP address after changing subnets
1818 until their old lease has expired, which could take quite a long
1819 time.
1820 Usually, writing authoritative; at the top level of the file should
1822 be sufficient. However, if a DHCP server is to be set up so that it
1823 is aware of some networks for which it is authoritative and some net‐
1824 works for which it is not, it may be more appropriate to declare
1825 authority on a per-network-segment basis.
1826 Note that the most specific scope for which the concept of authority
1828 makes any sense is the physical network segment - either a shared-
1829 network statement or a subnet statement that is not contained within
1830 a shared-network statement. It is not meaningful to specify that the
1831 server is authoritative for some subnets within a shared network, but
1832 not authoritative for others, nor is it meaningful to specify that
1833 the server is authoritative for some host declarations and not oth‐
1834 ers.
1835 The boot-unknown-clients statement
1837 boot-unknown-clients flag;
1839 If the boot-unknown-clients statement is present and has a value of
1841 false or off, then clients for which there is no host declaration
1842 will not be allowed to obtain IP addresses. If this statement is not
1843 present or has a value of true or on, then clients without host dec‐
1844 larations will be allowed to obtain IP addresses, as long as those
1845 addresses are not restricted by allow and deny statements within
1846 their pool declarations.
1847 The check-secs-byte-order statement
1849 check-secs-byte-order flag;
1851 When check-secs-byte-order is enabled, the server will check for
1853 DHCPv4 clients that do the byte ordering on the secs field incor‐
1854 rectly. This field should be in network byte order but some clients
1855 get it wrong. When this parameter is enabled the server will examine
1856 the secs field and if it looks wrong (high byte non zero and low byte
1857 zero) swap the bytes. The default is disabled. This parameter is
1858 only useful when doing load balancing within failover. (Formerly,
1859 this behavior had to be enabled during compilation configuration via
1860 --enable-secs-byteorder).
1861 The db-time-format statement
1863 db-time-format [ default | local ] ;
1865 The DHCP server software outputs several timestamps when writing
1867 leases to persistent storage. This configuration parameter
1868 selects one of two output formats. The default format prints the
1869 day, date, and time in UTC, while the local format prints the sys‐
1870 tem seconds-since-epoch, and helpfully provides the day and time
1871 in the system timezone in a comment. The time formats are
1872 described in detail in the dhcpd.leases(5) manpage.
1873 The ddns-hostname statement
1875 ddns-hostname name;
1877 The name parameter should be the hostname that will be used in
1879 setting up the client's A and PTR records. If no ddns-hostname is
1880 specified in scope, then the server will derive the hostname auto‐
1881 matically, using an algorithm that varies for each of the differ‐
1882 ent update methods.
1883 The ddns-domainname statement
1885 ddns-domainname name;
1887 The name parameter should be the domain name that will be appended
1889 to the client's hostname to form a fully-qualified domain-name
1890 (FQDN).
1891 The ddns-dual-stack-mixed-mode statement
1893 ddns-dual-stack-mixed-mode flag;
1895 The ddns-dual-stack-mixed-mode parameter controls whether or not
1897 the server applies Dual Stack Mixed Mode rules during DDNS con‐
1898 flict resolution. This parameter is off by default, has no effect
1899 unless update-conflict-detection is enabled, and may only be spec‐
1900 ified at the global scope.
1901 The ddns-guard-id-must-match statement
1903 ddns-guard-id-must-match flag;
1905 The ddns-guard-id-must-match parameter controls whether or not a
1907 the client id within a DHCID RR must match that of the DNS
1908 update's client to permit DNS entries associated with that DHCID
1909 RR to be ovewritten. Proper conflict resolution requires ID
1910 matching and should only be disabled after careful consideration.
1911 When disabled, it is allows any DNS updater to replace DNS entries
1912 that have an associated DHCID RR, regardless of client identity.
1913 This parameter is on by default, has no effect unless update-con‐
1914 flict-detection is enabled, and may only be specified at the
1915 global scope.
1916 The dns-local-address4 and dns-local-address6 statements
1918 ddns-local-address4 address;
1920 ddns-local-address6 address;
1922 The address parameter should be the local IPv4 or IPv6 address the
1924 server should use as the from address when sending DDNS update
1925 requests.
1926 The ddns-other-guard-is-dynamic statement
1928 ddns-other-guard-is-dynamic flag;
1930 The ddns-other-guard-is-dynamic parameter controls whether or not
1932 a a server running DSMM will consider the presence of the other
1933 update style DHCID RR as an indcation that a DNS entries may be
1934 overwritten. It should only be enabled after careful study as it
1935 allows DNS entries that would otherwise be protected as static, to
1936 be overwritten in certain cases. This paramater is off by default,
1937 has no effect unless ddns-dual-stack-mixed-mode is enabled, and
1938 may only be specified at the global scope.
1939 The ddns-rev-domainname statement
1941 ddns-rev-domainname name;
1943 The name parameter should be the domain name that will be appended
1945 to the client's reversed IP address to produce a name for use in
1946 the client's PTR record. By default, this is "in-addr.arpa.", but
1947 the default can be overridden here.
1948 The reversed IP address to which this domain name is appended is
1950 always the IP address of the client, in dotted quad notation,
1951 reversed - for example, if the IP address assigned to the client
1952 is 10.17.92.74, then the reversed IP address is 74.92.17.10. So a
1953 client with that IP address would, by default, be given a PTR
1954 record of 10.17.92.74.in-addr.arpa.
1955 The ddns-update-style parameter
1957 ddns-update-style style;
1959 The style parameter must be one of standard, interim or none. The
1961 ddns-update-style statement is only meaningful in the outer scope
1962 - it is evaluated once after reading the dhcpd.conf file, rather
1963 than each time a client is assigned an IP address, so there is no
1964 way to use different DNS update styles for different clients. The
1965 default is none.
1966 The ddns-updates statement
1968 ddns-updates flag;
1970 The ddns-updates parameter controls whether or not the server will
1972 attempt to do a DNS update when a lease is confirmed. Set this to
1973 off if the server should not attempt to do updates within a cer‐
1974 tain scope. The ddns-updates parameter is on by default. To dis‐
1975 able DNS updates in all scopes, it is preferable to use the ddns-
1976 update-style statement, setting the style to none.
1977 The default-lease-time statement
1979 default-lease-time time;
1981 Time should be the length in seconds that will be assigned to a
1983 lease if the client requesting the lease does not ask for a spe‐
1984 cific expiration time. This is used for both DHCPv4 and DHCPv6
1985 leases (it is also known as the "valid lifetime" in DHCPv6). The
1986 default is 43200 seconds.
1987 The delayed-ack and max-ack-delay statements
1989 delayed-ack count;
1991 max-ack-delay microseconds;
1993 Count should be an integer value from zero to 2^16-1 and defaults
1995 to 0, which means that the feature is disabled. Otherwise, 28 may
1996 be a sensible starting point for many configurations (SO_SNDBUF
1997 size / 576 bytes.) The count represents how many DHCPv4 replies
1998 maximum will be queued pending transmission until after a database
1999 commit event. If this number is reached, a database commit event
2000 (commonly resulting in fsync() and representing a performance
2001 penalty) will be made, and the reply packets will be transmitted
2002 in a batch afterwards. This preserves the RFC2131 direction that
2003 "stable storage" be updated prior to replying to clients. Should
2004 the DHCPv4 sockets "go dry" (select() returns immediately with no
2005 read sockets), the commit is made and any queued packets are
2006 transmitted.
2007 Similarly, microseconds indicates how many microseconds are per‐
2009 mitted to pass inbetween queuing a packet pending an fsync, and
2010 performing the fsync. Valid values range from 0 to 2^32-1, and
2011 defaults to 250,000 (1/4 of a second).
2012 The delayed-ack feature is compiled in by default, but can be dis‐
2014 abled at compile time with ´./configure --disable-delayed-ack´.
2015 Please note that the delayed-ack feature is not currently compati‐
2016 ble with support for DHPCv4-over-DHCPv6 so when a 4to6 port ommand
2017 line argument enables this in the server the delayed-ack value is
2018 reset to 0.
2019 The dhcp-cache-threshold statement
2021 dhcp-cache-threshold percentage;
2023 The dhcp-cache-threshold statement takes one integer parameter
2025 with allowed values between 0 and 100. The default value is 25
2026 (25% of the lease time). This parameter expresses the percentage
2027 of the total lease time, measured from the beginning, during which
2028 a client's attempt to renew its lease will result in getting the
2029 already assigned lease, rather than an extended lease. This fea‐
2030 ture is supported for both IPv4 and IPv6 and down to the pool
2031 level and for IPv6 all three pool types: NA, TA and PD.
2032 Clients that attempt renewal frequently can cause the server to
2034 update and write the database frequently resulting in a perfor‐
2035 mance impact on the server. The dhcp-cache-threshold statement
2036 instructs the DHCP server to avoid updating leases too frequently
2037 thus avoiding this behavior. Instead the server replies with the
2038 same lease (i.e. reuses it) with no modifications except for CLTT
2039 (Client Last Transmission Time) and for IPv4:
2040 the lease time sent to the client is shortened by the age of
2042 the lease
2043 while for IPv6:
2045 the preferred and valid lifetimes sent to the client are
2047 shortened by the age of the lease.
2048 None of these changes require writing the lease to disk.
2050 When an existing lease is matched to a renewing client, it will be
2053 reused if all of the following conditions are true:
2054 1. The dhcp-cache-threshold is larger than zero
2055 2. The current lease is active
2056 3. The percentage of the lease time that has elapsed is less than
2057 dhcp-cache-threshold
2058 4. The client information provided in the renewal does not alter
2059 any of the following:
2060 a. DNS information and DNS updates are enabled
2061 b. Billing class to which the lease is associated (IPv4 only)
2062 c. The host declaration associated with the lease (IPv4 only)
2063 d. The client id - this may happen if a client boots without
2064 a client id and then starts using one in subsequent
2065 requests. (IPv4 only)
2066 While lease data is not written to disk when a lease is reused,
2068 the server will still execute any on-commit statements.
2069 Note that the lease can be reused if the options the client or
2071 relay agent sends are changed. These changes will not be recorded
2072 in the in-memory or on-disk databases until the client renews
2073 after the threshold time is reached.
2074 The do-forward-updates statement
2076 do-forward-updates flag;
2078 The do-forward-updates statement instructs the DHCP server as to
2080 whether it should attempt to update a DHCP client´s A record when
2081 the client acquires or renews a lease. This statement has no
2082 effect unless DNS updates are enabled. Forward updates are
2083 enabled by default. If this statement is used to disable forward
2084 updates, the DHCP server will never attempt to update the client´s
2085 A record, and will only ever attempt to update the client´s PTR
2086 record if the client supplies an FQDN that should be placed in the
2087 PTR record using the fqdn option. If forward updates are enabled,
2088 the DHCP server will still honor the setting of the client-updates
2089 flag.
2090 The dont-use-fsync statement
2092 dont-use-fsync flag;
2094 The dont-use-fsync statement instructs the DHCP server if it
2096 should call fsync() when writing leases to the lease file. By
2097 default and if the flag is set to false the server will call
2098 fsync(). Suppressing the call to fsync() may increase the perfor‐
2099 mance of the server but it also adds a risk that a lease will not
2100 be properly written to the disk after it has been issued to a
2101 client and before the server stops. This can lead to duplicate
2102 leases being issued to different clients. Using this option is
2103 not recommended.
2104 The dynamic-bootp-lease-cutoff statement
2106 dynamic-bootp-lease-cutoff date;
2108 The dynamic-bootp-lease-cutoff statement sets the ending time for
2110 all leases assigned dynamically to BOOTP clients. Because BOOTP
2111 clients do not have any way of renewing leases, and don't know
2112 that their leases could expire, by default dhcpd assigns infinite
2113 leases to all BOOTP clients. However, it may make sense in some
2114 situations to set a cutoff date for all BOOTP leases - for exam‐
2115 ple, the end of a school term, or the time at night when a facil‐
2116 ity is closed and all machines are required to be powered off.
2117 Date should be the date on which all assigned BOOTP leases will
2119 end. The date is specified in the form:
2120 W YYYY/MM/DD HH:MM:SS
2122 W is the day of the week expressed as a number from zero (Sunday)
2124 to six (Saturday). YYYY is the year, including the century. MM
2125 is the month expressed as a number from 1 to 12. DD is the day of
2126 the month, counting from 1. HH is the hour, from zero to 23. MM
2127 is the minute and SS is the second. The time is always in Coordi‐
2128 nated Universal Time (UTC), not local time.
2129 The dynamic-bootp-lease-length statement
2131 dynamic-bootp-lease-length length;
2133 The dynamic-bootp-lease-length statement is used to set the length
2135 of leases dynamically assigned to BOOTP clients. At some sites,
2136 it may be possible to assume that a lease is no longer in use if
2137 its holder has not used BOOTP or DHCP to get its address within a
2138 certain time period. The period is specified in length as a num‐
2139 ber of seconds. If a client reboots using BOOTP during the time‐
2140 out period, the lease duration is reset to length, so a BOOTP
2141 client that boots frequently enough will never lose its lease.
2142 Needless to say, this parameter should be adjusted with extreme
2143 caution.
2144 The echo-client-id statement
2146 echo-client-id flag;
2148 The echo-client-id statement is used to enable or disable RFC 6842
2150 compliant behavior. If the echo-client-id statement is present
2151 and has a value of true or on, and a DHCP DISCOVER or REQUEST is
2152 received which contains the client identifier option (Option code
2153 61), the server will copy the option into its response (DHCP ACK
2154 or NAK) per RFC 6842. In other words if the client sends the
2155 option it will receive it back. By default, this flag is off and
2156 client identifiers will not echoed back to the client.
2157 The filename statement
2159 filename "filename";
2161 The filename statement can be used to specify the name of the ini‐
2163 tial boot file which is to be loaded by a client. The filename
2164 should be a filename recognizable to whatever file transfer proto‐
2165 col the client can be expected to use to load the file.
2166 The fixed-address declaration
2168 fixed-address address [, address ... ];
2170 The fixed-address declaration is used to assign one or more fixed
2172 IP addresses to a client. It should only appear in a host decla‐
2173 ration. If more than one address is supplied, then when the
2174 client boots, it will be assigned the address that corresponds to
2175 the network on which it is booting. If none of the addresses in
2176 the fixed-address statement are valid for the network to which the
2177 client is connected, that client will not match the host declara‐
2178 tion containing that fixed-address declaration. Each address in
2179 the fixed-address declaration should be either an IP address or a
2180 domain name that resolves to one or more IP addresses.
2181 The fixed-address6 declaration
2183 fixed-address6 ip6-address ;
2185 The fixed-address6 declaration is used to assign a fixed IPv6
2187 addresses to a client. It should only appear in a host declara‐
2188 tion.
2189 The fixed-prefix6 declaration
2191 fixed-prefix6 low-address / bits;
2193 The fixed-prefix6 declaration is used to assign a fixed IPv6 pre‐
2195 fix to a client. It should only appear in a host declaration, but
2196 multiple fixed-prefix6 statements may appear in a single host dec‐
2197 laration.
2198 The low-address specifies the start of the prefix and the bits
2200 specifies the size of the prefix in bits.
2201 If there are multiple prefixes for a given host entry the server
2203 will choose one that matches the requested prefix size or, if none
2204 match, the first one.
2205 If there are multiple host declarations the server will try to
2207 choose a declaration where the fixed-address6 matches the client's
2208 subnet. If none match it will choose one that doesn't have a
2209 fixed-address6 statement.
2210 Note Well: Unlike the fixed address the fixed prefix does not need
2212 to match a subnet in order to be served. This allows you to pro‐
2213 vide a prefix to a client that is outside of the subnet on which
2214 the client makes the request to the the server.
2215 The get-lease-hostnames statement
2217 get-lease-hostnames flag;
2219 The get-lease-hostnames statement is used to tell dhcpd whether or
2221 not to look up the domain name corresponding to the IP address of
2222 each address in the lease pool and use that address for the DHCP
2223 hostname option. If flag is true, then this lookup is done for
2224 all addresses in the current scope. By default, or if flag is
2225 false, no lookups are done.
2226 The hardware statement
2228 hardware hardware-type hardware-address;
2230 In order for a BOOTP client to be recognized, its network hardware
2232 address must be declared using a hardware clause in the host
2233 statement. hardware-type must be the name of a physical hardware
2234 interface type. Currently, only the ethernet and token-ring types
2235 are recognized, although support for a fddi hardware type (and
2236 others) would also be desirable. The hardware-address should be a
2237 set of hexadecimal octets (numbers from 0 through ff) separated by
2238 colons. The hardware statement may also be used for DHCP clients.
2239 The host-identifier option statement
2241 host-identifier option option-name option-data;
2243 or
2245 host-identifier v6relopt number option-name option-data;
2247 This identifies a DHCPv6 client in a host statement. option-name
2249 is any option, and option-data is the value for the option that
2250 the client will send. The option-data must be a constant value.
2251 In the v6relopts case the additional number is the relay to exam‐
2252 ine for the specified option name and value. The values are the
2253 same as for the v6relay option. 0 is a no-op, 1 is the relay
2254 closest to the client, 2 the next one in and so on. Values that
2255 are larger than the maximum number of relays (currently 32) indi‐
2256 cate the relay closest to the server independent of number.
2257 The ignore-client-uids statement
2259 ignore-client-uids flag;
2261 If the ignore-client-uids statement is present and has a value of
2263 true or on, the UID for clients will not be recorded. If this
2264 statement is not present or has a value of false or off, then
2265 client UIDs will be recorded.
2266 The infinite-is-reserved statement
2268 infinite-is-reserved flag;
2270 ISC DHCP now supports ´reserved´ leases. See the section on
2272 RESERVED LEASES below. If this flag is on, the server will auto‐
2273 matically reserve leases allocated to clients which requested an
2274 infinite (0xffffffff) lease-time.
2275 The default is off.
2277 The lease-file-name statement
2279 lease-file-name name;
2281 Name Where name is the name of the DHCP server's lease file. By
2283 default, this is /var/lib/dhcpd/dhcpd.leases. This statement must
2284 appear in the outer scope of the configuration file - if it
2285 appears in some other scope, it will have no effect. The value
2286 must be the absolute path of the file to use. The order of prece‐
2287 dence the server uses for the lease file name is:
2288 1. lease-file-name configuration file statement.
2290 2. -lf command line flag.
2291 3. PATH_DHCPD_DB environment variable.
2292 The dhcpv6-lease-file-name statement
2294 dhcpv6-lease-file-name name;
2296 Where name is the name of the DHCP server's lease file when the
2298 server is running DHCPv6. By default, this is
2299 /var/lib/dhcpd/dhcpd6.leases. This statement must appear in the
2300 outer scope of the configuration file - if it appears in some
2301 other scope, it will have no effect. The value must be the abso‐
2302 lute path of the file to use. The order of precedence the server
2303 uses for the lease file name is:
2304 1. dhcpv6-lease-file-name configuration file statement.
2306 2. -lf command line flag.
2307 3. PATH_DHCPD6_DB environment variable.
2308 The lease-id-format parameter
2310 lease-id-format format;
2312 The format parameter must be either octal or hex. This parameter
2314 governs the format used to write certain values to lease files.
2315 With the default format, octal, values are written as quoted
2316 strings in which non-printable characters are represented as octal
2317 escapes - a backslash character followed by three octal digits.
2318 When the hex format is specified, values are written as an
2319 unquoted series of pairs of hexadecimal digits, separated by
2320 colons.
2321 Currently, the values written out based on lease-id-format are the
2323 server-duid, the uid (DHCPv4 leases), and the IAID_DUID (DHCPv6
2324 leases). Note the server automatically reads the values in either
2325 format.
2326 The limit-addrs-per-ia statement
2328 limit-addrs-per-ia number;
2330 By default, the DHCPv6 server will limit clients to one IAADDR per
2332 IA option, meaning one address. If you wish to permit clients to
2333 hang onto multiple addresses at a time, configure a larger number
2334 here.
2335 Note that there is no present method to configure the server to
2337 forcibly configure the client with one IP address per each subnet
2338 on a shared network. This is left to future work.
2339 The local-port statement
2341 local-port port;
2343 This statement causes the DHCP server to listen for DHCP requests
2345 on the UDP port specified in port, rather than on port 67.
2346 The local-address statement
2348 local-address address;
2350 This statement causes the DHCP server to listen for DHCP requests
2352 sent to the specified address, rather than requests sent to all
2353 addresses. Since serving directly attached DHCP clients implies
2354 that the server must respond to requests sent to the all-ones IP
2355 address, this option cannot be used if clients are on directly
2356 attached networks; it is only realistically useful for a server
2357 whose only clients are reached via unicasts, such as via DHCP
2358 relay agents.
2359 Note: This statement is only effective if the server was compiled
2361 using the USE_SOCKETS #define statement, which is default on a
2362 small number of operating systems, and must be explicitly chosen
2363 at compile-time for all others. You can be sure if your server is
2364 compiled with USE_SOCKETS if you see lines of this format at
2365 startup:
2366 Listening on Socket/eth0
2368 Note also that since this bind()s all DHCP sockets to the speci‐
2370 fied address, that only one address may be supported in a daemon
2371 at a given time.
2372 The local-address6 and bind-local-address6 statements
2374 local-address6 address;
2376 bind-local-address6 flag;
2378 The local-address6 statement causes the DHCP server to send IPv6
2380 packets as originating from the specified IPv6 address, rather
2381 than leaving the kernel to fill in the source address field.
2382 When bind-local-address6 is present and has a value of true or on,
2384 service sockets are bound to address too.
2385 By default address is the undefined address and the bind-local-
2387 address6 is disabled, both may only be set at the global scope.
2388 The log-facility statement
2390 log-facility facility;
2392 This statement causes the DHCP server to do all of its logging on
2394 the specified log facility once the dhcpd.conf file has been read.
2395 By default the DHCP server logs to the daemon facility. Possible
2396 log facilities include auth, authpriv, cron, daemon, ftp, kern,
2397 lpr, mail, mark, news, ntp, security, syslog, user, uucp, and
2398 local0 through local7. Not all of these facilities are available
2399 on all systems, and there may be other facilities available on
2400 other systems.
2401 In addition to setting this value, you may need to modify your
2403 syslog.conf file to configure logging of the DHCP server. For
2404 example, you might add a line like this:
2405 local7.debug /var/log/dhcpd.log
2407 The syntax of the syslog.conf file may be different on some oper‐
2409 ating systems - consult the syslog.conf manual page to be sure.
2410 To get syslog to start logging to the new file, you must first
2411 create the file with correct ownership and permissions (usually,
2412 the same owner and permissions of your /var/log/messages or
2413 /usr/adm/messages file should be fine) and send a SIGHUP to sys‐
2414 logd. Some systems support log rollover using a shell script or
2415 program called newsyslog or logrotate, and you may be able to con‐
2416 figure this as well so that your log file doesn't grow uncontrol‐
2417 lably.
2418 Because the log-facility setting is controlled by the dhcpd.conf
2420 file, log messages printed while parsing the dhcpd.conf file or
2421 before parsing it are logged to the default log facility. To pre‐
2422 vent this, see the README file included with this distribution,
2423 which describes BUG: where is that mentioned in README? how to
2424 change the default log facility. When this parameter is used, the
2425 DHCP server prints its startup message a second time after parsing
2426 the configuration file, so that the log will be as complete as
2427 possible.
2428 The log-threshold-high and log-threshold-low statements
2430 log-threshold-high percentage;
2432 log-threshold-low percentage;
2434 The log-threshold-low and log-threshold-high statements are used
2436 to control when a message is output about pool usage. The value
2437 for both of them is the percentage of the pool in use. If the
2438 high threshold is 0 or has not been specified, no messages will be
2439 produced. If a high threshold is given, a message is output once
2440 the pool usage passes that level. After that, no more messages
2441 will be output until the pool usage falls below the low threshold.
2442 If the low threshold is not given, it default to a value of zero.
2443 A special case occurs when the low threshold is set to be higer
2445 than the high threshold. In this case, a message will be gener‐
2446 ated each time a lease is acknowledged when the pool usage is
2447 above the high threshold.
2448 Note that threshold logging will be automatically disabled for
2450 shared subnets whose total number of addresses is larger than
2451 (2^64)-1. The server will emit a log statement at startup when
2452 threshold logging is disabled as shown below:
2453 "Threshold logging disabled for shared subnet of ranges:
2455 <addresses>"
2456 This is likely to have no practical runtime effect as CPUs are
2458 unlikely to support a server actually reaching such a large number
2459 of leases.
2460 The max-lease-time statement
2462 max-lease-time time;
2464 Time should be the maximum length in seconds that will be assigned
2466 to a lease. If not defined, the default maximum lease time is
2467 86400. The only exception to this is that Dynamic BOOTP lease
2468 lengths, which are not specified by the client, are not limited by
2469 this maximum.
2470 The min-lease-time statement
2472 min-lease-time time;
2474 Time should be the minimum length in seconds that will be assigned
2476 to a lease. The default is the minimum of 300 seconds or max-
2477 lease-time.
2478 The min-secs statement
2480 min-secs seconds;
2482 Seconds should be the minimum number of seconds since a client
2484 began trying to acquire a new lease before the DHCP server will
2485 respond to its request. The number of seconds is based on what
2486 the client reports, and the maximum value that the client can
2487 report is 255 seconds. Generally, setting this to one will result
2488 in the DHCP server not responding to the client's first request,
2489 but always responding to its second request.
2490 This can be used to set up a secondary DHCP server which never
2492 offers an address to a client until the primary server has been
2493 given a chance to do so. If the primary server is down, the
2494 client will bind to the secondary server, but otherwise clients
2495 should always bind to the primary. Note that this does not, by
2496 itself, permit a primary server and a secondary server to share a
2497 pool of dynamically-allocatable addresses.
2498 The next-server statement
2500 next-server server-name;
2502 The next-server statement is used to specify the host address of
2504 the server from which the initial boot file (specified in the
2505 filename statement) is to be loaded. Server-name should be a
2506 numeric IP address or a domain name. If no next-server statement
2507 applies to a given client, the address 0.0.0.0 is used.
2508 The omapi-port statement
2510 omapi-port port;
2512 The omapi-port statement causes the DHCP server to listen for
2514 OMAPI connections on the specified port. This statement is
2515 required to enable the OMAPI protocol, which is used to examine
2516 and modify the state of the DHCP server as it is running.
2517 The one-lease-per-client statement
2519 one-lease-per-client flag;
2521 If this flag is enabled, whenever a client sends a DHCPREQUEST for
2523 a particular lease, the server will automatically free any other
2524 leases the client holds. This presumes that when the client sends
2525 a DHCPREQUEST, it has forgotten any lease not mentioned in the
2526 DHCPREQUEST - i.e., the client has only a single network interface
2527 and it does not remember leases it's holding on networks to which
2528 it is not currently attached. Neither of these assumptions are
2529 guaranteed or provable, so we urge caution in the use of this
2530 statement.
2531 The persist-eui-64-leases statement
2533 persist-eui-64-leases flag;
2535 When this flag is enabled, the server will write EUI-64 based
2537 leases to the leases file. Since such leases can only, ever be
2538 valid for a single DUID value it can be argued that writing them
2539 to the leases file isn't essential and not doing so may have per‐
2540 fomance advantages. See use-eui-64 statement for more details on
2541 EUI-64 based address allocation. The flag is enabled by default
2542 and may only be set at the global scope.
2543 The pid-file-name statement
2545 pid-file-name name;
2547 Name should be the name of the DHCP server's process ID file.
2549 This is the file in which the DHCP server's process ID is stored
2550 when the server starts. By default, this is /var/run/dhcpd.pid.
2551 Like the lease-file-name statement, this statement must appear in
2552 the outer scope of the configuration file. The order of precedence
2553 used by the server is:
2554 1. pid-file-name configuration file statement.
2556 2. -lf command line flag.
2557 3. PATH_DHCPD_PID environment variable.
2558 The dhcpv6-pid-file-name statement
2560 dhcpv6-pid-file-name name;
2562 Name is the name of the pid file to use if and only if the
2564 server is running in DHCPv6 mode. By default, this is
2565 /var/lib/dhcpd/dhcpd6.pid. This statement, like pid-file-name,
2566 must appear in the outer scope of the configuration file. The
2567 order of precedence used by the server is:
2568 1. dhcpv6-pid-file-name configuration file statement.
2570 2. -lf command line flag.
2571 3. PATH_DHCPD6_PID environment variable.
2572 The ping-check statement
2574 ping-check flag;
2576 When the DHCP server is considering dynamically allocating an IP
2578 address to a client, it first sends an ICMP Echo request (a
2579 ping) to the address being assigned. It waits for a second, and
2580 if no ICMP Echo response has been heard, it assigns the address.
2581 If a response is heard, the lease is abandoned, and the server
2582 does not respond to the client. The lease will remain abandoned
2583 for a minimum of abandon-lease-time seconds.
2584 If a there are no free addressses but there are abandoned IP
2586 addresses, the DHCP server will attempt to reclaim an abandoned
2587 IP address regardless of the value of abandon-lease-time.
2588 This ping check introduces a default one-second delay in
2590 responding to DHCPDISCOVER messages, which can be a problem for
2591 some clients. The default delay of one second may be configured
2592 using the ping-timeout parameter. The ping-check configuration
2593 parameter can be used to control checking - if its value is
2594 false, no ping check is done.
2595 The ping-cltt-secs statement
2597 ping-cltt-secs seconds;
2599 The server will conduct a ping check if all the following condi‐
2601 tions are true:
2602 1. Ping checking is enabled.
2604 2. The server is responding to a DISCOVER.
2606 3. The lease to be offered is neither static nor active (i.e.
2608 still a valid lease).
2609 4. And any of the following are true:
2611 a. This will be the first offer of this lease (CLTT is 0).
2612 b. The lease is being offered to a client other than its
2613 previous owner
2614 c. The lease is being offered to its previous owner and more
2615 than
2616 ping-cltt-secs have elapsed since CLTT of the original
2617 lease.
2618 d. The lease was abandoned and the server is attempting to
2619 reclaim it.
2620 The ping-cltt-secs statement allows the user to specify the
2623 amount of time that must elaspe after CLTT before a ping check
2624 will be conducted. The default value is sixty seconds.
2625 The ping-timeout statement
2627 ping-timeout seconds;
2629 If the DHCP server determined it should send an ICMP echo
2631 request (a ping) because the ping-check statement is true, ping-
2632 timeout allows you to configure how many seconds the DHCP server
2633 should wait for an ICMP Echo response to be heard, if no ICMP
2634 Echo response has been received before the timeout expires, it
2635 assigns the address. If a response is heard, the lease is aban‐
2636 doned, and the server does not respond to the client. If no
2637 value is set, ping-timeout defaults to 1 second. (See also ping-
2638 timeout-ms below)
2639 The ping-timeout-ms statement
2641 ping-timeout-ms milliseconds;
2643 Allows you to specify the ping timeout in milliseconds rather
2645 than seconds. If this value is greater than zero, the server
2646 will use it in place of ping-timeout. The default value is
2647 zero.
2648 The preferred-lifetime statement
2650 preferred-lifetime seconds;
2652 IPv6 addresses have ´valid´ and ´preferred´ lifetimes. The
2654 valid lifetime determines at what point at lease might be said
2655 to have expired, and is no longer useable. A preferred lifetime
2656 is an advisory condition to help applications move off of the
2657 address and onto currently valid addresses (should there still
2658 be any open TCP sockets or similar).
2659 The preferred lifetime defaults to 5/8 the default lease time.
2661 The prefix-length-mode statement
2663 prefix-length-mode mode;
2665 According to RFC 3633, DHCPv6 clients may specify preferences
2667 when soliciting prefixes by including an IA_PD Prefix option
2668 within the IA_PD option. Among the preferences that may be con‐
2669 veyed is the "prefix-length". When non-zero it indicates a
2670 client's desired length for offered prefixes. The RFC states
2671 that servers "MAY choose to use the information...to select pre‐
2672 fix(es)" but does not specify any particular rules for doing so.
2673 The prefix-length-mode statement can be used to set the prefix
2674 selection rules employed by the server, when clients send a non-
2675 zero prefix-length value. The mode parameter must be one of
2676 ignore, prefer, exact, minimum, or maximum where:
2677 1. ignore - The requested length is ignored. The server will
2679 offer the first available prefix.
2680 2. prefer - The server will offer the first available prefix
2682 with the same length as the requested length. If none are found
2683 then it will offer the first available prefix of any length.
2684 This is the default behavior.
2685 3. exact - The server will offer the first available prefix with
2687 the same length as the requested length. If none are found, it
2688 will return a status indicating no prefixes available.
2689 4. minimum - The server will offer the first available prefix
2691 with the same length as the requested length. If none are
2692 found, it will return the first available prefix whose length is
2693 greater than (e.g. longer than), the requested value. If none
2694 of those are found, it will return a status indicating no pre‐
2695 fixes available. For example, if client requests a length of
2696 /60, and the server has available prefixes of lengths /56 and
2697 /64, it will offer prefix of length /64.
2698 5. maximum - The server will offer the first available prefix
2700 with the same length as the requested length. If none are
2701 found, it will return the first available prefix whose length is
2702 less than (e.g. shorter than), the requested value. If none of
2703 those are found, it will return a status indicating no prefixes
2704 available. For example, if client requests a length of /60, and
2705 the server has available prefixes of lengths /56 and /64, it
2706 will offer a prefix of length /56.
2707 In general "first available" is determined by the order in which
2709 pools are defined in the server's configuration. For example,
2710 if a subnet is defined with three prefix pools A,B, and C:
2711 subnet 3000::/64 {
2713 # pool A
2714 pool6 {
2715 :
2716 }
2717 # pool B
2718 pool6 {
2719 :
2720 }
2721 # pool C
2722 pool6 {
2723 :
2724 }
2725 }
2726 then the pools will be checked in the order A, B, C. For modes
2728 prefer, minimum, and maximum this may mean checking the pools in
2729 that order twice. A first pass through is made looking for an
2730 available prefix of exactly the preferred length. If none are
2731 found, then a second pass is performed starting with pool A but
2732 with appropriately adjusted length criteria.
2733 The release-on-roam statement
2735 release-on-roam flag;
2737 When enabled and the dhcpd server detects that a DHCPv6 client
2739 (IAID+DUID) has roamed to a new network, it will release the
2740 pre-existing leases on the old network and emit a log statement
2741 similiar to the following:
2742 "Client: <id> roamed to new network, releasing lease:
2744 <address>"
2745 The server will carry out all of the same steps that would nor‐
2747 mally occur when a client explicitly releases a lease. When
2748 release-on-roam is disabled (the default) the server makes such
2749 leases unavailable until they expire or the server is restarted.
2750 Clients that need leases in multiple networks must supply a
2751 unique IAID in each IA. This parameter may only be specified at
2752 the global level.
2753 The remote-port statement
2755 remote-port port;
2757 This statement causes the DHCP server to transmit DHCP responses
2759 to DHCP clients upon the UDP port specified in port, rather than
2760 on port 68. In the event that the UDP response is transmitted
2761 to a DHCP Relay, the server generally uses the local-port con‐
2762 figuration value. Should the DHCP Relay happen to be addressed
2763 as 127.0.0.1, however, the DHCP Server transmits its response to
2764 the remote-port configuration value. This is generally only
2765 useful for testing purposes, and this configuration value should
2766 generally not be used.
2767 The server-identifier statement
2769 server-identifier hostname;
2771 The server-identifier statement can be used to define the value
2773 that is sent in the DHCP Server Identifier option for a given
2774 scope. The value specified must be an IP address for the DHCP
2775 server, and must be reachable by all clients served by a partic‐
2776 ular scope.
2777 The use of the server-identifier statement is not recommended -
2779 the only reason to use it is to force a value other than the
2780 default value to be sent on occasions where the default value
2781 would be incorrect. The default value is the first IP address
2782 associated with the physical network interface on which the
2783 request arrived.
2784 The usual case where the server-identifier statement needs to be
2786 sent is when a physical interface has more than one IP address,
2787 and the one being sent by default isn't appropriate for some or
2788 all clients served by that interface. Another common case is
2789 when an alias is defined for the purpose of having a consistent
2790 IP address for the DHCP server, and it is desired that the
2791 clients use this IP address when contacting the server.
2792 Supplying a value for the dhcp-server-identifier option is
2794 equivalent to using the server-identifier statement.
2795 The server-id-check statement
2797 server-id-check flag;
2799 The server-id-check statement is used to control whether or not
2801 a server, participating in failover, verifies that the value of
2802 the dhcp-server-identifier option in received DHCP REQUESTs
2803 match the server's id before processing the request. Server id
2804 checking is disabled by default. Setting this flag enables id
2805 checking and thereafter the server will only process requests
2806 that match. Note the flag setting should be consistent between
2807 failover partners.
2808 Unless overridden by use of the server-identifier statement, the
2810 value the server uses as its id will be the first IP address
2811 associated with the physical network interface on which the
2812 request arrived.
2813 In order to reduce runtime overhead the server only checks for a
2815 server id option in the global and subnet scopes. Complicated
2816 configurations may result in different server ids for this check
2817 and when the server id for a reply packet is determined, which
2818 would prohibit the server from responding.
2819 The primary use for this option is when a client broadcasts a
2821 request but requires that the response come from a specific
2822 failover peer. An example of this would be when a client
2823 reboots while its lease is still active - in this case both
2824 servers will normally respond. Most of the time the client
2825 won't check the server id and can use either of the responses.
2826 However if the client does check the server id it may reject the
2827 response if it came from the wrong peer. If the timing is such
2828 that the "wrong" peer responds first most of the time the client
2829 may not get an address for some time.
2830 Care should be taken before enabling this option.
2832 The server-duid statement
2834 server-duid LLT [ hardware-type timestamp hardware-address ] ;
2836 server-duid EN enterprise-number enterprise-identifier ;
2838 server-duid LL [ hardware-type hardware-address ] ;
2840 The server-duid statement configures the server DUID. You may
2842 pick either LLT (link local address plus time), EN (enterprise),
2843 or LL (link local).
2844 If you choose LLT or LL, you may specify the exact contents of
2846 the DUID. Otherwise the server will generate a DUID of the
2847 specified type.
2848 If you choose EN, you must include the enterprise number and the
2850 enterprise-identifier.
2851 If there is a server-duid statement in the lease file it will
2853 take precedence over the server-duid statement from the config
2854 file and a dhcp6.server-id option in the config file will over‐
2855 ride both.
2856 The default server-duid type is LLT.
2858 The server-name statement
2860 server-name name ;
2862 The server-name statement can be used to inform the client of
2864 the name of the server from which it is booting. Name should be
2865 the name that will be provided to the client.
2866 The dhcpv6-set-tee-times statement
2868 dhcpv6-set-tee-times flag;
2870 The dhcpv6-set-tee-times statement enables setting T1 and T2 to
2872 the values recommended in RFC 3315 (Section 22.4). When setting
2873 T1 and T2, the server will use dhcp-renewal-time and dhcp-
2874 rebinding-time, respectively. A value of zero tells the client
2875 it may choose its own value.
2876 When those options are not defined then values will be set to
2878 zero unless the global dhcpv6-set-tee-times is enabled. When
2879 this option is enabled the times are calculated as recommended
2880 by RFC 3315, Section 22.4:
2881 T1 will be set to 0.5 times the shortest preferred life‐
2883 time
2884 in the reply. If the "shortest" preferred lifetime is
2885 0xFFFFFFFF, T1 will set to 0xFFFFFFFF.
2886 T2 will be set to 0.8 times the shortest preferred life‐
2888 time
2889 in the reply. If the "shortest" preferred lifetime is
2890 0xFFFFFFFF, T2 will set to 0xFFFFFFFF.
2891 Keep in mind that given sufficiently small lease lifetimes, the
2893 above calculations will result in the two values being equal.
2894 For example, a 9 second lease lifetime would yield T1 = T2 = 4
2895 seconds, which would cause clients to issue rebinds only. In
2896 such a case it would likely be better to explicitly define the
2897 values.
2898 Note that dhcpv6-set-tee-times is intended to be transitional
2900 and will likely be removed in a future release. Once removed the
2901 behavior will be to use the configured values when present or
2902 calculate them per the RFC. If you want zeros, define them as
2903 zeros.
2904 The site-option-space statement
2906 site-option-space name ;
2908 The site-option-space statement can be used to determine from
2910 what option space site-local options will be taken. This can be
2911 used in much the same way as the vendor-option-space statement.
2912 Site-local options in DHCP are those options whose numeric codes
2913 are greater than 224. These options are intended for site-spe‐
2914 cific uses, but are frequently used by vendors of embedded hard‐
2915 ware that contains DHCP clients. Because site-specific options
2916 are allocated on an ad hoc basis, it is quite possible that one
2917 vendor's DHCP client might use the same option code that another
2918 vendor's client uses, for different purposes. The site-option-
2919 space option can be used to assign a different set of site-spe‐
2920 cific options for each such vendor, using conditional evaluation
2921 (see dhcp-eval (5) for details).
2922 The stash-agent-options statement
2924 stash-agent-options flag;
2926 If the stash-agent-options parameter is true for a given client,
2928 the server will record the relay agent information options sent
2929 during the client's initial DHCPREQUEST message when the client
2930 was in the SELECTING state and behave as if those options are
2931 included in all subsequent DHCPREQUEST messages sent in the
2932 RENEWING state. This works around a problem with relay agent
2933 information options, which is that they usually not appear in
2934 DHCPREQUEST messages sent by the client in the RENEWING state,
2935 because such messages are unicast directly to the server and not
2936 sent through a relay agent.
2937 The update-conflict-detection statement
2939 update-conflict-detection flag;
2941 If the update-conflict-detection parameter is true, the server
2943 will perform standard DHCID multiple-client, one-name conflict
2944 detection. If the parameter has been set false, the server will
2945 skip this check and instead simply tear down any previous bind‐
2946 ings to install the new binding without question. The default
2947 is true and this parameter may only be specified at the global
2948 scope.
2949 The update-optimization statement
2951 update-optimization flag;
2953 If the update-optimization parameter is false for a given
2955 client, the server will attempt a DNS update for that client
2956 each time the client renews its lease, rather than only attempt‐
2957 ing an update when it appears to be necessary. This will allow
2958 the DNS to heal from database inconsistencies more easily, but
2959 the cost is that the DHCP server must do many more DNS updates.
2960 We recommend leaving this option enabled, which is the default.
2961 If this parameter is not specified, or is true, the DHCP server
2962 will only update when the client information changes, the client
2963 gets a different lease, or the client's lease expires.
2964 The update-static-leases statement
2966 update-static-leases flag;
2968 The update-static-leases flag, if enabled, causes the DHCP
2970 server to do DNS updates for clients even if those clients are
2971 being assigned their IP address using a fixed-address or fixed-
2972 address6 statement - that is, the client is being given a static
2973 assignment. It is not recommended because the DHCP server has
2974 no way to tell that the update has been done, and therefore will
2975 not delete the record when it is not in use. Also, the server
2976 must attempt the update each time the client renews its lease,
2977 which could have a significant performance impact in environ‐
2978 ments that place heavy demands on the DHCP server. This feature
2979 is supported for both DHCPv4 and DHCPv6, and update modes stan‐
2980 dard or interim. It is disabled by default.
2981 The use-eui-64 statement
2983 use-eui-64 flag;
2985 (Support for this must be enabled at compile time, see EUI_64 in
2987 includes/site.h)
2988 The use-eui-64 flag, if enabled, instructs the server to con‐
2990 struct an address using the client's EUI-64 DUID (Type 3, HW
2991 Type EUI-64), rather than creating an address using the dynamic
2992 algorithm. This means that a given DUID will always generate
2993 the same address for a given pool and further that the address
2994 is guaranteed to be unique to that DUID. The IPv6 address will
2995 be calculated from the EUI-64 link layer address, conforming to
2996 RFC 2373, unless there is a host declaration for the client-id.
2997 The range6 statement for EUI-64 must define full /64 bit ranges.
2999 Invalid ranges will be flagged during configuration parsing as
3000 errors. See the following example:
3001 subnet6 fc00:e4::/64 {
3003 use-eui-64 true;
3004 range6 fc00:e4::/64;
3005 }
3006 The statement may be specified down to the pool level, allowing
3008 a mixture of dynamic and EUI-64 based pools.
3009 During lease file parsing, any leases which map to an EUI-64
3011 pool, that have a non-EUI-64 DUID or for which the lease address
3012 is not the EUI-64 address for that DUID in that pool, will be
3013 discarded.
3014 If a host declaration exists for the DUID, the server grants the
3016 address (fixed-prefix6, fixed-address6) according to the host
3017 declaration, regardless of the DUID type of the client (even for
3018 EUI-64 DUIDs).
3019 If a client request's an EUI-64 lease for a given network, and
3021 the resultant address conflicts with a fixed address reserva‐
3022 tion, the server will send the client a "no addresses available"
3023 response.
3024 Any client with a non-conforming DUID (not type 3 or not hw type
3026 EUI-64) that is not linked to a host declaration, which requests
3027 an address from an EUI-64 enabled pool will be ignored and the
3028 event will be logged.
3029 Pools that are configured for EUI-64 will be skipped for dynamic
3031 allocation. If there are no pools in the shared network from
3032 which to allocate, the client will get back a no addresses
3033 available status.
3034 On an EUI-64 enabled pool, any client with a DUID 3, HW Type
3036 EUI-64, requesting a solicit/renew and including IA_NA that do
3037 not match the EUI-64 policy, they will be treated as though they
3038 are "outside" the subnet for a given client message:
3039 Solicit - Server will advertise with EUI-64 ia suboption,
3041 but with rapid
3042 commit off
3043 Request - Server will send "an address not on link status",
3044 and no ia
3045 suboption Renew/Rebind - Server will send the requested
3046 address ia
3047 suboption with lifetimes of 0, plus an EUI-64 ia
3048 Whether or not EUI-64 based leases are written out to the lease
3050 database may be controlled by persist-eui-64-leases statement.
3051 The use-host-decl-names statement
3053 use-host-decl-names flag;
3055 If the use-host-decl-names parameter is true in a given scope,
3057 then for every host declaration within that scope, the name pro‐
3058 vided for the host declaration will be supplied to the client as
3059 its hostname. So, for example,
3060 group {
3062 use-host-decl-names on;
3063 host joe {
3065 hardware ethernet 08:00:2b:4c:29:32;
3066 fixed-address joe.example.com;
3067 }
3068 }
3069 is equivalent to
3071 host joe {
3073 hardware ethernet 08:00:2b:4c:29:32;
3074 fixed-address joe.example.com;
3075 option host-name "joe";
3076 }
3077 Additionally, enabling use-host-decl-names instructs the server
3079 to use the host declaration name in the the forward DNS name, if
3080 no other values are available. This value selection process is
3081 discussed in more detail under DNS updates.
3082 An option host-name statement within a host declaration will
3084 override the use of the name in the host declaration.
3085 It should be noted here that most DHCP clients completely ignore
3087 the host-name option sent by the DHCP server, and there is no
3088 way to configure them not to do this. So you generally have a
3089 choice of either not having any hostname to client IP address
3090 mapping that the client will recognize, or doing DNS updates.
3091 It is beyond the scope of this document to describe how to make
3092 this determination.
3093 The use-lease-addr-for-default-route statement
3095 use-lease-addr-for-default-route flag;
3097 If the use-lease-addr-for-default-route parameter is true in a
3099 given scope, then instead of sending the value specified in the
3100 routers option (or sending no value at all), the IP address of
3101 the lease being assigned is sent to the client. This supposedly
3102 causes Win95 machines to ARP for all IP addresses, which can be
3103 helpful if your router is configured for proxy ARP. The use of
3104 this feature is not recommended, because it won't work for many
3105 DHCP clients.
3106 The vendor-option-space statement
3108 vendor-option-space string;
3110 The vendor-option-space parameter determines from what option
3112 space vendor options are taken. The use of this configuration
3113 parameter is illustrated in the dhcp-options(5) manual page, in
3114 the VENDOR ENCAPSULATED OPTIONS section.
3115
3117 Sometimes it's helpful to be able to set the value of a DHCP server
3118 parameter based on some value that the client has sent. To do this,
3119 you can use expression evaluation. The dhcp-eval(5) manual page
3120 describes how to write expressions. To assign the result of an evalua‐
3121 tion to an option, define the option as follows:
3122 my-parameter = expression ;
3124 For example:
3126 ddns-hostname = binary-to-ascii (16, 8, "-",
3128 substring (hardware, 1, 6));
3129
3131 It's often useful to allocate a single address to a single client, in
3132 approximate perpetuity. Host statements with fixed-address clauses
3133 exist to a certain extent to serve this purpose, but because host
3134 statements are intended to approximate ´static configuration´, they
3135 suffer from not being referenced in a littany of other Server Services,
3136 such as dynamic DNS, failover, ´on events´ and so forth.
3137 If a standard dynamic lease, as from any range statement, is marked
3139 ´reserved´, then the server will only allocate this lease to the client
3140 it is identified by (be that by client identifier or hardware address).
3141 In practice, this means that the lease follows the normal state engine,
3143 enters ACTIVE state when the client is bound to it, expires, or is
3144 released, and any events or services that would normally be supplied
3145 during these events are processed normally, as with any other dynamic
3146 lease. The only difference is that failover servers treat reserved
3147 leases as special when they enter the FREE or BACKUP states - each
3148 server applies the lease into the state it may allocate from - and the
3149 leases are not placed on the queue for allocation to other clients.
3150 Instead they may only be ´found´ by client identity. The result is
3151 that the lease is only offered to the returning client.
3152 Care should probably be taken to ensure that the client only has one
3154 lease within a given subnet that it is identified by.
3155 Leases may be set ´reserved´ either through OMAPI, or through the
3157 ´infinite-is-reserved´ configuration option (if this is applicable to
3158 your environment and mixture of clients).
3159 It should also be noted that leases marked ´reserved´ are effectively
3161 treated the same as leases marked ´bootp´.
3162
3164 DHCP option statements are documented in the dhcp-options(5) manual
3165 page.
3166
3168 Expressions used in DHCP option statements and elsewhere are documented
3169 in the dhcp-eval(5) manual page.
3170
3172 dhcpd(8), dhcpd.leases(5), dhcp-options(5), dhcp-eval(5), RFC2132,
3173 RFC2131.
3174
3176 dhcpd.conf(5) is maintained by ISC. Information about Internet Systems
3177 Consortium can be found at https://www.isc.org.
3178 dhcpd.conf(5)