


dhcpd.conf(5)                                       dhcpd.conf(5)


NNAAMMEE
       dhcpd.conf - dhcpd configuration file

DDEESSCCRRIIPPTTIIOONN
       The dhcpd.conf file contains configuration information for
       _d_h_c_p_d_, the Internet Systems Consortium DHCP Server.

       The dhcpd.conf file is a free-form ASCII text  file.    It
       is  parsed  by  the  recursive-descent  parser  built into
       dhcpd.   The file may contain extra tabs and newlines  for
       formatting purposes.  Keywords in the file are case-insen-
       sitive.   Comments may be placed anywhere within the  file
       (except  within quotes).   Comments begin with the # char-
       acter and end at the end of the line.

       The file essentially consists of  a  list  of  statements.
       Statements fall into two broad categories - parameters and
       declarations.

       Parameter statements either say how to do something (e.g.,
       how long a lease to offer), whether to do something (e.g.,
       should dhcpd provide addresses  to  unknown  clients),  or
       what  parameters to provide to the client (e.g., use gate-
       way 220.177.244.7).

       Declarations are used to describe the topology of the net-
       work,  to  describe  clients  on  the  network, to provide
       addresses that can be assigned to clients, or to  apply  a
       group  of  parameters to a group of declarations.   In any
       group of parameters and declarations, all parameters  must
       be specified before any declarations which depend on those
       parameters may be specified.

       Declarations about network topology  include  the  _s_h_a_r_e_d_-
       _n_e_t_w_o_r_k  and  the  _s_u_b_n_e_t  declarations.   If clients on a
       subnet are to be assigned addresses dynamically,  a  _r_a_n_g_e
       declaration  must  appear  within  the _s_u_b_n_e_t declaration.
       For clients with statically  assigned  addresses,  or  for
       installations  where  only  known  clients will be served,
       each such client must have a _h_o_s_t declaration.   If param-
       eters  are  to be applied to a group of declarations which
       are not related strictly on a per-subnet basis, the  _g_r_o_u_p
       declaration can be used.

       For  every subnet which will be served, and for every sub-
       net to which the dhcp server is connected, there  must  be
       one _s_u_b_n_e_t declaration, which tells dhcpd how to recognize
       that an address is on that subnet.  A  _s_u_b_n_e_t  declaration
       is  required  for each subnet even if no addresses will be
       dynamically allocated on that subnet.

       Some installations have physical networks  on  which  more
       than  one IP subnet operates.   For example, if there is a
       site-wide requirement that 8-bit subnet masks be used, but



                                                                1





dhcpd.conf(5)                                       dhcpd.conf(5)


       a  department  with  a  single  physical  ethernet network
       expands to the point where it has more than 254 nodes,  it
       may be necessary to run two 8-bit subnets on the same eth-
       ernet until such time as a new  physical  network  can  be
       added.    In  this case, the _s_u_b_n_e_t declarations for these
       two networks must be enclosed in a _s_h_a_r_e_d_-_n_e_t_w_o_r_k declara-
       tion.

       Some sites may have departments which have clients on more
       than one subnet, but it may be desirable  to  offer  those
       clients  a  uniform  set of parameters which are different
       than what would be offered to clients from  other  depart-
       ments  on  the  same  subnet.    For clients which will be
       declared explicitly with _h_o_s_t declarations, these declara-
       tions  can  be  enclosed in a _g_r_o_u_p declaration along with
       the parameters which are common to that department.    For
       clients  whose  addresses  will  be  dynamically assigned,
       class declarations and  conditional  declarations  may  be
       used  to  group parameter assignments based on information
       the client sends.

       When a client is to be booted,  its  boot  parameters  are
       determined  by  consulting  that client's _h_o_s_t declaration
       (if any),  and  then  consulting  any  _c_l_a_s_s  declarations
       matching  the  client,  followed  by  the _p_o_o_l, _s_u_b_n_e_t and
       _s_h_a_r_e_d_-_n_e_t_w_o_r_k declarations for the IP address assigned to
       the  client.    Each  of these declarations itself appears
       within a lexical scope, and all declarations at less  spe-
       cific  lexical scopes are also consulted for client option
       declarations.   Scopes are never considered twice, and  if
       parameters are declared in more than one scope, the param-
       eter declared in the most specific scope is the  one  that
       is used.

       When  dhcpd tries to find a _h_o_s_t declaration for a client,
       it first looks for a _h_o_s_t declaration which has  a  _f_i_x_e_d_-
       _a_d_d_r_e_s_s declaration that lists an IP address that is valid
       for the subnet or shared network on which  the  client  is
       booting.    If it doesn't find any such entry, it tries to
       find an entry which has no _f_i_x_e_d_-_a_d_d_r_e_s_s declaration.

EEXXAAMMPPLLEESS
       A typical dhcpd.conf file will look something like this:

       _g_l_o_b_a_l _p_a_r_a_m_e_t_e_r_s_._._.

       subnet 204.254.239.0 netmask 255.255.255.224 {
         _s_u_b_n_e_t_-_s_p_e_c_i_f_i_c _p_a_r_a_m_e_t_e_r_s_._._.
         range 204.254.239.10 204.254.239.30;
       }

       subnet 204.254.239.32 netmask 255.255.255.224 {
         _s_u_b_n_e_t_-_s_p_e_c_i_f_i_c _p_a_r_a_m_e_t_e_r_s_._._.
         range 204.254.239.42 204.254.239.62;



                                                                2





dhcpd.conf(5)                                       dhcpd.conf(5)


       }

       subnet 204.254.239.64 netmask 255.255.255.224 {
         _s_u_b_n_e_t_-_s_p_e_c_i_f_i_c _p_a_r_a_m_e_t_e_r_s_._._.
         range 204.254.239.74 204.254.239.94;
       }

       group {
         _g_r_o_u_p_-_s_p_e_c_i_f_i_c _p_a_r_a_m_e_t_e_r_s_._._.
         host zappo.test.isc.org {
           _h_o_s_t_-_s_p_e_c_i_f_i_c _p_a_r_a_m_e_t_e_r_s_._._.
         }
         host beppo.test.isc.org {
           _h_o_s_t_-_s_p_e_c_i_f_i_c _p_a_r_a_m_e_t_e_r_s_._._.
         }
         host harpo.test.isc.org {
           _h_o_s_t_-_s_p_e_c_i_f_i_c _p_a_r_a_m_e_t_e_r_s_._._.
         }
       }

                                Figure 1


       Notice that at the beginning of the file, there's a  place
       for  global  parameters.    These might be things like the
       organization's domain name,  the  addresses  of  the  name
       servers  (if  they are common to the entire organization),
       and so on.   So, for example:

            option domain-name "isc.org";
            option domain-name-servers ns1.isc.org, ns2.isc.org;

                                Figure 2

       As you can see in Figure 2, you can specify host addresses
       in  parameters  using their domain names rather than their
       numeric IP addresses.  If a  given  hostname  resolves  to
       more  than  one  IP address (for example, if that host has
       two  ethernet  interfaces),  then  where  possible,   both
       addresses are supplied to the client.

       The most obvious reason for having subnet-specific parame-
       ters as shown in Figure 1 is that each subnet,  of  neces-
       sity,  has  its own router.   So for the first subnet, for
       example, there should be something like:

            option routers 204.254.239.1;

       Note that  the  address  here  is  specified  numerically.
       This is not required - if you have a different domain name
       for each interface on your router, it's perfectly  legiti-
       mate  to use the domain name for that interface instead of
       the numeric address.   However, in many cases there may be
       only  one  domain name for all of a router's IP addresses,



                                                                3





dhcpd.conf(5)                                       dhcpd.conf(5)


       and it would not be appropriate to use that name here.

       In Figure 1 there is also a _g_r_o_u_p  statement,  which  pro-
       vides  common parameters for a set of three hosts - zappo,
       beppo and harpo.  As you can see, these hosts are  all  in
       the  test.isc.org  domain,  so  it  might make sense for a
       group-specific parameter to override the domain name  sup-
       plied to these hosts:

            option domain-name "test.isc.org";

       Also, given the domain they're in, these are probably test
       machines.  If we wanted to test the  DHCP  leasing  mecha-
       nism, we might set the lease timeout somewhat shorter than
       the default:

            max-lease-time 120;
            default-lease-time 120;

       You may have noticed that while some parameters start with
       the  _o_p_t_i_o_n  keyword,  some  do not.   Parameters starting
       with the _o_p_t_i_o_n keyword correspond to actual DHCP options,
       while parameters that do not start with the option keyword
       either control the behavior of the DHCP server (e.g.,  how
       long  a  lease  dhcpd  will  give  out), or specify client
       parameters that are not optional in the DHCP protocol (for
       example, server-name and filename).

       In  Figure  1,  each  host  had  _h_o_s_t_-_s_p_e_c_i_f_i_c _p_a_r_a_m_e_t_e_r_s.
       These could include such things as  the  _h_o_s_t_n_a_m_e  option,
       the  name of a file to upload (the _f_i_l_e_n_a_m_e parameter) and
       the address of the server from which to  upload  the  file
       (the  _n_e_x_t_-_s_e_r_v_e_r  parameter).   In general, any parameter
       can appear anywhere that parameters are allowed, and  will
       be  applied  according to the scope in which the parameter
       appears.

       Imagine that you have a site with a lot  of  NCD  X-Termi-
       nals.    These  terminals come in a variety of models, and
       you want to specify the boot files for each  model.    One
       way to do this would be to have host declarations for each
       server and group them by model:

       group {
         filename "Xncd19r";
         next-server ncd-booter;

         host ncd1 { hardware ethernet 0:c0:c3:49:2b:57; }
         host ncd4 { hardware ethernet 0:c0:c3:80:fc:32; }
         host ncd8 { hardware ethernet 0:c0:c3:22:46:81; }
       }

       group {
         filename "Xncd19c";



                                                                4





dhcpd.conf(5)                                       dhcpd.conf(5)


         next-server ncd-booter;

         host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; }
         host ncd3 { hardware ethernet 0:c0:c3:00:14:11; }
       }

       group {
         filename "XncdHMX";
         next-server ncd-booter;

         host ncd1 { hardware ethernet 0:c0:c3:11:90:23; }
         host ncd4 { hardware ethernet 0:c0:c3:91:a7:8; }
         host ncd8 { hardware ethernet 0:c0:c3:cc:a:8f; }
       }

AADDDDRREESSSS PPOOOOLLSS
       The ppooooll declaration can be used  to  specify  a  pool  of
       addresses  that  will  be treated differently than another
       pool of addresses, even on the  same  network  segment  or
       subnet.   For example, you may want to provide a large set
       of addresses that can be assigned to DHCP clients that are
       registered  to your DHCP server, while providing a smaller
       set of addresses, possibly with short  lease  times,  that
       are  available  for unknown clients.   If you have a fire-
       wall, you may be able to arrange for  addresses  from  one
       pool to be allowed access to the Internet, while addresses
       in another pool are not, thus encouraging users to  regis-
       ter  their  DHCP clients.   To do this, you would set up a
       pair of pool declarations:

       subnet 10.0.0.0 netmask 255.255.255.0 {
         option routers 10.0.0.254;

         # Unknown clients get this pool.
         pool {
           option domain-name-servers bogus.example.com;
           max-lease-time 300;
           range 10.0.0.200 10.0.0.253;
           allow unknown-clients;
         }

         # Known clients get this pool.
         pool {
           option domain-name-servers ns1.example.com, ns2.example.com;
           max-lease-time 28800;
           range 10.0.0.5 10.0.0.199;
           deny unknown-clients;
         }
       }

       It is also possible to set up entirely  different  subnets
       for known and unknown clients - address pools exist at the
       level of shared networks, so address  ranges  within  pool
       declarations can be on different subnets.



                                                                5





dhcpd.conf(5)                                       dhcpd.conf(5)


       As  you  can  see in the preceding example, pools can have
       permit lists that control which clients are allowed access
       to the pool and which aren't.  Each entry in a pool's per-
       mit list is introduced with the  _a_l_l_o_w  or  _d_e_n_y  keyword.
       If  a pool has a permit list, then only those clients that
       match specific entries on the permit list will be eligible
       to  be assigned addresses from the pool.   If a pool has a
       deny list, then only those clients that do not  match  any
       entries on the deny list will be eligible.    If both per-
       mit and deny lists exist for a  pool,  then  only  clients
       that  match the permit list and do not match the deny list
       will be allowed access.

DDYYNNAAMMIICC AADDDDRREESSSS AALLLLOOCCAATTIIOONN
       Address allocation is actually only done when a client  is
       in the INIT state and has sent a DHCPDISCOVER message.  If
       the client thinks it has a valid lease and sends a DHCPRE-
       QUEST to initiate or renew that lease, the server has only
       three choices - it can  ignore  the  DHCPREQUEST,  send  a
       DHCPNAK  to  tell  the  client  it  should  stop using the
       address, or send a DHCPACK, telling the client to go ahead
       and use the address for a while.

       If  the server finds the address the client is requesting,
       and that address is available to the  client,  the  server
       will  send  a DHCPACK.  If the address is no longer avail-
       able, or the client isn't permitted to have it, the server
       will  send  a  DHCPNAK.  If the server knows nothing about
       the address, it will remain silent, unless the address  is
       incorrect  for the network segment to which the client has
       been attached and the server  is  authoritative  for  that
       network  segment,  in  which  case  the server will send a
       DHCPNAK even though it doesn't know about the address.

       There may be a  host  declaration  matching  the  client's
       identification.   If  that  host  declaration  contains  a
       fixed-address declaration that lists an IP address that is
       valid  for the network segment to which the client is con-
       nected.  In this case,  the  DHCP  server  will  never  do
       dynamic  address  allocation.  In this case, the client is
       _r_e_q_u_i_r_e_d to take the address specified in the host  decla-
       ration.   If the client sends a DHCPREQUEST for some other
       address, the server will respond with a DHCPNAK.

       When the DHCP server allocates a new address for a  client
       (remember,  this  only  happens  if  the client has sent a
       DHCPDISCOVER), it first looks to see if the client already
       has  a valid lease on an IP address, or if there is an old
       IP address the client had  before  that  hasn't  yet  been
       reassigned.   In  that  case,  the  server  will take that
       address and check it to see if the client is still permit-
       ted  to  use  it.  If the client is no longer permitted to
       use it, the lease is freed if the server  thought  it  was
       still  in  use  -  the  fact  that  the  client has sent a



                                                                6





