Help me make DHCP's documentation better.

[Patrick Schoo]

On Thursday 17 August 2006 23:45, David W. Hankins wrote:
> 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.

I think MAC Affinity is not a proper description for what it is used for. If I 
understand the function correctly Lease Affinity would be a better 
description. A lease either has affinity to 'reside' on the primary, or it 
has affinity to 'reside' on the secondary. This is an extra property apart 
from the 'binding state'. For example a lease can have 'binding state active' 
and also 'affinity secondary'. Once the lease expires it will move to the 
FREE status, while keeping the 'affinity secondary' property. The lease 
rebalancer only needs to touch the affinity property, once a misbalance is 
detected.

>
> - 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.

This text is not clear. Looking at the low percentage probably a lease balance 
ratio is meant:

 abs(#free leases on primary - #free leases on secondary) * 100
  -------------------------------------------------------
  #free leases on primary + #free leases on secondary)

When the leases are in perfect balance, the ratio is 0. If one server owns all 
leases the ratio is 100. If the ratio is higher than the max‐lease‐misbalance 
percentage a rebalance should be scheduled.

Note: With an odd number of leases the ratio is always larger than 0. If you 
have just 5 free leases the balance ratio can not get below 20.

>
>        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.

I cannot grasp this one. Perhaps a formula might explain its meaning. For all 
these variables a warning is appropriate, not to touch the defaults unless 
you know what you are doing.

>
>        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.

The function of the min and max is clear, but not how the actual value is 
calcaluted. Does it mean the following (with the default settings):

t = time elapsed since last rebalance

t < 60:	no rebalance
60 <= t <= 3600: rebalance if imbalance ration > "max‐lease‐misbalance 
percentage"
t > 3600: always rebalance

>
>           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.

Regards,

Patrick Schoo.
The contents of this e-mail are intended for the named addressee only. It contains information that may be confidential. Unless you are the named addressee or an authorized designee, you may not copy or use it, or disclose it to anyone else. If you received it in error please notify us immediately and then destroy it.