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. In this case, the DHCP server will never do
296 dynamic address allocation. In this case, the client is required to
297 take the address specified in the host declaration. If the client
298 sends a DHCPREQUEST for some other address, the server will respond
299 with a DHCPNAK.
300 When the DHCP server allocates a new address for a client (remember,
302 this only happens if the client has sent a DHCPDISCOVER), it first
303 looks to see if the client already has a valid lease on an IP address,
304 or if there is an old IP address the client had before that hasn't yet
305 been reassigned. In that case, the server will take that address and
306 check it to see if the client is still permitted to use it. If the
307 client is no longer permitted to use it, the lease is freed if the
308 server thought it was still in use - the fact that the client has sent
309 a DHCPDISCOVER proves to the server that the client is no longer using
310 the lease.
311 If no existing lease is found, or if the client is forbidden to receive
313 the existing lease, then the server will look in the list of address
314 pools for the network segment to which the client is attached for a
315 lease that is not in use and that the client is permitted to have. It
316 looks through each pool declaration in sequence (all range declarations
317 that appear outside of pool declarations are grouped into a single pool
318 with no permit list). If the permit list for the pool allows the
319 client to be allocated an address from that pool, the pool is examined
320 to see if there is an address available. If so, then the client is
321 tentatively assigned that address. Otherwise, the next pool is tested.
322 If no addresses are found that can be assigned to the client, no
323 response is sent to the client.
324 If an address is found that the client is permitted to have, and that
326 has never been assigned to any client before, the address is immedi‐
327 ately allocated to the client. If the address is available for alloca‐
328 tion but has been previously assigned to a different client, the server
329 will keep looking in hopes of finding an address that has never before
330 been assigned to a client.
331 The DHCP server generates the list of available IP addresses from a
333 hash table. This means that the addresses are not sorted in any par‐
334 ticular order, and so it is not possible to predict the order in which
335 the DHCP server will allocate IP addresses. Users of previous versions
336 of the ISC DHCP server may have become accustomed to the DHCP server
337 allocating IP addresses in ascending order, but this is no longer pos‐
338 sible, and there is no way to configure this behavior with version 3 of
339 the ISC DHCP server.
340
342 The DHCP server checks IP addresses to see if they are in use before
343 allocating them to clients. It does this by sending an ICMP Echo
344 request message to the IP address being allocated. If no ICMP Echo
345 reply is received within a second, the address is assumed to be free.
346 This is only done for leases that have been specified in range state‐
347 ments, and only when the lease is thought by the DHCP server to be free
348 - i.e., the DHCP server or its failover peer has not listed the lease
349 as in use.
350 If a response is received to an ICMP Echo request, the DHCP server
352 assumes that there is a configuration error - the IP address is in use
353 by some host on the network that is not a DHCP client. It marks the
354 address as abandoned, and will not assign it to clients. The lease will
355 remain abandoned for a minimum of abandon-lease-time seconds.
356 If a DHCP client tries to get an IP address, but none are available,
358 but there are abandoned IP addresses, then the DHCP server will attempt
359 to reclaim an abandoned IP address. It marks one IP address as free,
360 and then does the same ICMP Echo request check described previously.
361 If there is no answer to the ICMP Echo request, the address is assigned
362 to the client.
363 The DHCP server does not cycle through abandoned IP addresses if the
365 first IP address it tries to reclaim is free. Rather, when the next
366 DHCPDISCOVER comes in from the client, it will attempt a new allocation
367 using the same method described here, and will typically try a new IP
368 address.
369
371 This version of the ISC DHCP server supports the DHCP failover protocol
372 as documented in draft-ietf-dhc-failover-12.txt. This is not a final
373 protocol document, and we have not done interoperability testing with
374 other vendors' implementations of this protocol, so you must not assume
375 that this implementation conforms to the standard. If you wish to use
376 the failover protocol, make sure that both failover peers are running
377 the same version of the ISC DHCP server.
378 The failover protocol allows two DHCP servers (and no more than two) to
380 share a common address pool. Each server will have about half of the
381 available IP addresses in the pool at any given time for allocation.
382 If one server fails, the other server will continue to renew leases out
383 of the pool, and will allocate new addresses out of the roughly half of
384 available addresses that it had when communications with the other
385 server were lost.
386 It is possible during a prolonged failure to tell the remaining server
388 that the other server is down, in which case the remaining server will
389 (over time) reclaim all the addresses the other server had available
390 for allocation, and begin to reuse them. This is called putting the
391 server into the PARTNER-DOWN state.
392 You can put the server into the PARTNER-DOWN state either by using the
394 omshell (1) command or by stopping the server, editing the last
395 failover state declaration in the lease file, and restarting the
396 server. If you use this last method, change the "my state" line to:
397 failover peer name state {
399 my state partner-down;.
400 peer state state at date;
401 }
402 It is only required to change "my state" as shown above.
404 When the other server comes back online, it should automatically detect
406 that it has been offline and request a complete update from the server
407 that was running in the PARTNER-DOWN state, and then both servers will
408 resume processing together.
409 It is possible to get into a dangerous situation: if you put one server
411 into the PARTNER-DOWN state, and then *that* server goes down, and the
412 other server comes back up, the other server will not know that the
413 first server was in the PARTNER-DOWN state, and may issue addresses
414 previously issued by the other server to different clients, resulting
415 in IP address conflicts. Before putting a server into PARTNER-DOWN
416 state, therefore, make sure that the other server will not restart
417 automatically.
418 The failover protocol defines a primary server role and a secondary
420 server role. There are some differences in how primaries and secon‐
421 daries act, but most of the differences simply have to do with provid‐
422 ing a way for each peer to behave in the opposite way from the other.
423 So one server must be configured as primary, and the other must be con‐
424 figured as secondary, and it doesn't matter too much which one is
425 which.
426
428 When a server starts that has not previously communicated with its
429 failover peer, it must establish communications with its failover peer
430 and synchronize with it before it can serve clients. This can happen
431 either because you have just configured your DHCP servers to perform
432 failover for the first time, or because one of your failover servers
433 has failed catastrophically and lost its database.
434 The initial recovery process is designed to ensure that when one
436 failover peer loses its database and then resynchronizes, any leases
437 that the failed server gave out before it failed will be honored. When
438 the failed server starts up, it notices that it has no saved failover
439 state, and attempts to contact its peer.
440 When it has established contact, it asks the peer for a complete copy
442 its peer's lease database. The peer then sends its complete database,
443 and sends a message indicating that it is done. The failed server then
444 waits until MCLT has passed, and once MCLT has passed both servers make
445 the transition back into normal operation. This waiting period ensures
446 that any leases the failed server may have given out while out of con‐
447 tact with its partner will have expired.
448 While the failed server is recovering, its partner remains in the part‐
450 ner-down state, which means that it is serving all clients. The failed
451 server provides no service at all to DHCP clients until it has made the
452 transition into normal operation.
453 In the case where both servers detect that they have never before com‐
455 municated with their partner, they both come up in this recovery state
456 and follow the procedure we have just described. In this case, no ser‐
457 vice will be provided to DHCP clients until MCLT has expired.
458
460 In order to configure failover, you need to write a peer declaration
461 that configures the failover protocol, and you need to write peer ref‐
462 erences in each pool declaration for which you want to do failover.
463 You do not have to do failover for all pools on a given network seg‐
464 ment. You must not tell one server it's doing failover on a particu‐
465 lar address pool and tell the other it is not. You must not have any
466 common address pools on which you are not doing failover. A pool dec‐
467 laration that utilizes failover would look like this:
468 pool {
470 failover peer "foo";
471 pool specific parameters
472 };
473 Dynamic BOOTP leases are not compatible with failover, and, as such,
475 you need to disallow BOOTP in pools that you are using failover for.
476 The server currently does very little sanity checking, so if you
478 configure it wrong, it will just fail in odd ways. I would recommend
479 therefore that you either do failover or don't do failover, but don't
480 do any mixed pools. Also, use the same master configuration file for
481 both servers, and have a separate file that contains the peer
482 declaration and includes the master file. This will help you to avoid
483 configuration mismatches. As our implementation evolves, this will
484 become less of a problem. A basic sample dhcpd.conf file for a
485 primary server might look like this:
486 failover peer "foo" {
488 primary;
489 address anthrax.rc.example.com;
490 port 647;
491 peer address trantor.rc.example.com;
492 peer port 847;
493 max-response-delay 60;
494 max-unacked-updates 10;
495 mclt 3600;
496 split 128;
497 load balance max seconds 3;
498 }
499 include "/etc/dhcpd.master";
501 The statements in the peer declaration are as follows:
503 The primary and secondary statements
505 [ primary | secondary ];
507 This determines whether the server is primary or secondary, as
509 described earlier under DHCP FAILOVER.
510 The address statement
512 address address;
514 The address statement declares the IP address or DNS name on which
516 the server should listen for connections from its failover peer, and
517 also the value to use for the DHCP Failover Protocol server identi‐
518 fier. Because this value is used as an identifier, it may not be
519 omitted.
520 The peer address statement
522 peer address address;
524 The peer address statement declares the IP address or DNS name to
526 which the server should connect to reach its failover peer for
527 failover messages.
528 The port statement
530 port port-number;
532 The port statement declares the TCP port on which the server should
534 listen for connections from its failover peer. This statement may be
535 omitted, in which case the IANA assigned port number 647 will be used
536 by default.
537 The peer port statement
539 peer port port-number;
541 The peer port statement declares the TCP port to which the server
543 should connect to reach its failover peer for failover messages.
544 This statement may be omitted, in which case the IANA assigned port
545 number 647 will be used by default.
546 The max-response-delay statement
548 max-response-delay seconds;
550 The max-response-delay statement tells the DHCP server how many sec‐
552 onds may pass without receiving a message from its failover peer
553 before it assumes that connection has failed. This number should be
554 small enough that a transient network failure that breaks the connec‐
555 tion will not result in the servers being out of communication for a
556 long time, but large enough that the server isn't constantly making
557 and breaking connections. This parameter must be specified.
558 The max-unacked-updates statement
560 max-unacked-updates count;
562 The max-unacked-updates statement tells the remote DHCP server how
564 many BNDUPD messages it can send before it receives a BNDACK from the
565 local system. We don't have enough operational experience to say
566 what a good value for this is, but 10 seems to work. This parameter
567 must be specified.
568 The mclt statement
570 mclt seconds;
572 The mclt statement defines the Maximum Client Lead Time. It must be
574 specified on the primary, and may not be specified on the secondary.
575 This is the length of time for which a lease may be renewed by either
576 failover peer without contacting the other. The longer you set this,
577 the longer it will take for the running server to recover IP
578 addresses after moving into PARTNER-DOWN state. The shorter you set
579 it, the more load your servers will experience when they are not com‐
580 municating. A value of something like 3600 is probably reasonable,
581 but again bear in mind that we have no real operational experience
582 with this.
583 The split statement
585 split bits;
587 The split statement specifies the split between the primary and sec‐
589 ondary for the purposes of load balancing. Whenever a client makes a
590 DHCP request, the DHCP server runs a hash on the client identifica‐
591 tion, resulting in value from 0 to 255. This is used as an index
592 into a 256 bit field. If the bit at that index is set, the primary
593 is responsible. If the bit at that index is not set, the secondary
594 is responsible. The split value determines how many of the leading
595 bits are set to one. So, in practice, higher split values will cause
596 the primary to serve more clients than the secondary. Lower split
597 values, the converse. Legal values are between 0 and 256 inclusive,
598 of which the most reasonable is 128. Note that a value of 0 makes
599 the secondary responsible for all clients and a value of 256 makes
600 the primary responsible for all clients.
601 The hba statement
603 hba colon-separated-hex-list;
605 The hba statement specifies the split between the primary and sec‐
607 ondary as a bitmap rather than a cutoff, which theoretically allows
608 for finer-grained control. In practice, there is probably no need
609 for such fine-grained control, however. An example hba statement:
610 hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:
612 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00;
613 This is equivalent to a split 128; statement, and identical. The
615 following two examples are also equivalent to a split of 128, but are
616 not identical:
617 hba aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:
619 aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa;
620 hba 55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:
622 55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55;
623 They are equivalent, because half the bits are set to 0, half are set
625 to 1 (0xa and 0x5 are 1010 and 0101 binary respectively) and conse‐
626 quently this would roughly divide the clients equally between the
627 servers. They are not identical, because the actual peers this would
628 load balance to each server are different for each example.
629 You must only have split or hba defined, never both. For most cases,
631 the fine-grained control that hba offers isn't necessary, and split
632 should be used.
633 The load balance max seconds statement
635 load balance max seconds seconds;
637 This statement allows you to configure a cutoff after which load bal‐
639 ancing is disabled. The cutoff is based on the number of seconds
640 since the client sent its first DHCPDISCOVER or DHCPREQUEST message,
641 and only works with clients that correctly implement the secs field -
642 fortunately most clients do. We recommend setting this to something
643 like 3 or 5. The effect of this is that if one of the failover peers
644 gets into a state where it is responding to failover messages but not
645 responding to some client requests, the other failover peer will take
646 over its client load automatically as the clients retry.
647 The auto-partner-down statement
649 auto-partner-down seconds;
651 This statement instructs the server to initiate a timed delay upon
653 entering the communications-interrupted state (any situation of being
654 out-of-contact with the remote failover peer). At the conclusion of
655 the timer, the server will automatically enter the partner-down
656 state. This permits the server to allocate leases from the partner's
657 free lease pool after an STOS+MCLT timer expires, which can be dan‐
658 gerous if the partner is in fact operating at the time (the two
659 servers will give conflicting bindings).
660 Think very carefully before enabling this feature. The partner-down
662 and communications-interrupted states are intentionally segregated
663 because there do exist situations where a failover server can fail to
664 communicate with its peer, but still has the ability to receive and
665 reply to requests from DHCP clients. In general, this feature should
666 only be used in those deployments where the failover servers are
667 directly connected to one another, such as by a dedicated hardwired
668 link ("a heartbeat cable").
669 A zero value disables the auto-partner-down feature (also the
671 default), and any positive value indicates the time in seconds to
672 wait before automatically entering partner-down.
673 The Failover pool balance statements.
675 max-lease-misbalance percentage;
677 max-lease-ownership percentage;
678 min-balance seconds;
679 max-balance seconds;
680 This version of the DHCP Server evaluates pool balance on a schedule,
682 rather than on demand as leases are allocated. The latter approach
683 proved to be slightly klunky when pool misbalanced reach total satu‐
684 ration — when any server ran out of leases to assign, it also lost
685 its ability to notice it had run dry.
686 In order to understand pool balance, some elements of its operation
688 first need to be defined. First, there are ´free´ and ´backup´
689 leases. Both of these are referred to as ´free state leases´.
690 ´free´ and ´backup´ are ´the free states´ for the purpose of this
691 document. The difference is that only the primary may allocate from
692 ´free´ leases unless under special circumstances, and only the sec‐
693 ondary may allocate ´backup´ leases.
694 When pool balance is performed, the only plausible expectation is to
696 provide a 50/50 split of the free state leases between the two
697 servers. This is because no one can predict which server will fail,
698 regardless of the relative load placed upon the two servers, so giv‐
699 ing each server half the leases gives both servers the same amount of
700 ´failure endurance´. Therefore, there is no way to configure any
701 different behaviour, outside of some very small windows we will
702 describe shortly.
703 The first thing calculated on any pool balance run is a value
705 referred to as ´lts´, or "Leases To Send". This, simply, is the dif‐
706 ference in the count of free and backup leases, divided by two. For
707 the secondary, it is the difference in the backup and free leases,
708 divided by two. The resulting value is signed: if it is positive,
709 the local server is expected to hand out leases to retain a 50/50
710 balance. If it is negative, the remote server would need to send
711 leases to balance the pool. Once the lts value reaches zero, the
712 pool is perfectly balanced (give or take one lease in the case of an
713 odd number of total free state leases).
714 The current approach is still something of a hybrid of the old
716 approach, marked by the presence of the max-lease-misbalance state‐
717 ment. This parameter configures what used to be a 10% fixed value in
718 previous versions: if lts is less than free+backup * max-lease-mis‐
719 balance percent, then the server will skip balancing a given pool (it
720 won't bother moving any leases, even if some leases "should" be
721 moved). The meaning of this value is also somewhat overloaded, how‐
722 ever, in that it also governs the estimation of when to attempt to
723 balance the pool (which may then also be skipped over). The oldest
724 leases in the free and backup states are examined. The time they
725 have resided in their respective queues is used as an estimate to
726 indicate how much time it is probable it would take before the leases
727 at the top of the list would be consumed (and thus, how long it would
728 take to use all leases in that state). This percentage is directly
729 multiplied by this time, and fit into the schedule if it falls within
730 the min-balance and max-balance configured values. The scheduled
731 pool check time is only moved in a downwards direction, it is never
732 increased. Lastly, if the lts is more than double this number in the
733 negative direction, the local server will ´panic´ and transmit a
734 Failover protocol POOLREQ message, in the hopes that the remote sys‐
735 tem will be woken up into action.
736 Once the lts value exceeds the max-lease-misbalance percentage of
738 total free state leases as described above, leases are moved to the
739 remote server. This is done in two passes.
740 In the first pass, only leases whose most recent bound client would
742 have been served by the remote server - according to the Load Balance
743 Algorithm (see above split and hba configuration statements) - are
744 given away to the peer. This first pass will happily continue to
745 give away leases, decrementing the lts value by one for each, until
746 the lts value has reached the negative of the total number of leases
747 multiplied by the max-lease-ownership percentage. So it is through
748 this value that you can permit a small misbalance of the lease pools
749 - for the purpose of giving the peer more than a 50/50 share of
750 leases in the hopes that their clients might some day return and be
751 allocated by the peer (operating normally). This process is referred
752 to as ´MAC Address Affinity´, but this is somewhat misnamed: it
753 applies equally to DHCP Client Identifier options. Note also that
754 affinity is applied to leases when they enter the state ´free´ from
755 ´expired´ or ´released´. In this case also, leases will not be moved
756 from free to backup if the secondary already has more than its share.
757 The second pass is only entered into if the first pass fails to
759 reduce the lts underneath the total number of free state leases mul‐
760 tiplied by the max-lease-ownership percentage. In this pass, the
761 oldest leases are given over to the peer without second thought about
762 the Load Balance Algorithm, and this continues until the lts falls
763 under this value. In this way, the local server will also happily
764 keep a small percentage of the leases that would normally load bal‐
765 ance to itself.
766 So, the max-lease-misbalance value acts as a behavioural gate.
768 Smaller values will cause more leases to transition states to balance
769 the pools over time, higher values will decrease the amount of change
770 (but may lead to pool starvation if there's a run on leases).
771 The max-lease-ownership value permits a small (percentage) skew in
773 the lease balance of a percentage of the total number of free state
774 leases.
775 Finally, the min-balance and max-balance make certain that a sched‐
777 uled rebalance event happens within a reasonable timeframe (not to be
778 thrown off by, for example, a 7 year old free lease).
779 Plausible values for the percentages lie between 0 and 100, inclu‐
781 sive, but values over 50 are indistinguishable from one another (once
782 lts exceeds 50% of the free state leases, one server must therefore
783 have 100% of the leases in its respective free state). It is recom‐
784 mended to select a max-lease-ownership value that is lower than the
785 value selected for the max-lease-misbalance value. max-lease-owner‐
786 ship defaults to 10, and max-lease-misbalance defaults to 15.
787 Plausible values for the min-balance and max-balance times also range
789 from 0 to (2^32)-1 (or the limit of your local time_t value), but
790 default to values 60 and 3600 respectively (to place balance events
791 between 1 minute and 1 hour).
792
794 Clients can be separated into classes, and treated differently depend‐
795 ing on what class they are in. This separation can be done either with
796 a conditional statement, or with a match statement within the class
797 declaration. It is possible to specify a limit on the total number of
798 clients within a particular class or subclass that may hold leases at
799 one time, and it is possible to specify automatic subclassing based on
800 the contents of the client packet.
801 Classing support for DHCPv6 clients was added in 4.3.0. It follows the
803 same rules as for DHCPv4 except that support for billing classes has
804 not been added yet.
805 To add clients to classes based on conditional evaluation, you can
807 specify a matching expression in the class statement:
808 class "ras-clients" {
810 match if substring (option dhcp-client-identifier, 1, 3) = "RAS";
811 }
812 Note that whether you use matching expressions or add statements (or
814 both) to classify clients, you must always write a class declaration
815 for any class that you use. If there will be no match statement and no
816 in-scope statements for a class, the declaration should look like this:
817 class "ras-clients" {
819 }
820
822 In addition to classes, it is possible to declare subclasses. A sub‐
823 class is a class with the same name as a regular class, but with a spe‐
824 cific submatch expression which is hashed for quick matching. This is
825 essentially a speed hack - the main difference between five classes
826 with match expressions and one class with five subclasses is that it
827 will be quicker to find the subclasses. Subclasses work as follows:
828 class "allocation-class-1" {
830 match pick-first-value (option dhcp-client-identifier, hardware);
831 }
832 class "allocation-class-2" {
834 match pick-first-value (option dhcp-client-identifier, hardware);
835 }
836 subclass "allocation-class-1" 1:8:0:2b:4c:39:ad;
838 subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3;
839 subclass "allocation-class-1" 1:0:0:c4:aa:29:44;
840 subnet 10.0.0.0 netmask 255.255.255.0 {
842 pool {
843 allow members of "allocation-class-1";
844 range 10.0.0.11 10.0.0.50;
845 }
846 pool {
847 allow members of "allocation-class-2";
848 range 10.0.0.51 10.0.0.100;
849 }
850 }
851 The data following the class name in the subclass declaration is a con‐
853 stant value to use in matching the match expression for the class.
854 When class matching is done, the server will evaluate the match expres‐
855 sion and then look the result up in the hash table. If it finds a
856 match, the client is considered a member of both the class and the sub‐
857 class.
858 Subclasses can be declared with or without scope. In the above exam‐
860 ple, the sole purpose of the subclass is to allow some clients access
861 to one address pool, while other clients are given access to the other
862 pool, so these subclasses are declared without scopes. If part of the
863 purpose of the subclass were to define different parameter values for
864 some clients, you might want to declare some subclasses with scopes.
865 In the above example, if you had a single client that needed some con‐
867 figuration parameters, while most didn't, you might write the following
868 subclass declaration for that client:
869 subclass "allocation-class-2" 1:08:00:2b:a1:11:31 {
871 option root-path "samsara:/var/diskless/alphapc";
872 filename "/tftpboot/netbsd.alphapc-diskless";
873 }
874 In this example, we've used subclassing as a way to control address
876 allocation on a per-client basis. However, it's also possible to use
877 subclassing in ways that are not specific to clients - for example, to
878 use the value of the vendor-class-identifier option to determine what
879 values to send in the vendor-encapsulated-options option. An example
880 of this is shown under the VENDOR ENCAPSULATED OPTIONS head in the
881 dhcp-options(5) manual page.
882
884 You may specify a limit to the number of clients in a class that can be
885 assigned leases. The effect of this will be to make it difficult for a
886 new client in a class to get an address. Once a class with such a
887 limit has reached its limit, the only way a new client in that class
888 can get a lease is for an existing client to relinquish its lease,
889 either by letting it expire, or by sending a DHCPRELEASE packet.
890 Classes with lease limits are specified as follows:
891 class "limited-1" {
893 lease limit 4;
894 }
895 This will produce a class in which a maximum of four members may hold a
897 lease at one time.
898
900 It is possible to declare a spawning class. A spawning class is a
901 class that automatically produces subclasses based on what the client
902 sends. The reason that spawning classes were created was to make it
903 possible to create lease-limited classes on the fly. The envisioned
904 application is a cable-modem environment where the ISP wishes to pro‐
905 vide clients at a particular site with more than one IP address, but
906 does not wish to provide such clients with their own subnet, nor give
907 them an unlimited number of IP addresses from the network segment to
908 which they are connected.
909 Many cable modem head-end systems can be configured to add a Relay
911 Agent Information option to DHCP packets when relaying them to the DHCP
912 server. These systems typically add a circuit ID or remote ID option
913 that uniquely identifies the customer site. To take advantage of this,
914 you can write a class declaration as follows:
915 class "customer" {
917 spawn with option agent.circuit-id;
918 lease limit 4;
919 }
920 Now whenever a request comes in from a customer site, the circuit ID
922 option will be checked against the class´s hash table. If a subclass
923 is found that matches the circuit ID, the client will be classified in
924 that subclass and treated accordingly. If no subclass is found match‐
925 ing the circuit ID, a new one will be created and logged in the
926 dhcpd.leases file, and the client will be classified in this new class.
927 Once the client has been classified, it will be treated according to
928 the rules of the class, including, in this case, being subject to the
929 per-site limit of four leases.
930 The use of the subclass spawning mechanism is not restricted to relay
932 agent options - this particular example is given only because it is a
933 fairly straightforward one.
934
936 In some cases, it may be useful to use one expression to assign a
937 client to a particular class, and a second expression to put it into a
938 subclass of that class. This can be done by combining the match if and
939 spawn with statements, or the match if and match statements. For exam‐
940 ple:
941 class "jr-cable-modems" {
943 match if option dhcp-vendor-identifier = "jrcm";
944 spawn with option agent.circuit-id;
945 lease limit 4;
946 }
947 class "dv-dsl-modems" {
949 match if option dhcp-vendor-identifier = "dvdsl";
950 spawn with option agent.circuit-id;
951 lease limit 16;
952 }
953 This allows you to have two classes that both have the same spawn with
955 expression without getting the clients in the two classes confused with
956 each other.
957
959 The DHCP server has the ability to dynamically update the Domain Name
960 System. Within the configuration files, you can define how you want
961 the Domain Name System to be updated. These updates are RFC 2136 com‐
962 pliant so any DNS server supporting RFC 2136 should be able to accept
963 updates from the DHCP server.
964 There are two DNS schemes implemented. The interim option is based on
966 draft revisions of the DDNS documents while the standard option is
967 based on the RFCs for DHCP-DNS interaction and DHCIDs. A third option,
968 ad-hoc, was deprecated and has now been removed from the code base.
969 The DHCP server must be configured to use one of the two currently-sup‐
970 ported methods, or not to do DNS updates.
971 New installations should use the standard option. Older installations
973 may want to continue using the interim option for backwards compatibil‐
974 ity with the DNS database until the database can be updated. This can
975 be done with the ddns-update-style configuration parameter.
976
978 the interim and standard DNS update schemes operate mostly according to
979 work from the IETF. The interim version was based on the drafts in
980 progress at the time while the standard is based on the completed RFCs.
981 The standard RFCs are:
982 RFC 4701 (updated by RF5494)
984 RFC 4702
985 RFC 4703
986 And the corresponding drafts were:
988 draft-ietf-dnsext-dhcid-rr-??.txt
990 draft-ietf-dhc-fqdn-option-??.txt
991 draft-ietf-dhc-ddns-resolution-??.txt
992 The basic framework for the two schemes is similar with the main mate‐
994 rial difference being that a DHCID RR is used in the standard version
995 while the interim versions uses a TXT RR. The format of the TXT record
996 bears a resemblance to the DHCID RR but it is not equivalent (MD5 vs
997 SHA2, field length differences etc).
998 In these two schemes the DHCP server does not necessarily always update
1000 both the A and the PTR records. The FQDN option includes a flag which,
1001 when sent by the client, indicates that the client wishes to update its
1002 own A record. In that case, the server can be configured either to
1003 honor the client´s intentions or ignore them. This is done with the
1004 statement allow client-updates; or the statement ignore client-
1005 updates;. By default, client updates are allowed.
1006 If the server is configured to allow client updates, then if the client
1008 sends a fully-qualified domain name in the FQDN option, the server will
1009 use that name the client sent in the FQDN option to update the PTR
1010 record. For example, let us say that the client is a visitor from the
1011 "radish.org" domain, whose hostname is "jschmoe". The server is for
1012 the "example.org" domain. The DHCP client indicates in the FQDN option
1013 that its FQDN is "jschmoe.radish.org.". It also indicates that it
1014 wants to update its own A record. The DHCP server therefore does not
1015 attempt to set up an A record for the client, but does set up a PTR
1016 record for the IP address that it assigns the client, pointing at
1017 jschmoe.radish.org. Once the DHCP client has an IP address, it can
1018 update its own A record, assuming that the "radish.org" DNS server will
1019 allow it to do so.
1020 If the server is configured not to allow client updates, or if the
1022 client doesn´t want to do its own update, the server will simply choose
1023 a name for the client. By default, the server will choose from the fol‐
1024 lowing three values:
1025 1. fqdn option (if present)
1027 2. hostname option (if present)
1028 3. Configured hostname option (if defined).
1029 If these defaults for choosing the host name are not appropriate you
1031 can write your own statement to set the ddns-hostname variable as you
1032 wish. If none of the above are found the server will use the host dec‐
1033 laration name (if one) and use-host-decl-names is on.
1034 It will use its own domain name for the client. It will then update
1036 both the A and PTR record, using the name that it chose for the client.
1037 If the client sends a fully-qualified domain name in the fqdn option,
1038 the server uses only the leftmost part of the domain name - in the
1039 example above, "jschmoe" instead of "jschmoe.radish.org".
1040 Further, if the ignore client-updates; directive is used, then the
1042 server will in addition send a response in the DHCP packet, using the
1043 FQDN Option, that implies to the client that it should perform its own
1044 updates if it chooses to do so. With deny client-updates;, a response
1045 is sent which indicates the client may not perform updates.
1046 Both the standard and interim options also include a method to allow
1048 more than one DHCP server to update the DNS database without acciden‐
1049 tally deleting A records that shouldn´t be deleted nor failing to add A
1050 records that should be added. For the standard option the method works
1051 as follows:
1052 When the DHCP server issues a client a new lease, it creates a text
1054 string that is an SHA hash over the DHCP client´s identification (see
1055 RFCs 4701 & 4702 for details). The update attempts to add an A record
1056 with the name the server chose and a DHCID record containing the hashed
1057 identifier string (hashid). If this update succeeds, the server is
1058 done.
1059 If the update fails because the A record already exists, then the DHCP
1061 server attempts to add the A record with the prerequisite that there
1062 must be a DHCID record in the same name as the new A record, and that
1063 DHCID record´s contents must be equal to hashid. If this update suc‐
1064 ceeds, then the client has its A record and PTR record. If it fails,
1065 then the name the client has been assigned (or requested) is in use,
1066 and can´t be used by the client. At this point the DHCP server gives
1067 up trying to do a DNS update for the client until the client chooses a
1068 new name.
1069 The server also does not update very aggressively. Because each DNS
1071 update involves a round trip to the DNS server, there is a cost associ‐
1072 ated with doing updates even if they do not actually modify the DNS
1073 database. So the DHCP server tracks whether or not it has updated the
1074 record in the past (this information is stored on the lease) and does
1075 not attempt to update records that it thinks it has already updated.
1076 This can lead to cases where the DHCP server adds a record, and then
1078 the record is deleted through some other mechanism, but the server
1079 never again updates the DNS because it thinks the data is already
1080 there. In this case the data can be removed from the lease through
1081 operator intervention, and once this has been done, the DNS will be
1082 updated the next time the client renews.
1083 The interim DNS update scheme was written before the RFCs were final‐
1085 ized and does not quite follow them. The RFCs call for a new DHCID
1086 RRtype while the interim DNS update scheme uses a TXT record. In addi‐
1087 tion the ddns-resolution draft called for the DHCP server to put a
1088 DHCID RR on the PTR record, but the interim update method does not do
1089 this. In the final RFC this requirement was relaxed such that a server
1090 may add a DHCID RR to the PTR record.
1091
1093 When you set your DNS server up to allow updates from the DHCP server,
1094 you may be exposing it to unauthorized updates. To avoid this, you
1095 should use TSIG signatures - a method of cryptographically signing
1096 updates using a shared secret key. As long as you protect the secrecy
1097 of this key, your updates should also be secure. Note, however, that
1098 the DHCP protocol itself provides no security, and that clients can
1099 therefore provide information to the DHCP server which the DHCP server
1100 will then use in its updates, with the constraints described previ‐
1101 ously.
1102 The DNS server must be configured to allow updates for any zone that
1104 the DHCP server will be updating. For example, let us say that clients
1105 in the sneedville.edu domain will be assigned addresses on the
1106 10.10.17.0/24 subnet. In that case, you will need a key declaration
1107 for the TSIG key you will be using, and also two zone declarations -
1108 one for the zone containing A records that will be updates and one for
1109 the zone containing PTR records - for ISC BIND, something like this:
1110 key DHCP_UPDATER {
1112 algorithm hmac-md5;
1113 secret pRP5FapFoJ95JEL06sv4PQ==;
1114 };
1115 zone "example.org" {
1117 type master;
1118 file "example.org.db";
1119 allow-update { key DHCP_UPDATER; };
1120 };
1121 zone "17.10.10.in-addr.arpa" {
1123 type master;
1124 file "10.10.17.db";
1125 allow-update { key DHCP_UPDATER; };
1126 };
1127 You will also have to configure your DHCP server to do updates to these
1129 zones. To do so, you need to add something like this to your
1130 dhcpd.conf file:
1131 key DHCP_UPDATER {
1133 algorithm hmac-md5;
1134 secret pRP5FapFoJ95JEL06sv4PQ==;
1135 };
1136 zone EXAMPLE.ORG. {
1138 primary 127.0.0.1;
1139 key DHCP_UPDATER;
1140 }
1141 zone 17.127.10.in-addr.arpa. {
1143 primary 127.0.0.1;
1144 key DHCP_UPDATER;
1145 }
1146 The primary statement specifies the IP address of the name server whose
1148 zone information is to be updated. In addition to the primary state‐
1149 ment there are also the primary6 , secondary and secondary6 statements.
1150 The primary6 statement specifies an IPv6 address for the name server.
1151 The secondaries provide for additional addresses for name servers to be
1152 used if the primary does not respond. The number of name servers the
1153 DDNS code will attempt to use before giving up is limited and is cur‐
1154 rently set to three.
1155 Note that the zone declarations have to correspond to authority records
1157 in your name server - in the above example, there must be an SOA record
1158 for "example.org." and for "17.10.10.in-addr.arpa.". For example, if
1159 there were a subdomain "foo.example.org" with no separate SOA, you
1160 could not write a zone declaration for "foo.example.org." Also keep in
1161 mind that zone names in your DHCP configuration should end in a ".";
1162 this is the preferred syntax. If you do not end your zone name in a
1163 ".", the DHCP server will figure it out. Also note that in the DHCP
1164 configuration, zone names are not encapsulated in quotes where there
1165 are in the DNS configuration.
1166 You should choose your own secret key, of course. The ISC BIND 9 dis‐
1168 tribution comes with a program for generating secret keys called
1169 dnssec-keygen. If you are using BIND 9´s dnssec-keygen, the above key
1170 would be created as follows:
1171 dnssec-keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER
1173 The key name, algorithm, and secret must match that being used by the
1175 DNS server. The DHCP server currently supports the following algo‐
1176 rithms:
1177 HMAC-MD5
1179 HMAC-SHA1
1180 HMAC-SHA224
1181 HMAC-SHA256
1182 HMAC-SHA384
1183 HMAC-SHA512
1184 You may wish to enable logging of DNS updates on your DNS server. To
1186 do so, you might write a logging statement like the following:
1187 logging {
1189 channel update_debug {
1190 file "/var/log/update-debug.log";
1191 severity debug 3;
1192 print-category yes;
1193 print-severity yes;
1194 print-time yes;
1195 };
1196 channel security_info {
1197 file "/var/log/named-auth.info";
1198 severity info;
1199 print-category yes;
1200 print-severity yes;
1201 print-time yes;
1202 };
1203 category update { update_debug; };
1205 category security { security_info; };
1206 };
1207 You must create the /var/log/named-auth.info and /var/log/update-
1209 debug.log files before starting the name server. For more information
1210 on configuring ISC BIND, consult the documentation that accompanies it.
1211
1213 There are three kinds of events that can happen regarding a lease, and
1214 it is possible to declare statements that occur when any of these
1215 events happen. These events are the commit event, when the server has
1216 made a commitment of a certain lease to a client, the release event,
1217 when the client has released the server from its commitment, and the
1218 expiry event, when the commitment expires.
1219 To declare a set of statements to execute when an event happens, you
1221 must use the on statement, followed by the name of the event, followed
1222 by a series of statements to execute when the event happens, enclosed
1223 in braces.
1224
1226 The include statement
1227 include "filename";
1229 The include statement is used to read in a named file, and process the
1231 contents of that file as though it were entered in place of the include
1232 statement.
1233 The shared-network statement
1235 shared-network name {
1237 [ parameters ]
1238 [ declarations ]
1239 }
1240 The shared-network statement is used to inform the DHCP server that
1242 some IP subnets actually share the same physical network. Any subnets
1243 in a shared network should be declared within a shared-network state‐
1244 ment. Parameters specified in the shared-network statement will be
1245 used when booting clients on those subnets unless parameters provided
1246 at the subnet or host level override them. If any subnet in a shared
1247 network has addresses available for dynamic allocation, those addresses
1248 are collected into a common pool for that shared network and assigned
1249 to clients as needed. There is no way to distinguish on which subnet
1250 of a shared network a client should boot.
1251 Name should be the name of the shared network. This name is used when
1253 printing debugging messages, so it should be descriptive for the shared
1254 network. The name may have the syntax of a valid domain name (although
1255 it will never be used as such), or it may be any arbitrary name,
1256 enclosed in quotes.
1257 The subnet statement
1259 subnet subnet-number netmask netmask {
1261 [ parameters ]
1262 [ declarations ]
1263 }
1264 The subnet statement is used to provide dhcpd with enough information
1266 to tell whether or not an IP address is on that subnet. It may also be
1267 used to provide subnet-specific parameters and to specify what
1268 addresses may be dynamically allocated to clients booting on that sub‐
1269 net. Such addresses are specified using the range declaration.
1270 The subnet-number should be an IP address or domain name which resolves
1272 to the subnet number of the subnet being described. The netmask should
1273 be an IP address or domain name which resolves to the subnet mask of
1274 the subnet being described. The subnet number, together with the net‐
1275 mask, are sufficient to determine whether any given IP address is on
1276 the specified subnet.
1277 Although a netmask must be given with every subnet declaration, it is
1279 recommended that if there is any variance in subnet masks at a site, a
1280 subnet-mask option statement be used in each subnet declaration to set
1281 the desired subnet mask, since any subnet-mask option statement will
1282 override the subnet mask declared in the subnet statement.
1283 The subnet6 statement
1285 subnet6 subnet6-number {
1287 [ parameters ]
1288 [ declarations ]
1289 }
1290 The subnet6 statement is used to provide dhcpd with enough information
1292 to tell whether or not an IPv6 address is on that subnet6. It may also
1293 be used to provide subnet-specific parameters and to specify what
1294 addresses may be dynamically allocated to clients booting on that sub‐
1295 net.
1296 The subnet6-number should be an IPv6 network identifier, specified as
1298 ip6-address/bits.
1299 The range statement
1301 range [ dynamic-bootp ] low-address [ high-address];
1303 For any subnet on which addresses will be assigned dynamically, there
1305 must be at least one range statement. The range statement gives the
1306 lowest and highest IP addresses in a range. All IP addresses in the
1307 range should be in the subnet in which the range statement is declared.
1308 The dynamic-bootp flag may be specified if addresses in the specified
1309 range may be dynamically assigned to BOOTP clients as well as DHCP
1310 clients. When specifying a single address, high-address can be omit‐
1311 ted.
1312 The range6 statement
1314 range6 low-address high-address;
1316 range6 subnet6-number;
1317 range6 subnet6-number temporary;
1318 range6 address temporary;
1319 For any IPv6 subnet6 on which addresses will be assigned dynamically,
1321 there must be at least one range6 statement. The range6 statement can
1322 either be the lowest and highest IPv6 addresses in a range6, or use
1323 CIDR notation, specified as ip6-address/bits. All IP addresses in the
1324 range6 should be in the subnet6 in which the range6 statement is
1325 declared.
1326 The temporary variant makes the prefix (by default on 64 bits) avail‐
1328 able for temporary (RFC 4941) addresses. A new address per prefix in
1329 the shared network is computed at each request with an IA_TA option.
1330 Release and Confirm ignores temporary addresses.
1331 Any IPv6 addresses given to hosts with fixed-address6 are excluded from
1333 the range6, as are IPv6 addresses on the server itself.
1334 The prefix6 statement
1336 prefix6 low-address high-address / bits;
1338 The prefix6 is the range6 equivalent for Prefix Delegation (RFC 3633).
1340 Prefixes of bits length are assigned between low-address and high-
1341 address.
1342 Any IPv6 prefixes given to static entries (hosts) with fixed-prefix6
1344 are excluded from the prefix6.
1345 This statement is currently global but it should have a shared-network
1347 scope.
1348 The host statement
1350 host hostname {
1352 [ parameters ]
1353 [ declarations ]
1354 }
1355 The host declaration provides a way for the DHCP server to identify a
1357 DHCP or BOOTP client. This allows the server to provide configuration
1358 information including fixed addresses or, in DHCPv6, fixed prefixes for
1359 a specific client.
1360 If it is desirable to be able to boot a DHCP or BOOTP client on more
1362 than one subnet with fixed v4 addresses, more than one address may be
1363 specified in the fixed-address declaration, or more than one host
1364 statement may be specified matching the same client.
1365 The fixed-address6 declaration is used for v6 addresses. At this time
1367 it only works with a single address. For multiple addresses specify
1368 multiple host statements.
1369 If client-specific boot parameters must change based on the network to
1371 which the client is attached, then multiple host declarations should be
1372 used. The host declarations will only match a client if one of their
1373 fixed-address statements is viable on the subnet (or shared network)
1374 where the client is attached. Conversely, for a host declaration to
1375 match a client being allocated a dynamic address, it must not have any
1376 fixed-address statements. You may therefore need a mixture of host
1377 declarations for any given client...some having fixed-address state‐
1378 ments, others without.
1379 hostname should be a name identifying the host. If a hostname option
1381 is not specified for the host, hostname is used.
1382 Host declarations are matched to actual DHCP or BOOTP clients by match‐
1384 ing the dhcp-client-identifier or pxe-client-id options specified in
1385 the host declaration to the one supplied by the client, or, if the host
1386 declaration or the client does not provide a dhcp-client-identifier or
1387 pxe-client-id options, by matching the hardware parameter in the host
1388 declaration to the network hardware address supplied by the client.
1389 BOOTP clients do not normally provide a dhcp-client-identifier, so the
1390 hardware address must be used for all clients that may boot using the
1391 BOOTP protocol.
1392 DHCPv6 servers can use the host-identifier option parameter in the host
1394 declaration, and specify any option with a fixed value to identify
1395 hosts.
1396 Please be aware that only the dhcp-client-identifier and pxe-client-id
1398 options and the hardware address can be used to match a host declara‐
1399 tion, or the host-identifier option parameter for DHCPv6 servers. For
1400 example, it is not possible to match a host declaration to a host-name
1401 option. This is because the host-name option cannot be guaranteed to
1402 be unique for any given client, whereas both the hardware address and
1403 dhcp-client-identifier option are at least theoretically guaranteed to
1404 be unique to a given client.
1405 The group statement
1407 group {
1409 [ parameters ]
1410 [ declarations ]
1411 }
1412 The group statement is used simply to apply one or more parameters to a
1414 group of declarations. It can be used to group hosts, shared networks,
1415 subnets, or even other groups.
1416
1418 The allow and deny statements can be used to control the response of
1419 the DHCP server to various sorts of requests. The allow and deny key‐
1420 words actually have different meanings depending on the context. In a
1421 pool context, these keywords can be used to set up access lists for
1422 address allocation pools. In other contexts, the keywords simply con‐
1423 trol general server behavior with respect to clients based on scope.
1424 In a non-pool context, the ignore keyword can be used in place of the
1425 deny keyword to prevent logging of denied requests.
1426
1428 The following usages of allow and deny will work in any scope, although
1429 it is not recommended that they be used in pool declarations.
1430 The unknown-clients keyword
1432 allow unknown-clients;
1434 deny unknown-clients;
1435 ignore unknown-clients;
1436 The unknown-clients flag is used to tell dhcpd whether or not to dynam‐
1438 ically assign addresses to unknown clients. Dynamic address assignment
1439 to unknown clients is allowed by default. An unknown client is simply
1440 a client that has no host declaration.
1441 The use of this option is now deprecated. If you are trying to
1443 restrict access on your network to known clients, you should use deny
1444 unknown-clients; inside of your address pool, as described under the
1445 heading ALLOW AND DENY WITHIN POOL DECLARATIONS.
1446 The bootp keyword
1448 allow bootp;
1450 deny bootp;
1451 ignore bootp;
1452 The bootp flag is used to tell dhcpd whether or not to respond to bootp
1454 queries. Bootp queries are allowed by default.
1455 The booting keyword
1457 allow booting;
1459 deny booting;
1460 ignore booting;
1461 The booting flag is used to tell dhcpd whether or not to respond to
1463 queries from a particular client. This keyword only has meaning when
1464 it appears in a host declaration. By default, booting is allowed, but
1465 if it is disabled for a particular client, then that client will not be
1466 able to get an address from the DHCP server.
1467 The duplicates keyword
1469 allow duplicates;
1471 deny duplicates;
1472 Host declarations can match client messages based on the DHCP Client
1474 Identifier option or based on the client's network hardware type and
1475 MAC address. If the MAC address is used, the host declaration will
1476 match any client with that MAC address - even clients with different
1477 client identifiers. This doesn't normally happen, but is possible when
1478 one computer has more than one operating system installed on it - for
1479 example, Microsoft Windows and NetBSD or Linux.
1480 The duplicates flag tells the DHCP server that if a request is received
1482 from a client that matches the MAC address of a host declaration, any
1483 other leases matching that MAC address should be discarded by the
1484 server, even if the UID is not the same. This is a violation of the
1485 DHCP protocol, but can prevent clients whose client identifiers change
1486 regularly from holding many leases at the same time. By default,
1487 duplicates are allowed.
1488 The declines keyword
1490 allow declines;
1492 deny declines;
1493 ignore declines;
1494 The DHCPDECLINE message is used by DHCP clients to indicate that the
1496 lease the server has offered is not valid. When the server receives a
1497 DHCPDECLINE for a particular address, it normally abandons that
1498 address, assuming that some unauthorized system is using it. Unfortu‐
1499 nately, a malicious or buggy client can, using DHCPDECLINE messages,
1500 completely exhaust the DHCP server's allocation pool. The server will
1501 eventually reclaim these leases, but not while the client is running
1502 through the pool. This may cause serious thrashing in the DNS, and it
1503 will also cause the DHCP server to forget old DHCP client address allo‐
1504 cations.
1505 The declines flag tells the DHCP server whether or not to honor DHCPDE‐
1507 CLINE messages. If it is set to deny or ignore in a particular scope,
1508 the DHCP server will not respond to DHCPDECLINE messages.
1509 The declines flag is only supported by DHCPv4 servers. Given the large
1511 IPv6 address space and the internal limits imposed by the server's
1512 address generation mechanism we don't think it is necessary for DHCPv6
1513 servers at this time.
1514 Currently, abandoned IPv6 addresses are reclaimed in one of two ways:
1516 a) Client renews a specific address:
1517 If a client using a given DUID submits a DHCP REQUEST containing
1518 the last address abandoned by that DUID, the address will be
1519 reassigned to that client.
1520 b) Upon the second restart following an address abandonment. When
1522 an address is abandoned it is both recorded as such in the lease
1523 file and retained as abandoned in server memory until the server
1524 is restarted. Upon restart, the server will process the lease file
1525 and all addresses whose last known state is abandoned will be
1526 retained as such in memory but not rewritten to the lease file.
1527 This means that a subsequent restart of the server will not see the
1528 abandoned addresses in the lease file and therefore have no record
1529 of them as abandoned in memory and as such perceive them as free
1530 for assignment.
1531 The total number addresses in a pool, available for a given DUID value,
1533 is internally limited by the server's address generation mechanism. If
1534 through mistaken configuration, multiple clients are using the same
1535 DUID they will competing for the same addresses causing the server to
1536 reach this internal limit rather quickly. The internal limit isolates
1537 this type of activity such that address range is not exhausted for
1538 other DUID values. The appearance of the following error log, can be
1539 an indication of this condition:
1540 "Best match for DUID <XX> is an abandoned address, This may be a
1542 result of multiple clients attempting to use this DUID"
1543 where <XX> is an actual DUID value depicted as colon separated
1545 string of bytes in hexadecimal values.
1546 The client-updates keyword
1548 allow client-updates;
1550 deny client-updates;
1551 The client-updates flag tells the DHCP server whether or not to honor
1553 the client's intention to do its own update of its A record. See the
1554 documentation under the heading THE DNS UPDATE SCHEME for details.
1555 The leasequery keyword
1557 allow leasequery;
1559 deny leasequery;
1560 The leasequery flag tells the DHCP server whether or not to answer DHC‐
1562 PLEASEQUERY packets. The answer to a DHCPLEASEQUERY packet includes
1563 information about a specific lease, such as when it was issued and when
1564 it will expire. By default, the server will not respond to these pack‐
1565 ets.
1566
1568 The uses of the allow and deny keywords shown in the previous section
1569 work pretty much the same way whether the client is sending a DHCPDIS‐
1570 COVER or a DHCPREQUEST message - an address will be allocated to the
1571 client (either the old address it's requesting, or a new address) and
1572 then that address will be tested to see if it's okay to let the client
1573 have it. If the client requested it, and it's not okay, the server
1574 will send a DHCPNAK message. Otherwise, the server will simply not
1575 respond to the client. If it is okay to give the address to the
1576 client, the server will send a DHCPACK message.
1577 The primary motivation behind pool declarations is to have address
1579 allocation pools whose allocation policies are different. A client may
1580 be denied access to one pool, but allowed access to another pool on the
1581 same network segment. In order for this to work, access control has to
1582 be done during address allocation, not after address allocation is
1583 done.
1584 When a DHCPREQUEST message is processed, address allocation simply con‐
1586 sists of looking up the address the client is requesting and seeing if
1587 it's still available for the client. If it is, then the DHCP server
1588 checks both the address pool permit lists and the relevant in-scope
1589 allow and deny statements to see if it's okay to give the lease to the
1590 client. In the case of a DHCPDISCOVER message, the allocation process
1591 is done as described previously in the ADDRESS ALLOCATION section.
1592 When declaring permit lists for address allocation pools, the following
1594 syntaxes are recognized following the allow or deny keywords:
1595 known-clients;
1597 If specified, this statement either allows or prevents allocation from
1599 this pool to any client that has a host declaration (i.e., is known).
1600 A client is known if it has a host declaration in any scope, not just
1601 the current scope.
1602 unknown-clients;
1604 If specified, this statement either allows or prevents allocation from
1606 this pool to any client that has no host declaration (i.e., is not
1607 known).
1608 members of "class";
1610 If specified, this statement either allows or prevents allocation from
1612 this pool to any client that is a member of the named class.
1613 dynamic bootp clients;
1615 If specified, this statement either allows or prevents allocation from
1617 this pool to any bootp client.
1618 authenticated clients;
1620 If specified, this statement either allows or prevents allocation from
1622 this pool to any client that has been authenticated using the DHCP
1623 authentication protocol. This is not yet supported.
1624 unauthenticated clients;
1626 If specified, this statement either allows or prevents allocation from
1628 this pool to any client that has not been authenticated using the DHCP
1629 authentication protocol. This is not yet supported.
1630 all clients;
1632 If specified, this statement either allows or prevents allocation from
1634 this pool to all clients. This can be used when you want to write a
1635 pool declaration for some reason, but hold it in reserve, or when you
1636 want to renumber your network quickly, and thus want the server to
1637 force all clients that have been allocated addresses from this pool to
1638 obtain new addresses immediately when they next renew.
1639 after time;
1641 If specified, this statement either allows or prevents allocation from
1643 this pool after a given date. This can be used when you want to move
1644 clients from one pool to another. The server adjusts the regular lease
1645 time so that the latest expiry time is at the given time+min-lease-
1646 time. A short min-lease-time enforces a step change, whereas a longer
1647 min-lease-time allows for a gradual change. time is either second
1648 since epoch, or a UTC time string e.g. 4 2007/08/24 09:14:32 or a
1649 string with time zone offset in seconds e.g. 4 2007/08/24 11:14:32
1650 -7200
1651
1653 The abandon-lease-time statement
1654 adandon-lease-time time;
1656 Time should be the maximum amount of time (in seconds) that an aban‐
1658 doned IPv4 lease remains unavailable for assignment to a client.
1659 Abandoned leases will only be offered to clients if there are no free
1660 leases. If not defined, the default abandon lease time is 86400 sec‐
1661 onds (24 hours). Note the abandoned lease time for a given lease is
1662 preserved across server restarts. The parameter may only be set at
1663 the global scope and is evaluated only once during server startup.
1664 Values less than sixty seconds are not recommended as this is below
1666 the ping check threshold and can cause leases once abandoned but
1667 since returned to the free state to not be pinged before being
1668 offered. If the requested time is larger than 0x7FFFFFFF - 1 or the
1669 sum of the current time plus the abandoned time isgreater than
1670 0x7FFFFFFF it is treated as infinite.
1671 The adaptive-lease-time-threshold statement
1673 adaptive-lease-time-threshold percentage;
1675 When the number of allocated leases within a pool rises above the
1677 percentage given in this statement, the DHCP server decreases the
1678 lease length for new clients within this pool to min-lease-time sec‐
1679 onds. Clients renewing an already valid (long) leases get at least
1680 the remaining time from the current lease. Since the leases expire
1681 faster, the server may either recover more quickly or avoid pool
1682 exhaustion entirely. Once the number of allocated leases drop below
1683 the threshold, the server reverts back to normal lease times. Valid
1684 percentages are between 1 and 99.
1685 The always-broadcast statement
1687 always-broadcast flag;
1689 The DHCP and BOOTP protocols both require DHCP and BOOTP clients to
1691 set the broadcast bit in the flags field of the BOOTP message header.
1692 Unfortunately, some DHCP and BOOTP clients do not do this, and there‐
1693 fore may not receive responses from the DHCP server. The DHCP server
1694 can be made to always broadcast its responses to clients by setting
1695 this flag to ´on´ for the relevant scope; relevant scopes would be
1696 inside a conditional statement, as a parameter for a class, or as a
1697 parameter for a host declaration. To avoid creating excess broadcast
1698 traffic on your network, we recommend that you restrict the use of
1699 this option to as few clients as possible. For example, the Micro‐
1700 soft DHCP client is known not to have this problem, as are the Open‐
1701 Transport and ISC DHCP clients.
1702 The always-reply-rfc1048 statement
1704 always-reply-rfc1048 flag;
1706 Some BOOTP clients expect RFC1048-style responses, but do not follow
1708 RFC1048 when sending their requests. You can tell that a client is
1709 having this problem if it is not getting the options you have config‐
1710 ured for it and if you see in the server log the message "(non-
1711 rfc1048)" printed with each BOOTREQUEST that is logged.
1712 If you want to send rfc1048 options to such a client, you can set the
1714 always-reply-rfc1048 option in that client's host declaration, and
1715 the DHCP server will respond with an RFC-1048-style vendor options
1716 field. This flag can be set in any scope, and will affect all
1717 clients covered by that scope.
1718 The authoritative statement
1720 authoritative;
1722 not authoritative;
1724 The DHCP server will normally assume that the configuration informa‐
1726 tion about a given network segment is not known to be correct and is
1727 not authoritative. This is so that if a naive user installs a DHCP
1728 server not fully understanding how to configure it, it does not send
1729 spurious DHCPNAK messages to clients that have obtained addresses
1730 from a legitimate DHCP server on the network.
1731 Network administrators setting up authoritative DHCP servers for
1733 their networks should always write authoritative; at the top of their
1734 configuration file to indicate that the DHCP server should send DHCP‐
1735 NAK messages to misconfigured clients. If this is not done, clients
1736 will be unable to get a correct IP address after changing subnets
1737 until their old lease has expired, which could take quite a long
1738 time.
1739 Usually, writing authoritative; at the top level of the file should
1741 be sufficient. However, if a DHCP server is to be set up so that it
1742 is aware of some networks for which it is authoritative and some net‐
1743 works for which it is not, it may be more appropriate to declare
1744 authority on a per-network-segment basis.
1745 Note that the most specific scope for which the concept of authority
1747 makes any sense is the physical network segment - either a shared-
1748 network statement or a subnet statement that is not contained within
1749 a shared-network statement. It is not meaningful to specify that the
1750 server is authoritative for some subnets within a shared network, but
1751 not authoritative for others, nor is it meaningful to specify that
1752 the server is authoritative for some host declarations and not oth‐
1753 ers.
1754 The boot-unknown-clients statement
1756 boot-unknown-clients flag;
1758 If the boot-unknown-clients statement is present and has a value of
1760 false or off, then clients for which there is no host declaration
1761 will not be allowed to obtain IP addresses. If this statement is not
1762 present or has a value of true or on, then clients without host dec‐
1763 larations will be allowed to obtain IP addresses, as long as those
1764 addresses are not restricted by allow and deny statements within
1765 their pool declarations.
1766 The db-time-format statement
1768 db-time-format [ default | local ] ;
1770 The DHCP server software outputs several timestamps when writing
1772 leases to persistent storage. This configuration parameter selects
1773 one of two output formats. The default format prints the day, date,
1774 and time in UTC, while the local format prints the system seconds-
1775 since-epoch, and helpfully provides the day and time in the system
1776 timezone in a comment. The time formats are described in detail in
1777 the dhcpd.leases(5) manpage.
1778 The ddns-hostname statement
1780 ddns-hostname name;
1782 The name parameter should be the hostname that will be used in set‐
1784 ting up the client's A and PTR records. If no ddns-hostname is spec‐
1785 ified in scope, then the server will derive the hostname automati‐
1786 cally, using an algorithm that varies for each of the different
1787 update methods.
1788 The ddns-domainname statement
1790 ddns-domainname name;
1792 The name parameter should be the domain name that will be appended to
1794 the client's hostname to form a fully-qualified domain-name (FQDN).
1795 The dns-local-address4 and dns-local-address6 statements
1797 ddns-local-address4 address;
1799 ddns-local-address6 address;
1801 The address parameter should be the local IPv4 or IPv6 address the
1803 server should use as the from address when sending DDNS update
1804 requests.
1805 The ddns-rev-domainname statement
1807 ddns-rev-domainname name;
1809 The name parameter should be the domain name that will be appended to
1811 the client's reversed IP address to produce a name for use in the
1812 client's PTR record. By default, this is "in-addr.arpa.", but the
1813 default can be overridden here.
1814 The reversed IP address to which this domain name is appended is
1816 always the IP address of the client, in dotted quad notation,
1817 reversed - for example, if the IP address assigned to the client is
1818 10.17.92.74, then the reversed IP address is 74.92.17.10. So a
1819 client with that IP address would, by default, be given a PTR record
1820 of 10.17.92.74.in-addr.arpa.
1821 The ddns-update-style parameter
1823 ddns-update-style style;
1825 The style parameter must be one of standard, interim or none. The
1827 ddns-update-style statement is only meaningful in the outer scope -
1828 it is evaluated once after reading the dhcpd.conf file, rather than
1829 each time a client is assigned an IP address, so there is no way to
1830 use different DNS update styles for different clients. The default is
1831 none.
1832 The ddns-updates statement
1834 ddns-updates flag;
1836 The ddns-updates parameter controls whether or not the server will
1838 attempt to do a DNS update when a lease is confirmed. Set this to
1839 off if the server should not attempt to do updates within a certain
1840 scope. The ddns-updates parameter is on by default. To disable DNS
1841 updates in all scopes, it is preferable to use the ddns-update-style
1842 statement, setting the style to none.
1843 The default-lease-time statement
1845 default-lease-time time;
1847 Time should be the length in seconds that will be assigned to a lease
1849 if the client requesting the lease does not ask for a specific expi‐
1850 ration time. This is used for both DHCPv4 and DHCPv6 leases (it is
1851 also known as the "valid lifetime" in DHCPv6). The default is 43200
1852 seconds.
1853 The delayed-ack and max-ack-delay statements
1855 delayed-ack count;
1857 max-ack-delay microseconds;
1859 Count should be an integer value from zero to 2^16-1, and defaults to
1861 28. The count represents how many DHCPv4 replies maximum will be
1862 queued pending transmission until after a database commit event. If
1863 this number is reached, a database commit event (commonly resulting
1864 in fsync() and representing a performance penalty) will be made, and
1865 the reply packets will be transmitted in a batch afterwards. This
1866 preserves the RFC2131 direction that "stable storage" be updated
1867 prior to replying to clients. Should the DHCPv4 sockets "go dry"
1868 (select() returns immediately with no read sockets), the commit is
1869 made and any queued packets are transmitted.
1870 Similarly, microseconds indicates how many microseconds are permitted
1872 to pass inbetween queuing a packet pending an fsync, and performing
1873 the fsync. Valid values range from 0 to 2^32-1, and defaults to
1874 250,000 (1/4 of a second).
1875 The delayed-ack feature is not compiled in by default, but must be
1877 enabled at compile time with ´./configure --enable-delayed-ack´.
1878 While we no longer consider it experimental and we don't know of any
1879 issues with it, in order to minimize problems with existing configu‐
1880 ration files we have left it disabled by default.
1881 The dhcp-cache-threshold statement
1883 dhcp-cache-threshold percentage;
1885 The dhcp-cache-threshold statement takes one integer parameter with
1887 allowed values between 0 and 100. The default value is 25 (25% of the
1888 lease time). This parameter expresses the percentage of the total
1889 lease time, measured from the beginning, during which a client's
1890 attempt to renew its lease will result in getting the already
1891 assigned lease, rather than an extended lease.
1892 Clients that attempt renewal frequently can cause the server to
1894 update and write the database frequently resulting in a performance
1895 impact on the server. The dhcp-cache-threshold statement instructs
1896 the DHCP server to avoid updating leases too frequently thus avoiding
1897 this behavior. Instead the server assigns the same lease (i.e.
1898 reuses it) with no modifications except for CLTT (Client Last Trans‐
1899 mission Time) which does not require disk operations. This feature
1900 applies to IPv4 only.
1901 When an existing lease is matched to a renewing client, it will be
1903 reused if all of the following conditions are true:
1904 1. The dhcp-cache-threshold is larger than zero
1905 2. The current lease is active
1906 3. The percentage of the lease time that has elapsed is less than
1907 dhcp-cache-threshold
1908 4. The client information provided in the renewal does not alter
1909 any of the following:
1910 a. DNS information and DNS updates are enabled
1911 b. Billing class to which the lease is associated
1912 c. The host declaration associated with the lease
1913 d. The client id - this may happen if a client boots without
1914 a client id and then starts using one in subsequent requests.
1915 Note that the lease can be reused if the options the client or relay
1917 agent sends are changed. These changes will not be recorded in the
1918 in-memory or on-disk databases until the client renews after the
1919 threshold time is reached.
1920 The do-forward-updates statement
1922 do-forward-updates flag;
1924 The do-forward-updates statement instructs the DHCP server as to
1926 whether it should attempt to update a DHCP client´s A record when the
1927 client acquires or renews a lease. This statement has no effect
1928 unless DNS updates are enabled. Forward updates are enabled by
1929 default. If this statement is used to disable forward updates, the
1930 DHCP server will never attempt to update the client´s A record, and
1931 will only ever attempt to update the client´s PTR record if the
1932 client supplies an FQDN that should be placed in the PTR record using
1933 the fqdn option. If forward updates are enabled, the DHCP server
1934 will still honor the setting of the client-updates flag.
1935 The dont-use-fsync statement
1937 dont-use-fsync flag;
1939 The dont-use-fsync statement instructs the DHCP server if it should
1941 call fsync() when writing leases to the lease file. By default and
1942 if the flag is set to false the server will call fsync(). Suppress‐
1943 ing the call to fsync() may increase the performance of the server
1944 but it also adds a risk that a lease will not be properly written to
1945 the disk after it has been issued to a client and before the server
1946 stops. This can lead to duplicate leases being issued to different
1947 clients. Using this option is not recommended.
1948 The dynamic-bootp-lease-cutoff statement
1950 dynamic-bootp-lease-cutoff date;
1952 The dynamic-bootp-lease-cutoff statement sets the ending time for all
1954 leases assigned dynamically to BOOTP clients. Because BOOTP clients
1955 do not have any way of renewing leases, and don't know that their
1956 leases could expire, by default dhcpd assigns infinite leases to all
1957 BOOTP clients. However, it may make sense in some situations to set
1958 a cutoff date for all BOOTP leases - for example, the end of a school
1959 term, or the time at night when a facility is closed and all machines
1960 are required to be powered off.
1961 Date should be the date on which all assigned BOOTP leases will end.
1963 The date is specified in the form:
1964 W YYYY/MM/DD HH:MM:SS
1966 W is the day of the week expressed as a number from zero (Sunday) to
1968 six (Saturday). YYYY is the year, including the century. MM is the
1969 month expressed as a number from 1 to 12. DD is the day of the
1970 month, counting from 1. HH is the hour, from zero to 23. MM is the
1971 minute and SS is the second. The time is always in Coordinated Uni‐
1972 versal Time (UTC), not local time.
1973 The dynamic-bootp-lease-length statement
1975 dynamic-bootp-lease-length length;
1977 The dynamic-bootp-lease-length statement is used to set the length of
1979 leases dynamically assigned to BOOTP clients. At some sites, it may
1980 be possible to assume that a lease is no longer in use if its holder
1981 has not used BOOTP or DHCP to get its address within a certain time
1982 period. The period is specified in length as a number of seconds.
1983 If a client reboots using BOOTP during the timeout period, the lease
1984 duration is reset to length, so a BOOTP client that boots frequently
1985 enough will never lose its lease. Needless to say, this parameter
1986 should be adjusted with extreme caution.
1987 The echo-client-id statement
1989 echo-client-id flag;
1991 The echo-client-id statement is used to enable or disable RFC 6842
1993 compliant behavior. If the echo-client-id statement is present and
1994 has a value of true or on, and a DHCP DISCOVER or REQUEST is received
1995 which contains the client identifier option (Option code 61), the
1996 server will copy the option into its response (DHCP ACK or NAK) per
1997 RFC 6842. In other words if the client sends the option it will
1998 receive it back. By default, this flag is off and client identifiers
1999 will not echoed back to the client.
2000 The filename statement
2002 filename "filename";
2004 The filename statement can be used to specify the name of the initial
2006 boot file which is to be loaded by a client. The filename should be
2007 a filename recognizable to whatever file transfer protocol the client
2008 can be expected to use to load the file.
2009 The fixed-address declaration
2011 fixed-address address [, address ... ];
2013 The fixed-address declaration is used to assign one or more fixed IP
2015 addresses to a client. It should only appear in a host declaration.
2016 If more than one address is supplied, then when the client boots, it
2017 will be assigned the address that corresponds to the network on which
2018 it is booting. If none of the addresses in the fixed-address state‐
2019 ment are valid for the network to which the client is connected, that
2020 client will not match the host declaration containing that fixed-
2021 address declaration. Each address in the fixed-address declaration
2022 should be either an IP address or a domain name that resolves to one
2023 or more IP addresses.
2024 The fixed-address6 declaration
2026 fixed-address6 ip6-address ;
2028 The fixed-address6 declaration is used to assign a fixed IPv6
2030 addresses to a client. It should only appear in a host declaration.
2031 The fixed-prefix6 declaration
2033 fixed-prefix6 low-address / bits;
2035 The fixed-prefix6 declaration is used to assign a fixed IPv6 prefix
2037 to a client. It should only appear in a host declaration, but multi‐
2038 ple fixed-prefix6 statements may appear in a single host declaration.
2039 The low-address specifies the start of the prefix and the bits speci‐
2041 fies the size of the prefix in bits.
2042 If there are multiple prefixes for a given host entry the server will
2044 choose one that matches the requested prefix size or, if none match,
2045 the first one.
2046 If there are multiple host declarations the server will try to choose
2048 a declaration where the fixed-address6 matches the client's subnet.
2049 If none match it will choose one that doesn't have a fixed-address6
2050 statement.
2051 Note Well: Unlike the fixed address the fixed prefix does not need to
2053 match a subnet in order to be served. This allows you to provide a
2054 prefix to a client that is outside of the subnet on which the client
2055 makes the request to the the server.
2056 The get-lease-hostnames statement
2058 get-lease-hostnames flag;
2060 The get-lease-hostnames statement is used to tell dhcpd whether or
2062 not to look up the domain name corresponding to the IP address of
2063 each address in the lease pool and use that address for the DHCP
2064 hostname option. If flag is true, then this lookup is done for all
2065 addresses in the current scope. By default, or if flag is false, no
2066 lookups are done.
2067 The hardware statement
2069 hardware hardware-type hardware-address;
2071 In order for a BOOTP client to be recognized, its network hardware
2073 address must be declared using a hardware clause in the host state‐
2074 ment. hardware-type must be the name of a physical hardware inter‐
2075 face type. Currently, only the ethernet and token-ring types are
2076 recognized, although support for a fddi hardware type (and others)
2077 would also be desirable. The hardware-address should be a set of
2078 hexadecimal octets (numbers from 0 through ff) separated by colons.
2079 The hardware statement may also be used for DHCP clients.
2080 The host-identifier option statement
2082 host-identifier option option-name option-data;
2084 or
2086 host-identifier v6relopt number option-name option-data;
2088 This identifies a DHCPv6 client in a host statement. option-name is
2090 any option, and option-data is the value for the option that the
2091 client will send. The option-data must be a constant value. In the
2092 v6relopts case the additional number is the relay to examine for the
2093 specified option name and value. The values are the same as for the
2094 v6relay option. 0 is a no-op, 1 is the relay closest to the client,
2095 2 the next one in and so on. Values that are larger than the maximum
2096 number of relays (currently 32) indicate the relay closest to the
2097 server independent of number.
2098 The ignore-client-uids statement
2100 ignore-client-uids flag;
2102 If the ignore-client-uids statement is present and has a value of
2104 true or on, the UID for clients will not be recorded. If this state‐
2105 ment is not present or has a value of false or off, then client UIDs
2106 will be recorded.
2107 The infinite-is-reserved statement
2109 infinite-is-reserved flag;
2111 ISC DHCP now supports ´reserved´ leases. See the section on RESERVED
2113 LEASES below. If this flag is on, the server will automatically
2114 reserve leases allocated to clients which requested an infinite
2115 (0xffffffff) lease-time.
2116 The default is off.
2118 The lease-file-name statement
2120 lease-file-name name;
2122 Name should be the name of the DHCP server's lease file. By default,
2124 this is /var/lib/dhcpd/dhcpd.leases. This statement must appear in
2125 the outer scope of the configuration file - if it appears in some
2126 other scope, it will have no effect. Furthermore, it has no effect
2127 if overridden by the -lf flag or the PATH_DHCPD_DB environment vari‐
2128 able.
2129 The limit-addrs-per-ia statement
2131 limit-addrs-per-ia number;
2133 By default, the DHCPv6 server will limit clients to one IAADDR per IA
2135 option, meaning one address. If you wish to permit clients to hang
2136 onto multiple addresses at a time, configure a larger number here.
2137 Note that there is no present method to configure the server to
2139 forcibly configure the client with one IP address per each subnet on
2140 a shared network. This is left to future work.
2141 The dhcpv6-lease-file-name statement
2143 dhcpv6-lease-file-name name;
2145 Name is the name of the lease file to use if and only if the server
2147 is running in DHCPv6 mode. By default, this is
2148 /var/lib/dhcpd/dhcpd6.leases. This statement, like lease-file-name,
2149 must appear in the outer scope of the configuration file. It has no
2150 effect if overridden by the -lf flag or the PATH_DHCPD6_DB environ‐
2151 ment variable. If dhcpv6-lease-file-name is not specified, but
2152 lease-file-name is, the latter value will be used.
2153 The lease-id-format parameter
2155 lease-id-format format;
2157 The format parameter must be either octal or hex. This parameter
2159 governs the format used to write certain values to lease files. With
2160 the default format, octal, values are written as quoted strings in
2161 which non-printable characters are represented as octal escapes - a
2162 backslash character followed by three octal digits. When the hex
2163 format is specified, values are written as an unquoted series of
2164 pairs of hexadecimal digits, separated by colons.
2165 Currently, the values written out based on lease-id-format are the
2167 server-duid, the uid (DHCPv4 leases), and the IAID_DUID (DHCPv6
2168 leases). Note the server automatically reads the values in either
2169 format.
2170 The local-port statement
2172 local-port port;
2174 This statement causes the DHCP server to listen for DHCP requests on
2176 the UDP port specified in port, rather than on port 67.
2177 The local-address statement
2179 local-address address;
2181 This statement causes the DHCP server to listen for DHCP requests
2183 sent to the specified address, rather than requests sent to all
2184 addresses. Since serving directly attached DHCP clients implies that
2185 the server must respond to requests sent to the all-ones IP address,
2186 this option cannot be used if clients are on directly attached net‐
2187 works; it is only realistically useful for a server whose only
2188 clients are reached via unicasts, such as via DHCP relay agents.
2189 Note: This statement is only effective if the server was compiled
2191 using the USE_SOCKETS #define statement, which is default on a small
2192 number of operating systems, and must be explicitly chosen at com‐
2193 pile-time for all others. You can be sure if your server is compiled
2194 with USE_SOCKETS if you see lines of this format at startup:
2195 Listening on Socket/eth0
2197 Note also that since this bind()s all DHCP sockets to the specified
2199 address, that only one address may be supported in a daemon at a
2200 given time.
2201 The log-facility statement
2203 log-facility facility;
2205 This statement causes the DHCP server to do all of its logging on the
2207 specified log facility once the dhcpd.conf file has been read. By
2208 default the DHCP server logs to the daemon facility. Possible log
2209 facilities include auth, authpriv, cron, daemon, ftp, kern, lpr,
2210 mail, mark, news, ntp, security, syslog, user, uucp, and local0
2211 through local7. Not all of these facilities are available on all
2212 systems, and there may be other facilities available on other sys‐
2213 tems.
2214 In addition to setting this value, you may need to modify your sys‐
2216 log.conf file to configure logging of the DHCP server. For example,
2217 you might add a line like this:
2218 local7.debug /var/log/dhcpd.log
2220 The syntax of the syslog.conf file may be different on some operating
2222 systems - consult the syslog.conf manual page to be sure. To get
2223 syslog to start logging to the new file, you must first create the
2224 file with correct ownership and permissions (usually, the same owner
2225 and permissions of your /var/log/messages or /usr/adm/messages file
2226 should be fine) and send a SIGHUP to syslogd. Some systems support
2227 log rollover using a shell script or program called newsyslog or
2228 logrotate, and you may be able to configure this as well so that your
2229 log file doesn't grow uncontrollably.
2230 Because the log-facility setting is controlled by the dhcpd.conf
2232 file, log messages printed while parsing the dhcpd.conf file or
2233 before parsing it are logged to the default log facility. To prevent
2234 this, see the README file included with this distribution, which
2235 describes BUG: where is that mentioned in README? how to change the
2236 default log facility. When this parameter is used, the DHCP server
2237 prints its startup message a second time after parsing the configura‐
2238 tion file, so that the log will be as complete as possible.
2239 The log-threshold-high and log-threshold-low statements
2241 log-threshold-high percentage;
2243 log-threshold-low percentage;
2245 The log-threshold-low and log-threshold-high statements are used to
2247 control when a message is output about pool usage. The value for
2248 both of them is the percentage of the pool in use. If the high
2249 threshold is 0 or has not been specified, no messages will be pro‐
2250 duced. If a high threshold is given, a message is output once the
2251 pool usage passes that level. After that, no more messages will be
2252 output until the pool usage falls below the low threshold. If the
2253 low threshold is not given, it default to a value of zero.
2254 A special case occurs when the low threshold is set to be higer than
2256 the high threshold. In this case, a message will be generated each
2257 time a lease is acknowledged when the pool usage is above the high
2258 threshold.
2259 Note that threshold logging will be automatically disabled for shared
2261 subnets whose total number of addresses is larger than (2^64)-1. The
2262 server will emit a log statement at startup when threshold logging is
2263 disabled as shown below:
2264 "Threshold logging disabled for shared subnet of ranges:
2266 <addresses>"
2267 This is likely to have no practical runtime effect as CPUs are
2269 unlikely to support a server actually reaching such a large number of
2270 leases.
2271 The max-lease-time statement
2273 max-lease-time time;
2275 Time should be the maximum length in seconds that will be assigned to
2277 a lease. If not defined, the default maximum lease time is 86400.
2278 The only exception to this is that Dynamic BOOTP lease lengths, which
2279 are not specified by the client, are not limited by this maximum.
2280 The min-lease-time statement
2282 min-lease-time time;
2284 Time should be the minimum length in seconds that will be assigned to
2286 a lease. The default is the minimum of 300 seconds or max-lease-
2287 time.
2288 The min-secs statement
2290 min-secs seconds;
2292 Seconds should be the minimum number of seconds since a client began
2294 trying to acquire a new lease before the DHCP server will respond to
2295 its request. The number of seconds is based on what the client
2296 reports, and the maximum value that the client can report is 255 sec‐
2297 onds. Generally, setting this to one will result in the DHCP server
2298 not responding to the client's first request, but always responding
2299 to its second request.
2300 This can be used to set up a secondary DHCP server which never offers
2302 an address to a client until the primary server has been given a
2303 chance to do so. If the primary server is down, the client will bind
2304 to the secondary server, but otherwise clients should always bind to
2305 the primary. Note that this does not, by itself, permit a primary
2306 server and a secondary server to share a pool of dynamically-allocat‐
2307 able addresses.
2308 The next-server statement
2310 next-server server-name;
2312 The next-server statement is used to specify the host address of the
2314 server from which the initial boot file (specified in the filename
2315 statement) is to be loaded. Server-name should be a numeric IP
2316 address or a domain name. If no next-server statement applies to a
2317 given client, the address 0.0.0.0 is used.
2318 The omapi-port statement
2320 omapi-port port;
2322 The omapi-port statement causes the DHCP server to listen for OMAPI
2324 connections on the specified port. This statement is required to
2325 enable the OMAPI protocol, which is used to examine and modify the
2326 state of the DHCP server as it is running.
2327 The one-lease-per-client statement
2329 one-lease-per-client flag;
2331 If this flag is enabled, whenever a client sends a DHCPREQUEST for a
2333 particular lease, the server will automatically free any other leases
2334 the client holds. This presumes that when the client sends a DHCPRE‐
2335 QUEST, it has forgotten any lease not mentioned in the DHCPREQUEST -
2336 i.e., the client has only a single network interface and it does not
2337 remember leases it's holding on networks to which it is not currently
2338 attached. Neither of these assumptions are guaranteed or provable,
2339 so we urge caution in the use of this statement.
2340 The pid-file-name statement
2342 pid-file-name name;
2344 Name should be the name of the DHCP server's process ID file. This
2346 is the file in which the DHCP server's process ID is stored when the
2347 server starts. By default, this is /var/run/dhcpd.pid. Like the
2348 lease-file-name statement, this statement must appear in the outer
2349 scope of the configuration file. It has no effect if overridden by
2350 the -pf flag or the PATH_DHCPD_PID environment variable.
2351 The dhcpv6-pid-file-name statement
2353 dhcpv6-pid-file-name name;
2355 Name is the name of the pid file to use if and only if the server
2357 is running in DHCPv6 mode. By default, this is
2358 /var/lib/dhcpd/dhcpd6.pid. This statement, like pid-file-name,
2359 must appear in the outer scope of the configuration file. It has
2360 no effect if overridden by the -pf flag or the PATH_DHCPD6_PID
2361 environment variable. If dhcpv6-pid-file-name is not specified,
2362 but pid-file-name is, the latter value will be used.
2363 The ping-check statement
2365 ping-check flag;
2367 When the DHCP server is considering dynamically allocating an IP
2369 address to a client, it first sends an ICMP Echo request (a ping)
2370 to the address being assigned. It waits for a second, and if no
2371 ICMP Echo response has been heard, it assigns the address. If a
2372 response is heard, the lease is abandoned, and the server does not
2373 respond to the client. The lease will remain abandoned for a min‐
2374 imum of abandon-lease-time seconds.
2375 If a there are no free addressses but there are abandoned IP
2377 addresses, the DHCP server will attempt to reclaim an abandoned IP
2378 address regardless of the value of abandon-lease-time.
2379 This ping check introduces a default one-second delay in respond‐
2381 ing to DHCPDISCOVER messages, which can be a problem for some
2382 clients. The default delay of one second may be configured using
2383 the ping-timeout parameter. The ping-check configuration parame‐
2384 ter can be used to control checking - if its value is false, no
2385 ping check is done.
2386 The ping-timeout statement
2388 ping-timeout seconds;
2390 If the DHCP server determined it should send an ICMP echo request
2392 (a ping) because the ping-check statement is true, ping-timeout
2393 allows you to configure how many seconds the DHCP server should
2394 wait for an ICMP Echo response to be heard, if no ICMP Echo
2395 response has been received before the timeout expires, it assigns
2396 the address. If a response is heard, the lease is abandoned, and
2397 the server does not respond to the client. If no value is set,
2398 ping-timeout defaults to 1 second.
2399 The preferred-lifetime statement
2401 preferred-lifetime seconds;
2403 IPv6 addresses have ´valid´ and ´preferred´ lifetimes. The valid
2405 lifetime determines at what point at lease might be said to have
2406 expired, and is no longer useable. A preferred lifetime is an
2407 advisory condition to help applications move off of the address
2408 and onto currently valid addresses (should there still be any open
2409 TCP sockets or similar).
2410 The preferred lifetime defaults to 5/8 the default lease time.
2412 The prefix-length-mode statement
2414 prefix-length-mode mode;
2416 According to RFC 3633, DHCPv6 clients may specify preferences when
2418 soliciting prefixes by including an IA_PD Prefix option within the
2419 IA_PD option. Among the preferences that may be conveyed is the
2420 "prefix-length". When non-zero it indicates a client's desired
2421 length for offered prefixes. The RFC states that servers "MAY
2422 choose to use the information...to select prefix(es)" but does not
2423 specify any particular rules for doing so. The prefix-length-mode
2424 statement can be used to set the prefix selection rules employed
2425 by the server, when clients send a non-zero prefix-length value.
2426 The mode parameter must be one of ignore, prefer, exact, minimum,
2427 or maximum where:
2428 1. ignore - The requested length is ignored. The server will offer
2430 the first available prefix.
2431 2. prefer - The server will offer the first available prefix with
2433 the same length as the requested length. If none are found then
2434 it will offer the first available prefix of any length.
2435 3. exact - The server will offer the first available prefix with
2437 the same length as the requested length. If none are found, it
2438 will return a status indicating no prefixes available. This is
2439 the default behavior.
2440 4. minimum - The server will offer the first available prefix with
2442 the same length as the requested length. If none are found, it
2443 will return the first available prefix whose length is greater
2444 than (e.g. longer than), the requested value. If none of those
2445 are found, it will return a status indicating no prefixes avail‐
2446 able. For example, if client requests a length of /60, and the
2447 server has available prefixes of lengths /56 and /64, it will
2448 offer prefix of length /64.
2449 5. maximum - The server will offer the first available prefix with
2451 the same length as the requested length. If none are found, it
2452 will return the first available prefix whose length is less than
2453 (e.g. shorter than), the requested value. If none of those are
2454 found, it will return a status indicating no prefixes available.
2455 For example, if client requests a length of /60, and the server
2456 has available prefixes of lengths /56 and /64, it will offer a
2457 prefix of length /56.
2458 In general "first available" is determined by the order in which
2460 pools are defined in the server's configuration. For example, if
2461 a subnet is defined with three prefix pools A,B, and C:
2462 subnet 3000::/64 {
2464 # pool A
2465 pool6 {
2466 :
2467 }
2468 # pool B
2469 pool6 {
2470 :
2471 }
2472 # pool C
2473 pool6 {
2474 :
2475 }
2476 }
2477 then the pools will be checked in the order A, B, C. For modes
2479 prefer, minimum, and maximum this may mean checking the pools in
2480 that order twice. A first pass through is made looking for an
2481 available prefix of exactly the preferred length. If none are
2482 found, then a second pass is performed starting with pool A but
2483 with appropriately adjusted length criteria.
2484 The remote-port statement
2486 remote-port port;
2488 This statement causes the DHCP server to transmit DHCP responses
2490 to DHCP clients upon the UDP port specified in port, rather than
2491 on port 68. In the event that the UDP response is transmitted to
2492 a DHCP Relay, the server generally uses the local-port configura‐
2493 tion value. Should the DHCP Relay happen to be addressed as
2494 127.0.0.1, however, the DHCP Server transmits its response to the
2495 remote-port configuration value. This is generally only useful
2496 for testing purposes, and this configuration value should gener‐
2497 ally not be used.
2498 The server-identifier statement
2500 server-identifier hostname;
2502 The server-identifier statement can be used to define the value
2504 that is sent in the DHCP Server Identifier option for a given
2505 scope. The value specified must be an IP address for the DHCP
2506 server, and must be reachable by all clients served by a particu‐
2507 lar scope.
2508 The use of the server-identifier statement is not recommended -
2510 the only reason to use it is to force a value other than the
2511 default value to be sent on occasions where the default value
2512 would be incorrect. The default value is the first IP address
2513 associated with the physical network interface on which the
2514 request arrived.
2515 The usual case where the server-identifier statement needs to be
2517 sent is when a physical interface has more than one IP address,
2518 and the one being sent by default isn't appropriate for some or
2519 all clients served by that interface. Another common case is when
2520 an alias is defined for the purpose of having a consistent IP
2521 address for the DHCP server, and it is desired that the clients
2522 use this IP address when contacting the server.
2523 Supplying a value for the dhcp-server-identifier option is equiva‐
2525 lent to using the server-identifier statement.
2526 The server-id-check statement
2528 server-id-check flag;
2530 The server-id-check statement is used to control whether or not a
2532 server, participating in failover, verifies that the value of the
2533 dhcp-server-identifier option in received DHCP REQUESTs match the
2534 server's id before processing the request. Server id checking is
2535 disabled by default. Setting this flag enables id checking and
2536 thereafter the server will only process requests that match. Note
2537 the flag setting should be consistent between failover partners.
2538 Unless overridden by use of the server-identifier statement, the
2540 value the server uses as its id will be the first IP address asso‐
2541 ciated with the physical network interface on which the request
2542 arrived.
2543 In order to reduce runtime overhead the server only checks for a
2545 server id option in the global and subnet scopes. Complicated
2546 configurations may result in different server ids for this check
2547 and when the server id for a reply packet is determined, which
2548 would prohibit the server from responding.
2549 The primary use for this option is when a client broadcasts a
2551 request but requires that the response come from a specific
2552 failover peer. An example of this would be when a client reboots
2553 while its lease is still active - in this case both servers will
2554 normally respond. Most of the time the client won't check the
2555 server id and can use either of the responses. However if the
2556 client does check the server id it may reject the response if it
2557 came from the wrong peer. If the timing is such that the "wrong"
2558 peer responds first most of the time the client may not get an
2559 address for some time.
2560 Care should be taken before enabling this option.
2562 The server-duid statement
2564 server-duid LLT [ hardware-type timestamp hardware-address ] ;
2566 server-duid EN enterprise-number enterprise-identifier ;
2568 server-duid LL [ hardware-type hardware-address ] ;
2570 The server-duid statement configures the server DUID. You may pick
2572 either LLT (link local address plus time), EN (enterprise), or LL
2573 (link local).
2574 If you choose LLT or LL, you may specify the exact contents of the
2576 DUID. Otherwise the server will generate a DUID of the specified
2577 type.
2578 If you choose EN, you must include the enterprise number and the
2580 enterprise-identifier.
2581 If there is a server-duid statement in the lease file it will take
2583 precedence over the server-duid statement from the config file and
2584 a dhcp6.server-id option in the config file will override both.
2585 The default server-duid type is LLT.
2587 The server-name statement
2589 server-name name ;
2591 The server-name statement can be used to inform the client of the
2593 name of the server from which it is booting. Name should be the
2594 name that will be provided to the client.
2595 The dhcpv6-set-tee-times statement
2597 dhcpv6-set-tee-times flag;
2599 The dhcpv6-set-tee-times statement enables setting T1 and T2 to
2601 the values recommended in RFC 3315 (Section 22.4). When setting
2602 T1 and T2, the server will use dhcp-renewal-time and dhcp-rebind‐
2603 ing-time, respectively. A value of zero tells the client it may
2604 choose its own value.
2605 When those options are not defined then values will be set to zero
2607 unless the global dhcpv6-set-tee-timesis enabled. When this
2608 option is enabled the times are calculated as recommended by RFC
2609 3315, Section 22.4:
2610 T1 will be set to 0.5 times the shortest preferred lifetime
2612 in the reply. If the "shortest" preferred lifetime is
2613 0xFFFFFFFF, T1 will set to 0xFFFFFFFF.
2614 T2 will be set to 0.8 times the shortest preferred lifetime
2616 in the reply. If the "shortest" preferred lifetime is
2617 0xFFFFFFFF, T2 will set to 0xFFFFFFFF.
2618 Keep in mind that given sufficiently small lease lifetimes, the
2620 above calculations will result in the two values being equal. For
2621 example, a 9 second lease lifetime would yield T1 = T2 = 4 sec‐
2622 onds, which would cause clients to issue rebinds only. In such a
2623 case it would likely be better to explicitly define the values.
2624 Note that dhcpv6-set-tee-times is intended to be transitional and
2626 will likely be removed in a future release. Once removed the
2627 behavior will be to use the configured values when present or cal‐
2628 culate them per the RFC. If you want zeros, define them as zeros.
2629 The site-option-space statement
2631 site-option-space name ;
2633 The site-option-space statement can be used to determine from what
2635 option space site-local options will be taken. This can be used
2636 in much the same way as the vendor-option-space statement. Site-
2637 local options in DHCP are those options whose numeric codes are
2638 greater than 224. These options are intended for site-specific
2639 uses, but are frequently used by vendors of embedded hardware that
2640 contains DHCP clients. Because site-specific options are allo‐
2641 cated on an ad hoc basis, it is quite possible that one vendor's
2642 DHCP client might use the same option code that another vendor's
2643 client uses, for different purposes. The site-option-space option
2644 can be used to assign a different set of site-specific options for
2645 each such vendor, using conditional evaluation (see dhcp-eval (5)
2646 for details).
2647 The stash-agent-options statement
2649 stash-agent-options flag;
2651 If the stash-agent-options parameter is true for a given client,
2653 the server will record the relay agent information options sent
2654 during the client's initial DHCPREQUEST message when the client
2655 was in the SELECTING state and behave as if those options are
2656 included in all subsequent DHCPREQUEST messages sent in the RENEW‐
2657 ING state. This works around a problem with relay agent informa‐
2658 tion options, which is that they usually not appear in DHCPREQUEST
2659 messages sent by the client in the RENEWING state, because such
2660 messages are unicast directly to the server and not sent through a
2661 relay agent.
2662 The update-conflict-detection statement
2664 update-conflict-detection flag;
2666 If the update-conflict-detection parameter is true, the server
2668 will perform standard DHCID multiple-client, one-name conflict
2669 detection. If the parameter has been set false, the server will
2670 skip this check and instead simply tear down any previous bindings
2671 to install the new binding without question. The default is true.
2672 The update-optimization statement
2674 update-optimization flag;
2676 If the update-optimization parameter is false for a given client,
2678 the server will attempt a DNS update for that client each time the
2679 client renews its lease, rather than only attempting an update
2680 when it appears to be necessary. This will allow the DNS to heal
2681 from database inconsistencies more easily, but the cost is that
2682 the DHCP server must do many more DNS updates. We recommend leav‐
2683 ing this option enabled, which is the default. If this parameter
2684 is not specified, or is true, the DHCP server will only update
2685 when the client information changes, the client gets a different
2686 lease, or the client's lease expires.
2687 The update-static-leases statement
2689 update-static-leases flag;
2691 The update-static-leases flag, if enabled, causes the DHCP server
2693 to do DNS updates for clients even if those clients are being
2694 assigned their IP address using a fixed-address statement - that
2695 is, the client is being given a static assignment. It is not rec‐
2696 ommended because the DHCP server has no way to tell that the
2697 update has been done, and therefore will not delete the record
2698 when it is not in use. Also, the server must attempt the update
2699 each time the client renews its lease, which could have a signifi‐
2700 cant performance impact in environments that place heavy demands
2701 on the DHCP server.
2702 The use-host-decl-names statement
2704 use-host-decl-names flag;
2706 If the use-host-decl-names parameter is true in a given scope,
2708 then for every host declaration within that scope, the name pro‐
2709 vided for the host declaration will be supplied to the client as
2710 its hostname. So, for example,
2711 group {
2713 use-host-decl-names on;
2714 host joe {
2716 hardware ethernet 08:00:2b:4c:29:32;
2717 fixed-address joe.example.com;
2718 }
2719 }
2720 is equivalent to
2722 host joe {
2724 hardware ethernet 08:00:2b:4c:29:32;
2725 fixed-address joe.example.com;
2726 option host-name "joe";
2727 }
2728 Additionally, enabling use-host-decl-names instructs the server to
2730 use the host declaration name in the the forward DNS name, if no
2731 other values are available. This value selection process is dis‐
2732 cussed in more detail under DNS updates.
2733 An option host-name statement within a host declaration will over‐
2735 ride the use of the name in the host declaration.
2736 It should be noted here that most DHCP clients completely ignore
2738 the host-name option sent by the DHCP server, and there is no way
2739 to configure them not to do this. So you generally have a choice
2740 of either not having any hostname to client IP address mapping
2741 that the client will recognize, or doing DNS updates. It is
2742 beyond the scope of this document to describe how to make this
2743 determination.
2744 The use-lease-addr-for-default-route statement
2746 use-lease-addr-for-default-route flag;
2748 If the use-lease-addr-for-default-route parameter is true in a
2750 given scope, then instead of sending the value specified in the
2751 routers option (or sending no value at all), the IP address of the
2752 lease being assigned is sent to the client. This supposedly
2753 causes Win95 machines to ARP for all IP addresses, which can be
2754 helpful if your router is configured for proxy ARP. The use of
2755 this feature is not recommended, because it won't work for many
2756 DHCP clients.
2757 The vendor-option-space statement
2759 vendor-option-space string;
2761 The vendor-option-space parameter determines from what option
2763 space vendor options are taken. The use of this configuration
2764 parameter is illustrated in the dhcp-options(5) manual page, in
2765 the VENDOR ENCAPSULATED OPTIONS section.
2766
2768 Sometimes it's helpful to be able to set the value of a DHCP server
2769 parameter based on some value that the client has sent. To do this,
2770 you can use expression evaluation. The dhcp-eval(5) manual page
2771 describes how to write expressions. To assign the result of an evalua‐
2772 tion to an option, define the option as follows:
2773 my-parameter = expression ;
2775 For example:
2777 ddns-hostname = binary-to-ascii (16, 8, "-",
2779 substring (hardware, 1, 6));
2780
2782 It's often useful to allocate a single address to a single client, in
2783 approximate perpetuity. Host statements with fixed-address clauses
2784 exist to a certain extent to serve this purpose, but because host
2785 statements are intended to approximate ´static configuration´, they
2786 suffer from not being referenced in a littany of other Server Services,
2787 such as dynamic DNS, failover, ´on events´ and so forth.
2788 If a standard dynamic lease, as from any range statement, is marked
2790 ´reserved´, then the server will only allocate this lease to the client
2791 it is identified by (be that by client identifier or hardware address).
2792 In practice, this means that the lease follows the normal state engine,
2794 enters ACTIVE state when the client is bound to it, expires, or is
2795 released, and any events or services that would normally be supplied
2796 during these events are processed normally, as with any other dynamic
2797 lease. The only difference is that failover servers treat reserved
2798 leases as special when they enter the FREE or BACKUP states - each
2799 server applies the lease into the state it may allocate from - and the
2800 leases are not placed on the queue for allocation to other clients.
2801 Instead they may only be ´found´ by client identity. The result is
2802 that the lease is only offered to the returning client.
2803 Care should probably be taken to ensure that the client only has one
2805 lease within a given subnet that it is identified by.
2806 Leases may be set ´reserved´ either through OMAPI, or through the
2808 ´infinite-is-reserved´ configuration option (if this is applicable to
2809 your environment and mixture of clients).
2810 It should also be noted that leases marked ´reserved´ are effectively
2812 treated the same as leases marked ´bootp´.
2813
2815 DHCP option statements are documented in the dhcp-options(5) manual
2816 page.
2817
2819 Expressions used in DHCP option statements and elsewhere are documented
2820 in the dhcp-eval(5) manual page.
2821
2823 dhcpd(8), dhcpd.leases(5), dhcp-options(5), dhcp-eval(5), RFC2132,
2824 RFC2131.
2825
2827 dhcpd.conf(5) is maintained by ISC. Information about Internet Systems
2828 Consortium can be found at https://www.isc.org.
2829 dhcpd.conf(5)