dhcpd.conf(5)                                       dhcpd.conf(5)


       DHCPDISCOVER proves to the server that the  client  is  no
       longer using the lease.

       If no existing lease is found, or if the client is forbid-
       den to receive the existing lease, then  the  server  will
       look  in the list of address pools for the network segment
       to which the client is attached for a lease that is not in
       use  and  that the client is permitted to have.   It looks
       through each pool declaration in sequence (all _r_a_n_g_e  dec-
       larations  that  appear  outside  of pool declarations are
       grouped into a single pool with no permit list).   If  the
       permit list for the pool allows the client to be allocated
       an address from that pool, the pool is examined to see  if
       there is an address available.   If so, then the client is
       tentatively assigned that address.   Otherwise,  the  next
       pool  is  tested.    If no addresses are found that can be
       assigned to the client, no response is sent to the client.

       If  an  address  is  found that the client is permitted to
       have, and that has  never  been  assigned  to  any  client
       before,  the  address  is  immediately  allocated  to  the
       client.   If the address is available for  allocation  but
       has  been  previously  assigned to a different client, the
       server will keep looking in hopes of  finding  an  address
       that has never before been assigned to a client.

       The  DHCP  server  generates  the  list  of  available  IP
       addresses  from  a  hash  table.    This  means  that  the
       addresses  are  not sorted in any particular order, and so
       it is not possible to predict the order in which the  DHCP
       server  will  allocate  IP  addresses.   Users of previous
       versions of the ISC DHCP server may have become accustomed
       to  the  DHCP  server allocating IP addresses in ascending
       order, but this is no longer possible, and there is no way
       to  configure this behavior with version 3 of the ISC DHCP
       server.

IIPP AADDDDRREESSSS CCOONNFFLLIICCTT PPRREEVVEENNTTIIOONN
       The DHCP server checks IP addresses to see if they are  in
       use  before  allocating them to clients.   It does this by
       sending an ICMP Echo request message  to  the  IP  address
       being  allocated.    If  no  ICMP  Echo  reply is received
       within a second, the address is assumed to be free.   This
       is  only done for leases that have been specified in range
       statements, and only when the lease is thought by the DHCP
       server  to be free - i.e., the DHCP server or its failover
       peer has not listed the lease as in use.

       If a response is received to an  ICMP  Echo  request,  the
       DHCP  server assumes that there is a configuration error -
       the IP address is in use by some host on the network  that
       is not a DHCP client.   It marks the address as abandoned,
       and will not assign it to clients.




                                                                7





dhcpd.conf(5)                                       dhcpd.conf(5)


       If a DHCP client tries to get an IP address, but none  are
       available,  but there are abandoned IP addresses, then the
       DHCP server  will  attempt  to  reclaim  an  abandoned  IP
       address.    It marks one IP address as free, and then does
       the same ICMP Echo  request  check  described  previously.
       If  there  is  no  answer  to  the  ICMP Echo request, the
       address is assigned to the client.

       The DHCP  server  does  not  cycle  through  abandoned  IP
       addresses  if  the first IP address it tries to reclaim is
       free.   Rather, when the next DHCPDISCOVER comes  in  from
       the  client,  it  will  attempt a new allocation using the
       same method described here, and will typically try  a  new
       IP address.

DDHHCCPP FFAAIILLOOVVEERR
       This  version  of  the  ISC  DHCP server supports the DHCP
       failover  protocol  as   documented   in   draft-ietf-dhc-
       failover-07.txt.    This is not a final protocol document,
       and we have not done interoperability testing  with  other
       vendors' implementations of this protocol, so you must not
       assume that this implementation conforms to the  standard.
       If  you  wish to use the failover protocol, make sure that
       both failover peers are running the same  version  of  the
       ISC DHCP server.

       The failover protocol allows two DHCP servers (and no more
       than two) to share a common address  pool.    Each  server
       will  have about half of the available IP addresses in the
       pool at any given time for  allocation.    If  one  server
       fails,  the other server will continue to renew leases out
       of the pool, and will allocate new addresses  out  of  the
       roughly  half of available addresses that it had when com-
       munications with the other server were lost.

       It is possible during a  prolonged  failure  to  tell  the
       remaining  server  that the other server is down, in which
       case the remaining server will (over time) reclaim all the
       addresses  the  other server had available for allocation,
       and begin to reuse them.    This  is  called  putting  the
       server into the PARTNER-DOWN state.

       You  can put the server into the PARTNER-DOWN state either
       by using the  oommsshheellll  ((11))  command  or  by  stopping  the
       server,  editing  the  last  peer state declaration in the
       lease file, and restarting the server.   If you  use  this
       last  method,  be  sure  to leave the date and time of the
       start of the state blank:

       ffaaiilloovveerr ppeeeerr _n_a_m_e ssttaattee {{
       mmyy ssttaattee ppaarrttnneerr--ddoowwnn;;
       ppeeeerr ssttaattee _s_t_a_t_e aatt _d_a_t_e;;
       }}




                                                                8





dhcpd.conf(5)                                       dhcpd.conf(5)


       When the other server comes back online, it  should  auto-
       matically  detect  that  it has been offline and request a
       complete update from the server that was  running  in  the
       PARTNER-DOWN state, and then both servers will resume pro-
       cessing together.

       It is possible to get into a dangerous situation:  if  you
       put  one  server  into  the  PARTNER-DOWN  state, and then
       *that* server goes down, and the other server  comes  back
       up,  the  other server will not know that the first server
       was in the PARTNER-DOWN state,  and  may  issue  addresses
       previously   issued  by  the  other  server  to  different
       clients,  resulting  in  IP  address  conflicts.    Before
       putting  a server into PARTNER-DOWN state, therefore, make
       _s_u_r_e that the other server will not restart automatically.

       The  failover protocol defines a primary server role and a
       secondary server role.   There are some differences in how
       primaries and secondaries act, but most of the differences
       simply have to do with providing a way for  each  peer  to
       behave in the opposite way from the other.   So one server
       must be configured as primary, and the other must be  con-
       figured as secondary, and it doesn't matter too much which
       one is which.

FFAAIILLOOVVEERR SSTTAARRTTUUPP
       When a server starts that has not previously  communicated
       with  its  failover peer, it must establish communications
       with its failover peer and synchronize with it  before  it
       can  serve  clients.    This can happen either because you
       have just configured your DHCP servers to perform failover
       for  the  first  time,  or  because  one  of your failover
       servers has failed catastrophically and lost its database.

       The  initial  recovery  process is designed to ensure that
       when one failover peer loses its database and then  resyn-
       chronizes,  any  leases  that  the  failed server gave out
       before it failed will be honored.  When the failed  server
       starts up, it notices that it has no saved failover state,
       and attempts to contact its peer.

       When it has established contact, it asks the  peer  for  a
       complete  copy  its  peer's lease database.  The peer then
       sends its complete database, and sends a message  indicat-
       ing  that  it is done.  The failed server then waits until
       MCLT has passed, and once MCLT  has  passed  both  servers
       make  the  transition  back  into  normal operation.  This
       waiting period ensures that any leases the  failed  server
       may  have  given out while out of contact with its partner
       will have expired.

       While the failed server is recovering, its partner remains
       in  the partner-down state, which means that it is serving
       all clients.  The failed server provides no service at all



                                                                9





dhcpd.conf(5)                                       dhcpd.conf(5)


       to DHCP clients until it has made the transition into nor-
       mal operation.

       In the case where both servers detect that they have never
       before  communicated with their partner, they both come up
       in this recovery state and follow the  procedure  we  have
       just  described.    In  this case, no service will be pro-
       vided to DHCP clients until MCLT has expired.

CCOONNFFIIGGUURRIINNGG FFAAIILLOOVVEERR
       In order to configure failover, you need to write  a  peer
       declaration that configures the failover protocol, and you
       need to write peer references in each pool declaration for
       which  you  want  to  do failover.   You do not have to do
       failover for all pools on a given network segment.     You
       must not tell one server it's doing failover on a particu-
       lar address pool and tell the other it is not.   You  must
       not  have  any  common  address pools on which you are not
       doing failover.  A pool declaration that utilizes failover
       would look like this:

       pool {
            failover peer "foo";
            _p_o_o_l _s_p_e_c_i_f_i_c _p_a_r_a_m_e_t_e_r_s
       };

       The  server currently  does very  little  sanity checking,
       so if  you configure it wrong, it will just  fail  in  odd
       ways.   I  would  recommend  therefore  that you either do
       failover or don't do failover,  but  don't  do  any  mixed
       pools.   Also,  use the same master configuration file for
       both  servers,  and  have  a  separate  file   that   con-
       tains  the  peer declaration and includes the master file.
       This will help you to avoid configuration  mismatches.  As
       our  implementation evolves,  this will become  less of  a
       problem.  A  basic  sample dhcpd.conf  file for  a primary
       server might look like this:

       failover peer "foo" {
         primary;
         address anthrax.rc.vix.com;
         port 519;
         peer address trantor.rc.vix.com;
         peer port 520;
         max-response-delay 60;
         max-unacked-updates 10;
         mclt 3600;
         split 128;
         load balance max seconds 3;
       }

       include "/etc/dhcpd.master";

       The statements in the peer declaration are as follows:



                                                               10





dhcpd.conf(5)                                       dhcpd.conf(5)


       The _p_r_i_m_a_r_y and _s_e_c_o_n_d_a_r_y statements

          [ pprriimmaarryy | sseeccoonnddaarryy ];;

          This  determines  whether the server is primary or sec-
          ondary, as described earlier under DHCP FAILOVER.

       The _a_d_d_r_e_s_s statement

          aaddddrreessss _a_d_d_r_e_s_s;;

          The aaddddrreessss statement declares the IP  address  or  DNS
          name  on which the server should listen for connections
          from its failover peer, and also the value to  use  for
          the  DHCP Failover Protocol server identifier.  Because
          this value is used as an  identifier,  it  may  not  be
          omitted.

       The _p_e_e_r _a_d_d_r_e_s_s statement

          ppeeeerr aaddddrreessss _a_d_d_r_e_s_s;;

          The  ppeeeerr  aaddddrreessss statement declares the IP address or
          DNS name to which the server should  connect  to  reach
          its failover peer for failover messages.

       The _p_o_r_t statement

          ppoorrtt _p_o_r_t_-_n_u_m_b_e_r;;

          The  ppoorrtt  statement declares the TCP port on which the
          server should listen for connections from its  failover
          peer.    This  statement  may not currently be omitted,
          because the failover  protocol  does  not  yet  have  a
          reserved TCP port number.

       The _p_e_e_r _p_o_r_t statement

          ppeeeerr ppoorrtt _p_o_r_t_-_n_u_m_b_e_r;;

          The  ppeeeerr ppoorrtt statement declares the TCP port to which
          the server should connect to reach  its  failover  peer
          for  failover  messages.    This  statement  may not be
          omitted because the failover protocol does not yet have
          a  reserved TCP port number.   The port number declared
          in the ppeeeerr ppoorrtt statement may be the same as the  port
          number declared in the ppoorrtt statement.

       The _m_a_x_-_r_e_s_p_o_n_s_e_-_d_e_l_a_y statement

          mmaaxx--rreessppoonnssee--ddeellaayy _s_e_c_o_n_d_s;;

          The  mmaaxx--rreessppoonnssee--ddeellaayy statement tells the DHCP server
          how many seconds may pass without receiving  a  message



                                                               11





dhcpd.conf(5)                                       dhcpd.conf(5)


          from  its  failover peer before it assumes that connec-
          tion has failed.   This number should be  small  enough
          that  a  transient network failure that breaks the con-
          nection will not result in the  servers  being  out  of
          communication  for  a  long time, but large enough that
          the server isn't constantly making and breaking connec-
          tions.   This parameter must be specified.

       The _m_a_x_-_u_n_a_c_k_e_d_-_u_p_d_a_t_e_s statement

          mmaaxx--uunnaacckkeedd--uuppddaatteess _c_o_u_n_t;;

          The mmaaxx--uunnaacckkeedd--uuppddaatteess statement tells the remote DHCP
          server how many BNDUPD messages it can send  before  it
          receives  a  BNDACK  from  the local system.   We don't
          have enough operational experience to say what  a  good
          value for this is, but 10 seems to work.   This parame-
          ter must be specified.

       The _m_c_l_t statement

          mmcclltt _s_e_c_o_n_d_s;;

          The mmcclltt statement  defines  the  Maximum  Client  Lead
          Time.    It  must  be specified on the primary, and may
          not be specified on the secondary.   This is the length
          of  time  for  which  a  lease may be renewed by either
          failover  peer  without  contacting  the  other.    The
          longer  you  set  this, the longer it will take for the
          running server to recover  IP  addresses  after  moving
          into  PARTNER-DOWN state.   The shorter you set it, the
          more load your servers will experience  when  they  are
          not  communicating.   A value of something like 3600 is
          probably reasonable, but again bear  in  mind  that  we
          have no real operational experience with this.

       The _s_p_l_i_t statement

          sspplliitt _i_n_d_e_x;;

          The  split  statement  specifies  the split between the
          primary and secondary for the purposes of load  balanc-
          ing.   Whenever a client makes a DHCP request, the DHCP
          server  runs  a  hash  on  the  client  identification,
          resulting  in  value from 0 to 255.  This is used as an
          index into a 256 bit field.  If the bit at  that  index
          is set, the primary is responsible.  If the bit at that
          index is not set, the secondary  is  responsible.   The
          sspplliitt value determines how many of the leading bits are
          set to one.  So, in practice, higher split values  will
          cause  the  primary to serve more clients than the sec-
          ondary.  Lower split values, the converse.  Legal  val-
          ues are between 0 and 255, of which the most reasonable
          is 128.



                                                               12





dhcpd.conf(5)                                       dhcpd.conf(5)


       The _h_b_a statement

          hhbbaa _c_o_l_o_n_-_s_e_p_a_r_a_t_e_d_-_h_e_x_-_l_i_s_t;;

          The hba statement specifies the split between the  pri-
          mary  and  secondary  as a bitmap rather than a cutoff,
          which theoretically allows for  finer-grained  control.
          In  practice,  there is probably no need for such fine-
          grained control, however.   An example hba statement:

            hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:
                00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00;

          This is equivalent to a sspplliitt 112288;; statement, and iden-
          tical.   The following two examples are also equivalent
          to a sspplliitt of 128, but are not identical:

            hba aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:
                aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa;

            hba 55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:
                55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55;

          They are equivalent, because half the bits are  set  to
          0,  half  are  set  to 1 (0xa and 0x5 are 1010 and 0101
          binary  respectively)  and  consequently   this   would
          roughly divide the clients equally between the servers.
          They are not identical, because the actual  peers  this
          would  load  balance  to  each server are different for
          each example.

          You must only have sspplliitt or hhbbaa  defined,  never  both.
          For  most  cases,  the  fine-grained  control  that hhbbaa
          offers isn't necessary, and sspplliitt should be used.

       The _l_o_a_d _b_a_l_a_n_c_e _m_a_x _s_e_c_o_n_d_s statement

          llooaadd bbaallaannccee mmaaxx sseeccoonnddss _s_e_c_o_n_d_s;;

          This statement allows you to configure a  cutoff  after
          which  load balancing is disabled.  The cutoff is based
          on the number of seconds  since  the  client  sent  its
          first  DHCPDISCOVER  or  DHCPREQUEST  message, and only
          works with clients that correctly  implement  the  _s_e_c_s
          field - fortunately most clients do.  We recommend set-
          ting this to something like 3 or 5.  The effect of this
          is  that if one of the failover peers gets into a state
          where it is responding to  failover  messages  but  not
          responding  to some client requests, the other failover
          peer will take over its client  load  automatically  as
          the clients retry.

       The Failover pool balance statements.




                                                               13





