1dhcpd.conf(5)                 File Formats Manual                dhcpd.conf(5)
2
3
4

NAME

6       dhcpd.conf - dhcpd configuration file
7

DESCRIPTION

9       The  dhcpd.conf  file contains configuration information for dhcpd, the
10       Internet Systems Consortium DHCP Server.
11
12       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
19       The file essentially consists of a list of statements.  Statements fall
20       into two broad categories - parameters and declarations.
21
22       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
27       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
34       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
43       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
49       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
58       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
65       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
76       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
86       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

EXAMPLES

93       A typical dhcpd.conf file will look something like this:
94
95       global parameters...
96
97       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
102       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
107       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
112       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
125                                      Figure 1
126
127
128       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
133            option domain-name "isc.org";
134            option domain-name-servers ns1.isc.org, ns2.isc.org;
135
136                                      Figure 2
137
138       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
144       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
148            option routers 204.254.239.1;
149
150       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
157       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
163            option domain-name "test.isc.org";
164
165       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
169            max-lease-time 120;
170            default-lease-time 120;
171
172       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
180       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
187       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
192       group {
193         filename "Xncd19r";
194         next-server ncd-booter;
195
196         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
201       group {
202         filename "Xncd19c";
203         next-server ncd-booter;
204
205         host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; }
206         host ncd3 { hardware ethernet 0:c0:c3:00:14:11; }
207       }
208
209       group {
210         filename "XncdHMX";
211         next-server ncd-booter;
212
213         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

ADDRESS POOLS

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
231       subnet 10.0.0.0 netmask 255.255.255.0 {
232         option routers 10.0.0.254;
233
234         # 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
242         # 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
251       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
255       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
266       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

DYNAMIC ADDRESS ALLOCATION

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
282       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
292       There may be a host declaration matching the  client's  identification.
293       If  that  host  declaration  contains  a fixed-address declaration that
294       lists an IP address that is valid for the network segment to which  the
295       client  is  connected,  the  DHCP  server will never do dynamic address
296       allocation.  In this case, the client is required to take  the  address
297       specified  in  the host declaration.  If the client sends a DHCPREQUEST
298       for some other address, the server will respond with a DHCPNAK.
299
300       When the DHCP server allocates a new address for  a  client  (remember,
301       this  only  happens  if  the  client has sent a DHCPDISCOVER), it first
302       looks to see if the client already has a valid lease on an IP  address,
303       or  if there is an old IP address the client had before that hasn't yet
304       been reassigned.  In that case, the server will take that  address  and
305       check  it  to  see  if the client is still permitted to use it.  If the
306       client is no longer permitted to use it, the  lease  is  freed  if  the
307       server  thought it was still in use - the fact that the client has sent
308       a DHCPDISCOVER proves to the server that the client is no longer  using
309       the lease.
310
311       If no existing lease is found, or if the client is forbidden to receive
312       the existing lease, then the server will look in the  list  of  address
313       pools  for  the  network  segment to which the client is attached for a
314       lease that is not in use and that the client is permitted to have.   It
315       looks through each pool declaration in sequence (all range declarations
316       that appear outside of pool declarations are grouped into a single pool
317       with  no  permit  list).   If  the  permit list for the pool allows the
318       client to be allocated an address from that pool, the pool is  examined
319       to  see  if  there  is an address available.  If so, then the client is
320       tentatively assigned that address.  Otherwise, the next pool is tested.
321       If  no  addresses  are  found  that  can  be assigned to the client, no
322       response is sent to the client.
323
324       If an address is found that the client is permitted to have,  and  that
325       has  never  been  assigned to any client before, the address is immedi‐
326       ately allocated to the client.  If the address is available for alloca‐
327       tion but has been previously assigned to a different client, the server
328       will keep looking in hopes of finding an address that has never  before
329       been assigned to a client.
330
331       The  DHCP  server  generates  the list of available IP addresses from a
332       hash table.  This means that the addresses are not sorted in  any  par‐
333       ticular  order, and so it is not possible to predict the order in which
334       the DHCP server will allocate IP addresses.  Users of previous versions
335       of  the  ISC  DHCP server may have become accustomed to the DHCP server
336       allocating IP addresses in ascending order, but this is no longer  pos‐
337       sible, and there is no way to configure this behavior with version 3 of
338       the ISC DHCP server.
339

IP ADDRESS CONFLICT PREVENTION

341       The DHCP server checks IP addresses to see if they are  in  use  before
342       allocating  them  to  clients.   It  does  this by sending an ICMP Echo
343       request message to the IP address being allocated.   If  no  ICMP  Echo
344       reply  is  received within a second, the address is assumed to be free.
345       This is only done for leases that have been specified in  range  state‐
346       ments, and only when the lease is thought by the DHCP server to be free
347       - i.e., the DHCP server or its failover peer has not listed  the  lease
348       as in use.
349
350       If  a  response  is  received  to an ICMP Echo request, the DHCP server
351       assumes that there is a configuration error - the IP address is in  use
352       by  some  host  on the network that is not a DHCP client.  It marks the
353       address as abandoned, and will not assign it to clients. The lease will
354       remain abandoned for a minimum of abandon-lease-time seconds.
355
356       If  a  DHCP  client tries to get an IP address, but none are available,
357       but there are abandoned IP addresses, then the DHCP server will attempt
358       to  reclaim  an abandoned IP address.  It marks one IP address as free,
359       and then does the same ICMP Echo request  check  described  previously.
360       If there is no answer to the ICMP Echo request, the address is assigned
361       to the client.
362
363       The DHCP server does not cycle through abandoned IP  addresses  if  the
364       first  IP  address  it tries to reclaim is free.  Rather, when the next
365       DHCPDISCOVER comes in from the client, it will attempt a new allocation
366       using  the  same method described here, and will typically try a new IP
367       address.
368

DHCP FAILOVER

370       This version of the ISC DHCP server supports the DHCP failover protocol
371       as  documented  in draft-ietf-dhc-failover-12.txt.  This is not a final
372       protocol document, and we have not done interoperability  testing  with
373       other vendors' implementations of this protocol, so you must not assume
374       that this implementation conforms to the standard.  If you wish to  use
375       the  failover  protocol, make sure that both failover peers are running
376       the same version of the ISC DHCP server.
377
378       The failover protocol allows two DHCP servers (and no more than two) to
379       share  a  common address pool.  Each server will have about half of the
380       available IP addresses in the pool at any given  time  for  allocation.
381       If one server fails, the other server will continue to renew leases out
382       of the pool, and will allocate new addresses out of the roughly half of
383       available  addresses  that  it  had  when communications with the other
384       server were lost.
385
386       It is possible during a prolonged failure to tell the remaining  server
387       that  the other server is down, in which case the remaining server will
388       (over time) reclaim all the addresses the other  server  had  available
389       for  allocation,  and  begin to reuse them.  This is called putting the
390       server into the PARTNER-DOWN state.
391
392       You can put the server into the PARTNER-DOWN state either by using  the
393       omshell  (1)  command  or  by  stopping  the  server,  editing the last
394       failover state declaration  in  the  lease  file,  and  restarting  the
395       server.  If you use this last method, change the "my state" line to:
396
397       failover peer name state {
398       my state partner-down;.
399       peer state state at date;
400       }
401
402       It is only required to change "my state" as shown above.
403
404       When the other server comes back online, it should automatically detect
405       that it has been offline and request a complete update from the  server
406       that  was running in the PARTNER-DOWN state, and then both servers will
407       resume processing together.
408
409       It is possible to get into a dangerous situation: if you put one server
410       into  the PARTNER-DOWN state, and then *that* server goes down, and the
411       other server comes back up, the other server will  not  know  that  the
412       first  server  was  in  the PARTNER-DOWN state, and may issue addresses
413       previously issued by the other server to different  clients,  resulting
414       in  IP  address  conflicts.   Before putting a server into PARTNER-DOWN
415       state, therefore, make sure that the  other  server  will  not  restart
416       automatically.
417
418       The  failover  protocol  defines  a primary server role and a secondary
419       server role.  There are some differences in how  primaries  and  secon‐
420       daries  act, but most of the differences simply have to do with provid‐
421       ing a way for each peer to behave in the opposite way from  the  other.
422       So one server must be configured as primary, and the other must be con‐
423       figured as secondary, and it doesn't  matter  too  much  which  one  is
424       which.
425

FAILOVER STARTUP

427       When  a  server  starts  that  has not previously communicated with its
428       failover peer, it must establish communications with its failover  peer
429       and  synchronize  with it before it can serve clients.  This can happen
430       either because you have just configured your DHCP  servers  to  perform
431       failover  for  the  first time, or because one of your failover servers
432       has failed catastrophically and lost its database.
433
434       The initial recovery process  is  designed  to  ensure  that  when  one
435       failover  peer  loses  its database and then resynchronizes, any leases
436       that the failed server gave out before it failed will be honored.  When
437       the  failed  server starts up, it notices that it has no saved failover
438       state, and attempts to contact its peer.
439
440       When it has established contact, it asks the peer for a  complete  copy
441       its  peer's lease database.  The peer then sends its complete database,
442       and sends a message indicating that it is done.  The failed server then
443       waits until MCLT has passed, and once MCLT has passed both servers make
444       the transition back into normal operation.  This waiting period ensures
445       that  any leases the failed server may have given out while out of con‐
446       tact with its partner will have expired.
447
448       While the failed server is recovering, its partner remains in the part‐
449       ner-down state, which means that it is serving all clients.  The failed
450       server provides no service at all to DHCP clients until it has made the
451       transition into normal operation.
452
453       In  the case where both servers detect that they have never before com‐
454       municated with their partner, they both come up in this recovery  state
455       and follow the procedure we have just described.  In this case, no ser‐
456       vice will be provided to DHCP clients until MCLT has expired.
457

CONFIGURING FAILOVER

459       In order to configure failover, you need to write  a  peer  declaration
460       that  configures the failover protocol, and you need to write peer ref‐
461       erences in each pool declaration for which you  want  to  do  failover.
462       You  do  not  have to do failover for all pools on a given network seg‐
463       ment.   You must not tell one server it's doing failover on a  particu‐
464       lar  address  pool and tell the other it is not.  You must not have any
465       common address pools on which you are not doing failover.  A pool  dec‐
466       laration that utilizes failover would look like this:
467
468       pool {
469            failover peer "foo";
470            pool specific parameters
471       };
472
473       Dynamic  BOOTP  leases  are not compatible with failover, and, as such,
474       you need to disallow BOOTP in pools that you are using failover for.
475
476       The  server currently  does very  little  sanity checking,  so if   you
477       configure  it wrong, it will just  fail in odd ways.  I would recommend
478       therefore that you either do  failover or don't do failover, but  don't
479       do  any mixed pools.  Also,  use the same master configuration file for
480       both  servers,  and  have  a  separate file  that  contains  the   peer
481       declaration  and includes the master file.  This will help you to avoid
482       configuration  mismatches.  As our  implementation evolves,  this  will
483       become   less of  a  problem.  A  basic  sample dhcpd.conf  file for  a
484       primary server might look like this:
485
486       failover peer "foo" {
487         primary;
488         address anthrax.rc.example.com;
489         port 647;
490         peer address trantor.rc.example.com;
491         peer port 847;
492         max-response-delay 60;
493         max-unacked-updates 10;
494         mclt 3600;
495         split 128;
496         load balance max seconds 3;
497       }
498
499       include "/etc/dhcpd.master";
500
501       The statements in the peer declaration are as follows:
502
503       The primary and secondary statements
504
505         [ primary | secondary ];
506
507         This determines whether  the  server  is  primary  or  secondary,  as
508         described earlier under DHCP FAILOVER.
509
510       The address statement
511
512         address address;
513
514         The  address  statement  declares the IP address or DNS name on which
515         the server should listen for connections from its failover peer,  and
516         also  the  value to use for the DHCP Failover Protocol server identi‐
517         fier.  Because this value is used as an identifier,  it  may  not  be
518         omitted.
519
520       The peer address statement
521
522         peer address address;
523
524         The  peer  address  statement  declares the IP address or DNS name to
525         which the server should  connect  to  reach  its  failover  peer  for
526         failover messages.
527
528       The port statement
529
530         port port-number;
531
532         The  port  statement declares the TCP port on which the server should
533         listen for connections from its failover peer.  This statement may be
534         omitted, in which case the IANA assigned port number 647 will be used
535         by default.
536
537       The peer port statement
538
539         peer port port-number;
540
541         The peer port statement declares the TCP port  to  which  the  server
542         should  connect  to  reach  its  failover peer for failover messages.
543         This statement may be omitted, in which case the IANA  assigned  port
544         number 647 will be used by default.
545
546       The max-response-delay statement
547
548         max-response-delay seconds;
549
550         The  max-response-delay statement tells the DHCP server how many sec‐
551         onds may pass without receiving a  message  from  its  failover  peer
552         before  it assumes that connection has failed.  This number should be
553         small enough that a transient network failure that breaks the connec‐
554         tion  will not result in the servers being out of communication for a
555         long time, but large enough that the server isn't  constantly  making
556         and breaking connections.  This parameter must be specified.
557
558       The max-unacked-updates statement
559
560         max-unacked-updates count;
561
562         The  max-unacked-updates  statement  tells the remote DHCP server how
563         many BNDUPD messages it can send before it receives a BNDACK from the
564         local  system.   We  don't  have enough operational experience to say
565         what a good value for this is, but 10 seems to work.  This  parameter
566         must be specified.
567
568       The mclt statement
569
570         mclt seconds;
571
572         The  mclt statement defines the Maximum Client Lead Time.  It must be
573         specified on the primary, and may not be specified on the  secondary.
574         This is the length of time for which a lease may be renewed by either
575         failover peer without contacting the other.  The longer you set this,
576         the  longer  it  will  take  for  the  running  server  to recover IP
577         addresses after moving into PARTNER-DOWN state.  The shorter you  set
578         it, the more load your servers will experience when they are not com‐
579         municating.  A value of something like 3600 is  probably  reasonable,
580         but  again  bear  in mind that we have no real operational experience
581         with this.
582
583       The split statement
584
585         split bits;
586
587         The split statement specifies the split between the primary and  sec‐
588         ondary for the purposes of load balancing.  Whenever a client makes a
589         DHCP request, the DHCP server runs a hash on the  client  identifica‐
590         tion,  resulting  in  value  from 0 to 255.  This is used as an index
591         into a 256 bit field.  If the bit at that index is set,  the  primary
592         is  responsible.   If the bit at that index is not set, the secondary
593         is responsible.  The split value determines how many of  the  leading
594         bits are set to one.  So, in practice, higher split values will cause
595         the primary to serve more clients than the  secondary.   Lower  split
596         values,  the converse.  Legal values are between 0 and 256 inclusive,
597         of which the most reasonable is 128.  Note that a value  of  0  makes
598         the  secondary  responsible  for all clients and a value of 256 makes
599         the primary responsible for all clients.
600
601       The hba statement
602
603         hba colon-separated-hex-list;
604
605         The hba statement specifies the split between the  primary  and  sec‐
606         ondary  as  a bitmap rather than a cutoff, which theoretically allows
607         for finer-grained control.  In practice, there is  probably  no  need
608         for such fine-grained control, however.  An example hba statement:
609
610           hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:
611               00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00;
612
613         This  is  equivalent  to  a split 128; statement, and identical.  The
614         following two examples are also equivalent to a split of 128, but are
615         not identical:
616
617           hba aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:
618               aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa;
619
620           hba 55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:
621               55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55;
622
623         They are equivalent, because half the bits are set to 0, half are set
624         to 1 (0xa and 0x5 are 1010 and 0101 binary respectively)  and  conse‐
625         quently  this  would  roughly  divide the clients equally between the
626         servers.  They are not identical, because the actual peers this would
627         load balance to each server are different for each example.
628
629         You must only have split or hba defined, never both.  For most cases,
630         the fine-grained control that hba offers isn't necessary,  and  split
631         should be used.
632
633       The load balance max seconds statement
634
635         load balance max seconds seconds;
636
637         This statement allows you to configure a cutoff after which load bal‐
638         ancing is disabled.  The cutoff is based on  the  number  of  seconds
639         since  the client sent its first DHCPDISCOVER or DHCPREQUEST message,
640         and only works with clients that correctly implement the secs field -
641         fortunately  most clients do.  We recommend setting this to something
642         like 3 or 5.  The effect of this is that if one of the failover peers
643         gets into a state where it is responding to failover messages but not
644         responding to some client requests, the other failover peer will take
645         over its client load automatically as the clients retry.
646
647         It  is  possible  to  disable load balancing between peers by setting
648         this value to 0 on both peers.  Bear in mind  that  this  means  both
649         peers will respond to all DHCPDISCOVERs or DHCPREQUESTs.
650
651       The auto-partner-down statement
652
653         auto-partner-down seconds;
654
655         This  statement  instructs  the server to initiate a timed delay upon
656         entering the communications-interrupted state (any situation of being
657         out-of-contact  with the remote failover peer).  At the conclusion of
658         the timer, the  server  will  automatically  enter  the  partner-down
659         state.  This permits the server to allocate leases from the partner's
660         free lease pool after an STOS+MCLT timer expires, which can  be  dan‐
661         gerous  if  the  partner  is  in  fact operating at the time (the two
662         servers will give conflicting bindings).
663
664         Think very carefully before enabling this feature.  The  partner-down
665         and  communications-interrupted  states  are intentionally segregated
666         because there do exist situations where a failover server can fail to
667         communicate  with  its peer, but still has the ability to receive and
668         reply to requests from DHCP clients.  In general, this feature should
669         only  be  used  in  those  deployments where the failover servers are
670         directly connected to one another, such as by a  dedicated  hardwired
671         link ("a heartbeat cable").
672
673         A  zero  value  disables  the  auto-partner-down  feature  (also  the
674         default), and any positive value indicates the  time  in  seconds  to
675         wait before automatically entering partner-down.
676
677       The Failover pool balance statements.
678
679          max-lease-misbalance percentage;
680          max-lease-ownership percentage;
681          min-balance seconds;
682          max-balance seconds;
683
684         This version of the DHCP Server evaluates pool balance on a schedule,
685         rather than on demand as leases are allocated.  The  latter  approach
686         proved  to be slightly klunky when pool misbalanced reach total satu‐
687         ration — when any server ran out of leases to assign,  it  also  lost
688         its ability to notice it had run dry.
689
690         In  order  to understand pool balance, some elements of its operation
691         first need to be defined.   First,  there  are  ´free´  and  ´backup´
692         leases.   Both  of  these  are  referred  to  as ´free state leases´.
693         ´free´ and ´backup´ are ´the free states´ for  the  purpose  of  this
694         document.   The difference is that only the primary may allocate from
695         ´free´ leases unless under special circumstances, and only  the  sec‐
696         ondary may allocate ´backup´ leases.
697
698         When  pool balance is performed, the only plausible expectation is to
699         provide a 50/50 split of  the  free  state  leases  between  the  two
700         servers.   This is because no one can predict which server will fail,
701         regardless of the relative load placed upon the two servers, so  giv‐
702         ing each server half the leases gives both servers the same amount of
703         ´failure endurance´.  Therefore, there is no  way  to  configure  any
704         different  behaviour,  outside  of  some  very  small windows we will
705         describe shortly.
706
707         The first thing calculated  on  any  pool  balance  run  is  a  value
708         referred to as ´lts´, or "Leases To Send".  This, simply, is the dif‐
709         ference in the count of free and backup leases, divided by two.   For
710         the  secondary,  it  is the difference in the backup and free leases,
711         divided by two.  The resulting value is signed: if  it  is  positive,
712         the  local  server  is  expected to hand out leases to retain a 50/50
713         balance.  If it is negative, the remote server  would  need  to  send
714         leases  to  balance  the  pool.  Once the lts value reaches zero, the
715         pool is perfectly balanced (give or take one lease in the case of  an
716         odd number of total free state leases).
717
718         The  current  approach  is  still  something  of  a hybrid of the old
719         approach, marked by the presence of the  max-lease-misbalance  state‐
720         ment.  This parameter configures what used to be a 10% fixed value in
721         previous versions: if lts is less than free+backup  *  max-lease-mis‐
722         balance percent, then the server will skip balancing a given pool (it
723         won't bother moving any leases,  even  if  some  leases  "should"  be
724         moved).   The meaning of this value is also somewhat overloaded, how‐
725         ever, in that it also governs the estimation of when  to  attempt  to
726         balance  the  pool (which may then also be skipped over).  The oldest
727         leases in the free and backup states are  examined.   The  time  they
728         have  resided  in  their  respective queues is used as an estimate to
729         indicate how much time it is probable it would take before the leases
730         at the top of the list would be consumed (and thus, how long it would
731         take to use all leases in that state).  This percentage  is  directly
732         multiplied by this time, and fit into the schedule if it falls within
733         the min-balance and max-balance  configured  values.   The  scheduled
734         pool  check  time is only moved in a downwards direction, it is never
735         increased.  Lastly, if the lts is more than double this number in the
736         negative  direction,  the  local  server  will ´panic´ and transmit a
737         Failover protocol POOLREQ message, in the hopes that the remote  sys‐
738         tem will be woken up into action.
739
740         Once  the  lts  value  exceeds the max-lease-misbalance percentage of
741         total free state leases as described above, leases are moved  to  the
742         remote server.  This is done in two passes.
743
744         In  the  first pass, only leases whose most recent bound client would
745         have been served by the remote server - according to the Load Balance
746         Algorithm  (see  above  split and hba configuration statements) - are
747         given away to the peer.  This first pass  will  happily  continue  to
748         give  away  leases, decrementing the lts value by one for each, until
749         the lts value has reached the negative of the total number of  leases
750         multiplied  by  the max-lease-ownership percentage.  So it is through
751         this value that you can permit a small misbalance of the lease  pools
752         -  for  the  purpose  of  giving  the peer more than a 50/50 share of
753         leases in the hopes that their clients might some day return  and  be
754         allocated by the peer (operating normally).  This process is referred
755         to as ´MAC Address Affinity´,  but  this  is  somewhat  misnamed:  it
756         applies  equally  to  DHCP Client Identifier options.  Note also that
757         affinity is applied to leases when they enter the state  ´free´  from
758         ´expired´ or ´released´.  In this case also, leases will not be moved
759         from free to backup if the secondary already has more than its share.
760
761         The second pass is only entered into  if  the  first  pass  fails  to
762         reduce  the lts underneath the total number of free state leases mul‐
763         tiplied by the max-lease-ownership percentage.   In  this  pass,  the
764         oldest leases are given over to the peer without second thought about
765         the Load Balance Algorithm, and this continues until  the  lts  falls
766         under  this  value.   In this way, the local server will also happily
767         keep a small percentage of the leases that would normally  load  bal‐
768         ance to itself.
769
770         So,  the  max-lease-misbalance  value  acts  as  a  behavioural gate.
771         Smaller values will cause more leases to transition states to balance
772         the pools over time, higher values will decrease the amount of change
773         (but may lead to pool starvation if there's a run on leases).
774
775         The max-lease-ownership value permits a small  (percentage)  skew  in
776         the  lease  balance of a percentage of the total number of free state
777         leases.
778
779         Finally, the min-balance and max-balance make certain that  a  sched‐
780         uled rebalance event happens within a reasonable timeframe (not to be
781         thrown off by, for example, a 7 year old free lease).
782
783         Plausible values for the percentages lie between 0  and  100,  inclu‐
784         sive, but values over 50 are indistinguishable from one another (once
785         lts exceeds 50% of the free state leases, one server  must  therefore
786         have  100% of the leases in its respective free state).  It is recom‐
787         mended to select a max-lease-ownership value that is lower  than  the
788         value  selected for the max-lease-misbalance value.  max-lease-owner‐
789         ship defaults to 10, and max-lease-misbalance defaults to 15.
790
791         Plausible values for the min-balance and max-balance times also range
792         from  0  to  (2^32)-1  (or the limit of your local time_t value), but
793         default to values 60 and 3600 respectively (to place  balance  events
794         between 1 minute and 1 hour).
795

CLIENT CLASSING

797       Clients  can be separated into classes, and treated differently depend‐
798       ing on what class they are in.  This separation can be done either with
799       a  conditional  statement,  or  with a match statement within the class
800       declaration.  It is possible to specify a limit on the total number  of
801       clients  within  a particular class or subclass that may hold leases at
802       one time, and it is possible to specify automatic subclassing based  on
803       the contents of the client packet.
804
805       Classing support for DHCPv6 clients was added in 4.3.0.  It follows the
806       same rules as for DHCPv4 except that support for  billing  classes  has
807       not been added yet.
808
809       To  add  clients  to  classes  based on conditional evaluation, you can
810       specify a matching expression in the class statement:
811
812       class "ras-clients" {
813         match if substring (option dhcp-client-identifier, 1, 3) = "RAS";
814       }
815
816       Please note that the values used in match  expressions  may  only  come
817       from data or options that are part of the client packet. It is not pos‐
818       sible to use values constructed through one or more  executable  state‐
819       ments.   This  stems  from  the  fact that client classification occurs
820       before any statements are executed. Attempting  to  do  so  will  yield
821       indeterminate results.
822
823       Note  that  whether  you use matching expressions or add statements (or
824       both) to classify clients, you must always write  a  class  declaration
825       for any class that you use.  If there will be no match statement and no
826       in-scope statements for a class, the declaration should look like this:
827
828       class "ras-clients" {
829       }
830

SUBCLASSES

832       In addition to classes, it is possible to declare subclasses.   A  sub‐
833       class is a class with the same name as a regular class, but with a spe‐
834       cific submatch expression which is hashed for quick matching.  This  is
835       essentially  a  speed  hack  - the main difference between five classes
836       with match expressions and one class with five subclasses  is  that  it
837       will be quicker to find the subclasses.  Subclasses work as follows:
838
839       class "allocation-class-1" {
840         match pick-first-value (option dhcp-client-identifier, hardware);
841       }
842
843       class "allocation-class-2" {
844         match pick-first-value (option dhcp-client-identifier, hardware);
845       }
846
847       subclass "allocation-class-1" 1:8:0:2b:4c:39:ad;
848       subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3;
849       subclass "allocation-class-1" 1:0:0:c4:aa:29:44;
850
851       subnet 10.0.0.0 netmask 255.255.255.0 {
852         pool {
853           allow members of "allocation-class-1";
854           range 10.0.0.11 10.0.0.50;
855         }
856         pool {
857           allow members of "allocation-class-2";
858           range 10.0.0.51 10.0.0.100;
859         }
860       }
861
862       The data following the class name in the subclass declaration is a con‐
863       stant value to use in matching the  match  expression  for  the  class.
864       When class matching is done, the server will evaluate the match expres‐
865       sion and then look the result up in the hash  table.   If  it  finds  a
866       match, the client is considered a member of both the class and the sub‐
867       class.
868
869       Subclasses can be declared with or without scope.  In the  above  exam‐
870       ple,  the  sole purpose of the subclass is to allow some clients access
871       to one address pool, while other clients are given access to the  other
872       pool,  so these subclasses are declared without scopes.  If part of the
873       purpose of the subclass were to define different parameter  values  for
874       some clients, you might want to declare some subclasses with scopes.
875
876       In  the above example, if you had a single client that needed some con‐
877       figuration parameters, while most didn't, you might write the following
878       subclass declaration for that client:
879
880       subclass "allocation-class-2" 1:08:00:2b:a1:11:31 {
881         option root-path "samsara:/var/diskless/alphapc";
882         filename "/tftpboot/netbsd.alphapc-diskless";
883       }
884
885       In  this  example,  we've  used subclassing as a way to control address
886       allocation on a per-client basis.  However, it's also possible  to  use
887       subclassing  in ways that are not specific to clients - for example, to
888       use the value of the vendor-class-identifier option to  determine  what
889       values  to  send in the vendor-encapsulated-options option.  An example
890       of this is shown under the VENDOR  ENCAPSULATED  OPTIONS  head  in  the
891       dhcp-options(5) manual page.
892

PER-CLASS LIMITS ON DYNAMIC ADDRESS ALLOCATION

894       You may specify a limit to the number of clients in a class that can be
895       assigned leases.  The effect of this will be to make it difficult for a
896       new  client  in  a  class  to get an address.  Once a class with such a
897       limit has reached its limit, the only way a new client  in  that  class
898       can  get  a  lease  is  for an existing client to relinquish its lease,
899       either by letting it  expire,  or  by  sending  a  DHCPRELEASE  packet.
900       Classes with lease limits are specified as follows:
901
902       class "limited-1" {
903         lease limit 4;
904       }
905
906       This will produce a class in which a maximum of four members may hold a
907       lease at one time.
908

SPAWNING CLASSES

910       It is possible to declare a spawning class.   A  spawning  class  is  a
911       class  that  automatically produces subclasses based on what the client
912       sends.  The reason that spawning classes were created was  to  make  it
913       possible  to  create  lease-limited classes on the fly.  The envisioned
914       application is a cable-modem environment where the ISP wishes  to  pro‐
915       vide  clients  at  a particular site with more than one IP address, but
916       does not wish to provide such clients with their own subnet,  nor  give
917       them  an  unlimited  number of IP addresses from the network segment to
918       which they are connected.
919
920       Many cable modem head-end systems can be  configured  to  add  a  Relay
921       Agent Information option to DHCP packets when relaying them to the DHCP
922       server.  These systems typically add a circuit ID or remote  ID  option
923       that uniquely identifies the customer site.  To take advantage of this,
924       you can write a class declaration as follows:
925
926       class "customer" {
927         spawn with option agent.circuit-id;
928         lease limit 4;
929       }
930
931       Now whenever a request comes in from a customer site,  the  circuit  ID
932       option  will  be checked against the class´s hash table.  If a subclass
933       is found that matches the circuit ID, the client will be classified  in
934       that  subclass and treated accordingly.  If no subclass is found match‐
935       ing the circuit ID, a new  one  will  be  created  and  logged  in  the
936       dhcpd.leases file, and the client will be classified in this new class.
937       Once the client has been classified, it will be  treated  according  to
938       the  rules  of the class, including, in this case, being subject to the
939       per-site limit of four leases.
940
941       The use of the subclass spawning mechanism is not restricted  to  relay
942       agent  options  - this particular example is given only because it is a
943       fairly straightforward one.
944

COMBINING MATCH, MATCH IF AND SPAWN WITH

946       In some cases, it may be useful to  use  one  expression  to  assign  a
947       client  to a particular class, and a second expression to put it into a
948       subclass of that class.  This can be done by combining the match if and
949       spawn with statements, or the match if and match statements.  For exam‐
950       ple:
951
952       class "jr-cable-modems" {
953         match if option dhcp-vendor-identifier = "jrcm";
954         spawn with option agent.circuit-id;
955         lease limit 4;
956       }
957
958       class "dv-dsl-modems" {
959         match if option dhcp-vendor-identifier = "dvdsl";
960         spawn with option agent.circuit-id;
961         lease limit 16;
962       }
963
964       This allows you to have two classes that both have the same spawn  with
965       expression without getting the clients in the two classes confused with
966       each other.
967

DYNAMIC DNS UPDATES

969       The DHCP server has the ability to dynamically update the  Domain  Name
970       System.   Within  the  configuration files, you can define how you want
971       the Domain Name System to be updated.  These updates are RFC 2136  com‐
972       pliant  so  any DNS server supporting RFC 2136 should be able to accept
973       updates from the DHCP server.
974
975       There are two DNS schemes implemented.  The interim option is based  on
976       draft  revisions  of  the  DDNS  documents while the standard option is
977       based on the RFCs for DHCP-DNS interaction and DHCIDs.  A third option,
978       ad-hoc,  was  deprecated  and  has now been removed from the code base.
979       The DHCP server must be configured to use one of the two currently-sup‐
980       ported methods, or not to do DNS updates.
981
982       New  installations  should use the standard option. Older installations
983       may want to continue using the interim option for backwards compatibil‐
984       ity  with the DNS database until the database can be updated.  This can
985       be done with the ddns-update-style configuration parameter.
986

THE DNS UPDATE SCHEME

988       the interim and standard DNS update schemes operate mostly according to
989       work  from  the  IETF.   The interim version was based on the drafts in
990       progress at the time while the standard is based on the completed RFCs.
991       The standard RFCs are:
992
993                            RFC 4701 (updated by RF5494)
994                                      RFC 4702
995                                      RFC 4703
996
997       And the corresponding drafts were:
998
999                          draft-ietf-dnsext-dhcid-rr-??.txt
1000                          draft-ietf-dhc-fqdn-option-??.txt
1001                        draft-ietf-dhc-ddns-resolution-??.txt
1002
1003       The  basic framework for the two schemes is similar with the main mate‐
1004       rial difference being that a DHCID RR is used in the  standard  version
1005       while the interim versions uses a TXT RR.  The format of the TXT record
1006       bears a resemblance to the DHCID RR but it is not  equivalent  (MD5  vs
1007       SHA2, field length differences etc).
1008
1009       In these two schemes the DHCP server does not necessarily always update
1010       both the A and the PTR records.  The FQDN option includes a flag which,
1011       when sent by the client, indicates that the client wishes to update its
1012       own A record.  In that case, the server can  be  configured  either  to
1013       honor  the  client´s  intentions or ignore them.  This is done with the
1014       statement  allow  client-updates;  or  the  statement  ignore   client-
1015       updates;.  By default, client updates are allowed.
1016
1017       If the server is configured to allow client updates, then if the client
1018       sends a fully-qualified domain name in the FQDN option, the server will
1019       use  that  name  the  client  sent in the FQDN option to update the PTR
1020       record.  For example, let us say that the client is a visitor from  the
1021       "radish.org"  domain,  whose  hostname is "jschmoe".  The server is for
1022       the "example.org" domain.  The DHCP client indicates in the FQDN option
1023       that  its  FQDN  is  "jschmoe.radish.org.".   It also indicates that it
1024       wants to update its own A record.  The DHCP server therefore  does  not
1025       attempt  to  set  up  an A record for the client, but does set up a PTR
1026       record for the IP address that  it  assigns  the  client,  pointing  at
1027       jschmoe.radish.org.   Once  the  DHCP  client has an IP address, it can
1028       update its own A record, assuming that the "radish.org" DNS server will
1029       allow it to do so.
1030
1031       If  the  server  is  configured  not to allow client updates, or if the
1032       client doesn´t want to do its own update, the server will simply choose
1033       a name for the client. By default, the server will choose from the fol‐
1034       lowing three values:
1035
1036            1. fqdn option (if present)
1037            2. hostname option (if present)
1038            3. Configured hostname option (if defined).
1039
1040       If these defaults for choosing the host name are  not  appropriate  you
1041       can  write  your own statement to set the ddns-hostname variable as you
1042       wish.  If none of the above are found the server will use the host dec‐
1043       laration name (if one) and use-host-decl-names is on.
1044
1045       It  will  use  its own domain name for the client.  It will then update
1046       both the A and PTR record, using the name that it chose for the client.
1047       If  the  client sends a fully-qualified domain name in the fqdn option,
1048       the server uses only the leftmost part of the  domain  name  -  in  the
1049       example above, "jschmoe" instead of "jschmoe.radish.org".
1050
1051       Further,  if  the  ignore  client-updates;  directive is used, then the
1052       server will in addition send a response in the DHCP packet,  using  the
1053       FQDN  Option, that implies to the client that it should perform its own
1054       updates if it chooses to do so.  With deny client-updates;, a  response
1055       is sent which indicates the client may not perform updates.
1056
1057       Both  the  standard  and interim options also include a method to allow
1058       more than one DHCP server to update the DNS database  without  acciden‐
1059       tally deleting A records that shouldn´t be deleted nor failing to add A
1060       records that should be added.  For the standard option the method works
1061       as follows:
1062
1063       When  the  DHCP  server  issues a client a new lease, it creates a text
1064       string that is an SHA hash over the DHCP client´s  identification  (see
1065       RFCs  4701 & 4702 for details).  The update attempts to add an A record
1066       with the name the server chose and a DHCID record containing the hashed
1067       identifier  string  (hashid).   If  this update succeeds, the server is
1068       done.
1069
1070       If the update fails because the A record already exists, then the  DHCP
1071       server  attempts  to  add the A record with the prerequisite that there
1072       must be a DHCID record in the same name as the new A record,  and  that
1073       DHCID  record´s  contents must be equal to hashid.  If this update suc‐
1074       ceeds, then the client has its A record and PTR record.  If  it  fails,
1075       then  the  name  the client has been assigned (or requested) is in use,
1076       and can´t be used by the client.  At this point the DHCP  server  gives
1077       up  trying to do a DNS update for the client until the client chooses a
1078       new name.
1079
1080       The server also does not update very aggressively.   Because  each  DNS
1081       update involves a round trip to the DNS server, there is a cost associ‐
1082       ated with doing updates even if they do not  actually  modify  the  DNS
1083       database.   So the DHCP server tracks whether or not it has updated the
1084       record in the past (this information is stored on the lease)  and  does
1085       not attempt to update records that it thinks it has already updated.
1086
1087       This  can  lead  to cases where the DHCP server adds a record, and then
1088       the record is deleted through some  other  mechanism,  but  the  server
1089       never  again  updates  the  DNS  because  it thinks the data is already
1090       there.  In this case the data can be removed  from  the  lease  through
1091       operator  intervention,  and  once  this has been done, the DNS will be
1092       updated the next time the client renews.
1093
1094       The interim DNS update scheme was written before the RFCs  were  final‐
1095       ized  and  does  not  quite follow them.  The RFCs call for a new DHCID
1096       RRtype while the interim DNS update scheme uses a TXT record.  In addi‐
1097       tion  the  ddns-resolution  draft  called  for the DHCP server to put a
1098       DHCID RR on the PTR record, but the interim update method does  not  do
1099       this.  In the final RFC this requirement was relaxed such that a server
1100       may add a DHCID RR to the PTR record.
1101

DDNS IN DUAL STACK ENVIRONMENTS

1103       As described in RFC 4703, section 5.2, in order to perform DDNS in dual
1104       stack environments, both IPv4 and IPv6 servers would need to be config‐
1105       ured to use the standard update style and  participating  IPv4  clients
1106       MUST  convey  DUIDs  as  described  in RFC 4361, section 6.1., in their
1107       dhcp-client-identifiers.
1108
1109       In a nutshell, this mechanism is intended to use globally unique  DUIDs
1110       to  idenfity  both  IPv4  and IPv6 clients, and where a device has both
1111       IPv4 and IPv6 leases it is identified by the same DUID.  This allows  a
1112       dual  stack  client to use the same FQDN for both mappings, while being
1113       protected from updates for other  clients  by  the  rules  of  conflict
1114       detection.
1115
1116       However,  not all IPv4 clients implement this behavior which makes sup‐
1117       porting them dual stack environments problematic.  In order to  address
1118       this  issue ISC DHCP (as of 4.4.0) supports a new mode of DDNS conflict
1119       resolution referred to as Dual Stack Mixed Mode (DSMM).
1120
1121       The concept behind DSMM is relatively simple.  All dhcp servers of  one
1122       protocol  (IPv4  or v6) use one ddns-update-style (interim or standard)
1123       while all servers of the "other" protocol will use  the  "other"  ddns-
1124       udpate-style.   In  this way, all servers of a given protocol are using
1125       the same record type (TXT or DHCID) for their DHCID RR  entries.   This
1126       allows  conflict  detection to be enforced within each protocol without
1127       interferring with the other's entries.
1128
1129       DSMM modifications now ensure that IPv4 DSMM servers only ever modify A
1130       records,  their  associated  PTR  records and DHCID records, while DSMM
1131       IPv6 severs only modify AAAA records, their associated PTR records, and
1132       DHCID records.
1133
1134       Note  that  DSMM is not a perfect solution, it is a compromise that can
1135       work well provided all participating DNS updaters play by  DSMM  rules.
1136       As  with anything else in life, it only works as well as those who par‐
1137       ticpate behave.
1138
1139       While conflict detection is enabled by default, DSMM is not.  To enable
1140       DSMM,  both  update-conflict-detection  and  ddns-dual-stack-mixed-mode
1141       must be true.
1142

PROTECTING DNS ENTRIES FOR STATIC CLIENTS

1144       Built into conflict resolution  is  the  protection  of  manually  made
1145       entries  for  static clients.  Per the rules of conflict resolution,  a
1146       DNS updater may not alter forward DNS entries unless there is  a  DHCID
1147       RR  which  matches  for  whom the update is being made.  Therefore, any
1148       forward DNS entries without a corresponding DHCID RR cannot be  altered
1149       by such an updater.
1150
1151       In  some  environments,  it may be desirable to use only this aspect of
1152       conflict resolution and allow DNS updaters  to  overwrite  entries  for
1153       dynamic  clients  regardless of what client owns them.  In other words,
1154       the presence or lack of a DHCID RR is used to determine whether entries
1155       may  or  may not be overwritten.  Whether or not the client matches the
1156       data value of the DHCID RR  is  irrelevant.    This  behavior,  off  by
1157       default,  can  be configured through the parameter, ddns-guard-id-must-
1158       match.  As with DSMM, this behavior is can only be enabled if  conflict
1159       resolution  is  enabled.   This behavior should be considered carefully
1160       before electing to use it.
1161
1162       There is an additional parameter that can be used with DSMM ddns-other-
1163       guard-is-dynamic.   When  enabled along with DSMM, a server will regard
1164       the presence of a DHCID RR of the other style type as  indicating  that
1165       the  forward  DNS  entries  for  that FQDN should be dynamic and may be
1166       overwritten.  For example, such a  server  using  interim  style  could
1167       overwrite  the  DNS  entries  for an FQDN if there is only a DHDID type
1168       DHDID RR for the FQDN.  Essentially, if there are dynamic  entries  for
1169       one  protocol,  that  is  enough  to  overcome the static protection of
1170       entries for the other protocol.  This behavior warrants careful consid‐
1171       eration before electing to use it.
1172

DYNAMIC DNS UPDATE SECURITY

1174       When  you set your DNS server up to allow updates from the DHCP server,
1175       you may be exposing it to unauthorized updates.   To  avoid  this,  you
1176       should  use  TSIG  signatures  -  a method of cryptographically signing
1177       updates using a shared secret key.  As long as you protect the  secrecy
1178       of  this  key, your updates should also be secure.  Note, however, that
1179       the DHCP protocol itself provides no security,  and  that  clients  can
1180       therefore  provide information to the DHCP server which the DHCP server
1181       will then use in its updates, with  the  constraints  described  previ‐
1182       ously.
1183
1184       The  DNS  server  must be configured to allow updates for any zone that
1185       the DHCP server will be updating.  For example, let us say that clients
1186       in  the  sneedville.edu  domain  will  be  assigned  addresses  on  the
1187       10.10.17.0/24 subnet.  In that case, you will need  a  key  declaration
1188       for  the  TSIG  key you will be using, and also two zone declarations -
1189       one for the zone containing A records that will be updates and one  for
1190       the zone containing PTR records - for ISC BIND, something like this:
1191
1192       key DHCP_UPDATER {
1193         algorithm hmac-md5;
1194         secret pRP5FapFoJ95JEL06sv4PQ==;
1195       };
1196
1197       zone "example.org" {
1198            type master;
1199            file "example.org.db";
1200            allow-update { key DHCP_UPDATER; };
1201       };
1202
1203       zone "17.10.10.in-addr.arpa" {
1204            type master;
1205            file "10.10.17.db";
1206            allow-update { key DHCP_UPDATER; };
1207       };
1208
1209       You will also have to configure your DHCP server to do updates to these
1210       zones.  To do  so,  you  need  to  add  something  like  this  to  your
1211       dhcpd.conf file:
1212
1213       key DHCP_UPDATER {
1214         algorithm hmac-md5;
1215         secret pRP5FapFoJ95JEL06sv4PQ==;
1216       };
1217
1218       zone EXAMPLE.ORG. {
1219         primary 127.0.0.1;
1220         key DHCP_UPDATER;
1221       }
1222
1223       zone 17.127.10.in-addr.arpa. {
1224         primary 127.0.0.1;
1225         key DHCP_UPDATER;
1226       }
1227
1228       The primary statement specifies the IP address of the name server whose
1229       zone information is to be updated.  In addition to the  primary  state‐
1230       ment there are also the primary6 , secondary and secondary6 statements.
1231       The primary6 statement specifies an IPv6 address for the  name  server.
1232       The secondaries provide for additional addresses for name servers to be
1233       used if the primary does not respond.  The number of name  servers  the
1234       DDNS  code  will attempt to use before giving up is limited and is cur‐
1235       rently set to three.
1236
1237       Note that the zone declarations have to correspond to authority records
1238       in your name server - in the above example, there must be an SOA record
1239       for "example.org." and for "17.10.10.in-addr.arpa.".  For  example,  if
1240       there  were  a  subdomain  "foo.example.org"  with no separate SOA, you
1241       could not write a zone declaration for "foo.example.org."  Also keep in
1242       mind  that  zone  names in your DHCP configuration should end in a ".";
1243       this is the preferred syntax.  If you do not end your zone  name  in  a
1244       ".",  the  DHCP  server will figure it out.  Also note that in the DHCP
1245       configuration, zone names are not encapsulated in  quotes  where  there
1246       are in the DNS configuration.
1247
1248       You  should choose your own secret key, of course.  The ISC BIND 9 dis‐
1249       tribution comes with  a  program  for  generating  secret  keys  called
1250       dnssec-keygen.   If you are using BIND 9´s dnssec-keygen, the above key
1251       would be created as follows:
1252
1253            dnssec-keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER
1254
1255       The key name, algorithm, and secret must match that being used  by  the
1256       DNS  server.  The  DHCP  server  currently supports the following algo‐
1257       rithms:
1258
1259               HMAC-MD5
1260               HMAC-SHA1
1261               HMAC-SHA224
1262               HMAC-SHA256
1263               HMAC-SHA384
1264               HMAC-SHA512
1265
1266       You may wish to enable logging of DNS updates on your DNS  server.   To
1267       do so, you might write a logging statement like the following:
1268
1269       logging {
1270            channel update_debug {
1271                 file "/var/log/update-debug.log";
1272                 severity  debug 3;
1273                 print-category yes;
1274                 print-severity yes;
1275                 print-time     yes;
1276            };
1277            channel security_info    {
1278                 file "/var/log/named-auth.info";
1279                 severity  info;
1280                 print-category yes;
1281                 print-severity yes;
1282                 print-time     yes;
1283            };
1284
1285            category update { update_debug; };
1286            category security { security_info; };
1287       };
1288
1289       You  must  create  the  /var/log/named-auth.info  and  /var/log/update-
1290       debug.log files before starting the name server.  For more  information
1291       on configuring ISC BIND, consult the documentation that accompanies it.
1292

REFERENCE: EVENTS

1294       There  are three kinds of events that can happen regarding a lease, and
1295       it is possible to declare statements  that  occur  when  any  of  these
1296       events  happen.  These events are the commit event, when the server has
1297       made a commitment of a certain lease to a client,  the  release  event,
1298       when  the  client  has released the server from its commitment, and the
1299       expiry event, when the commitment expires.
1300
1301       To declare a set of statements to execute when an  event  happens,  you
1302       must  use the on statement, followed by the name of the event, followed
1303       by a series of statements to execute when the event  happens,  enclosed
1304       in braces.
1305

REFERENCE: DECLARATIONS

1307       The include statement
1308
1309        include "filename";
1310
1311       The  include statement is used to read in a named file, and process the
1312       contents of that file as though it were entered in place of the include
1313       statement.
1314
1315       The shared-network statement
1316
1317        shared-network name {
1318          [ parameters ]
1319          [ declarations ]
1320        }
1321
1322       The  shared-network  statement  is  used to inform the DHCP server that
1323       some IP subnets actually share the same physical network.  Any  subnets
1324       in  a  shared network should be declared within a shared-network state‐
1325       ment.  Parameters specified in the  shared-network  statement  will  be
1326       used  when  booting clients on those subnets unless parameters provided
1327       at the subnet or host level override them.  If any subnet in  a  shared
1328       network has addresses available for dynamic allocation, those addresses
1329       are collected into a common pool for that shared network  and  assigned
1330       to  clients  as needed.  There is no way to distinguish on which subnet
1331       of a shared network a client should boot.
1332
1333       Name should be the name of the shared network.  This name is used  when
1334       printing debugging messages, so it should be descriptive for the shared
1335       network.  The name may have the syntax of a valid domain name (although
1336       it  will  never  be  used  as  such),  or it may be any arbitrary name,
1337       enclosed in quotes.
1338
1339       The subnet statement
1340
1341        subnet subnet-number netmask netmask {
1342          [ parameters ]
1343          [ declarations ]
1344        }
1345
1346       The subnet statement is used to provide dhcpd with  enough  information
1347       to tell whether or not an IP address is on that subnet.  It may also be
1348       used  to  provide  subnet-specific  parameters  and  to  specify   what
1349       addresses  may be dynamically allocated to clients booting on that sub‐
1350       net.  Such addresses are specified using the range declaration.
1351
1352       The subnet-number should be an IP address or domain name which resolves
1353       to the subnet number of the subnet being described.  The netmask should
1354       be an IP address or domain name which resolves to the  subnet  mask  of
1355       the  subnet being described.  The subnet number, together with the net‐
1356       mask, are sufficient to determine whether any given IP  address  is  on
1357       the specified subnet.
1358
1359       Although  a  netmask must be given with every subnet declaration, it is
1360       recommended that if there is any variance in subnet masks at a site,  a
1361       subnet-mask  option statement be used in each subnet declaration to set
1362       the desired subnet mask, since any subnet-mask  option  statement  will
1363       override the subnet mask declared in the subnet statement.
1364
1365       The subnet6 statement
1366
1367        subnet6 subnet6-number {
1368          [ parameters ]
1369          [ declarations ]
1370        }
1371
1372       The  subnet6 statement is used to provide dhcpd with enough information
1373       to tell whether or not an IPv6 address is on that subnet6.  It may also
1374       be  used  to  provide  subnet-specific  parameters  and to specify what
1375       addresses may be dynamically allocated to clients booting on that  sub‐
1376       net.
1377
1378       The  subnet6-number  should be an IPv6 network identifier, specified as
1379       ip6-address/bits.
1380
1381       The range statement
1382
1383       range [ dynamic-bootp ] low-address [ high-address];
1384
1385       For any subnet on which addresses will be assigned  dynamically,  there
1386       must  be  at  least one range statement.  The range statement gives the
1387       lowest and highest IP addresses in a range.  All IP  addresses  in  the
1388       range should be in the subnet in which the range statement is declared.
1389       The dynamic-bootp flag may be specified if addresses in  the  specified
1390       range  may  be  dynamically  assigned  to BOOTP clients as well as DHCP
1391       clients.  When specifying a single address, high-address can  be  omit‐
1392       ted.
1393
1394       The range6 statement
1395
1396       range6 low-address high-address;
1397       range6 subnet6-number;
1398       range6 subnet6-number temporary;
1399       range6 address temporary;
1400
1401       For  any  IPv6 subnet6 on which addresses will be assigned dynamically,
1402       there must be at least one range6 statement. The range6  statement  can
1403       either  be  the  lowest  and highest IPv6 addresses in a range6, or use
1404       CIDR notation, specified as ip6-address/bits. All IP addresses  in  the
1405       range6  should  be  in  the  subnet6  in  which the range6 statement is
1406       declared.
1407
1408       The temporary variant makes the prefix (by default on 64  bits)  avail‐
1409       able  for  temporary  (RFC 4941) addresses. A new address per prefix in
1410       the shared network is computed at each request with  an  IA_TA  option.
1411       Release and Confirm ignores temporary addresses.
1412
1413       Any IPv6 addresses given to hosts with fixed-address6 are excluded from
1414       the range6, as are IPv6 addresses on the server itself.
1415
1416       The prefix6 statement
1417
1418       prefix6 low-address high-address / bits;
1419
1420       The prefix6 is the range6 equivalent for Prefix Delegation (RFC  3633).
1421       Prefixes  of  bits  length  are  assigned between low-address and high-
1422       address.
1423
1424       Any IPv6 prefixes given to static entries  (hosts)  with  fixed-prefix6
1425       are excluded from the prefix6.
1426
1427       This  statement is currently global but it should have a shared-network
1428       scope.
1429
1430       The host statement
1431
1432        host hostname {
1433          [ parameters ]
1434          [ declarations ]
1435        }
1436
1437       The host declaration provides a way for the DHCP server to  identify  a
1438       DHCP  or BOOTP client.  This allows the server to provide configuration
1439       information including fixed addresses or, in DHCPv6, fixed prefixes for
1440       a specific client.
1441
1442       If  it  is  desirable to be able to boot a DHCP or BOOTP client on more
1443       than one subnet with fixed v4 addresses, more than one address  may  be
1444       specified  in  the  fixed-address  declaration,  or  more than one host
1445       statement may be specified matching the same client.
1446
1447       The fixed-address6 declaration is used for v6 addresses.  At this  time
1448       it  only  works  with a single address.  For multiple addresses specify
1449       multiple host statements.
1450
1451       If client-specific boot parameters must change based on the network  to
1452       which the client is attached, then multiple host declarations should be
1453       used.  The host declarations will only match a client if one  of  their
1454       fixed-address  statements  is  viable on the subnet (or shared network)
1455       where the client is attached.  Conversely, for a  host  declaration  to
1456       match  a client being allocated a dynamic address, it must not have any
1457       fixed-address statements.  You may therefore need  a  mixture  of  host
1458       declarations  for  any  given client...some having fixed-address state‐
1459       ments, others without.
1460
1461       hostname should be a name identifying the host.  If a  hostname  option
1462       is not specified for the host, hostname is used.
1463
1464       Host declarations are matched to actual DHCP or BOOTP clients by match‐
1465       ing the dhcp-client-identifier or pxe-client-id  options  specified  in
1466       the host declaration to the one supplied by the client, or, if the host
1467       declaration or the client does not provide a dhcp-client-identifier  or
1468       pxe-client-id  options,  by matching the hardware parameter in the host
1469       declaration to the network hardware address  supplied  by  the  client.
1470       BOOTP  clients do not normally provide a dhcp-client-identifier, so the
1471       hardware address must be used for all clients that may boot  using  the
1472       BOOTP protocol.
1473
1474       DHCPv6 servers can use the host-identifier option parameter in the host
1475       declaration, and specify any option with  a  fixed  value  to  identify
1476       hosts.
1477
1478       Please  be aware that only the dhcp-client-identifier and pxe-client-id
1479       options and the hardware address can be used to match a  host  declara‐
1480       tion,  or the host-identifier option parameter for DHCPv6 servers.  For
1481       example, it is not possible to match a host declaration to a  host-name
1482       option.   This  is because the host-name option cannot be guaranteed to
1483       be unique for any given client, whereas both the hardware  address  and
1484       dhcp-client-identifier  option are at least theoretically guaranteed to
1485       be unique to a given client.
1486
1487       The group statement
1488
1489        group {
1490          [ parameters ]
1491          [ declarations ]
1492        }
1493
1494       The group statement is used simply to apply one or more parameters to a
1495       group of declarations.  It can be used to group hosts, shared networks,
1496       subnets, or even other groups.
1497

REFERENCE: ALLOW AND DENY

1499       The allow and deny statements can be used to control  the  response  of
1500       the  DHCP server to various sorts of requests.  The allow and deny key‐
1501       words actually have different meanings depending on the context.  In  a
1502       pool  context,  these  keywords  can be used to set up access lists for
1503       address allocation pools.  In other contexts, the keywords simply  con‐
1504       trol  general  server  behavior with respect to clients based on scope.
1505       In a non-pool context, the ignore keyword can be used in place  of  the
1506       deny keyword to prevent logging of denied requests.
1507

ALLOW DENY AND IGNORE IN SCOPE

1509       The following usages of allow and deny will work in any scope, although
1510       it is not recommended that they be used in pool declarations.
1511
1512       The unknown-clients keyword
1513
1514        allow unknown-clients;
1515        deny unknown-clients;
1516        ignore unknown-clients;
1517
1518       The unknown-clients flag is used to tell dhcpd whether or not to dynam‐
1519       ically assign addresses to unknown clients.  Dynamic address assignment
1520       to unknown clients is allowed by default.  An unknown client is  simply
1521       a client that has no host declaration.
1522
1523       The  use  of  this  option  is  now  deprecated.   If you are trying to
1524       restrict access on your network to known clients, you should  use  deny
1525       unknown-clients;  inside  of  your address pool, as described under the
1526       heading ALLOW AND DENY WITHIN POOL DECLARATIONS.
1527
1528       The bootp keyword
1529
1530        allow bootp;
1531        deny bootp;
1532        ignore bootp;
1533
1534       The bootp flag is used to tell dhcpd whether or not to respond to bootp
1535       queries.  Bootp queries are allowed by default.
1536
1537       The booting keyword
1538
1539        allow booting;
1540        deny booting;
1541        ignore booting;
1542
1543       The  booting  flag  is  used to tell dhcpd whether or not to respond to
1544       queries from a particular client.  This keyword only has  meaning  when
1545       it  appears in a host declaration.  By default, booting is allowed, but
1546       if it is disabled for a particular client, then that client will not be
1547       able to get an address from the DHCP server.
1548
1549       The duplicates keyword
1550
1551        allow duplicates;
1552        deny duplicates;
1553
1554       Host  declarations  can  match client messages based on the DHCP Client
1555       Identifier option or based on the client's network  hardware  type  and
1556       MAC  address.   If  the  MAC address is used, the host declaration will
1557       match any client with that MAC address - even  clients  with  different
1558       client identifiers.  This doesn't normally happen, but is possible when
1559       one computer has more than one operating system installed on it  -  for
1560       example, Microsoft Windows and NetBSD or Linux.
1561
1562       The duplicates flag tells the DHCP server that if a request is received
1563       from a client that matches the MAC address of a host  declaration,  any
1564       other  leases  matching  that  MAC  address  should be discarded by the
1565       server, even if the UID is not the same.  This is a  violation  of  the
1566       DHCP  protocol, but can prevent clients whose client identifiers change
1567       regularly from holding many leases  at  the  same  time.   By  default,
1568       duplicates are allowed.
1569
1570       The declines keyword
1571
1572        allow declines;
1573        deny declines;
1574        ignore declines;
1575
1576       The  DHCPDECLINE  message  is used by DHCP clients to indicate that the
1577       lease the server has offered is not valid.  When the server receives  a
1578       DHCPDECLINE  for  a  particular  address,  it  normally  abandons  that
1579       address, assuming that some unauthorized system is using it.   Unfortu‐
1580       nately,  a  malicious  or buggy client can, using DHCPDECLINE messages,
1581       completely exhaust the DHCP server's allocation pool.  The server  will
1582       eventually  reclaim  these  leases, but not while the client is running
1583       through the pool. This may cause serious thrashing in the DNS,  and  it
1584       will also cause the DHCP server to forget old DHCP client address allo‐
1585       cations.
1586
1587       The declines flag tells the DHCP server whether or not to honor DHCPDE‐
1588       CLINE  messages.  If it is set to deny or ignore in a particular scope,
1589       the DHCP server will not respond to DHCPDECLINE messages.
1590
1591       The declines flag is only supported by DHCPv4 servers.  Given the large
1592       IPv6  address  space  and  the  internal limits imposed by the server's
1593       address generation mechanism we don't think it is necessary for  DHCPv6
1594       servers at this time.
1595
1596       Currently, abandoned IPv6 addresses are reclaimed in one of two ways:
1597           a) Client renews a specific address:
1598           If a client using a given DUID submits a DHCP REQUEST containing
1599           the last address abandoned by that DUID, the address will be
1600           reassigned to that client.
1601
1602           b) Upon the second restart following an address abandonment.  When
1603           an address is abandoned it is both recorded as such in the lease
1604           file and retained as abandoned in server memory until the server
1605           is restarted. Upon restart, the server will process the lease file
1606           and all addresses whose last known state is abandoned will be
1607           retained as such in memory but not rewritten to the lease file.
1608           This means that a subsequent restart of the server will not see the
1609           abandoned addresses in the lease file and therefore have no record
1610           of them as abandoned in memory and as such perceive them as free
1611           for assignment.
1612
1613       The total number addresses in a pool, available for a given DUID value,
1614       is internally limited by the server's address generation mechanism.  If
1615       through  mistaken  configuration,  multiple  clients are using the same
1616       DUID they will competing for the same addresses causing the  server  to
1617       reach  this internal limit rather quickly.  The internal limit isolates
1618       this type of activity such that address  range  is  not  exhausted  for
1619       other  DUID  values.  The appearance of the following error log, can be
1620       an indication of this condition:
1621
1622           "Best match for DUID <XX> is an abandoned address, This may be a
1623            result of multiple clients attempting to use this DUID"
1624
1625           where <XX> is an actual DUID value depicted as colon separated
1626           string of bytes in hexadecimal values.
1627
1628       The client-updates keyword
1629
1630        allow client-updates;
1631        deny client-updates;
1632
1633       The client-updates flag tells the DHCP server whether or not  to  honor
1634       the  client's  intention to do its own update of its A record.  See the
1635       documentation under the heading THE DNS UPDATE SCHEME for details.
1636
1637       The leasequery keyword
1638
1639        allow leasequery;
1640        deny leasequery;
1641
1642       The leasequery flag tells the DHCP server whether or not to answer DHC‐
1643       PLEASEQUERY  packets.  The  answer  to a DHCPLEASEQUERY packet includes
1644       information about a specific lease, such as when it was issued and when
1645       it  will expire. By default, the server will not respond to these pack‐
1646       ets.
1647

ALLOW AND DENY WITHIN POOL DECLARATIONS

1649       The uses of the allow and deny keywords shown in the  previous  section
1650       work  pretty much the same way whether the client is sending a DHCPDIS‐
1651       COVER or a DHCPREQUEST message - an address will be  allocated  to  the
1652       client  (either  the old address it's requesting, or a new address) and
1653       then that address will be tested to see if it's okay to let the  client
1654       have  it.   If  the  client requested it, and it's not okay, the server
1655       will send a DHCPNAK message.  Otherwise, the  server  will  simply  not
1656       respond  to  the  client.   If  it  is  okay to give the address to the
1657       client, the server will send a DHCPACK message.
1658
1659       The primary motivation behind pool  declarations  is  to  have  address
1660       allocation pools whose allocation policies are different.  A client may
1661       be denied access to one pool, but allowed access to another pool on the
1662       same network segment.  In order for this to work, access control has to
1663       be done during address allocation,  not  after  address  allocation  is
1664       done.
1665
1666       When a DHCPREQUEST message is processed, address allocation simply con‐
1667       sists of looking up the address the client is requesting and seeing  if
1668       it's  still  available  for the client.  If it is, then the DHCP server
1669       checks both the address pool permit lists  and  the  relevant  in-scope
1670       allow  and deny statements to see if it's okay to give the lease to the
1671       client.  In the case of a DHCPDISCOVER message, the allocation  process
1672       is done as described previously in the ADDRESS ALLOCATION section.
1673
1674       When declaring permit lists for address allocation pools, the following
1675       syntaxes are recognized following the allow or deny keywords:
1676
1677        known-clients;
1678
1679       If specified, this statement either allows or prevents allocation  from
1680       this  pool  to any client that has a host declaration (i.e., is known).
1681       A client is known if it has a host declaration in any scope,  not  just
1682       the current scope.
1683
1684        unknown-clients;
1685
1686       If  specified, this statement either allows or prevents allocation from
1687       this pool to any client that has no  host  declaration  (i.e.,  is  not
1688       known).
1689
1690        members of "class";
1691
1692       If  specified, this statement either allows or prevents allocation from
1693       this pool to any client that is a member of the named class.
1694
1695        dynamic bootp clients;
1696
1697       If specified, this statement either allows or prevents allocation  from
1698       this pool to any bootp client.
1699
1700        authenticated clients;
1701
1702       If  specified, this statement either allows or prevents allocation from
1703       this pool to any client that has  been  authenticated  using  the  DHCP
1704       authentication protocol.  This is not yet supported.
1705
1706        unauthenticated clients;
1707
1708       If  specified, this statement either allows or prevents allocation from
1709       this pool to any client that has not been authenticated using the  DHCP
1710       authentication protocol.  This is not yet supported.
1711
1712        all clients;
1713
1714       If  specified, this statement either allows or prevents allocation from
1715       this pool to all clients.  This can be used when you want  to  write  a
1716       pool  declaration  for some reason, but hold it in reserve, or when you
1717       want to renumber your network quickly, and  thus  want  the  server  to
1718       force  all clients that have been allocated addresses from this pool to
1719       obtain new addresses immediately when they next renew.
1720
1721        after time;
1722
1723       If specified, this statement either allows or prevents allocation  from
1724       this  pool  after  a given date. This can be used when you want to move
1725       clients from one pool to another. The server adjusts the regular  lease
1726       time  so  that  the  latest expiry time is at the given time+min-lease-
1727       time.  A short min-lease-time enforces a step change, whereas a  longer
1728       min-lease-time  allows  for  a  gradual  change.  time is either second
1729       since epoch, or a UTC time string e.g.   4  2007/08/24  09:14:32  or  a
1730       string  with  time  zone  offset  in seconds e.g. 4 2007/08/24 11:14:32
1731       -7200
1732

REFERENCE: PARAMETERS

1734       The abandon-lease-time statement
1735
1736         abandon-lease-time time;
1737
1738         Time should be the maximum amount of time (in seconds) that an  aban‐
1739         doned  IPv4  lease  remains  unavailable  for assignment to a client.
1740         Abandoned leases will only be offered to clients if there are no free
1741         leases.  If not defined, the default abandon lease time is 86400 sec‐
1742         onds (24 hours).  Note the abandoned lease time for a given lease  is
1743         preserved  across  server restarts.  The parameter may only be set at
1744         the global scope and is evaluated only once during server startup.
1745
1746         Values less than sixty seconds are not recommended as this  is  below
1747         the  ping  check  threshold  and  can cause leases once abandoned but
1748         since returned to the free  state  to  not  be  pinged  before  being
1749         offered.   If the requested time is larger than 0x7FFFFFFF - 1 or the
1750         sum of the current  time  plus  the  abandoned  time  isgreater  than
1751         0x7FFFFFFF it is treated as infinite.
1752
1753       The adaptive-lease-time-threshold statement
1754
1755         adaptive-lease-time-threshold percentage;
1756
1757         When  the  number  of  allocated leases within a pool rises above the
1758         percentage given in this statement, the  DHCP  server  decreases  the
1759         lease  length for new clients within this pool to min-lease-time sec‐
1760         onds. Clients renewing an already valid (long) leases  get  at  least
1761         the  remaining  time  from the current lease. Since the leases expire
1762         faster, the server may either recover  more  quickly  or  avoid  pool
1763         exhaustion  entirely.  Once the number of allocated leases drop below
1764         the threshold, the server reverts back to normal lease times.   Valid
1765         percentages are between 1 and 99.
1766
1767       The always-broadcast statement
1768
1769         always-broadcast flag;
1770
1771         The  DHCP  and BOOTP protocols both require DHCP and BOOTP clients to
1772         set the broadcast bit in the flags field of the BOOTP message header.
1773         Unfortunately, some DHCP and BOOTP clients do not do this, and there‐
1774         fore may not receive responses from the DHCP server.  The DHCP server
1775         can  be  made to always broadcast its responses to clients by setting
1776         this flag to ´on´ for the relevant scope; relevant  scopes  would  be
1777         inside  a  conditional statement, as a parameter for a class, or as a
1778         parameter for a host declaration.  To avoid creating excess broadcast
1779         traffic  on  your  network, we recommend that you restrict the use of
1780         this option to as few clients as possible.  For example,  the  Micro‐
1781         soft  DHCP client is known not to have this problem, as are the Open‐
1782         Transport and ISC DHCP clients.
1783
1784       The always-reply-rfc1048 statement
1785
1786         always-reply-rfc1048 flag;
1787
1788         Some BOOTP clients expect RFC1048-style responses, but do not  follow
1789         RFC1048  when  sending their requests.  You can tell that a client is
1790         having this problem if it is not getting the options you have config‐
1791         ured  for  it  and  if  you  see in the server log the message "(non-
1792         rfc1048)" printed with each BOOTREQUEST that is logged.
1793
1794         If you want to send rfc1048 options to such a client, you can set the
1795         always-reply-rfc1048  option  in  that client's host declaration, and
1796         the DHCP server will respond with an  RFC-1048-style  vendor  options
1797         field.   This  flag  can  be  set  in  any scope, and will affect all
1798         clients covered by that scope.
1799
1800       The authoritative statement
1801
1802         authoritative;
1803
1804         not authoritative;
1805
1806         The DHCP server will normally assume that the configuration  informa‐
1807         tion  about a given network segment is not known to be correct and is
1808         not authoritative.  This is so that if a naive user installs  a  DHCP
1809         server  not fully understanding how to configure it, it does not send
1810         spurious DHCPNAK messages to clients  that  have  obtained  addresses
1811         from a legitimate DHCP server on the network.
1812
1813         Network  administrators  setting  up  authoritative  DHCP servers for
1814         their networks should always write authoritative; at the top of their
1815         configuration file to indicate that the DHCP server should send DHCP‐
1816         NAK messages to misconfigured clients.  If this is not done,  clients
1817         will  be  unable  to  get a correct IP address after changing subnets
1818         until their old lease has expired, which  could  take  quite  a  long
1819         time.
1820
1821         Usually,  writing  authoritative; at the top level of the file should
1822         be sufficient.  However, if a DHCP server is to be set up so that  it
1823         is aware of some networks for which it is authoritative and some net‐
1824         works for which it is not, it may  be  more  appropriate  to  declare
1825         authority on a per-network-segment basis.
1826
1827         Note  that the most specific scope for which the concept of authority
1828         makes any sense is the physical network segment -  either  a  shared-
1829         network  statement or a subnet statement that is not contained within
1830         a shared-network statement.  It is not meaningful to specify that the
1831         server is authoritative for some subnets within a shared network, but
1832         not authoritative for others, nor is it meaningful  to  specify  that
1833         the  server  is authoritative for some host declarations and not oth‐
1834         ers.
1835
1836       The boot-unknown-clients statement
1837
1838         boot-unknown-clients flag;
1839
1840         If the boot-unknown-clients statement is present and has a  value  of
1841         false  or  off,  then  clients for which there is no host declaration
1842         will not be allowed to obtain IP addresses.  If this statement is not
1843         present  or has a value of true or on, then clients without host dec‐
1844         larations will be allowed to obtain IP addresses, as  long  as  those
1845         addresses  are  not  restricted  by  allow and deny statements within
1846         their pool declarations.
1847
1848       The check-secs-byte-order statement
1849
1850         check-secs-byte-order flag;
1851
1852         When check-secs-byte-order is enabled,  the  server  will  check  for
1853         DHCPv4  clients  that  do  the byte ordering on the secs field incor‐
1854         rectly. This field should be in network byte order but  some  clients
1855         get  it wrong. When this parameter is enabled the server will examine
1856         the secs field and if it looks wrong (high byte non zero and low byte
1857         zero)  swap  the  bytes.   The default is disabled. This parameter is
1858         only useful when doing load  balancing  within  failover.  (Formerly,
1859         this  behavior had to be enabled during compilation configuration via
1860         --enable-secs-byteorder).
1861
1862         The db-time-format statement
1863
1864            db-time-format [ default | local ] ;
1865
1866            The DHCP server software outputs several timestamps  when  writing
1867            leases   to  persistent  storage.   This  configuration  parameter
1868            selects one of two output formats.  The default format prints  the
1869            day, date, and time in UTC, while the local format prints the sys‐
1870            tem seconds-since-epoch, and helpfully provides the day  and  time
1871            in  the  system  timezone  in  a  comment.   The  time formats are
1872            described in detail in the dhcpd.leases(5) manpage.
1873
1874         The ddns-hostname statement
1875
1876            ddns-hostname name;
1877
1878            The name parameter should be the hostname that  will  be  used  in
1879            setting up the client's A and PTR records.  If no ddns-hostname is
1880            specified in scope, then the server will derive the hostname auto‐
1881            matically,  using an algorithm that varies for each of the differ‐
1882            ent update methods.
1883
1884         The ddns-domainname statement
1885
1886            ddns-domainname name;
1887
1888            The name parameter should be the domain name that will be appended
1889            to  the  client's  hostname  to form a fully-qualified domain-name
1890            (FQDN).
1891
1892         The ddns-dual-stack-mixed-mode statement
1893
1894            ddns-dual-stack-mixed-mode flag;
1895
1896            The ddns-dual-stack-mixed-mode parameter controls whether  or  not
1897            the  server  applies  Dual Stack Mixed Mode rules during DDNS con‐
1898            flict resolution.  This parameter is off by default, has no effect
1899            unless update-conflict-detection is enabled, and may only be spec‐
1900            ified at the global scope.
1901
1902         The ddns-guard-id-must-match statement
1903
1904            ddns-guard-id-must-match flag;
1905
1906            The ddns-guard-id-must-match parameter controls whether or  not  a
1907            the  client  id  within  a  DHCID  RR  must  match that of the DNS
1908            update's client to permit DNS entries associated with  that  DHCID
1909            RR  to  be  ovewritten.   Proper  conflict  resolution requires ID
1910            matching and should only be disabled after careful  consideration.
1911            When disabled, it is allows any DNS updater to replace DNS entries
1912            that have an associated DHCID RR, regardless of  client  identity.
1913            This  parameter is on by default, has no effect unless update-con‐
1914            flict-detection is enabled, and  may  only  be  specified  at  the
1915            global scope.
1916
1917         The dns-local-address4 and dns-local-address6 statements
1918
1919            ddns-local-address4 address;
1920
1921            ddns-local-address6 address;
1922
1923            The address parameter should be the local IPv4 or IPv6 address the
1924            server should use as the from address  when  sending  DDNS  update
1925            requests.
1926
1927         The ddns-other-guard-is-dynamic statement
1928
1929            ddns-other-guard-is-dynamic flag;
1930
1931            The  ddns-other-guard-is-dynamic parameter controls whether or not
1932            a a server running DSMM will consider the presence  of  the  other
1933            update  style  DHCID  RR as an indcation that a DNS entries may be
1934            overwritten. It should only be enabled after careful study  as  it
1935            allows DNS entries that would otherwise be protected as static, to
1936            be overwritten in certain cases. This paramater is off by default,
1937            has  no  effect  unless ddns-dual-stack-mixed-mode is enabled, and
1938            may only be specified at the global scope.
1939
1940         The ddns-rev-domainname statement
1941
1942            ddns-rev-domainname name;
1943
1944            The name parameter should be the domain name that will be appended
1945            to  the  client's reversed IP address to produce a name for use in
1946            the client's PTR record.  By default, this is "in-addr.arpa.", but
1947            the default can be overridden here.
1948
1949            The  reversed  IP address to which this domain name is appended is
1950            always the IP address of the  client,  in  dotted  quad  notation,
1951            reversed  -  for example, if the IP address assigned to the client
1952            is 10.17.92.74, then the reversed IP address is 74.92.17.10.  So a
1953            client  with  that  IP  address  would, by default, be given a PTR
1954            record of 10.17.92.74.in-addr.arpa.
1955
1956         The ddns-update-style parameter
1957
1958            ddns-update-style style;
1959
1960            The style parameter must be one of standard, interim or none.  The
1961            ddns-update-style  statement is only meaningful in the outer scope
1962            - it is evaluated once after reading the dhcpd.conf  file,  rather
1963            than  each time a client is assigned an IP address, so there is no
1964            way to use different DNS update styles for different clients.  The
1965            default is none.
1966
1967         The ddns-updates statement
1968
1969             ddns-updates flag;
1970
1971            The ddns-updates parameter controls whether or not the server will
1972            attempt to do a DNS update when a lease is confirmed.  Set this to
1973            off  if  the server should not attempt to do updates within a cer‐
1974            tain scope.  The ddns-updates parameter is on by default.  To dis‐
1975            able  DNS updates in all scopes, it is preferable to use the ddns-
1976            update-style statement, setting the style to none.
1977
1978         The default-lease-time statement
1979
1980            default-lease-time time;
1981
1982            Time should be the length in seconds that will be  assigned  to  a
1983            lease  if  the client requesting the lease does not ask for a spe‐
1984            cific expiration time.  This is used for both  DHCPv4  and  DHCPv6
1985            leases  (it is also known as the "valid lifetime" in DHCPv6).  The
1986            default is 43200 seconds.
1987
1988         The delayed-ack and max-ack-delay statements
1989
1990            delayed-ack count;
1991
1992            max-ack-delay microseconds;
1993
1994            Count should be an integer value from zero to 2^16-1 and  defaults
1995            to 0, which means that the feature is disabled.  Otherwise, 28 may
1996            be a sensible starting point for  many  configurations  (SO_SNDBUF
1997            size  /  576 bytes.)  The count represents how many DHCPv4 replies
1998            maximum will be queued pending transmission until after a database
1999            commit  event.  If this number is reached, a database commit event
2000            (commonly resulting in  fsync()  and  representing  a  performance
2001            penalty)  will  be made, and the reply packets will be transmitted
2002            in a batch afterwards.  This preserves the RFC2131 direction  that
2003            "stable  storage" be updated prior to replying to clients.  Should
2004            the DHCPv4 sockets "go dry" (select() returns immediately with  no
2005            read  sockets),  the  commit  is  made  and any queued packets are
2006            transmitted.
2007
2008            Similarly, microseconds indicates how many microseconds  are  per‐
2009            mitted  to  pass  inbetween queuing a packet pending an fsync, and
2010            performing the fsync.  Valid values range from 0  to  2^32-1,  and
2011            defaults to 250,000 (1/4 of a second).
2012
2013            The delayed-ack feature is compiled in by default, but can be dis‐
2014            abled at compile time  with  ´./configure  --disable-delayed-ack´.
2015            Please note that the delayed-ack feature is not currently compati‐
2016            ble with support for DHPCv4-over-DHCPv6 so when a 4to6 port ommand
2017            line  argument enables this in the server the delayed-ack value is
2018            reset to 0.
2019
2020         The dhcp-cache-threshold statement
2021
2022            dhcp-cache-threshold percentage;
2023
2024            The dhcp-cache-threshold statement  takes  one  integer  parameter
2025            with  allowed  values  between  0 and 100. The default value is 25
2026            (25% of the lease time). This parameter expresses  the  percentage
2027            of the total lease time, measured from the beginning, during which
2028            a client's attempt to renew its lease will result in  getting  the
2029            already  assigned lease, rather than an extended lease.  This fea‐
2030            ture is supported for both IPv4 and IPv6  and  down  to  the  pool
2031            level and for IPv6 all three pool types: NA, TA and PD.
2032
2033            Clients  that  attempt  renewal frequently can cause the server to
2034            update and write the database frequently resulting  in  a  perfor‐
2035            mance  impact  on  the server.  The dhcp-cache-threshold statement
2036            instructs the DHCP server to avoid updating leases too  frequently
2037            thus  avoiding this behavior.  Instead the server replies with the
2038            same lease (i.e. reuses it) with no modifications except for  CLTT
2039            (Client Last Transmission Time) and for IPv4:
2040
2041                the lease time sent to the client is shortened by the age of
2042                the lease
2043
2044            while for IPv6:
2045
2046                the preferred and valid lifetimes sent to the client are
2047                shortened by the age of the lease.
2048
2049            None of these changes require writing the lease to disk.
2050
2051
2052            When an existing lease is matched to a renewing client, it will be
2053            reused if all of the following conditions are true:
2054                1. The dhcp-cache-threshold is larger than zero
2055                2. The current lease is active
2056                3. The percentage of the lease time that has elapsed is less than
2057                dhcp-cache-threshold
2058                4. The client information provided in the renewal does not alter
2059                any of the following:
2060                   a. DNS information and DNS updates are enabled
2061                   b. Billing class to which the lease is associated (IPv4 only)
2062                   c. The host declaration associated with the lease (IPv4 only)
2063                   d. The client id - this may happen if a client boots without
2064                      a client id and then starts using one in subsequent
2065                      requests. (IPv4 only)
2066
2067            While lease data is not written to disk when a  lease  is  reused,
2068            the server will still execute any on-commit statements.
2069
2070            Note  that  the  lease  can be reused if the options the client or
2071            relay agent sends are changed.  These changes will not be recorded
2072            in  the  in-memory  or  on-disk  databases until the client renews
2073            after the threshold time is reached.
2074
2075         The do-forward-updates statement
2076
2077            do-forward-updates flag;
2078
2079            The do-forward-updates statement instructs the DHCP server  as  to
2080            whether  it should attempt to update a DHCP client´s A record when
2081            the client acquires or renews a  lease.   This  statement  has  no
2082            effect  unless  DNS  updates  are  enabled.   Forward  updates are
2083            enabled by default.  If this statement is used to disable  forward
2084            updates, the DHCP server will never attempt to update the client´s
2085            A record, and will only ever attempt to update  the  client´s  PTR
2086            record if the client supplies an FQDN that should be placed in the
2087            PTR record using the fqdn option.  If forward updates are enabled,
2088            the DHCP server will still honor the setting of the client-updates
2089            flag.
2090
2091         The dont-use-fsync statement
2092
2093            dont-use-fsync flag;
2094
2095            The dont-use-fsync statement  instructs  the  DHCP  server  if  it
2096            should  call  fsync()  when  writing leases to the lease file.  By
2097            default and if the flag is set  to  false  the  server  will  call
2098            fsync().  Suppressing the call to fsync() may increase the perfor‐
2099            mance of the server but it also adds a risk that a lease will  not
2100            be  properly  written  to  the  disk after it has been issued to a
2101            client and before the server stops.  This can  lead  to  duplicate
2102            leases  being  issued  to different clients.  Using this option is
2103            not recommended.
2104
2105         The dynamic-bootp-lease-cutoff statement
2106
2107            dynamic-bootp-lease-cutoff date;
2108
2109            The dynamic-bootp-lease-cutoff statement sets the ending time  for
2110            all  leases  assigned dynamically to BOOTP clients.  Because BOOTP
2111            clients do not have any way of renewing  leases,  and  don't  know
2112            that  their leases could expire, by default dhcpd assigns infinite
2113            leases to all BOOTP clients.  However, it may make sense  in  some
2114            situations  to  set a cutoff date for all BOOTP leases - for exam‐
2115            ple, the end of a school term, or the time at night when a  facil‐
2116            ity is closed and all machines are required to be powered off.
2117
2118            Date  should  be  the date on which all assigned BOOTP leases will
2119            end.  The date is specified in the form:
2120
2121                                  W YYYY/MM/DD HH:MM:SS
2122
2123            W is the day of the week expressed as a number from zero  (Sunday)
2124            to  six  (Saturday).  YYYY is the year, including the century.  MM
2125            is the month expressed as a number from 1 to 12.  DD is the day of
2126            the  month, counting from 1.  HH is the hour, from zero to 23.  MM
2127            is the minute and SS is the second.  The time is always in Coordi‐
2128            nated Universal Time (UTC), not local time.
2129
2130         The dynamic-bootp-lease-length statement
2131
2132            dynamic-bootp-lease-length length;
2133
2134            The dynamic-bootp-lease-length statement is used to set the length
2135            of leases dynamically assigned to BOOTP clients.  At  some  sites,
2136            it  may  be possible to assume that a lease is no longer in use if
2137            its holder has not used BOOTP or DHCP to get its address within  a
2138            certain  time period.  The period is specified in length as a num‐
2139            ber of seconds.  If a client reboots using BOOTP during the  time‐
2140            out  period,  the  lease  duration  is reset to length, so a BOOTP
2141            client that boots frequently enough will  never  lose  its  lease.
2142            Needless  to  say,  this parameter should be adjusted with extreme
2143            caution.
2144
2145         The echo-client-id statement
2146
2147            echo-client-id flag;
2148
2149            The echo-client-id statement is used to enable or disable RFC 6842
2150            compliant  behavior.   If  the echo-client-id statement is present
2151            and has a value of true or on, and a DHCP DISCOVER or  REQUEST  is
2152            received  which contains the client identifier option (Option code
2153            61), the server will copy the option into its response  (DHCP  ACK
2154            or  NAK)  per  RFC  6842.   In other words if the client sends the
2155            option it will receive it back. By default, this flag is  off  and
2156            client identifiers will not echoed back to the client.
2157
2158         The filename statement
2159
2160            filename "filename";
2161
2162            The filename statement can be used to specify the name of the ini‐
2163            tial boot file which is to be loaded by a  client.   The  filename
2164            should be a filename recognizable to whatever file transfer proto‐
2165            col the client can be expected to use to load the file.
2166
2167         The fixed-address declaration
2168
2169            fixed-address address [, address ... ];
2170
2171            The fixed-address declaration is used to assign one or more  fixed
2172            IP  addresses to a client.  It should only appear in a host decla‐
2173            ration.  If more than one  address  is  supplied,  then  when  the
2174            client  boots, it will be assigned the address that corresponds to
2175            the network on which it is booting.  If none of the  addresses  in
2176            the fixed-address statement are valid for the network to which the
2177            client is connected, that client will not match the host  declara‐
2178            tion  containing  that fixed-address declaration.  Each address in
2179            the fixed-address declaration should be either an IP address or  a
2180            domain name that resolves to one or more IP addresses.
2181
2182         The fixed-address6 declaration
2183
2184            fixed-address6 ip6-address ;
2185
2186            The  fixed-address6  declaration  is  used  to assign a fixed IPv6
2187            addresses to a client.  It should only appear in a  host  declara‐
2188            tion.
2189
2190         The fixed-prefix6 declaration
2191
2192            fixed-prefix6 low-address / bits;
2193
2194            The  fixed-prefix6 declaration is used to assign a fixed IPv6 pre‐
2195            fix to a client.  It should only appear in a host declaration, but
2196            multiple fixed-prefix6 statements may appear in a single host dec‐
2197            laration.
2198
2199            The low-address specifies the start of the  prefix  and  the  bits
2200            specifies the size of the prefix in bits.
2201
2202            If  there  are multiple prefixes for a given host entry the server
2203            will choose one that matches the requested prefix size or, if none
2204            match, the first one.
2205
2206            If  there  are  multiple  host declarations the server will try to
2207            choose a declaration where the fixed-address6 matches the client's
2208            subnet.   If  none  match  it  will choose one that doesn't have a
2209            fixed-address6 statement.
2210
2211            Note Well: Unlike the fixed address the fixed prefix does not need
2212            to  match a subnet in order to be served.  This allows you to pro‐
2213            vide a prefix to a client that is outside of the subnet  on  which
2214            the client makes the request to the the server.
2215
2216         The get-lease-hostnames statement
2217
2218            get-lease-hostnames flag;
2219
2220            The get-lease-hostnames statement is used to tell dhcpd whether or
2221            not to look up the domain name corresponding to the IP address  of
2222            each  address  in the lease pool and use that address for the DHCP
2223            hostname option.  If flag is true, then this lookup  is  done  for
2224            all  addresses  in  the  current scope.  By default, or if flag is
2225            false, no lookups are done.
2226
2227         The hardware statement
2228
2229            hardware hardware-type hardware-address;
2230
2231            In order for a BOOTP client to be recognized, its network hardware
2232            address  must  be  declared  using  a  hardware clause in the host
2233            statement.  hardware-type must be the name of a physical  hardware
2234            interface type.  Currently, only the ethernet and token-ring types
2235            are recognized, although support for a  fddi  hardware  type  (and
2236            others) would also be desirable.  The hardware-address should be a
2237            set of hexadecimal octets (numbers from 0 through ff) separated by
2238            colons.  The hardware statement may also be used for DHCP clients.
2239
2240         The host-identifier option statement
2241
2242            host-identifier option option-name option-data;
2243
2244            or
2245
2246            host-identifier v6relopt number option-name option-data;
2247
2248            This  identifies a DHCPv6 client in a host statement.  option-name
2249            is any option, and option-data is the value for  the  option  that
2250            the  client  will  send. The option-data must be a constant value.
2251            In the v6relopts case the additional number is the relay to  exam‐
2252            ine  for  the specified option name and value.  The values are the
2253            same as for the v6relay option.  0 is a  no-op,  1  is  the  relay
2254            closest  to  the client, 2 the next one in and so on.  Values that
2255            are larger than the maximum number of relays (currently 32)  indi‐
2256            cate the relay closest to the server independent of number.
2257
2258         The ignore-client-uids statement
2259
2260            ignore-client-uids flag;
2261
2262            If  the ignore-client-uids statement is present and has a value of
2263            true or on, the UID for clients will not  be  recorded.   If  this
2264            statement  is  not  present  or  has a value of false or off, then
2265            client UIDs will be recorded.
2266
2267         The infinite-is-reserved statement
2268
2269            infinite-is-reserved flag;
2270
2271            ISC DHCP now supports  ´reserved´  leases.   See  the  section  on
2272            RESERVED  LEASES below.  If this flag is on, the server will auto‐
2273            matically reserve leases allocated to clients which  requested  an
2274            infinite (0xffffffff) lease-time.
2275
2276            The default is off.
2277
2278         The lease-file-name statement
2279
2280            lease-file-name name;
2281
2282            Name  Where  name  is the name of the DHCP server's lease file. By
2283            default, this is /var/lib/dhcpd/dhcpd.leases.  This statement must
2284            appear  in  the  outer  scope  of  the  configuration file - if it
2285            appears in some other scope, it will have no  effect.   The  value
2286            must be the absolute path of the file to use.  The order of prece‐
2287            dence the server uses for the lease file name is:
2288
2289                1. lease-file-name configuration file statement.
2290                2. -lf command line flag.
2291                3. PATH_DHCPD_DB environment variable.
2292
2293         The dhcpv6-lease-file-name statement
2294
2295            dhcpv6-lease-file-name name;
2296
2297            Where name is the name of the DHCP server's lease  file  when  the
2298            server    is    running    DHCPv6.    By    default,    this    is
2299            /var/lib/dhcpd/dhcpd6.leases. This statement must  appear  in  the
2300            outer  scope  of  the  configuration  file - if it appears in some
2301            other scope, it will have no effect.  The value must be the  abso‐
2302            lute  path of the file to use.  The order of precedence the server
2303            uses for the lease file name is:
2304
2305                1. dhcpv6-lease-file-name configuration file statement.
2306                2. -lf command line flag.
2307                3. PATH_DHCPD6_DB environment variable.
2308
2309         The lease-id-format parameter
2310
2311            lease-id-format format;
2312
2313            The format parameter must be either octal or hex.  This  parameter
2314            governs  the  format  used to write certain values to lease files.
2315            With the default format,  octal,  values  are  written  as  quoted
2316            strings in which non-printable characters are represented as octal
2317            escapes - a backslash character followed by  three  octal  digits.
2318            When  the  hex  format  is  specified,  values  are  written as an
2319            unquoted series of  pairs  of  hexadecimal  digits,  separated  by
2320            colons.
2321
2322            Currently, the values written out based on lease-id-format are the
2323            server-duid, the uid (DHCPv4 leases), and  the  IAID_DUID  (DHCPv6
2324            leases).  Note the server automatically reads the values in either
2325            format.
2326
2327         The limit-addrs-per-ia statement
2328
2329            limit-addrs-per-ia number;
2330
2331            By default, the DHCPv6 server will limit clients to one IAADDR per
2332            IA  option, meaning one address.  If you wish to permit clients to
2333            hang onto multiple addresses at a time, configure a larger  number
2334            here.
2335
2336            Note  that  there  is no present method to configure the server to
2337            forcibly configure the client with one IP address per each  subnet
2338            on a shared network.  This is left to future work.
2339
2340         The local-port statement
2341
2342            local-port port;
2343
2344            This  statement causes the DHCP server to listen for DHCP requests
2345            on the UDP port specified in port, rather than on port 67.
2346
2347         The local-address statement
2348
2349            local-address address;
2350
2351            This statement causes the DHCP server to listen for DHCP  requests
2352            sent  to  the  specified address, rather than requests sent to all
2353            addresses.  Since serving directly attached DHCP  clients  implies
2354            that  the  server must respond to requests sent to the all-ones IP
2355            address, this option cannot be used if  clients  are  on  directly
2356            attached  networks;  it  is only realistically useful for a server
2357            whose only clients are reached via  unicasts,  such  as  via  DHCP
2358            relay agents.
2359
2360            Note:  This statement is only effective if the server was compiled
2361            using the USE_SOCKETS #define statement, which  is  default  on  a
2362            small  number  of operating systems, and must be explicitly chosen
2363            at compile-time for all others.  You can be sure if your server is
2364            compiled  with  USE_SOCKETS  if  you  see  lines of this format at
2365            startup:
2366
2367             Listening on Socket/eth0
2368
2369            Note also that since this bind()s all DHCP sockets to  the  speci‐
2370            fied  address,  that only one address may be supported in a daemon
2371            at a given time.
2372
2373         The local-address6 and bind-local-address6 statements
2374
2375            local-address6 address;
2376
2377            bind-local-address6 flag;
2378
2379            The local-address6 statement causes the DHCP server to  send  IPv6
2380            packets  as  originating  from  the specified IPv6 address, rather
2381            than leaving the kernel to fill in the source address field.
2382
2383            When bind-local-address6 is present and has a value of true or on,
2384            service sockets are bound to address too.
2385
2386            By  default  address  is the undefined address and the bind-local-
2387            address6 is disabled, both may only be set at the global scope.
2388
2389         The log-facility statement
2390
2391            log-facility facility;
2392
2393            This statement causes the DHCP server to do all of its logging  on
2394            the specified log facility once the dhcpd.conf file has been read.
2395            By default the DHCP server logs to the daemon facility.   Possible
2396            log  facilities  include  auth, authpriv, cron, daemon, ftp, kern,
2397            lpr, mail, mark, news, ntp,  security,  syslog,  user,  uucp,  and
2398            local0  through local7.  Not all of these facilities are available
2399            on all systems, and there may be  other  facilities  available  on
2400            other systems.
2401
2402            In  addition  to  setting  this value, you may need to modify your
2403            syslog.conf file to configure logging of  the  DHCP  server.   For
2404            example, you might add a line like this:
2405
2406                 local7.debug /var/log/dhcpd.log
2407
2408            The  syntax of the syslog.conf file may be different on some oper‐
2409            ating systems - consult the syslog.conf manual page  to  be  sure.
2410            To  get  syslog  to  start logging to the new file, you must first
2411            create the file with correct ownership and  permissions  (usually,
2412            the  same  owner  and  permissions  of  your  /var/log/messages or
2413            /usr/adm/messages file should be fine) and send a SIGHUP  to  sys‐
2414            logd.   Some  systems support log rollover using a shell script or
2415            program called newsyslog or logrotate, and you may be able to con‐
2416            figure  this as well so that your log file doesn't grow uncontrol‐
2417            lably.
2418
2419            Because the log-facility setting is controlled by  the  dhcpd.conf
2420            file,  log  messages  printed while parsing the dhcpd.conf file or
2421            before parsing it are logged to the default log facility.  To pre‐
2422            vent  this,  see  the README file included with this distribution,
2423            which describes BUG: where is that mentioned in  README?   how  to
2424            change the default log facility.  When this parameter is used, the
2425            DHCP server prints its startup message a second time after parsing
2426            the  configuration  file,  so  that the log will be as complete as
2427            possible.
2428
2429         The log-threshold-high and log-threshold-low statements
2430
2431            log-threshold-high percentage;
2432
2433            log-threshold-low percentage;
2434
2435            The log-threshold-low and log-threshold-high statements  are  used
2436            to  control  when a message is output about pool usage.  The value
2437            for both of them is the percentage of the pool  in  use.   If  the
2438            high threshold is 0 or has not been specified, no messages will be
2439            produced.  If a high threshold is given, a message is output  once
2440            the  pool  usage  passes that level.  After that, no more messages
2441            will be output until the pool usage falls below the low threshold.
2442            If the low threshold is not given, it default to a value of zero.
2443
2444            A  special  case  occurs when the low threshold is set to be higer
2445            than the high threshold.  In this case, a message will  be  gener‐
2446            ated  each  time  a  lease  is acknowledged when the pool usage is
2447            above the high threshold.
2448
2449            Note that threshold logging will  be  automatically  disabled  for
2450            shared  subnets  whose  total  number  of addresses is larger than
2451            (2^64)-1.  The server will emit a log statement  at  startup  when
2452            threshold logging is disabled as shown below:
2453
2454                "Threshold  logging  disabled  for  shared  subnet  of ranges:
2455            <addresses>"
2456
2457            This is likely to have no practical runtime  effect  as  CPUs  are
2458            unlikely to support a server actually reaching such a large number
2459            of leases.
2460
2461         The max-lease-time statement
2462
2463            max-lease-time time;
2464
2465            Time should be the maximum length in seconds that will be assigned
2466            to  a  lease.   If  not defined, the default maximum lease time is
2467            86400.  The only exception to this is  that  Dynamic  BOOTP  lease
2468            lengths, which are not specified by the client, are not limited by
2469            this maximum.
2470
2471         The min-lease-time statement
2472
2473            min-lease-time time;
2474
2475            Time should be the minimum length in seconds that will be assigned
2476            to  a  lease.   The  default is the minimum of 300 seconds or max-
2477            lease-time.
2478
2479         The min-secs statement
2480
2481            min-secs seconds;
2482
2483            Seconds should be the minimum number of  seconds  since  a  client
2484            began  trying  to  acquire a new lease before the DHCP server will
2485            respond to its request.  The number of seconds is  based  on  what
2486            the  client  reports,  and  the  maximum value that the client can
2487            report is 255 seconds.  Generally, setting this to one will result
2488            in  the  DHCP server not responding to the client's first request,
2489            but always responding to its second request.
2490
2491            This can be used to set up a secondary  DHCP  server  which  never
2492            offers  an  address  to a client until the primary server has been
2493            given a chance to do so.  If  the  primary  server  is  down,  the
2494            client  will  bind  to the secondary server, but otherwise clients
2495            should always bind to the primary.  Note that this  does  not,  by
2496            itself,  permit a primary server and a secondary server to share a
2497            pool of dynamically-allocatable addresses.
2498
2499         The next-server statement
2500
2501            next-server server-name;
2502
2503            The next-server statement is used to specify the host  address  of
2504            the  server  from  which  the  initial boot file (specified in the
2505            filename statement) is to be  loaded.   Server-name  should  be  a
2506            numeric  IP address or a domain name.  If no next-server statement
2507            applies to a given client, the address 0.0.0.0 is used.
2508
2509         The omapi-port statement
2510
2511            omapi-port port;
2512
2513            The omapi-port statement causes the  DHCP  server  to  listen  for
2514            OMAPI  connections  on  the  specified  port.   This  statement is
2515            required to enable the OMAPI protocol, which is  used  to  examine
2516            and modify the state of the DHCP server as it is running.
2517
2518         The one-lease-per-client statement
2519
2520            one-lease-per-client flag;
2521
2522            If this flag is enabled, whenever a client sends a DHCPREQUEST for
2523            a particular lease, the server will automatically free  any  other
2524            leases the client holds.  This presumes that when the client sends
2525            a DHCPREQUEST, it has forgotten any lease  not  mentioned  in  the
2526            DHCPREQUEST - i.e., the client has only a single network interface
2527            and it does not remember leases it's holding on networks to  which
2528            it  is  not  currently attached.  Neither of these assumptions are
2529            guaranteed or provable, so we urge caution  in  the  use  of  this
2530            statement.
2531
2532         The persist-eui-64-leases statement
2533
2534            persist-eui-64-leases flag;
2535
2536            When  this  flag  is  enabled,  the server will write EUI-64 based
2537            leases to the leases file. Since such leases  can  only,  ever  be
2538            valid  for  a single DUID value it can be argued that writing them
2539            to the leases file isn't essential and not doing so may have  per‐
2540            fomance  advantages.  See use-eui-64 statement for more details on
2541            EUI-64 based address allocation.  The flag is enabled  by  default
2542            and may only be set at the global scope.
2543
2544         The pid-file-name statement
2545
2546            pid-file-name name;
2547
2548            Name  should  be  the  name  of the DHCP server's process ID file.
2549            This is the file in which the DHCP server's process ID  is  stored
2550            when  the  server starts.  By default, this is /var/run/dhcpd.pid.
2551            Like the lease-file-name statement, this statement must appear  in
2552            the outer scope of the configuration file. The order of precedence
2553            used by the server is:
2554
2555                1. pid-file-name configuration file statement.
2556                2. -lf command line flag.
2557                3. PATH_DHCPD_PID environment variable.
2558
2559            The dhcpv6-pid-file-name statement
2560
2561              dhcpv6-pid-file-name name;
2562
2563              Name is the name of the pid file to  use  if  and  only  if  the
2564              server   is  running  in  DHCPv6  mode.   By  default,  this  is
2565              /var/lib/dhcpd/dhcpd6.pid.  This statement, like  pid-file-name,
2566              must  appear  in the outer scope of the configuration file.  The
2567              order of precedence used by the server is:
2568
2569                  1. dhcpv6-pid-file-name configuration file statement.
2570                  2. -lf command line flag.
2571                  3. PATH_DHCPD6_PID environment variable.
2572
2573            The ping-check statement
2574
2575              ping-check flag;
2576
2577              When the DHCP server is considering dynamically allocating an IP
2578              address  to  a  client,  it  first sends an ICMP Echo request (a
2579              ping) to the address being assigned.  It waits for a second, and
2580              if no ICMP Echo response has been heard, it assigns the address.
2581              If a response is heard, the lease is abandoned, and  the  server
2582              does not respond to the client.  The lease will remain abandoned
2583              for a minimum of abandon-lease-time seconds.
2584
2585              If a there are no free addressses but  there  are  abandoned  IP
2586              addresses,  the DHCP server will attempt to reclaim an abandoned
2587              IP address regardless of the value of abandon-lease-time.
2588
2589              This  ping  check  introduces  a  default  one-second  delay  in
2590              responding  to DHCPDISCOVER messages, which can be a problem for
2591              some clients.  The default delay of one second may be configured
2592              using  the ping-timeout parameter.  The ping-check configuration
2593              parameter can be used to control checking  -  if  its  value  is
2594              false, no ping check is done.
2595
2596            The ping-cltt-secs statement
2597
2598              ping-cltt-secs seconds;
2599
2600              The server will conduct a ping check if all the following condi‐
2601              tions are true:
2602
2603              1. Ping checking is enabled.
2604
2605              2. The server is responding to a DISCOVER.
2606
2607              3. The lease to be offered is neither static  nor  active  (i.e.
2608              still a valid lease).
2609
2610              4. And any of the following are true:
2611                  a. This will be the first offer of this lease (CLTT is 0).
2612                  b.  The  lease  is  being offered to a client other than its
2613              previous owner
2614                  c. The lease is being offered to its previous owner and more
2615              than
2616                  ping-cltt-secs  have  elapsed  since  CLTT  of  the original
2617              lease.
2618                  d. The lease was abandoned and the server is  attempting  to
2619              reclaim it.
2620
2621
2622              The  ping-cltt-secs  statement  allows  the  user to specify the
2623              amount of time that must elaspe after CLTT before a  ping  check
2624              will be conducted.  The default value is sixty seconds.
2625
2626            The ping-timeout statement
2627
2628              ping-timeout seconds;
2629
2630              If  the  DHCP  server  determined  it  should  send an ICMP echo
2631              request (a ping) because the ping-check statement is true, ping-
2632              timeout allows you to configure how many seconds the DHCP server
2633              should wait for an ICMP Echo response to be heard,  if  no  ICMP
2634              Echo  response  has been received before the timeout expires, it
2635              assigns the address.  If a response is heard, the lease is aban‐
2636              doned,  and  the  server  does not respond to the client.  If no
2637              value is set, ping-timeout defaults to 1 second. (See also ping-
2638              timeout-ms below)
2639
2640            The ping-timeout-ms statement
2641
2642              ping-timeout-ms milliseconds;
2643
2644              Allows  you  to  specify the ping timeout in milliseconds rather
2645              than seconds.  If this value is greater than  zero,  the  server
2646              will  use  it  in  place  of ping-timeout.  The default value is
2647              zero.
2648
2649            The preferred-lifetime statement
2650
2651              preferred-lifetime seconds;
2652
2653              IPv6 addresses have  ´valid´  and  ´preferred´  lifetimes.   The
2654              valid  lifetime  determines at what point at lease might be said
2655              to have expired, and is no longer useable.  A preferred lifetime
2656              is  an  advisory  condition to help applications move off of the
2657              address and onto currently valid addresses (should  there  still
2658              be any open TCP sockets or similar).
2659
2660              The preferred lifetime defaults to 5/8 the default lease time.
2661
2662            The prefix-length-mode statement
2663
2664              prefix-length-mode mode;
2665
2666              According  to  RFC  3633, DHCPv6 clients may specify preferences
2667              when soliciting prefixes by including  an  IA_PD  Prefix  option
2668              within  the IA_PD option. Among the preferences that may be con‐
2669              veyed is the  "prefix-length".  When  non-zero  it  indicates  a
2670              client's  desired  length  for offered prefixes.  The RFC states
2671              that servers "MAY choose to use the information...to select pre‐
2672              fix(es)" but does not specify any particular rules for doing so.
2673              The prefix-length-mode statement can be used to set  the  prefix
2674              selection rules employed by the server, when clients send a non-
2675              zero prefix-length value. The mode  parameter  must  be  one  of
2676              ignore, prefer, exact, minimum, or maximum where:
2677
2678              1.  ignore  -  The  requested length is ignored. The server will
2679              offer the first available prefix.
2680
2681              2. prefer - The server will offer  the  first  available  prefix
2682              with the same length as the requested length.  If none are found
2683              then it will offer the first available  prefix  of  any  length.
2684              This is the default behavior.
2685
2686              3. exact - The server will offer the first available prefix with
2687              the same length as the requested length.  If none are found,  it
2688              will return a status indicating no prefixes available.
2689
2690              4.  minimum  -  The server will offer the first available prefix
2691              with the same length as  the  requested  length.   If  none  are
2692              found, it will return the first available prefix whose length is
2693              greater than (e.g. longer than), the requested value.   If  none
2694              of  those  are found, it will return a status indicating no pre‐
2695              fixes available.  For example, if client requests  a  length  of
2696              /60,  and  the  server has available prefixes of lengths /56 and
2697              /64, it will offer prefix of length /64.
2698
2699              5. maximum - The server will offer the  first  available  prefix
2700              with  the  same  length  as  the  requested length.  If none are
2701              found, it will return the first available prefix whose length is
2702              less  than (e.g. shorter than), the requested value.  If none of
2703              those are found, it will return a status indicating no  prefixes
2704              available.  For example, if client requests a length of /60, and
2705              the server has available prefixes of lengths  /56  and  /64,  it
2706              will offer a prefix of length /56.
2707
2708              In general "first available" is determined by the order in which
2709              pools are defined in the server's configuration.   For  example,
2710              if a subnet is defined with three prefix pools A,B, and C:
2711
2712              subnet 3000::/64 {
2713                   # pool A
2714                   pool6 {
2715                        :
2716                   }
2717                   # pool B
2718                   pool6 {
2719                        :
2720                   }
2721                   # pool C
2722                   pool6 {
2723                        :
2724                   }
2725              }
2726
2727              then  the  pools will be checked in the order A, B, C. For modes
2728              prefer, minimum, and maximum this may mean checking the pools in
2729              that  order  twice.  A first pass through is made looking for an
2730              available prefix of exactly the preferred length.  If  none  are
2731              found,  then a second pass is performed starting with pool A but
2732              with appropriately adjusted length criteria.
2733
2734            The release-on-roam statement
2735
2736              release-on-roam flag;
2737
2738              When enabled and the dhcpd server detects that a  DHCPv6  client
2739              (IAID+DUID)  has  roamed  to  a new network, it will release the
2740              pre-existing leases on the old network and emit a log  statement
2741              similiar to the following:
2742
2743                    "Client:  <id>  roamed  to  new  network, releasing lease:
2744              <address>"
2745
2746              The server will carry out all of the same steps that would  nor‐
2747              mally  occur  when  a  client explicitly releases a lease.  When
2748              release-on-roam is disabled (the default) the server makes  such
2749              leases unavailable until they expire or the server is restarted.
2750              Clients that need leases in  multiple  networks  must  supply  a
2751              unique IAID in each IA.  This parameter may only be specified at
2752              the global level.
2753
2754            The remote-port statement
2755
2756              remote-port port;
2757
2758              This statement causes the DHCP server to transmit DHCP responses
2759              to DHCP clients upon the UDP port specified in port, rather than
2760              on port 68.  In the event that the UDP response  is  transmitted
2761              to  a  DHCP Relay, the server generally uses the local-port con‐
2762              figuration value.  Should the DHCP Relay happen to be  addressed
2763              as 127.0.0.1, however, the DHCP Server transmits its response to
2764              the remote-port configuration value.   This  is  generally  only
2765              useful for testing purposes, and this configuration value should
2766              generally not be used.
2767
2768            The server-identifier statement
2769
2770              server-identifier hostname;
2771
2772              The server-identifier statement can be used to define the  value
2773              that  is  sent  in the DHCP Server Identifier option for a given
2774              scope.  The value specified must be an IP address for  the  DHCP
2775              server, and must be reachable by all clients served by a partic‐
2776              ular scope.
2777
2778              The use of the server-identifier statement is not recommended  -
2779              the  only  reason  to  use it is to force a value other than the
2780              default value to be sent on occasions where  the  default  value
2781              would  be  incorrect.  The default value is the first IP address
2782              associated with the physical  network  interface  on  which  the
2783              request arrived.
2784
2785              The usual case where the server-identifier statement needs to be
2786              sent is when a physical interface has more than one IP  address,
2787              and  the one being sent by default isn't appropriate for some or
2788              all clients served by that interface.  Another  common  case  is
2789              when  an alias is defined for the purpose of having a consistent
2790              IP address for the DHCP server,  and  it  is  desired  that  the
2791              clients use this IP address when contacting the server.
2792
2793              Supplying  a  value  for  the  dhcp-server-identifier  option is
2794              equivalent to using the server-identifier statement.
2795
2796            The server-id-check statement
2797
2798              server-id-check flag;
2799
2800              The server-id-check statement is used to control whether or  not
2801              a  server, participating in failover, verifies that the value of
2802              the dhcp-server-identifier  option  in  received  DHCP  REQUESTs
2803              match  the  server's id before processing the request. Server id
2804              checking is disabled by default.  Setting this flag  enables  id
2805              checking  and  thereafter  the server will only process requests
2806              that match.  Note the flag setting should be consistent  between
2807              failover partners.
2808
2809              Unless overridden by use of the server-identifier statement, the
2810              value the server uses as its id will be  the  first  IP  address
2811              associated  with  the  physical  network  interface on which the
2812              request arrived.
2813
2814              In order to reduce runtime overhead the server only checks for a
2815              server  id  option in the global and subnet scopes.  Complicated
2816              configurations may result in different server ids for this check
2817              and  when  the server id for a reply packet is determined, which
2818              would prohibit the server from responding.
2819
2820              The primary use for this option is when a  client  broadcasts  a
2821              request  but  requires  that  the  response come from a specific
2822              failover peer.  An example  of  this  would  be  when  a  client
2823              reboots  while  its  lease  is  still active - in this case both
2824              servers will normally respond.  Most  of  the  time  the  client
2825              won't  check  the server id and can use either of the responses.
2826              However if the client does check the server id it may reject the
2827              response  if it came from the wrong peer.  If the timing is such
2828              that the "wrong" peer responds first most of the time the client
2829              may not get an address for some time.
2830
2831              Care should be taken before enabling this option.
2832
2833            The server-duid statement
2834
2835              server-duid LLT [ hardware-type timestamp hardware-address ] ;
2836
2837              server-duid EN enterprise-number enterprise-identifier ;
2838
2839              server-duid LL [ hardware-type hardware-address ] ;
2840
2841              The  server-duid  statement  configures the server DUID. You may
2842              pick either LLT (link local address plus time), EN (enterprise),
2843              or LL (link local).
2844
2845              If  you  choose LLT or LL, you may specify the exact contents of
2846              the DUID.  Otherwise the server will  generate  a  DUID  of  the
2847              specified type.
2848
2849              If you choose EN, you must include the enterprise number and the
2850              enterprise-identifier.
2851
2852              If there is a server-duid statement in the lease  file  it  will
2853              take  precedence  over the server-duid statement from the config
2854              file and a dhcp6.server-id option in the config file will  over‐
2855              ride both.
2856
2857              The default server-duid type is LLT.
2858
2859            The server-name statement
2860
2861              server-name name ;
2862
2863              The  server-name  statement  can be used to inform the client of
2864              the name of the server from which it is booting.  Name should be
2865              the name that will be provided to the client.
2866
2867            The dhcpv6-set-tee-times statement
2868
2869              dhcpv6-set-tee-times flag;
2870
2871              The  dhcpv6-set-tee-times statement enables setting T1 and T2 to
2872              the values recommended in RFC 3315 (Section 22.4).  When setting
2873              T1  and  T2,  the  server  will  use dhcp-renewal-time and dhcp-
2874              rebinding-time, respectively.  A value of zero tells the  client
2875              it may choose its own value.
2876
2877              When  those  options  are not defined then values will be set to
2878              zero unless the global dhcpv6-set-tee-times  is  enabled.   When
2879              this  option  is enabled the times are calculated as recommended
2880              by RFC 3315, Section 22.4:
2881
2882                    T1 will be set to 0.5 times the shortest  preferred  life‐
2883              time
2884                    in the reply.  If the "shortest" preferred lifetime is
2885                    0xFFFFFFFF,  T1 will set to 0xFFFFFFFF.
2886
2887                    T2  will  be set to 0.8 times the shortest preferred life‐
2888              time
2889                    in the reply.  If the "shortest" preferred lifetime is
2890                    0xFFFFFFFF,  T2 will set to 0xFFFFFFFF.
2891
2892              Keep in mind that given sufficiently small lease lifetimes,  the
2893              above  calculations  will  result in the two values being equal.
2894              For example, a 9 second lease lifetime would yield T1 = T2  =  4
2895              seconds,  which  would  cause clients to issue rebinds only.  In
2896              such a case it would likely be better to explicitly  define  the
2897              values.
2898
2899              Note  that  dhcpv6-set-tee-times  is intended to be transitional
2900              and will likely be removed in a future release. Once removed the
2901              behavior  will  be  to use the configured values when present or
2902              calculate them per the RFC. If you want zeros,  define  them  as
2903              zeros.
2904
2905            The site-option-space statement
2906
2907              site-option-space name ;
2908
2909              The  site-option-space  statement  can be used to determine from
2910              what option space site-local options will be taken.  This can be
2911              used  in much the same way as the vendor-option-space statement.
2912              Site-local options in DHCP are those options whose numeric codes
2913              are  greater than 224.  These options are intended for site-spe‐
2914              cific uses, but are frequently used by vendors of embedded hard‐
2915              ware  that contains DHCP clients.  Because site-specific options
2916              are allocated on an ad hoc basis, it is quite possible that  one
2917              vendor's DHCP client might use the same option code that another
2918              vendor's client uses, for different purposes.  The  site-option-
2919              space  option can be used to assign a different set of site-spe‐
2920              cific options for each such vendor, using conditional evaluation
2921              (see dhcp-eval (5) for details).
2922
2923            The stash-agent-options statement
2924
2925              stash-agent-options flag;
2926
2927              If the stash-agent-options parameter is true for a given client,
2928              the server will record the relay agent information options  sent
2929              during  the client's initial DHCPREQUEST message when the client
2930              was in the SELECTING state and behave as if  those  options  are
2931              included  in  all  subsequent  DHCPREQUEST  messages sent in the
2932              RENEWING state.  This works around a problem  with  relay  agent
2933              information  options,  which  is that they usually not appear in
2934              DHCPREQUEST messages sent by the client in the  RENEWING  state,
2935              because such messages are unicast directly to the server and not
2936              sent through a relay agent.
2937
2938            The update-conflict-detection statement
2939
2940              update-conflict-detection flag;
2941
2942              If the update-conflict-detection parameter is true,  the  server
2943              will  perform  standard DHCID multiple-client, one-name conflict
2944              detection.  If the parameter has been set false, the server will
2945              skip  this check and instead simply tear down any previous bind‐
2946              ings to install the new binding without question.   The  default
2947              is  true  and this parameter may only be specified at the global
2948              scope.
2949
2950            The update-optimization statement
2951
2952              update-optimization flag;
2953
2954              If the  update-optimization  parameter  is  false  for  a  given
2955              client,  the  server  will  attempt a DNS update for that client
2956              each time the client renews its lease, rather than only attempt‐
2957              ing  an update when it appears to be necessary.  This will allow
2958              the DNS to heal from database inconsistencies more  easily,  but
2959              the  cost is that the DHCP server must do many more DNS updates.
2960              We recommend leaving this option enabled, which is the  default.
2961              If  this parameter is not specified, or is true, the DHCP server
2962              will only update when the client information changes, the client
2963              gets a different lease, or the client's lease expires.
2964
2965            The update-static-leases statement
2966
2967              update-static-leases flag;
2968
2969              The  update-static-leases  flag,  if  enabled,  causes  the DHCP
2970              server to do DNS updates for clients even if those  clients  are
2971              being  assigned their IP address using a fixed-address or fixed-
2972              address6 statement - that is, the client is being given a static
2973              assignment.   It  is not recommended because the DHCP server has
2974              no way to tell that the update has been done, and therefore will
2975              not  delete  the record when it is not in use.  Also, the server
2976              must attempt the update each time the client renews  its  lease,
2977              which  could  have  a significant performance impact in environ‐
2978              ments that place heavy demands on the DHCP server.  This feature
2979              is  supported for both DHCPv4 and DHCPv6, and update modes stan‐
2980              dard or interim. It is disabled by default.
2981
2982            The use-eui-64 statement
2983
2984              use-eui-64 flag;
2985
2986              (Support for this must be enabled at compile time, see EUI_64 in
2987               includes/site.h)
2988
2989              The use-eui-64 flag, if enabled, instructs the  server  to  con‐
2990              struct  an  address  using  the client's EUI-64 DUID (Type 3, HW
2991              Type EUI-64), rather than creating an address using the  dynamic
2992              algorithm.   This  means  that a given DUID will always generate
2993              the same address for a given pool and further that  the  address
2994              is  guaranteed to be unique to that DUID.  The IPv6 address will
2995              be calculated from the EUI-64 link layer address, conforming  to
2996              RFC 2373, unless there is a host declaration for the client-id.
2997
2998              The range6 statement for EUI-64 must define full /64 bit ranges.
2999              Invalid ranges will be flagged during configuration  parsing  as
3000              errors.  See the following example:
3001
3002                  subnet6 fc00:e4::/64 {
3003                      use-eui-64 true;
3004                      range6 fc00:e4::/64;
3005                  }
3006
3007              The  statement may be specified down to the pool level, allowing
3008              a mixture of dynamic and EUI-64 based pools.
3009
3010              During lease file parsing, any leases which  map  to  an  EUI-64
3011              pool, that have a non-EUI-64 DUID or for which the lease address
3012              is not the EUI-64 address for that DUID in that  pool,  will  be
3013              discarded.
3014
3015              If a host declaration exists for the DUID, the server grants the
3016              address (fixed-prefix6, fixed-address6) according  to  the  host
3017              declaration, regardless of the DUID type of the client (even for
3018              EUI-64 DUIDs).
3019
3020              If a client request's an EUI-64 lease for a given  network,  and
3021              the  resultant  address  conflicts with a fixed address reserva‐
3022              tion, the server will send the client a "no addresses available"
3023              response.
3024
3025              Any client with a non-conforming DUID (not type 3 or not hw type
3026              EUI-64) that is not linked to a host declaration, which requests
3027              an  address  from an EUI-64 enabled pool will be ignored and the
3028              event will be logged.
3029
3030              Pools that are configured for EUI-64 will be skipped for dynamic
3031              allocation.   If  there  are no pools in the shared network from
3032              which to allocate, the client  will  get  back  a  no  addresses
3033              available status.
3034
3035              On  an  EUI-64  enabled  pool, any client with a DUID 3, HW Type
3036              EUI-64, requesting a solicit/renew and including IA_NA  that  do
3037              not match the EUI-64 policy, they will be treated as though they
3038              are "outside" the subnet for a given client message:
3039
3040                  Solicit - Server will advertise with  EUI-64  ia  suboption,
3041              but with rapid
3042                  commit off
3043                  Request  - Server will send "an address not on link status",
3044              and no ia
3045                  suboption Renew/Rebind -  Server  will  send  the  requested
3046              address ia
3047                  suboption with lifetimes of 0, plus an EUI-64 ia
3048
3049              Whether or not  EUI-64 based leases are written out to the lease
3050              database may be controlled by persist-eui-64-leases statement.
3051
3052            The use-host-decl-names statement
3053
3054              use-host-decl-names flag;
3055
3056              If the use-host-decl-names parameter is true in a  given  scope,
3057              then for every host declaration within that scope, the name pro‐
3058              vided for the host declaration will be supplied to the client as
3059              its hostname.  So, for example,
3060
3061                  group {
3062                    use-host-decl-names on;
3063
3064                    host joe {
3065                      hardware ethernet 08:00:2b:4c:29:32;
3066                      fixed-address joe.example.com;
3067                    }
3068                  }
3069
3070              is equivalent to
3071
3072                    host joe {
3073                      hardware ethernet 08:00:2b:4c:29:32;
3074                      fixed-address joe.example.com;
3075                      option host-name "joe";
3076                    }
3077
3078              Additionally,  enabling use-host-decl-names instructs the server
3079              to use the host declaration name in the the forward DNS name, if
3080              no  other values are available.  This value selection process is
3081              discussed in more detail under DNS updates.
3082
3083              An option host-name statement within  a  host  declaration  will
3084              override the use of the name in the host declaration.
3085
3086              It should be noted here that most DHCP clients completely ignore
3087              the host-name option sent by the DHCP server, and  there  is  no
3088              way  to  configure them not to do this.  So you generally have a
3089              choice of either not having any hostname to  client  IP  address
3090              mapping  that  the  client will recognize, or doing DNS updates.
3091              It is beyond the scope of this document to describe how to  make
3092              this determination.
3093
3094            The use-lease-addr-for-default-route statement
3095
3096              use-lease-addr-for-default-route flag;
3097
3098              If  the  use-lease-addr-for-default-route parameter is true in a
3099              given scope, then instead of sending the value specified in  the
3100              routers  option  (or sending no value at all), the IP address of
3101              the lease being assigned is sent to the client.  This supposedly
3102              causes  Win95 machines to ARP for all IP addresses, which can be
3103              helpful if your router is configured for proxy ARP.  The use  of
3104              this  feature is not recommended, because it won't work for many
3105              DHCP clients.
3106
3107            The vendor-option-space statement
3108
3109              vendor-option-space string;
3110
3111              The vendor-option-space parameter determines  from  what  option
3112              space  vendor  options are taken.  The use of this configuration
3113              parameter is illustrated in the dhcp-options(5) manual page,  in
3114              the VENDOR ENCAPSULATED OPTIONS section.
3115

