Help me make DHCP's documentation better.

[David W. Hankins]

Amidst the failover changes in 3.1.0, two new options have been added.
Below, I've pasted the relevant RELNOTES lines and the new manual page
entries for these configuration options (scoped in the failover {}
section).

If folks could give a read and tell me if this makes sense or not, I'd
appreciate it.


- Failover pairs now implement 'MAC Affinity' on leases moving from the
  active to free states.  Leases that belonged to the failover secondary
  are moved to BACKUP state rather than FREE upon exiting EXPIRED state.
  If lease rebalancing must move leases, it tries first to move leases
  that belong to the peer in need.

- The server no longer sends POOLREQ messages unless the pool is severely
  misbalanced in the peer's favor (see 'man dhcpd.conf' for more details).

- Pool rebalance events no longer happen upon successfully allocating a
  lease.  Instead, they happen on a schedule.  See 'man dhcpd.conf' for the
  min-balance and max-balance statements for more information.



       The max‐lease‐misbalance statement

          max‐lease‐misbalance percentage;

          The max‐lease‐misbalance statement tells the DHCP server  what  per‐
          centage  of  total  free  leases  (as defined as the total number of
          leases in either the FREE or BACKUP states) a peer is allowed to own
          before  a rebalance check is made.  Configuring higher values causes
          the server to rebalance less frequently, but permits a  larger  mis‐
          balance  between  the  FREE  and  BACKUP lease pools.  Configuring a
          lower value causes the server  to  rebalance  more  frequently,  but
          keeps  the  pools  more  balanced.   ISC DHCP servers no longer send
          POOLREQ messages unless the misbalance is at least twice  this  per‐
          centage  in  the  peer’s favor.  Valid values are between 0 and 100.
          The default is 15.

       The max‐lease‐ownership statement

          max‐lease‐ownership percentage;

          The max‐lease‐ownership statement tells the DHCP  server  what  per‐
          centage  of  total  free  leases  either it or its peer are normally
          allowed to own in excess of balance for the purpose of  MAC  Address
          Affinity.  When a server undergoes a lease rebalancing operation, it
          first tries to move as many leases as it can to the peer whose  pre‐
          vious client was Load‐Balanced to that peer (as governed by the Load
          Balance Algorithm, see the split  configuration  value).   The  max‐
          lease‐ownership  value  determines  the maximum percentage of leases
          either server will hold before giving its  peer  the  oldest  leases
          (regardless of the previous client’s place in the Load Balance algo‐
          rithm).  Valid values are between 0 and 100, and should probably  be
          less  than the max‐lease‐misbalance value.  Larger values will allow
          servers to retain leases to reallocate to returning clients, smaller
          values promote pool balance.  The default is 10.

       The min‐balance and max‐balance statements

          min‐balance seconds; max‐balance seconds;

          The DHCP Server schedules pool rebalance events at  a  time  between
          these  two values, estimated to be when the the max‐lease‐misbalance
          percent of leases have been allocated by its peer.  This estimate is
          reached  from  however  many  seconds  have elapsed since the oldest
          lease in the failover peer’s pool has been expired.

          The min‐balance value defaults to 60, one minute, and  the  max‐bal‐
          ance value defaults to 3600, one hour.

          Lease rebalancing events can be CPU intensive, particular on instal‐
          lations where failover peers may have large  numbers  of  pools  and
          addresses to examine, so these parameters should be used to keep the
          estimation of the need for pool rebalance sane...not  so  long  that
          you  are  in  danger of exhausting your pool, not so short that your
          server is constantly rebalancing.

-- 
ISC Training!  October 16-20, 2006, in the San Francisco Bay Area,
covering topics from DNS to DDNS & DHCP.  Email training at isc.org.
-- 
David W. Hankins	"If you don't do it right the first time,
Software Engineer		you'll just have to do it again."
Internet Systems Consortium, Inc.	-- Jack T. Hankins