dhcpd.conf(5)                                       dhcpd.conf(5)


           mmaaxx--lleeaassee--mmiissbbaallaannccee _p_e_r_c_e_n_t_a_g_e;;
           mmaaxx--lleeaassee--oowwnneerrsshhiipp _p_e_r_c_e_n_t_a_g_e;;
           mmiinn--bbaallaannccee _s_e_c_o_n_d_s;;
           mmaaxx--bbaallaannccee _s_e_c_o_n_d_s;;

          This  version of the DHCP Server evaluates pool balance
          on a schedule, rather than  on  demand  as  leases  are
          allocated.   The  latter approach proved to be slightly
          klunky  when  pool  misbalanced  reach  total   satura-
          tion...when  any server ran out of leases to assign, it
          also lost its ability to notice it had run dry.

          In order to understand pool balance, some  elements  of
          its  operation  first need to be defined.  First, there
          are 'free' and 'backup'  leases.   Both  of  these  are
          referred   to  as  'free  state  leases'.   'free'  and
          'backup' are 'the free states' for the purpose of  this
          document.   The difference is that only the primary may
          allocate from 'free' leases unless under  special  cir-
          cumstances,   and   only  the  secondary  may  allocate
          'backup' leases.

          When pool balance  is  performed,  the  only  plausible
          expectation  is  to  provide  a 50/50 split of the free
          state leases between the two servers.  This is  because
          no  one  can predict which server will fail, regardless
          of the relative load placed upon the  two  servers,  so
          giving  each  server half the leases gives both servers
          the same amount  of  'failure  endurance'.   Therefore,
          there  is  no way to configure any different behaviour,
          outside of some very small  windows  we  will  describe
          shortly.

          The first thing calculated on any pool balance run is a
          value referred to as 'lts', or "Leases To Send".  This,
          simply,  is  the  difference  in  the count of free and
          backup leases, divided by two.  For the  secondary,  it
          is  the  difference  in  the  backup  and  free leases,
          divided by two.  The resulting value is signed:  if  it
          is  positive,  the local server is expected to hand out
          leases to retain a 50/50 balance.  If it  is  negative,
          the  remote server would need to send leases to balance
          the pool.  Once the lts value reaches zero, the pool is
          perfectly  balanced (give or take one lease in the case
          of an odd number of total free state leases).

          The current approach is still something of a hybrid  of
          the  old  approach,  marked by the presence of the mmaaxx--
          lleeaassee--mmiissbbaallaannccee statement.  This parameter  configures
          what used to be a 10% fixed value in previous versions:
          if lts is less than free+backup *  mmaaxx--lleeaassee--mmiissbbaallaannccee
          percent,  then  the  server will skip balancing a given
          pool (it won't bother moving any leases, even  if  some
          leases  "should"  be moved).  The meaning of this value



                                                               14





dhcpd.conf(5)                                       dhcpd.conf(5)


          is also somewhat overloaded, however, in that  it  also
          governs  the  estimation  of when to attempt to balance
          the pool (which may then also be  skipped  over).   The
          oldest  leases  in the free and backup states are exam-
          ined.  The time they have resided in  their  respective
          queues is used as an estimate to indicate how much time
          it is probable it would take before the leases  at  the
          top  of  the list would be consumed (and thus, how long
          it would take to use all leases in that  state).   This
          percentage is directly multiplied by this time, and fit
          into the schedule if it falls  within  the  mmiinn--bbaallaannccee
          and  mmaaxx--bbaallaannccee configured values.  The scheduled pool
          check time is only moved in a downwards  direction,  it
          is  never  increased.   Lastly, if the lts is more than
          double this number in the negative direction, the local
          server  will  'panic'  and transmit a Failover protocol
          POOLREQ message, in the hopes that  the  remote  system
          will be woken up into action.

          Once  the  lts  value  exceeds the mmaaxx--lleeaassee--mmiissbbaallaannccee
          percentage of total  free  state  leases  as  described
          above,  leases are moved to the remote server.  This is
          done in two passes.

          In the first pass, only leases whose most recent  bound
          client  would  have  been served by the remote server -
          according to the  Load  Balance  Algorithm  (see  above
          sspplliitt  and  hhbbaa  configuration  statements) - are given
          away to the peer.  This first pass  will  happily  con-
          tinue  to  give away leases, decrementing the lts value
          by one for each, until the lts value  has  reached  the
          negative  of  the  total number of leases multiplied by
          the mmaaxx--lleeaassee--oowwnneerrsshhiipp percentage.  So it  is  through
          this  value  that  you can permit a small misbalance of
          the lease pools - for the purpose of  giving  the  peer
          more  than  a  50/50  share of leases in the hopes that
          their clients might some day return and be allocated by
          the   peer   (operating  normally).   This  process  is
          referred to as 'MAC  Address  Affinity',  but  this  is
          somewhat  misnamed:  it  applies equally to DHCP Client
          Identifier options.  Note also that affinity is applied
          to  leases when they enter the state be moved from free
          to backup if the secondary already has  more  than  its
          share.

          The  second pass is only entered into if the first pass
          fails to reduce the lts underneath the total number  of
          free state leases multiplied by the mmaaxx--lleeaassee--oowwnneerrsshhiipp
          percentage.  In this pass, the oldest leases are  given
          over  to the peer without second thought about the Load
          Balance Algorithm, and this  continues  until  the  lts
          falls  under this value.  In this way, the local server
          will also happily keep a small percentage of the leases
          that would normally load balance to itself.



                                                               15





dhcpd.conf(5)                                       dhcpd.conf(5)


          So,   the   mmaaxx--lleeaassee--mmiissbbaallaannccee   value   acts   as  a
          behavioural  gate.   Smaller  values  will  cause  more
          leases  to  transition states to balance the pools over
          time, higher values will decrease the amount of  change
          (but  may  lead  to pool starvation if there's a run on
          leases).

          The mmaaxx--lleeaassee--oowwnneerrsshhiipp value permits a  small  (perce-
          natge) skew in the lease balance of a percentage of the
          total number of free state leases.

          Finally, the mmiinn--bbaallaannccee and mmaaxx--bbaallaannccee  make  certain
          that  a scheduled rebalance event happens within a rea-
          sonable timeframe (not to be thrown off by,  for  exam-
          ple, a 7 year old free lease).

          Plausible  values for the percentages lie between 0 and
          100, inclusive, but values over 50  are  indistinguish-
          able from one another (once lts exceeds 50% of the free
          state leases, one server must therefore  have  100%  of
          the leases in its respective free state).  It is recom-
          mended to select a mmaaxx--lleeaassee--oowwnneerrsshhiipp  value  that  is
          lower than the value selected for the mmaaxx--lleeaassee--mmiissbbaall--
          aannccee value.  mmaaxx--lleeaassee--oowwnneerrsshhiipp defaults  to  10,  and
          mmaaxx--lleeaassee--mmiissbbaallaannccee defaults to 15.

          Plausible  values  for  the mmiinn--bbaallaannccee and mmaaxx--bbaallaannccee
          times also range from 0 to (2^32)-1 (or  the  limit  of
          your  local time_t value), but default to values 60 and
          3600 respectively (to place balance  events  between  1
          minute and 1 hour).

CCLLIIEENNTT CCLLAASSSSIINNGG
       Clients can be separated into classes, and treated differ-
       ently depending on what class they are in.   This  separa-
       tion  can  be done either with a conditional statement, or
       with a match statement within the class declaration.    It
       is  possible  to  specify  a  limit on the total number of
       clients within a particular class  or  subclass  that  may
       hold  leases  at  one  time, and it is possible to specify
       automatic subclassing based on the contents of the  client
       packet.

       To add clients to classes based on conditional evaluation,
       you can specify a matching expression in the class  state-
       ment:

       class "ras-clients" {
         match if substring (option dhcp-client-identifier, 1, 3) = "RAS";
       }

       Note  that  whether  you  use  matching expressions or add
       statements (or both) to classify clients, you must  always
       write a class declaration for any class that you use.   If



                                                               16





dhcpd.conf(5)                                       dhcpd.conf(5)


       there will be no match statement and  no  in-scope  state-
       ments for a class, the declaration should look like this:

       class "ras-clients" {
       }

SSUUBBCCLLAASSSSEESS
       In  addition  to  classes,  it is possible to declare sub-
       classes.   A subclass is a class with the same name  as  a
       regular  class,  but  with  a specific submatch expression
       which is hashed for quick matching.  This is essentially a
       speed hack - the main difference between five classes with
       match expressions and one class with  five  subclasses  is
       that  it  will  be  quicker to find the subclasses.   Sub-
       classes work as follows:

       class "allocation-class-1" {
         match pick-first-value (option dhcp-client-identifier, hardware);
       }

       class "allocation-class-2" {
         match pick-first-value (option dhcp-client-identifier, hardware);
       }

       subclass "allocation-class-1" 1:8:0:2b:4c:39:ad;
       subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3;
       subclass "allocation-class-1" 1:0:0:c4:aa:29:44;

       subnet 10.0.0.0 netmask 255.255.255.0 {
         pool {
           allow members of "allocation-class-1";
           range 10.0.0.11 10.0.0.50;
         }
         pool {
           allow members of "allocation-class-2";
           range 10.0.0.51 10.0.0.100;
         }
       }

       The data following the class name in the subclass declara-
       tion  is  a  constant  value  to use in matching the match
       expression for the class.  When class  matching  is  done,
       the  server  will  evaluate  the match expression and then
       look the result up in the hash  table.    If  it  finds  a
       match, the client is considered a member of both the class
       and the subclass.

       Subclasses can be declared with or without scope.   In the
       above  example,  the  sole  purpose  of the subclass is to
       allow some clients access to one address pool, while other
       clients  are given access to the other pool, so these sub-
       classes are declared without scopes.   If part of the pur-
       pose  of  the  subclass were to define different parameter
       values for some clients, you might want  to  declare  some



                                                               17





dhcpd.conf(5)                                       dhcpd.conf(5)


       subclasses with scopes.

       In  the  above  example,  if  you had a single client that
       needed some configuration parameters, while  most  didn't,
       you  might  write  the  following subclass declaration for
       that client:

       subclass "allocation-class-2" 1:08:00:2b:a1:11:31 {
         option root-path "samsara:/var/diskless/alphapc";
         filename "/tftpboot/netbsd.alphapc-diskless";
       }

       In this example, we've used subclassing as a way  to  con-
       trol  address  allocation on a per-client basis.  However,
       it's also possible to use subclassing in ways that are not
       specific to clients - for example, to use the value of the
       vendor-class-identifier option to determine what values to
       send  in the vendor-encapsulated-options option.  An exam-
       ple of this is shown under the VENDOR ENCAPSULATED OPTIONS
       head in the ddhhccpp--ooppttiioonnss((55)) manual page.

PPEERR--CCLLAASSSS LLIIMMIITTSS OONN DDYYNNAAMMIICC AADDDDRREESSSS AALLLLOOCCAATTIIOONN
       You  may  specify  a  limit  to the number of clients in a
       class that can be assigned leases.   The  effect  of  this
       will  be  to make it difficult for a new client in a class
       to get an address.   Once a class with such  a  limit  has
       reached its limit, the only way a new client in that class
       can get a lease is for an existing  client  to  relinquish
       its  lease,  either  by letting it expire, or by sending a
       DHCPRELEASE packet.   Classes with lease limits are speci-
       fied as follows:

       class "limited-1" {
         lease limit 4;
       }

       This  will produce a class in which a maximum of four mem-
       bers may hold a lease at one time.

SSPPAAWWNNIINNGG CCLLAASSSSEESS
       It is possible to declare a _s_p_a_w_n_i_n_g  _c_l_a_s_s.   A  spawning
       class  is  a  class that automatically produces subclasses
       based on what the client sends.   The reason that spawning
       classes  were  created  was  to make it possible to create
       lease-limited classes on the fly.   The envisioned  appli-
       cation  is  a cable-modem environment where the ISP wishes
       to provide clients at a particular site with more than one
       IP address, but does not wish to provide such clients with
       their own subnet, nor give them an unlimited number of  IP
       addresses  from the network segment to which they are con-
       nected.

       Many cable modem head-end systems can be configured to add
       a  Relay  Agent  Information  option  to DHCP packets when



                                                               18





dhcpd.conf(5)                                       dhcpd.conf(5)


       relaying them to the DHCP server.    These  systems  typi-
       cally  add  a circuit ID or remote ID option that uniquely
       identifies the customer site.   To take advantage of this,
       you can write a class declaration as follows:

       class "customer" {
         spawn with option agent.circuit-id;
         lease limit 4;
       }

       Now  whenever a request comes in from a customer site, the
       circuit ID option will be checked against the class's hash
       table.    If  a subclass is found that matches the circuit
       ID, the client will be classified  in  that  subclass  and
       treated  accordingly.    If  no subclass is found matching
       the circuit ID, a new one will be created  and  logged  in
       the  ddhhccppdd..lleeaasseess  file, and the client will be classified
       in this new class.   Once the client has been  classified,
       it  will  be  treated according to the rules of the class,
       including, in this case, being  subject  to  the  per-site
       limit of four leases.

       The   use  of  the  subclass  spawning  mechanism  is  not
       restricted to relay agent options - this particular  exam-
       ple  is  given only because it is a fairly straightforward
       one.

CCOOMMBBIINNIINNGG MMAATTCCHH,, MMAATTCCHH IIFF AANNDD SSPPAAWWNN WWIITTHH
       In some cases, it may be useful to use one  expression  to
       assign  a  client  to  a  particular  class,  and a second
       expression to put it into a subclass of that class.   This
       can  be  done  by  combining  the  mmaattcchh iiff and ssppaawwnn wwiitthh
       statements, or the mmaattcchh iiff and  mmaattcchh  statements.    For
       example:

       class "jr-cable-modems" {
         match if option dhcp-vendor-identifier = "jrcm";
         spawn with option agent.circuit-id;
         lease limit 4;
       }

       class "dv-dsl-modems" {
         match if opton dhcp-vendor-identifier = "dvdsl";
         spawn with option agent.circuit-id;
         lease limit 16;
       }

       This  allows  you  to  have two classes that both have the
       same ssppaawwnn wwiitthh expression without getting the clients  in
       the two classes confused with each other.