SETTING PARAMETER VALUES USING EXPRESSIONS

3117       Sometimes  it's  helpful  to  be able to set the value of a DHCP server
3118       parameter based on some value that the client has sent.   To  do  this,
3119       you  can  use  expression  evaluation.   The  dhcp-eval(5)  manual page
3120       describes how to write expressions.  To assign the result of an evalua‐
3121       tion to an option, define the option as follows:
3122
3123         my-parameter = expression ;
3124
3125       For example:
3126
3127         ddns-hostname = binary-to-ascii (16, 8, "-",
3128                                          substring (hardware, 1, 6));
3129

RESERVED LEASES

3131       It's  often  useful to allocate a single address to a single client, in
3132       approximate perpetuity.  Host  statements  with  fixed-address  clauses
3133       exist  to  a  certain  extent  to  serve this purpose, but because host
3134       statements are intended to  approximate  ´static  configuration´,  they
3135       suffer from not being referenced in a littany of other Server Services,
3136       such as dynamic DNS, failover, ´on events´ and so forth.
3137
3138       If a standard dynamic lease, as from any  range  statement,  is  marked
3139       ´reserved´, then the server will only allocate this lease to the client
3140       it is identified by (be that by client identifier or hardware address).
3141
3142       In practice, this means that the lease follows the normal state engine,
3143       enters  ACTIVE  state  when  the  client is bound to it, expires, or is
3144       released, and any events or services that would  normally  be  supplied
3145       during  these  events are processed normally, as with any other dynamic
3146       lease.  The only difference is that  failover  servers  treat  reserved
3147       leases  as  special  when  they  enter the FREE or BACKUP states - each
3148       server applies the lease into the state it may allocate from - and  the
3149       leases  are  not  placed  on the queue for allocation to other clients.
3150       Instead they may only be ´found´ by client  identity.   The  result  is
3151       that the lease is only offered to the returning client.
3152
3153       Care  should  probably  be taken to ensure that the client only has one
3154       lease within a given subnet that it is identified by.
3155
3156       Leases may be set ´reserved´  either  through  OMAPI,  or  through  the
3157       ´infinite-is-reserved´  configuration  option (if this is applicable to
3158       your environment and mixture of clients).
3159
3160       It should also be noted that leases marked ´reserved´  are  effectively
3161       treated the same as leases marked ´bootp´.
3162

REFERENCE: OPTION STATEMENTS

3164       DHCP  option  statements  are  documented in the dhcp-options(5) manual
3165       page.
3166

REFERENCE: EXPRESSIONS

3168       Expressions used in DHCP option statements and elsewhere are documented
3169       in the dhcp-eval(5) manual page.
3170

SEE ALSO

3172       dhcpd(8),   dhcpd.leases(5),  dhcp-options(5),  dhcp-eval(5),  RFC2132,
3173       RFC2131.
3174

AUTHOR

3176       dhcpd.conf(5) is maintained by ISC.  Information about Internet Systems
3177       Consortium can be found at https://www.isc.org.
3178
3179
3180
3181                                                                 dhcpd.conf(5)
Impressum