DDYYNNAAMMIICC DDNNSS UUPPDDAATTEESS
       The  DHCP server has the ability to dynamically update the
       Domain Name System.  Within the configuration  files,  you



                                                               19





dhcpd.conf(5)                                       dhcpd.conf(5)


       can  define  how  you  want  the  Domain Name System to be
       updated.  These updates are RFC 2136 compliant so any  DNS
       server  supporting  RFC  2136  should  be  able  to accept
       updates from the DHCP server.

       Two DNS update  schemes  are  currently  implemented,  and
       another is planned.   The two that are currently available
       are the ad-hoc DNS update mode and  the  interim  DHCP-DNS
       interaction  draft  update mode.  If and when the DHCP-DNS
       interaction draft and the DHCID draft make it through  the
       IETF  standards process, there will be a third mode, which
       will be the standard DNS update method.   The DHCP  server
       must  be  configured  to use one of the two currently-sup-
       ported methods, or not to do dns updates.    This  can  be
       done with the _d_d_n_s_-_u_p_d_a_t_e_-_s_t_y_l_e configuration parameter.

TTHHEE AADD--HHOOCC DDNNSS UUPPDDAATTEE SSCCHHEEMMEE
       The ad-hoc Dynamic DNS update scheme is nnooww ddeepprreeccaatteedd and
       ddooeess nnoott wwoorrkk..  In future releases of the ISC DHCP server,
       this  scheme  will  not  likely be available.  The interim
       scheme works, allows for failover, and should now be used.
       The  following  description is left here for informational
       purposes only.

       The ad-hoc Dynamic DNS update scheme implemented  in  this
       version  of  the  ISC  DHCP  server is a prototype design,
       which does not have much to do with  the  standard  update
       method  that is being standardized in the IETF DHC working
       group, but rather implements some very basic, yet  useful,
       update  capabilities.    This  mode ddooeess nnoott wwoorrkk with the
       _f_a_i_l_o_v_e_r _p_r_o_t_o_c_o_l because it does not account for the pos-
       sibility  of  two different DHCP servers updating the same
       set of DNS records.

       For the ad-hoc DNS update method,  the  client's  FQDN  is
       derived in two parts.   First, the hostname is determined.
       Then, the domain name is determined, and appended  to  the
       hostname.

       The  DHCP server determines the client's hostname by first
       looking for  a  _d_d_n_s_-_h_o_s_t_n_a_m_e  configuration  option,  and
       using  that  if  it is present.  If no such option is pre-
       sent, the server looks for a valid hostname  in  the  FQDN
       option  sent  by the client.  If one is found, it is used;
       otherwise, if the client sent a host-name option, that  is
       used.   Otherwise,  if  there  is  a host declaration that
       applies to the client, the name from that declaration will
       be  used.   If  none of these applies, the server will not
       have a hostname for the client, and will not be able to do
       a DNS update.

       The  domain  name  is  determined from the _d_d_n_s_-_d_o_m_a_i_n_n_a_m_e
       configuration option.  The default configuration for  this
       option is:



                                                               20





dhcpd.conf(5)                                       dhcpd.conf(5)


         option server.ddns-domainname = config-option domain-name;

       So  if  this  configuration  option is not configured to a
       different value (over-riding the above default), or  if  a
       domain-name   option  has  not  been  configured  for  the
       client's scope, then the server will not attempt  to  per-
       form a DNS update.

       The  client's  fully-qualified  domain name, derived as we
       have described, is used as the name on which an "A" record
       will  be stored.  The A record will contain the IP address
       that the client was assigned in its lease.   If  there  is
       already  an A record with the same name in the DNS server,
       no update of either the A or PTR records will occur - this
       prevents  a  client from claiming that its hostname is the
       name of some network server.   For example, if you have  a
       fileserver  called  "fs.sneedville.edu",  and  the  client
       claims its hostname is "fs", no DNS update  will  be  done
       for that client, and an error message will be logged.

       If  the  A record update succeeds, a PTR record update for
       the assigned IP address will be done, pointing  to  the  A
       record.    This  update is unconditional - it will be done
       even if another  PTR  record  of  the  same  name  exists.
       Since the IP address has been assigned to the DHCP server,
       this should be safe.

       Please  note  that  the  current  implementation   assumes
       clients  only  have a single network interface.   A client
       with two network interfaces will see unpredictable  behav-
       ior.    This  is  considered a bug, and will be fixed in a
       later release.   It may be  helpful  to  enable  the  _o_n_e_-
       _l_e_a_s_e_-_p_e_r_-_c_l_i_e_n_t  parameter so that roaming clients do not
       trigger this same behavior.

       The DHCP protocol normally involves a four-packet exchange
       -  first the client sends a DHCPDISCOVER message, then the
       server sends a DHCPOFFER, then the client sends a  DHCPRE-
       QUEST,  then  the server sends a DHCPACK.   In the current
       version of the server, the server will  do  a  DNS  update
       after  it  has received the DHCPREQUEST, and before it has
       sent the DHCPACK.   It only sends the DNS update if it has
       not  sent one for the client's address before, in order to
       minimize the impact on the DHCP server.

       When the client's lease expires, the DHCP server (if it is
       operating  at  the  time,  or  when next it operates) will
       remove the  client's  A  and  PTR  records  from  the  DNS
       database.    If the client releases its lease by sending a
       DHCPRELEASE message, the server will likewise remove the A
       and PTR records.

TTHHEE IINNTTEERRIIMM DDNNSS UUPPDDAATTEE SSCCHHEEMMEE
       The interim DNS update scheme operates mostly according to



                                                               21





dhcpd.conf(5)                                       dhcpd.conf(5)


       several drafts that are being considered by the  IETF  and
       are  expected  to  become standards, but are not yet stan-
       dards, and may not be standardized  exactly  as  currently
       proposed.   These are:

                 draft-ietf-dhc-ddns-resolution-??.txt
                   draft-ietf-dhc-fqdn-option-??.txt
                   draft-ietf-dnsext-dhcid-rr-??.txt

       Because  our implementation is slightly different than the
       standard, we will briefly document the operation  of  this
       update style here.

       The  first  point  to  understand  about this style of DNS
       update is that unlike the ad-hoc style,  the  DHCP  server
       does  not necessarily always update both the A and the PTR
       records.   The FQDN option includes  a  flag  which,  when
       sent  by  the  client, indicates that the client wishes to
       update its own A record.   In that case, the server can be
       configured  either  to  honor  the  client's intentions or
       ignore them.   This  is  done  with  the  statement  _a_l_l_o_w
       _c_l_i_e_n_t_-_u_p_d_a_t_e_s_;  or  the statement _i_g_n_o_r_e _c_l_i_e_n_t_-_u_p_d_a_t_e_s_;.
       By default, client updates are allowed.

       If the server is configured to allow client updates,  then
       if  the  client sends a fully-qualified domain name in the
       FQDN option, the server will use that name the client sent
       in  the  FQDN option to update the PTR record.   For exam-
       ple, let us say that the client  is  a  visitor  from  the
       "radish.org"  domain,  whose  hostname is "jschmoe".   The
       server is for the "example.org" domain.   The DHCP  client
       indicates   in   the   FQDN   option   that  its  FQDN  is
       "jschmoe.radish.org.".   It also indicates that  it  wants
       to  update  its  own A record.   The DHCP server therefore
       does not attempt to set up an A record for the client, but
       does  set  up  a  PTR  record  for  the IP address that it
       assigns the client, pointing at jschmoe.radish.org.   Once
       the DHCP client has an IP address, it can update its own A
       record, assuming that the  "radish.org"  DNS  server  will
       allow it to do so.

       If  the  server is configured not to allow client updates,
       or if the client doesn't want to do its  own  update,  the
       server  will  simply  choose  a  name  for the client from
       either the fqdn option (if present) or the hostname option
       (if  present).   It  will  use its own domain name for the
       client, just as in the ad-hoc update scheme.  It will then
       update  both  the A and PTR record, using the name that it
       chose for the client.   If the client sends a fully-quali-
       fied  domain name in the fqdn option, the server uses only
       the leftmost part of the domain  name  -  in  the  example
       above, "jschmoe" instead of "jschmoe.radish.org".

       Further,  if the _i_g_n_o_r_e _c_l_i_e_n_t_-_u_p_d_a_t_e_s_; directive is used,



                                                               22





dhcpd.conf(5)                                       dhcpd.conf(5)


       then the server will in addition send a  response  in  the
       DHCP  packet,  using  the FQDN Option, that implies to the
       client that it  should  perform  its  own  updates  if  it
       chooses  to  do so.  With _d_e_n_y _c_l_i_e_n_t_-_u_p_d_a_t_e_s_;, a response
       is  sent  which  indicates  the  client  may  not  perform
       updates.

       Also,  if  the _u_s_e_-_h_o_s_t_-_d_e_c_l_-_n_a_m_e_s configuration option is
       enabled, then the host declaration's _h_o_s_t_n_a_m_e will be used
       in  place  of the _h_o_s_t_n_a_m_e option, and the same rules will
       apply as described above.

       The other difference between the  ad-hoc  scheme  and  the
       interim  scheme  is that with the interim scheme, a method
       is used that allows more than one DHCP  server  to  update
       the  DNS  database without accidentally deleting A records
       that shouldn't be deleted nor failing  to  add  A  records
       that should be added.   The scheme works as follows:

       When  the DHCP server issues a client a new lease, it cre-
       ates a text string that is  an  MD5  hash  over  the  DHCP
       client's   identification   (see  draft-ietf-dnsext-dhcid-
       rr-??.txt for details).   The update adds an A record with
       the  name the server chose and a TXT record containing the
       hashed identifier string (hashid).   If this  update  suc-
       ceeds, the server is done.

       If  the  update fails because the A record already exists,
       then the DHCP server attempts to add the A record with the
       prerequisite  that  there must be a TXT record in the same
       name as the new A record, and that TXT  record's  contents
       must  be  equal to hashid.   If this update succeeds, then
       the client has its A record and PTR record.   If it fails,
       then  the name the client has been assigned (or requested)
       is in use, and can't be used  by  the  client.    At  this
       point  the  DHCP server gives up trying to do a DNS update
       for the client until the client chooses a new name.

       The interim DNS update scheme is called  interim  for  two
       reasons.   First,  it  does  not  quite follow the drafts.
       The current versions of the drafts call for  a  new  DHCID
       RRtype,  but  this is not yet available.   The interim DNS
       update scheme uses  a  TXT  record  instead.    Also,  the
       existing  ddns-resolution  draft calls for the DHCP server
       to put a DHCID RR on  the  PTR  record,  but  the  _i_n_t_e_r_i_m
       update  method does not do this.   It is our position that
       this is not useful, and we are working with the author  in
       hopes  of  removing it from the next version of the draft,
       or better understanding why it is considered useful.

       In addition to these differences, the server also does not
       update   very   aggressively.   Because  each  DNS  update
       involves a round trip to the DNS server, there is  a  cost
       associated with doing updates even if they do not actually



                                                               23





dhcpd.conf(5)                                       dhcpd.conf(5)


       modify the DNS  database.    So  the  DHCP  server  tracks
       whether or not it has updated the record in the past (this
       information is stored on the lease) and does  not  attempt
       to update records that it thinks it has already updated.

       This  can  lead  to  cases  where  the  DHCP server adds a
       record, and then the record is deleted through some  other
       mechanism,  but  the  server  never  again updates the DNS
       because it thinks the data is  already  there.    In  this
       case the data can be removed from the lease through opera-
       tor intervention, and once this has  been  done,  the  DNS
       will be updated the next time the client renews.

DDYYNNAAMMIICC DDNNSS UUPPDDAATTEE SSEECCUURRIITTYY
       When  you set your DNS server up to allow updates from the
       DHCP server,  you  may  be  exposing  it  to  unauthorized
       updates.   To avoid this, you should use TSIG signatures -
       a method of  cryptographically  signing  updates  using  a
       shared secret key.   As long as you protect the secrecy of
       this key, your updates should also be secure.   Note, how-
       ever,  that the DHCP protocol itself provides no security,
       and that clients can therefore provide information to  the
       DHCP  server  which  the  DHCP server will then use in its
       updates, with the constraints described previously.

       The DNS server must be configured to allow updates for any
       zone  that the DHCP server will be updating.  For example,
       let us say that clients in the sneedville.edu domain  will
       be  assigned  addresses  on  the 10.10.17.0/24 subnet.  In
       that case, you will need a key declaration  for  the  TSIG
       key  you  will  be using, and also two zone declarations -
       one for the zone containing A records that will be updates
       and  one  for  the  zone  containing PTR records - for ISC
       BIND, something like this:

       key DHCP_UPDATER {
         algorithm HMAC-MD5.SIG-ALG.REG.INT;
         secret pRP5FapFoJ95JEL06sv4PQ==;
       };

       zone "example.org" {
            type master;
            file "example.org.db";
            allow-update { key DHCP_UPDATER; };
       };

       zone "17.10.10.in-addr.arpa" {
            type master;
            file "10.10.17.db";
            allow-update { key DHCP_UPDATER; };
       };

       You will also have to configure your  DHCP  server  to  do
       updates  to  these  zones.    To  do  so,  you need to add



                                                               24





dhcpd.conf(5)                                       dhcpd.conf(5)


       something like this to your dhcpd.conf file:

       key DHCP_UPDATER {
         algorithm HMAC-MD5.SIG-ALG.REG.INT;
         secret pRP5FapFoJ95JEL06sv4PQ==;
       };

       zone EXAMPLE.ORG. {
         primary 127.0.0.1;
         key DHCP_UPDATER;
       }

       zone 17.127.10.in-addr.arpa. {
         primary 127.0.0.1;
         key DHCP_UPDATER;
       }

       The _p_r_i_m_a_r_y statement specifies the IP address of the name
       server whose zone information is to be updated.

       Note  that  the  zone  declarations  have to correspond to
       authority records in your name server - in the above exam-
       ple,  there  must  be an SOA record for "example.org." and
       for "17.10.10.in-addr.arpa.".   For example, if there were
       a  subdomain  "foo.example.org"  with no separate SOA, you
       could not write a zone declaration for  "foo.example.org."
       Also  keep in mind that zone names in your DHCP configura-
       tion should end in a "."; this is  the  preferred  syntax.
       If you do not end your zone name in a ".", the DHCP server
       will figure it out.  Also note that in the DHCP configura-
       tion,  zone  names  are  not  encapsulated in quotes where
       there are in the DNS configuration.

       You should choose your own secret key, of course.  The ISC
       BIND  8 and 9 distributions come with a program for gener-
       ating secret keys called dnssec-keygen.  The version  that
       comes  with  BIND  9  is likely to produce a substantially
       more random key, so we recommend you use that one even  if
       you  are  not using BIND 9 as your DNS server.  If you are
       using BIND 9's dnssec-keygen, the above key would be  cre-
       ated as follows:

            dnssec-keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER

       If you are using the BIND 8 dnskeygen program, the follow-
       ing command will generate a key as seen above:

            dnskeygen -H 128 -u -c -n DHCP_UPDATER

       You may wish to enable logging of DNS updates on your  DNS
       server.   To  do  so,  you might write a logging statement
       like the following:

       logging {



                                                               25





dhcpd.conf(5)                                       dhcpd.conf(5)


            channel update_debug {
                 file "/var/log/update-debug.log";
                 severity  debug 3;
                 print-category yes;
                 print-severity yes;
                 print-time     yes;
            };
            channel security_info    {
                 file "/var/log/named-auth.info";
                 severity  info;
                 print-category yes;
                 print-severity yes;
                 print-time     yes;
            };

            category update { update_debug; };
            category security { security_info; };
       };

       You   must   create   the   /var/log/named-auth.info   and
       /var/log/update-debug.log  files  before starting the name
       server.   For more information on  configuring  ISC  BIND,
       consult the documentation that accompanies it.

RREEFFEERREENNCCEE:: EEVVEENNTTSS
       There  are three kinds of events that can happen regarding
       a lease, and it is possible  to  declare  statements  that
       occur  when any of these events happen.   These events are
       the commit event, when the server has made a commitment of
       a  certain  lease to a client, the release event, when the
       client has released the server from  its  commitment,  and
       the expiry event, when the commitment expires.

       To  declare  a  set of statements to execute when an event
       happens, you must use the oonn statement,  followed  by  the
       name  of  the event, followed by a series of statements to
       execute  when  the  event  happens,  enclosed  in  braces.
       Events  are  used  to implement DNS updates, so you should
       not define your own event handlers if you  are  using  the
       built-in DNS update mechanism.

       The  built-in  version of the DNS update mechanism is in a
       text string towards the top of  server/dhcpd.c.    If  you
       want  to use events for things other than DNS updates, and
       you also want DNS updates, you will have to start  out  by
       copying  this code into your dhcpd.conf file and modifying
       it.

RREEFFEERREENNCCEE:: DDEECCLLAARRAATTIIOONNSS
       TThhee _i_n_c_l_u_d_e ssttaatteemmeenntt

        iinncclluuddee _"_f_i_l_e_n_a_m_e_";;

       The _i_n_c_l_u_d_e statement is used to read in a named file, and



                                                               26





dhcpd.conf(5)                                       dhcpd.conf(5)


       process  the  contents  of  that  file  as  though it were
       entered in place of the include statement.

       TThhee _s_h_a_r_e_d_-_n_e_t_w_o_r_k ssttaatteemmeenntt

        sshhaarreedd--nneettwwoorrkk _n_a_m_e {{
          [ _p_a_r_a_m_e_t_e_r_s ]
          [ _d_e_c_l_a_r_a_t_i_o_n_s ]
        }}

       The _s_h_a_r_e_d_-_n_e_t_w_o_r_k statement is used to  inform  the  DHCP
       server that some IP subnets actually share the same physi-
       cal network.  Any subnets in a shared  network  should  be
       declared  within  a  _s_h_a_r_e_d_-_n_e_t_w_o_r_k statement.  Parameters
       specified in the _s_h_a_r_e_d_-_n_e_t_w_o_r_k  statement  will  be  used
       when  booting  clients  on those subnets unless parameters
       provided at the subnet or host level  override  them.   If
       any subnet in a shared network has addresses available for
       dynamic allocation, those addresses are collected  into  a
       common  pool  for  that  shared  network  and  assigned to
       clients as needed.  There is  no  way  to  distinguish  on
       which subnet of a shared network a client should boot.

       _N_a_m_e should be the name of the shared network.   This name
       is used when printing debugging messages, so it should  be
       descriptive  for  the  shared network.   The name may have
       the syntax of a valid domain name (although it will  never
       be  used  as  such),  or  it  may  be  any arbitrary name,
       enclosed in quotes.

       TThhee _s_u_b_n_e_t ssttaatteemmeenntt

        ssuubbnneett _s_u_b_n_e_t_-_n_u_m_b_e_r nneettmmaasskk _n_e_t_m_a_s_k {{
          [ _p_a_r_a_m_e_t_e_r_s ]
          [ _d_e_c_l_a_r_a_t_i_o_n_s ]
        }}

       The _s_u_b_n_e_t statement is used to provide dhcpd with  enough
       information  to  tell  whether  or not an IP address is on
       that subnet.  It may also be used to  provide  subnet-spe-
       cific  parameters  and  to  specify  what addresses may be
       dynamically allocated to clients booting on  that  subnet.
       Such  addresses are specified using the _r_a_n_g_e declaration.

       The _s_u_b_n_e_t_-_n_u_m_b_e_r should be an IP address or  domain  name
       which  resolves  to  the subnet number of the subnet being
       described.   The _n_e_t_m_a_s_k should be an IP address or domain
       name which resolves to the subnet mask of the subnet being
       described.   The subnet number, together with the netmask,
       are  sufficient  to determine whether any given IP address
       is on the specified subnet.

       Although a netmask must be given with every subnet  decla-
       ration, it is recommended that if there is any variance in



                                                               27





dhcpd.conf(5)                                       dhcpd.conf(5)


       subnet masks at a site, a subnet-mask option statement  be
       used  in each subnet declaration to set the desired subnet
       mask, since any subnet-mask option statement will override
       the subnet mask declared in the subnet statement.

       TThhee _r_a_n_g_e ssttaatteemmeenntt

       rraannggee [ ddyynnaammiicc--bboooottpp ] _l_o_w_-_a_d_d_r_e_s_s [ _h_i_g_h_-_a_d_d_r_e_s_s];;

       For any subnet on which addresses will be assigned dynami-
       cally, there must be at least one _r_a_n_g_e  statement.    The
       range  statement gives the lowest and highest IP addresses
       in a range.   All IP addresses in the range should  be  in
       the subnet in which the _r_a_n_g_e statement is declared.   The
       _d_y_n_a_m_i_c_-_b_o_o_t_p flag may be specified if  addresses  in  the
       specified  range  may  be  dynamically  assigned  to BOOTP
       clients as well as DHCP clients.   When specifying a  sin-
       gle address, _h_i_g_h_-_a_d_d_r_e_s_s can be omitted.

       TThhee _h_o_s_t ssttaatteemmeenntt

        hhoosstt _h_o_s_t_n_a_m_e {
          [ _p_a_r_a_m_e_t_e_r_s ]
          [ _d_e_c_l_a_r_a_t_i_o_n_s ]
        }}

       The  hhoosstt declaration provides a scope in which to provide
       configuration information about  a  specific  client,  and
       also  provides  a  way to assign a client a fixed address.
       The host declaration provides a way for the DHCP server to
       identify  a DHCP or BOOTP client, and also a way to assign
       the client a static IP address.

       If it is desirable to be able to  boot  a  DHCP  or  BOOTP
       client  on more than one subnet with fixed addresses, more
       than one address may be  specified  in  the  _f_i_x_e_d_-_a_d_d_r_e_s_s
       declaration, or more than one hhoosstt statement may be speci-
       fied matching the same client.

       If client-specific boot parameters must  change  based  on
       the network to which the client is attached, then multiple
       hhoosstt declarations should be used.  The  hhoosstt  declarations
       will  only  match  a  client if one of their _f_i_x_e_d_-_a_d_d_r_e_s_s
       statements is viable on the  subnet  (or  shared  network)
       where the client is attached.  Conversely, for a hhoosstt dec-
       laration to match  a  client  being  allocated  a  dynamic
       address,  it  must  not have any _f_i_x_e_d_-_a_d_d_r_e_s_s statements.
       You may therefore need a mixture of hhoosstt declarations  for
       any  given  client...some having _f_i_x_e_d_-_a_d_d_r_e_s_s statements,
       others without.

       _h_o_s_t_n_a_m_e should be a name  identifying  the  host.   If  a
       _h_o_s_t_n_a_m_e option is not specified for the host, _h_o_s_t_n_a_m_e is
       used.



                                                               28





dhcpd.conf(5)                                       dhcpd.conf(5)


       _H_o_s_t declarations are matched  to  actual  DHCP  or  BOOTP
       clients  by  matching  the  dhcp-client-identifier  option
       specified in the _h_o_s_t declaration to the one  supplied  by
       the client, or, if the _h_o_s_t declaration or the client does
       not provide a dhcp-client-identifier option,  by  matching
       the _h_a_r_d_w_a_r_e parameter in the _h_o_s_t declaration to the net-
       work hardware address  supplied  by  the  client.    BOOTP
       clients  do not normally provide a _d_h_c_p_-_c_l_i_e_n_t_-_i_d_e_n_t_i_f_i_e_r,
       so the hardware address must be used for all clients  that
       may boot using the BOOTP protocol.

       Please  be  aware  that  oonnllyy  the  _d_h_c_p_-_c_l_i_e_n_t_-_i_d_e_n_t_i_f_i_e_r
       option and the hardware address can be  used  to  match  a
       host  declaration.    For  example,  it is not possible to
       match a host declaration to a _h_o_s_t_-_n_a_m_e option.   This  is
       because  the  host-name  option cannot be guaranteed to be
       unique for any given client,  whereas  both  the  hardware
       address  and  _d_h_c_p_-_c_l_i_e_n_t_-_i_d_e_n_t_i_f_i_e_r  option  are at least
       theoretically guaranteed to be unique to a given client.

       TThhee _g_r_o_u_p ssttaatteemmeenntt

        ggrroouupp {
          [ _p_a_r_a_m_e_t_e_r_s ]
          [ _d_e_c_l_a_r_a_t_i_o_n_s ]
        }}

       The group statement is used simply to apply  one  or  more
       parameters to a group of declarations.   It can be used to
       group hosts,  shared  networks,  subnets,  or  even  other
       groups.

RREEFFEERREENNCCEE:: AALLLLOOWW AANNDD DDEENNYY
       The  _a_l_l_o_w  and _d_e_n_y statements can be used to control the
       response of the DHCP server to various sorts of  requests.
       The  allow and deny keywords actually have different mean-
       ings depending on the context.  In a pool  context,  these
       keywords  can  be  used to set up access lists for address
       allocation pools.  In other contexts, the keywords  simply
       control  general  server  behavior with respect to clients
       based on scope.   In a non-pool context, the  _i_g_n_o_r_e  key-
       word  can  be used in place of the _d_e_n_y keyword to prevent
       logging of denied requests.


AALLLLOOWW DDEENNYY AANNDD IIGGNNOORREE IINN SSCCOOPPEE
       The following usages of allow and deny will  work  in  any
       scope, although it is not recommended that they be used in
       pool declarations.

       TThhee _u_n_k_n_o_w_n_-_c_l_i_e_n_t_s kkeeyywwoorrdd

        aallllooww uunnkknnoowwnn--cclliieennttss;;
        ddeennyy uunnkknnoowwnn--cclliieennttss;;



                                                               29





dhcpd.conf(5)                                       dhcpd.conf(5)


        iiggnnoorree uunnkknnoowwnn--cclliieennttss;;

       The uunnkknnoowwnn--cclliieennttss flag is used to tell dhcpd whether  or
       not  to  dynamically  assign addresses to unknown clients.
       Dynamic address assignment to unknown clients  is  aalllloowwed
       by default.  An unknown client is simply a client that has
       no host declaration.

       The use of this option is now _d_e_p_r_e_c_a_t_e_d.  If you are try-
       ing  to  restrict access on your network to known clients,
       you  should  use  ddeennyy  uunnkknnoowwnn--cclliieennttss;;  inside  of  your
       address  pool,  as  described  under the heading ALLOW AND
       DENY WITHIN POOL DECLARAIONS.

       TThhee _b_o_o_t_p kkeeyywwoorrdd

        aallllooww bboooottpp;;
        ddeennyy bboooottpp;;
        iiggnnoorree bboooottpp;;

       The bboooottpp flag is used to tell dhcpd  whether  or  not  to
       respond  to  bootp  queries.  Bootp queries are aalllloowwed by
       default.

       This option does not satisfy the requirement  of  failover
       peers for denying dynamic bootp clients.  The ddeennyy ddyynnaammiicc
       bboooottpp cclliieennttss;; option should  be  used  instead.  See  the
       ALLOW  AND  DENY  WITHIN POOL DECLARATIONS section of this
       man page for more details.

       TThhee _b_o_o_t_i_n_g kkeeyywwoorrdd

        aallllooww bboooottiinngg;;
        ddeennyy bboooottiinngg;;
        iiggnnoorree bboooottiinngg;;

       The bboooottiinngg flag is used to tell dhcpd whether or  not  to
       respond to queries from a particular client.  This keyword
       only has meaning when it appears in  a  host  declaration.
       By  default, booting is aalllloowwed, but if it is disabled for
       a particular client, then that client will not be able  to
       get an address from the DHCP server.

       TThhee _d_u_p_l_i_c_a_t_e_s kkeeyywwoorrdd

        aallllooww dduupplliiccaatteess;;
        ddeennyy dduupplliiccaatteess;;

       Host  declarations  can match client messages based on the
       DHCP Client Identifier option or  based  on  the  client's
       network  hardware  type  and  MAC  address.    If  the MAC
       address is used,  the  host  declaration  will  match  any
       client with that MAC address - even clients with different
       client identifiers.   This doesn't normally happen, but is



                                                               30





dhcpd.conf(5)                                       dhcpd.conf(5)


       possible  when  one  computer  has more than one operating
       system installed on it - for  example,  Microsoft  Windows
       and NetBSD or Linux.

       The  dduupplliiccaatteess  flag  tells  the  DHCP  server  that if a
       request is received from a client  that  matches  the  MAC
       address  of  a host declaration, any other leases matching
       that MAC address should be discarded by the  server,  even
       if  the  UID is not the same.   This is a violation of the
       DHCP protocol, but can prevent clients whose client  iden-
       tifiers  change  regularly from holding many leases at the
       same time.  By default, duplicates are aalllloowwed.

       TThhee _d_e_c_l_i_n_e_s kkeeyywwoorrdd

        aallllooww ddeecclliinneess;;
        ddeennyy ddeecclliinneess;;
        iiggnnoorree ddeecclliinneess;;

       The DHCPDECLINE message is used by DHCP clients  to  indi-
       cate  that  the lease the server has offered is not valid.
       When the server receives a DHCPDECLINE  for  a  particular
       address,  it normally abandons that address, assuming that
       some unauthorized system is using  it.   Unfortunately,  a
       malicious or buggy client can, using DHCPDECLINE messages,
       completely exhaust  the  DHCP  server's  allocation  pool.
       The server will reclaim these leases, but while the client
       is running through the pool, it may cause serious  thrash-
       ing  in the DNS, and it will also cause the DHCP server to
       forget old DHCP client address allocations.

       The ddeecclliinneess flag tells the DHCP server whether or not  to
       honor  DHCPDECLINE  messages.    If  it  is set to ddeennyy or
       iiggnnoorree in a particular scope, the  DHCP  server  will  not
       respond to DHCPDECLINE messages.

       TThhee _c_l_i_e_n_t_-_u_p_d_a_t_e_s kkeeyywwoorrdd

        aallllooww cclliieenntt--uuppddaatteess;;
        ddeennyy cclliieenntt--uuppddaatteess;;

       The  cclliieenntt--uuppddaatteess  flag tells the DHCP server whether or
       not to honor the client's intention to do its  own  update
       of its A record.  This is only relevant when doing _i_n_t_e_r_i_m
       DNS updates.   See the documentation under the heading THE
       INTERIM DNS UPDATE SCHEME for details.

       TThhee _l_e_a_s_e_q_u_e_r_y kkeeyywwoorrdd

        aallllooww lleeaasseeqquueerryy;;
        ddeennyy lleeaasseeqquueerryy;;

       The  lleeaasseeqquueerryy  flag tells the DHCP server whether or not
       to  answer  DHCPLEASEQUERY  packets.  The  answer   to   a



                                                               31





dhcpd.conf(5)                                       dhcpd.conf(5)


       DHCPLEASEQUERY  packet  includes  information about a spe-
       cific lease, such as when it was issued and when  it  will
       expire.  By  default, the server will not respond to these
       packets.

AALLLLOOWW AANNDD DDEENNYY WWIITTHHIINN PPOOOOLL DDEECCLLAARRAATTIIOONNSS
       The uses of the allow and deny keywords shown in the  pre-
       vious  section  work  pretty much the same way whether the
       client is sending a DHCPDISCOVER or a DHCPREQUEST  message
       -  an  address will be allocated to the client (either the
       old address it's requesting, or a new  address)  and  then
       that address will be tested to see if it's okay to let the
       client have it.   If the client requested it, and it's not
       okay, the server will send a DHCPNAK message.   Otherwise,
       the server will simply not respond to the client.   If  it
       is okay to give the address to the client, the server will
       send a DHCPACK message.

       The primary motivation behind pool declarations is to have
       address  allocation  pools  whose  allocation policies are
       different.   A client may be denied access  to  one  pool,
       but  allowed  access  to  another pool on the same network
       segment.   In order for this to work, access  control  has
       to  be  done  during address allocation, not after address
       allocation is done.

       When a DHCPREQUEST message is processed,  address  alloca-
       tion  simply consists of looking up the address the client
       is requesting and seeing if it's still available  for  the
       client.   If  it  is, then the DHCP server checks both the
       address pool permit lists and the relevant in-scope  allow
       and  deny statements to see if it's okay to give the lease
       to the client.  In the case of a DHCPDISCOVER message, the
       allocation  process is done as described previously in the
       ADDRESS ALLOCATION section.

       When declaring permit lists for address allocation  pools,
       the  following syntaxes are recognized following the allow
       or deny keywords:

        kknnoowwnn--cclliieennttss;;

       If specified, this statement  either  allows  or  prevents
       allocation  from  this  pool to any client that has a host
       declaration (i.e., is known).  A client is known if it has
       a  host  declaration  in  _a_n_y  scope, not just the current
       scope.

        uunnkknnoowwnn--cclliieennttss;;

       If specified, this statement  either  allows  or  prevents
       allocation  from  this pool to any client that has no host
       declaration (i.e., is not known).




                                                               32





dhcpd.conf(5)                                       dhcpd.conf(5)


        mmeemmbbeerrss ooff ""class"";;

       If specified, this statement  either  allows  or  prevents
       allocation  from  this pool to any client that is a member
       of the named class.

        ddyynnaammiicc bboooottpp cclliieennttss;;

       If specified, this statement  either  allows  or  prevents
       allocation from this pool to any bootp client.

        aauutthheennttiiccaatteedd cclliieennttss;;

       If  specified,  this  statement  either allows or prevents
       allocation from this pool to  any  client  that  has  been
       authenticated  using  the  DHCP  authentication  protocol.
       This is not yet supported.

        uunnaauutthheennttiiccaatteedd cclliieennttss;;

       If specified, this statement  either  allows  or  prevents
       allocation  from this pool to any client that has not been
       authenticated  using  the  DHCP  authentication  protocol.
       This is not yet supported.

        aallll cclliieennttss;;

       If  specified,  this  statement  either allows or prevents
       allocation from this pool to all clients.    This  can  be
       used  when  you  want to write a pool declaration for some
       reason, but hold it in reserve, or when you want to renum-
       ber  your  network  quickly,  and  thus want the server to
       force all clients that have been allocated addresses  from
       this  pool  to  obtain new addresses immediately when they
       next renew.

RREEFFEERREENNCCEE:: PPAARRAAMMEETTEERRSS
       The _a_d_a_p_t_i_v_e_-_l_e_a_s_e_-_t_i_m_e_-_t_h_r_e_s_h_o_l_d statement

          aaddaappttiivvee--lleeaassee--ttiimmee--tthhrreesshhoolldd _p_e_r_c_e_n_t_a_g_e;;

          When the number of allocated leases within a pool rises
          above  the _p_e_r_c_e_n_t_a_g_e given in this statement, the DHCP
          server decreases  the  lease  length  for  new  clients
          within  this  pool  to  _m_i_n_-_l_e_a_s_e_-_t_i_m_e seconds. Clients
          renewing an already valid (long) leases  get  at  least
          the  remaining  time  from the current lease. Since the
          leases expire faster, the  server  may  either  recover
          more  quickly  or avoid pool exhaustion entirely.  Once
          the number of allocated leases drop below  the  thresh-
          old,  the  server  reverts  back to normal lease times.
          Valid percentages are between 1 and 99.

       The _a_l_w_a_y_s_-_b_r_o_a_d_c_a_s_t statement



                                                               33





dhcpd.conf(5)                                       dhcpd.conf(5)


          aallwwaayyss--bbrrooaaddccaasstt _f_l_a_g;;

          The DHCP and BOOTP  protocols  both  require  DHCP  and
          BOOTP  clients  to  set  the broadcast bit in the flags
          field of the BOOTP message header.  Unfortunately, some
          DHCP  and  BOOTP  clients do not do this, and therefore
          may not receive responses from the DHCP  server.    The
          DHCP  server  can  be  made  to  always  broadcast  its
          responses to clients by setting this flag to  'on'  for
          the  relevant  scope; relevant scopes would be inside a
          conditional statement, as a parameter for a  class,  or
          as  a parameter for a host declaration.   To avoid cre-
          ating excess broadcast traffic on your network, we rec-
          ommend  that  you restrict the use of this option to as
          few clients as possible.   For example,  the  Microsoft
          DHCP  client  is known not to have this problem, as are
          the OpenTransport and ISC DHCP clients.

       The _a_l_w_a_y_s_-_r_e_p_l_y_-_r_f_c_1_0_4_8 statement

          aallwwaayyss--rreeppllyy--rrffcc11004488 _f_l_a_g;;

          Some BOOTP clients expect RFC1048-style responses,  but
          do  not  follow  RFC1048  when  sending their requests.
          You can tell that a client is having this problem if it
          is  not  getting the options you have configured for it
          and if you see in the server  log  the  message  "(non-
          rfc1048)" printed with each BOOTREQUEST that is logged.

          If you want to send rfc1048 options to such  a  client,
          you  can  set  the  aallwwaayyss--rreeppllyy--rrffcc11004488 option in that
          client's host declaration, and  the  DHCP  server  will
          respond  with  an  RFC-1048-style vendor options field.
          This flag can be set in any scope, and will affect  all
          clients covered by that scope.

       The _a_u_t_h_o_r_i_t_a_t_i_v_e statement

          aauutthhoorriittaattiivvee;;

          nnoott aauutthhoorriittaattiivvee;;

          The  DHCP server will normally assume that the configu-
          ration information about a given network segment is not
          known  to be correct and is not authoritative.  This is
          so that if a naive user  installs  a  DHCP  server  not
          fully  understanding  how  to configure it, it does not
          send spurious DHCPNAK messages  to  clients  that  have
          obtained addresses from a legitimate DHCP server on the
          network.

          Network administrators setting  up  authoritative  DHCP
          servers for their networks should always write aauutthhoorrii--
          ttaattiivvee;; at the  top  of  their  configuration  file  to



                                                               34





dhcpd.conf(5)                                       dhcpd.conf(5)


          indicate  that the DHCP server _s_h_o_u_l_d send DHCPNAK mes-
          sages to misconfigured clients.   If this is not  done,
          clients  will  be  unable  to  get a correct IP address
          after  changing  subnets  until  their  old  lease  has
          expired, which could take quite a long time.

          Usually, writing aauutthhoorriittaattiivvee;; at the top level of the
          file should be sufficient.   However, if a DHCP  server
          is  to  be  set up so that it is aware of some networks
          for which it is authoritative  and  some  networks  for
          which  it is not, it may be more appropriate to declare
          authority on a per-network-segment basis.

          Note that the most specific scope for which the concept
          of  authority  makes  any sense is the physical network
          segment - either a shared-network statement or a subnet
          statement that is not contained within a shared-network
          statement.  It is not meaningful to  specify  that  the
          server  is  authoritative  for  some  subnets  within a
          shared network, but not authoritative for  others,  nor
          is it meaningful to specify that the server is authori-
          tative for some host declarations and not others.

       The _b_o_o_t_-_u_n_k_n_o_w_n_-_c_l_i_e_n_t_s statement

          bboooott--uunnkknnoowwnn--cclliieennttss _f_l_a_g;;

          If the _b_o_o_t_-_u_n_k_n_o_w_n_-_c_l_i_e_n_t_s statement  is  present  and
          has  a  value  of  _f_a_l_s_e or _o_f_f, then clients for which
          there is no _h_o_s_t declaration will  not  be  allowed  to
          obtain IP addresses.   If this statement is not present
          or has a value of _t_r_u_e or _o_n, then clients without host
          declarations will be allowed to obtain IP addresses, as
          long as those addresses are not restricted by _a_l_l_o_w and
          _d_e_n_y statements within their _p_o_o_l declarations.

       The _d_b_-_t_i_m_e_-_f_o_r_m_a_t statement

          ddbb--ttiimmee--ffoorrmmaatt [ _d_e_f_a_u_l_t | _l_o_c_a_l ] ;;

          The  DHCP  server  software  outputs several timestamps
          when writing leases to persistent storage.   This  con-
          figuration parameter selects one of two output formats.
          The _d_e_f_a_u_l_t format prints the day, date,  and  time  in
          UTC,  while the _l_o_c_a_l format prints the system seconds-
          since-epoch, and helpfully provides the day and time in
          the system timezone in a comment.  The time formats are
          described in detail in the dhcpd.leases(5) manpage.

       The _d_d_n_s_-_h_o_s_t_n_a_m_e statement

          ddddnnss--hhoossttnnaammee _n_a_m_e;;

          The _n_a_m_e parameter should be the hostname that will  be



                                                               35





dhcpd.conf(5)                                       dhcpd.conf(5)


          used in setting up the client's A and PTR records.   If
          no ddns-hostname is specified in scope, then the server
          will  derive the hostname automatically, using an algo-
          rithm that varies for  each  of  the  different  update
          methods.

       The _d_d_n_s_-_d_o_m_a_i_n_n_a_m_e statement

          ddddnnss--ddoommaaiinnnnaammee _n_a_m_e;;

          The  _n_a_m_e parameter should be the domain name that will
          be appended to the client's hostname to form  a  fully-
          qualified domain-name (FQDN).

       The _d_d_n_s_-_r_e_v_-_d_o_m_a_i_n_n_a_m_e statement

          ddddnnss--rreevv--ddoommaaiinnnnaammee  _n_a_m_e;; The _n_a_m_e parameter should be
          the domain name that will be appended to  the  client's
          reversed  IP  address  to produce a name for use in the
          client's  PTR  record.    By  default,  this  is   "in-
          addr.arpa.", but the default can be overridden here.

          The  reversed  IP  address to which this domain name is
          appended is always the IP address  of  the  client,  in
          dotted quad notation, reversed - for example, if the IP
          address assigned to the client is 10.17.92.74, then the
          reversed  IP address is 74.92.17.10.   So a client with
          that IP address would,  by  default,  be  given  a  PTR
          record of 10.17.92.74.in-addr.arpa.

       The _d_d_n_s_-_u_p_d_a_t_e_-_s_t_y_l_e parameter

          ddddnnss--uuppddaattee--ssttyyllee _s_t_y_l_e;;

          The  _s_t_y_l_e  parameter must be one of aadd--hhoocc, iinntteerriimm or
          nnoonnee.  The _d_d_n_s_-_u_p_d_a_t_e_-_s_t_y_l_e statement is only meaning-
          ful  in  the  outer  scope - it is evaluated once after
          reading the dhcpd.conf file, rather than  each  time  a
          client is assigned an IP address, so there is no way to
          use different DNS update styles for different  clients.

       TThhee _d_d_n_s_-_u_p_d_a_t_e_s ssttaatteemmeenntt

           ddddnnss--uuppddaatteess _f_l_a_g;;

          The  _d_d_n_s_-_u_p_d_a_t_e_s parameter controls whether or not the
          server will attempt to do a DNS update when a lease  is
          confirmed.    Set  this to _o_f_f if the server should not
          attempt to do updates  within  a  certain  scope.   The
          _d_d_n_s_-_u_p_d_a_t_e_s  parameter  is on by default.   To disable
          DNS updates in all scopes, it is preferable to use  the
          _d_d_n_s_-_u_p_d_a_t_e_-_s_t_y_l_e statement, setting the style to _n_o_n_e.

       The _d_e_f_a_u_l_t_-_l_e_a_s_e_-_t_i_m_e statement



                                                               36





dhcpd.conf(5)                                       dhcpd.conf(5)


          ddeeffaauulltt--lleeaassee--ttiimmee _t_i_m_e;;

          _T_i_m_e should be the  length  in  seconds  that  will  be
          assigned  to a lease if the client requesting the lease
          does not ask for a specific expiration time.

       The _d_o_-_f_o_r_w_a_r_d_-_u_p_d_a_t_e_s statement

          ddoo--ffoorrwwaarrdd--uuppddaatteess _f_l_a_g;;

          The _d_o_-_f_o_r_w_a_r_d_-_u_p_d_a_t_e_s  statement  instructs  the  DHCP
          server as to whether it should attempt to update a DHCP
          client's A record when the client acquires or renews  a
          lease.    This  statement  has  no  effect  unless  DNS
          updates are enabled and  ddddnnss--uuppddaattee--ssttyyllee  is  set  to
          iinntteerriimm.   Forward updates are enabled by default.   If
          this statement is used to disable forward updates,  the
          DHCP server will never attempt to update the client's A
          record, and  will  only  ever  attempt  to  update  the
          client's PTR record if the client supplies an FQDN that
          should be placed in  the  PTR  record  using  the  fqdn
          option.   If  forward  updates  are  enabled,  the DHCP
          server will still honor  the  setting  of  the  cclliieenntt--
          uuppddaatteess flag.

       The _d_y_n_a_m_i_c_-_b_o_o_t_p_-_l_e_a_s_e_-_c_u_t_o_f_f statement

          ddyynnaammiicc--bboooottpp--lleeaassee--ccuuttooffff _d_a_t_e;;

          The  _d_y_n_a_m_i_c_-_b_o_o_t_p_-_l_e_a_s_e_-_c_u_t_o_f_f statement sets the end-
          ing time for all leases assigned dynamically  to  BOOTP
          clients.   Because BOOTP clients do not have any way of
          renewing leases, and don't know that their leases could
          expire, by default dhcpd assigns infinite leases to all
          BOOTP clients.  However, it may make sense in some sit-
          uations to set a cutoff date for all BOOTP leases - for
          example, the end of a school term, or the time at night
          when a facility is closed and all machines are required
          to be powered off.

          _D_a_t_e should be the date on  which  all  assigned  BOOTP
          leases will end.  The date is specified in the form:

                           W YYYY/MM/DD HH:MM:SS

          W  is  the  day  of the week expressed as a number from
          zero (Sunday) to six (Saturday).   YYYY  is  the  year,
          including  the century.  MM is the month expressed as a
          number from 1 to 12.  DD  is  the  day  of  the  month,
          counting  from 1.  HH is the hour, from zero to 23.  MM
          is the minute and SS is the second.  The time is always
          in Coordinated Universal Time (UTC), not local time.

       The _d_y_n_a_m_i_c_-_b_o_o_t_p_-_l_e_a_s_e_-_l_e_n_g_t_h statement



                                                               37





dhcpd.conf(5)                                       dhcpd.conf(5)


          ddyynnaammiicc--bboooottpp--lleeaassee--lleennggtthh _l_e_n_g_t_h;;

          The _d_y_n_a_m_i_c_-_b_o_o_t_p_-_l_e_a_s_e_-_l_e_n_g_t_h statement is used to set
          the length of  leases  dynamically  assigned  to  BOOTP
          clients.    At some sites, it may be possible to assume
          that a lease is no longer in use if its holder has  not
          used  BOOTP or DHCP to get its address within a certain
          time period.   The period is specified in _l_e_n_g_t_h  as  a
          number  of  seconds.    If a client reboots using BOOTP
          during the timeout period, the lease duration is  reset
          to  _l_e_n_g_t_h,  so  a  BOOTP  client that boots frequently
          enough will never lose its  lease.   Needless  to  say,
          this parameter should be adjusted with extreme caution.

       The _f_i_l_e_n_a_m_e statement

          ffiilleennaammee ""_f_i_l_e_n_a_m_e"";;

          The _f_i_l_e_n_a_m_e statement can be used to specify the  name
          of  the  initial  boot  file which is to be loaded by a
          client.  The _f_i_l_e_n_a_m_e should be a filename recognizable
          to  whatever  file  transfer protocol the client can be
          expected to use to load the file.

       The _f_i_x_e_d_-_a_d_d_r_e_s_s declaration

          ffiixxeedd--aaddddrreessss aaddddrreessss [,, _a_d_d_r_e_s_s ... ];;

          The _f_i_x_e_d_-_a_d_d_r_e_s_s declaration is used to assign one  or
          more  fixed  IP  addresses to a client.  It should only
          appear in a _h_o_s_t declaration.  If more than one address
          is  supplied,  then  when  the client boots, it will be
          assigned the address that corresponds to the network on
          which  it  is booting.  If none of the addresses in the
          _f_i_x_e_d_-_a_d_d_r_e_s_s statement are valid for  the  network  to
          which  the  client  is  connected, that client will not
          match  the  _h_o_s_t  declaration  containing  that  _f_i_x_e_d_-
          _a_d_d_r_e_s_s declaration.  Each _a_d_d_r_e_s_s in the _f_i_x_e_d_-_a_d_d_r_e_s_s
          declaration should be either an IP address or a  domain
          name that resolves to one or more IP addresses.

       The _g_e_t_-_l_e_a_s_e_-_h_o_s_t_n_a_m_e_s statement

          ggeett--lleeaassee--hhoossttnnaammeess _f_l_a_g;;

          The _g_e_t_-_l_e_a_s_e_-_h_o_s_t_n_a_m_e_s statement is used to tell dhcpd
          whether or not to look up the domain name corresponding
          to the IP address of each address in the lease pool and
          use that address for the DHCP _h_o_s_t_n_a_m_e option.  If _f_l_a_g
          is  true, then this lookup is done for all addresses in
          the current scope.   By default, or if _f_l_a_g  is  false,
          no lookups are done.

       The _h_a_r_d_w_a_r_e statement



                                                               38





dhcpd.conf(5)                                       dhcpd.conf(5)


          hhaarrddwwaarree _h_a_r_d_w_a_r_e_-_t_y_p_e _h_a_r_d_w_a_r_e_-_a_d_d_r_e_s_s;;

          In  order for a BOOTP client to be recognized, its net-
          work hardware address must be declared using a _h_a_r_d_w_a_r_e
          clause  in  the  _h_o_s_t statement.  _h_a_r_d_w_a_r_e_-_t_y_p_e must be
          the name of a physical hardware interface type.    Cur-
          rently, only the eetthheerrnneett and ttookkeenn--rriinngg types are rec-
          ognized, although support for a ffddddii hardware type (and
          others)  would also be desirable.  The _h_a_r_d_w_a_r_e_-_a_d_d_r_e_s_s
          should be a set of hexadecimal octets (numbers  from  0
          through  ff) separated by colons.   The _h_a_r_d_w_a_r_e state-
          ment may also be used for DHCP clients.

       The _i_n_f_i_n_i_t_e_-_i_s_-_r_e_s_e_r_v_e_d statement

          iinnffiinniittee--iiss--rreesseerrvveedd _f_l_a_g;;

          ISC DHCP now supports 'reserved' leases.  See the  sec-
          tion on RESERVED LEASES below.  If this _f_l_a_g is on, the
          server will automatically reserve leases  allocated  to
          clients which requested an infinite (0xffffffff) lease-
          time.

          The default is off.

       The _l_e_a_s_e_-_f_i_l_e_-_n_a_m_e statement

          lleeaassee--ffiillee--nnaammee _n_a_m_e;;

          _N_a_m_e should be the name  of  the  DHCP  server's  lease
          file.     By  default,  this  is  /var/db/dhcpd.leases.
          This statement mmuusstt appear in the outer  scope  of  the
          configuration file - if it appears in some other scope,
          it will have no effect.

       The _l_o_c_a_l_-_p_o_r_t statement

          llooccaall--ppoorrtt _p_o_r_t;;

          This statement causes the DHCP  server  to  listen  for
          DHCP requests on the UDP port specified in _p_o_r_t, rather
          than on port 67.

       The _l_o_c_a_l_-_a_d_d_r_e_s_s statement

          llooccaall--aaddddrreessss _a_d_d_r_e_s_s;;

          This statement causes the DHCP  server  to  listen  for
          DHCP  requests  sent  to  the specified _a_d_d_r_e_s_s, rather
          than requests sent to  all  addresses.   Since  serving
          directly  attached DHCP clients implies that the server
          must respond  to  requests  sent  to  the  all-ones  IP
          address,  this  option cannot be used if clients are on
          directly attached networks...it is  only  realistically



                                                               39





dhcpd.conf(5)                                       dhcpd.conf(5)


          useful  for a server whose only clients are reached via
          unicasts, such as via DHCP relay agents.

          Note:  This statement is only effective if  the  server
          was  compiled  using the USE_SOCKETS #define statement,
          which is default on a small number  of  operating  sys-
          tems, and must be explicitly chosen at compile-time for
          all others.  You can be sure if your server is compiled
          with  USE_SOCKETS  if  you  see lines of this format at
          startup:

           Listening on Socket/eth0

          Note also that since this bind()s all DHCP  sockets  to
          the  specified  address,  that  only one address may be
          supported in a daemon at a given time.

       The _l_o_g_-_f_a_c_i_l_i_t_y statement

          lloogg--ffaacciilliittyy _f_a_c_i_l_i_t_y;;

          This statement causes the DHCP server to do all of  its
          logging   on   the  specified  log  facility  once  the
          dhcpd.conf file has been read.   By  default  the  DHCP
          server  logs  to  the  daemon  facility.   Possible log
          facilities include auth, authpriv, cron,  daemon,  ftp,
          kern,  lpr,  mail,  mark,  news, ntp, security, syslog,
          user, uucp, and local0 through  local7.    Not  all  of
          these  facilities  are  available  on  all systems, and
          there may be other facilities available on  other  sys-
          tems.

          In addition to setting this value, you may need to mod-
          ify your _s_y_s_l_o_g_._c_o_n_f file to configure logging  of  the
          DHCP  server.    For example, you might add a line like
          this:

               local7.debug /var/log/dhcpd.log

          The syntax of the _s_y_s_l_o_g_._c_o_n_f file may be different  on
          some operating systems - consult the _s_y_s_l_o_g_._c_o_n_f manual
          page to be sure.  To get syslog to start logging to the
          new  file,  you must first create the file with correct
          ownership and permissions (usually, the same owner  and
          permissions  of your /var/log/messages or /usr/adm/mes-
          sages file should be fine) and send a  SIGHUP  to  sys-
          logd.   Some systems support log rollover using a shell
          script or program called newsyslog  or  logrotate,  and
          you  may be able to configure this as well so that your
          log file doesn't grow uncontrollably.

          Because the _l_o_g_-_f_a_c_i_l_i_t_y setting is controlled  by  the
          dhcpd.conf file, log messages printed while parsing the
          dhcpd.conf file or before parsing it are logged to  the



                                                               40





dhcpd.conf(5)                                       dhcpd.conf(5)


          default  log facility.  To prevent this, see the README
          file included with this distribution,  which  describes
          how  to  change  the  default  log facility.  When this
          parameter is used, the DHCP server prints  its  startup
          message  a  second time after parsing the configuration
          file, so that the log will be as complete as  possible.

       The _m_a_x_-_l_e_a_s_e_-_t_i_m_e statement

          mmaaxx--lleeaassee--ttiimmee _t_i_m_e;;

          _T_i_m_e  should be the maximum length in seconds that will
          be assigned to a lease.   The only exception to this is
          that  Dynamic BOOTP lease lengths, which are not speci-
          fied by the client, are not limited by this maximum.

       The _m_i_n_-_l_e_a_s_e_-_t_i_m_e statement

          mmiinn--lleeaassee--ttiimmee _t_i_m_e;;

          _T_i_m_e should be the minimum length in seconds that  will
          be assigned to a lease.

       The _m_i_n_-_s_e_c_s statement

          mmiinn--sseeccss _s_e_c_o_n_d_s;;

          _S_e_c_o_n_d_s should be the minimum number of seconds since a
          client began trying to acquire a new lease  before  the
          DHCP server will respond to its request.  The number of
          seconds is based on what the client  reports,  and  the
          maximum  value  that  the client can report is 255 sec-
          onds.   Generally, setting this to one will  result  in
          the  DHCP  server  not responding to the client's first
          request, but always responding to its second request.

          This can be used to set  up  a  secondary  DHCP  server
          which  never  offers  an  address to a client until the
          primary server has been given a chance to do  so.    If
          the primary server is down, the client will bind to the
          secondary server, but otherwise clients  should  always
          bind  to  the  primary.    Note  that this does not, by
          itself, permit a primary server and a secondary  server
          to share a pool of dynamically-allocatable addresses.

       The _n_e_x_t_-_s_e_r_v_e_r statement

          nneexxtt--sseerrvveerr _s_e_r_v_e_r_-_n_a_m_e;;

          The  _n_e_x_t_-_s_e_r_v_e_r  statement is used to specify the host
          address of the server from which the initial boot  file
          (specified  in the _f_i_l_e_n_a_m_e statement) is to be loaded.
          _S_e_r_v_e_r_-_n_a_m_e should be a numeric IP address or a  domain
          name.



                                                               41





dhcpd.conf(5)                                       dhcpd.conf(5)


       The _o_m_a_p_i_-_p_o_r_t statement

          oommaappii--ppoorrtt _p_o_r_t;;

          The _o_m_a_p_i_-_p_o_r_t statement causes the DHCP server to lis-
          ten for OMAPI connections on the specified port.   This
          statement  is  required  to  enable the OMAPI protocol,
          which is used to examine and modify the  state  of  the
          DHCP server as it is running.

       The _o_n_e_-_l_e_a_s_e_-_p_e_r_-_c_l_i_e_n_t statement

          oonnee--lleeaassee--ppeerr--cclliieenntt _f_l_a_g;;

          If  this  flag  is  enabled,  whenever a client sends a
          DHCPREQUEST for a particular  lease,  the  server  will
          automatically  free  any other leases the client holds.
          This presumes that when the client sends a DHCPREQUEST,
          it has forgotten any lease not mentioned in the DHCPRE-
          QUEST - i.e., the client  has  only  a  single  network
          interface  _a_n_d it does not remember leases it's holding
          on networks to which  it  is  not  currently  attached.
          Neither  of  these  assumptions are guaranteed or prov-
          able, so we urge caution in the use of this  statement.

       The _p_i_d_-_f_i_l_e_-_n_a_m_e statement

          ppiidd--ffiillee--nnaammee _n_a_m_e;;

          _N_a_m_e should be the name of the DHCP server's process ID
          file.   This is the file in  which  the  DHCP  server's
          process  ID  is  stored  when  the  server starts.   By
          default, this is /var/run/dhcpd.pid.   Like the  lease-
          file-name  statement, this statement must appear in the
          outer scope of the configuration file.

       The _p_i_n_g_-_c_h_e_c_k statement

          ppiinngg--cchheecckk _f_l_a_g;;

          When the DHCP server is considering  dynamically  allo-
          cating  an  IP  address  to a client, it first sends an
          ICMP  Echo  request  (a  _p_i_n_g)  to  the  address  being
          assigned.    It waits for a second, and if no ICMP Echo
          response has been heard, it assigns the address.   If a
          response  _i_s  heard,  the  lease  is abandoned, and the
          server does not respond to the client.

          This _p_i_n_g _c_h_e_c_k introduces a default  one-second  delay
          in  responding to DHCPDISCOVER messages, which can be a
          problem for some clients.   The default  delay  of  one
          second may be configured using the ping-timeout parame-
          ter.  The ping-check  configuration  parameter  can  be
          used  to  control  checking - if its value is false, no



                                                               42





dhcpd.conf(5)                                       dhcpd.conf(5)


          ping check is done.

       The _p_i_n_g_-_t_i_m_e_o_u_t statement

          ppiinngg--ttiimmeeoouutt _s_e_c_o_n_d_s;;

          If the DHCP server determined it should  send  an  ICMP
          echo  request (a _p_i_n_g) because the ping-check statement
          is true, ping-timeout allows you to configure how  many
          seconds  the  DHCP  server should wait for an ICMP Echo
          response to be heard, if no ICMP Echo response has been
          received  before  the  timeout  expires, it assigns the
          address.  If a response _i_s heard, the  lease  is  aban-
          doned,  and  the server does not respond to the client.
          If no value is set, ping-timeout defaults to 1  second.

       The _r_e_m_o_t_e_-_p_o_r_t statement

          rreemmoottee--ppoorrtt _p_o_r_t;;

          This  statement causes the DHCP server to transmit DHCP
          responses to DHCP clients upon the UDP  port  specified
          in _p_o_r_t, rather than on port 68.  In the event that the
          UDP response is transmitted to a DHCP Relay, the server
          generally  uses  the  llooccaall--ppoorrtt  configuration  value.
          Should  the  DHCP  Relay  happen  to  be  addressed  as
          127.0.0.1,  however,  the  DHCP  Server  transmits  its
          response to the rreemmoottee--ppoorrtt configuration value.   This
          is generally only useful for testing purposes, and this
          configuration value should generally not be used.

       The _s_e_r_v_e_r_-_i_d_e_n_t_i_f_i_e_r statement

          sseerrvveerr--iiddeennttiiffiieerr _h_o_s_t_n_a_m_e;;

          The server-identifier statement can be used  to  define
          the  value  that  is sent in the DHCP Server Identifier
          option for a given scope.   The value specified mmuusstt be
          an  IP  address for the DHCP server, and must be reach-
          able by all clients served by a particular scope.

          The use of the server-identifier statement is not  rec-
          ommended  -  the  only  reason  to use it is to force a
          value other than the default value to be sent on  occa-
          sions where the default value would be incorrect.   The
          default value is the first IP address  associated  with
          the  physical  network  interface  on which the request
          arrived.

          The usual case where  the  _s_e_r_v_e_r_-_i_d_e_n_t_i_f_i_e_r  statement
          needs  to be sent is when a physical interface has more
          than one IP address, and the one being sent by  default
          isn't  appropriate  for  some  or all clients served by
          that interface.  Another common case is when  an  alias



                                                               43





dhcpd.conf(5)                                       dhcpd.conf(5)


          is  defined  for  the purpose of having a consistent IP
          address for the DHCP server, and it is desired that the
          clients use this IP address when contacting the server.

          Supplying a value for the dhcp-server-identifier option
          is equivalent to using the server-identifier statement.

       The _s_e_r_v_e_r_-_n_a_m_e statement

          sseerrvveerr--nnaammee _n_a_m_e ;;

          The _s_e_r_v_e_r_-_n_a_m_e statement can be  used  to  inform  the
          client of the name of the server from which it is boot-
          ing.   _N_a_m_e should be the name that will be provided to
          the client.

       The _s_i_t_e_-_o_p_t_i_o_n_-_s_p_a_c_e statement

          ssiittee--ooppttiioonn--ssppaaccee _n_a_m_e ;;

          The  _s_i_t_e_-_o_p_t_i_o_n_-_s_p_a_c_e  statement can be used to deter-
          mine from what option space site-local options will  be
          taken.    This  can be used in much the same way as the
          _v_e_n_d_o_r_-_o_p_t_i_o_n_-_s_p_a_c_e statement.  Site-local  options  in
          DHCP  are those options whose numeric codes are greater
          than 224.   These options are  intended  for  site-spe-
          cific  uses,  but  are  frequently  used  by vendors of
          embedded hardware that contains DHCP clients.   Because
          site-specific options are allocated on an ad hoc basis,
          it is quite possible  that  one  vendor's  DHCP  client
          might  use  the  same option code that another vendor's
          client uses, for different purposes.   The _s_i_t_e_-_o_p_t_i_o_n_-
          _s_p_a_c_e  option  can be used to assign a different set of
          site-specific options for each such vendor, using  con-
          ditional evaluation (see ddhhccpp--eevvaall ((55)) for details).

       The _s_t_a_s_h_-_a_g_e_n_t_-_o_p_t_i_o_n_s statement

          ssttaasshh--aaggeenntt--ooppttiioonnss _f_l_a_g;;

          If  the  _s_t_a_s_h_-_a_g_e_n_t_-_o_p_t_i_o_n_s  parameter  is  true for a
          given client, the server will record  the  relay  agent
          information  options  sent  during the client's initial
          DHCPREQUEST message when the client was in the  SELECT-
          ING  state  and behave as if those options are included
          in all subsequent  DHCPREQUEST  messages  sent  in  the
          RENEWING  state.    This  works  around  a problem with
          relay agent information options,  which  is  that  they
          usually  not appear in DHCPREQUEST messages sent by the
          client in the RENEWING state, because such messages are
          unicast  directly  to the server and not sent through a
          relay agent.

       The _u_p_d_a_t_e_-_c_o_n_f_l_i_c_t_-_d_e_t_e_c_t_i_o_n statement



                                                               44





dhcpd.conf(5)                                       dhcpd.conf(5)


          uuppddaattee--ccoonnfflliicctt--ddeetteeccttiioonn _f_l_a_g;;

          If the _u_p_d_a_t_e_-_c_o_n_f_l_i_c_t_-_d_e_t_e_c_t_i_o_n parameter is true, the
          server  will  perform  standard  DHCID multiple-client,
          one-name conflict detection.  If the parameter has been
          set  false, the server will skip this check and instead
          simply tear down any previous bindings to  install  the
          new binding without question.  The default is true.

       The _u_p_d_a_t_e_-_o_p_t_i_m_i_z_a_t_i_o_n statement

          uuppddaattee--ooppttiimmiizzaattiioonn _f_l_a_g;;

          If  the  _u_p_d_a_t_e_-_o_p_t_i_m_i_z_a_t_i_o_n  parameter  is false for a
          given client, the server will attempt a DNS update  for
          that  client  each  time  the  client renews its lease,
          rather than only attempting an update when  it  appears
          to be necessary.   This will allow the DNS to heal from
          database inconsistencies more easily, but the  cost  is
          that  the  DHCP  server  must do many more DNS updates.
          We recommend leaving this option enabled, which is  the
          default.   This option only affects the behavior of the
          interim DNS update scheme, and has no effect on the ad-
          hoc DNS update scheme.   If this parameter is not spec-
          ified, or is true, the DHCP  server  will  only  update
          when  the client information changes, the client gets a
          different lease, or the client's lease expires.

       The _u_p_d_a_t_e_-_s_t_a_t_i_c_-_l_e_a_s_e_s statement

          uuppddaattee--ssttaattiicc--lleeaasseess _f_l_a_g;;

          The _u_p_d_a_t_e_-_s_t_a_t_i_c_-_l_e_a_s_e_s flag, if enabled,  causes  the
          DHCP server to do DNS updates for clients even if those
          clients are being assigned their  IP  address  using  a
          _f_i_x_e_d_-_a_d_d_r_e_s_s  statement - that is, the client is being
          given a static assignment.   This can  only  work  with
          the  _i_n_t_e_r_i_m DNS update scheme.   It is not recommended
          because the DHCP server has no way  to  tell  that  the
          update has been done, and therefore will not delete the
          record when it is not in use.   Also, the  server  must
          attempt  the  update  each  time  the client renews its
          lease,  which  could  have  a  significant  performance
          impact  in environments that place heavy demands on the
          DHCP server.

       The _u_s_e_-_h_o_s_t_-_d_e_c_l_-_n_a_m_e_s statement

          uussee--hhoosstt--ddeeccll--nnaammeess _f_l_a_g;;

          If the _u_s_e_-_h_o_s_t_-_d_e_c_l_-_n_a_m_e_s parameter is true in a given
          scope,  then  for  every  host  declaration within that
          scope, the name provided for the host declaration  will
          be  supplied  to  the client as its hostname.   So, for



                                                               45





dhcpd.conf(5)                                       dhcpd.conf(5)


          example,

              group {
                use-host-decl-names on;

                host joe {
                  hardware ethernet 08:00:2b:4c:29:32;
                  fixed-address joe.fugue.com;
                }
              }

          is equivalent to

                host joe {
                  hardware ethernet 08:00:2b:4c:29:32;
                  fixed-address joe.fugue.com;
                  option host-name "joe";
                }

          An _o_p_t_i_o_n _h_o_s_t_-_n_a_m_e statement within a host declaration
          will  override the use of the name in the host declara-
          tion.

          It should be noted here that  most  DHCP  clients  com-
          pletely  ignore  the  host-name option sent by the DHCP
          server, and there is no way to configure them not to do
          this.    So  you  generally have a choice of either not
          having any hostname to client IP address  mapping  that
          the  client  will recognize, or doing DNS updates.   It
          is beyond the scope of this document to describe how to
          make this determination.

       The _u_s_e_-_l_e_a_s_e_-_a_d_d_r_-_f_o_r_-_d_e_f_a_u_l_t_-_r_o_u_t_e statement

          uussee--lleeaassee--aaddddrr--ffoorr--ddeeffaauulltt--rroouuttee _f_l_a_g;;

          If  the  _u_s_e_-_l_e_a_s_e_-_a_d_d_r_-_f_o_r_-_d_e_f_a_u_l_t_-_r_o_u_t_e  parameter is
          true in a given scope,  then  instead  of  sending  the
          value  specified  in  the routers option (or sending no
          value at all),  the  IP  address  of  the  lease  being
          assigned  is  sent  to  the  client.    This supposedly
          causes Win95 machines to  ARP  for  all  IP  addresses,
          which  can  be helpful if your router is configured for
          proxy ARP.   The use of  this  feature  is  not  recom-
          mended, because it won't work for many DHCP clients.

       The _v_e_n_d_o_r_-_o_p_t_i_o_n_-_s_p_a_c_e statement

          vveennddoorr--ooppttiioonn--ssppaaccee _s_t_r_i_n_g;;

          The  _v_e_n_d_o_r_-_o_p_t_i_o_n_-_s_p_a_c_e parameter determines from what
          option space vendor options are  taken.    The  use  of
          this  configuration  parameter  is  illustrated  in the
          ddhhccpp--ooppttiioonnss((55)) manual page, in the _V_E_N_D_O_R _E_N_C_A_P_S_U_L_A_T_E_D



                                                               46





dhcpd.conf(5)                                       dhcpd.conf(5)


          _O_P_T_I_O_N_S section.

SSEETTTTIINNGG PPAARRAAMMEETTEERR VVAALLUUEESS UUSSIINNGG EEXXPPRREESSSSIIOONNSS
       Sometimes  it's  helpful  to be able to set the value of a
       DHCP server parameter based on some value that the  client
       has sent.   To do this, you can use expression evaluation.
       The  ddhhccpp--eevvaall((55))  manual  page  describes  how  to  write
       expressions.   To assign the result of an evaluation to an
       option, define the option as follows:

         _m_y_-_p_a_r_a_m_e_t_e_r == _e_x_p_r_e_s_s_i_o_n ;;

       For example:

         ddns-hostname = binary-to-ascii (16, 8, "-",
                                          substring (hardware, 1, 6));

RREESSEERRVVEEDD LLEEAASSEESS
       It's often useful to allocate a single address to a single
       client,  in  approximate perpetuity.  Host statements with
       ffiixxeedd--aaddddrreessss clauses exist to a certain extent  to  serve
       this  purpose, but because host statements are intended to
       approximate 'static configuration', they suffer  from  not
       being  referenced  in  a littany of other Server Services,
       such as dynamic DNS, failover, 'on events' and so forth.

       If a standard dynamic lease, as from any range  statement,
       is  marked  'reserved', then the server will only allocate
       this lease to the client it is identified by (be  that  by
       client identifier or hardware address).

       In  practice, this means that the lease follows the normal
       state engine, enters ACTIVE state when the client is bound
       to it, expires, or is released, and any events or services
       that would normally be supplied during  these  events  are
       processed  normally, as with any other dynamic lease.  The
       only difference is that failover  servers  treat  reserved
       leases  as  special  when  they  enter  the FREE or BACKUP
       states - each server applies the lease into the  state  it
       may  allocate  from - and the leases are not placed on the
       queue for allocation to other clients.  Instead  they  may
       only  be  'found'  by client identity.  The result is that
       the lease is only offered to the returning client.

       Care should probably be taken to ensure  that  the  client
       only  has one lease within a given subnet that it is iden-
       tified by.

       Leases may be set  'reserved'  either  through  OMAPI,  or
       through  the  'infinite-is-reserved'  configuration option
       (if this is applicable to your environment and mixture  of
       clients).

       It  should also be noted that leases marked 'reserved' are



                                                               47





dhcpd.conf(5)                                       dhcpd.conf(5)


       effectively treated the same as leases marked 'bootp'.

RREEFFEERREENNCCEE:: OOPPTTIIOONN SSTTAATTEEMMEENNTTSS
       DHCP  option  statements  are  documented  in  the   ddhhccpp--
       ooppttiioonnss((55)) manual page.

RREEFFEERREENNCCEE:: EEXXPPRREESSSSIIOONNSS
       Expressions  used  in DHCP option statements and elsewhere
       are documented in the ddhhccpp--eevvaall((55)) manual page.

SSEEEE AALLSSOO
       dhcpd(8), dhcpd.leases(5), dhcp-options(5),  dhcp-eval(5),
       RFC2132, RFC2131.

AAUUTTHHOORR
       ddhhccppdd..ccoonnff((55))  was  written  by Ted Lemon under a contract
       with Vixie Labs.   Funding for this project  was  provided
       by  Internet Systems Consortium.  Information about Inter-
       net    Systems    Consortium    can    be     found     at
       hhttttppss::////wwwwww..iisscc..oorrgg..





































                                                               48


