Help me make DHCP's documentation better.

[Sten Carlsen]

Writing clear and unambigously is not easy.

I thought I understood the "max‐lease‐ownership percentage" until I saw
the default value. I read this as the maximum percentage of leases that
one server can own out of a pair of servers. That indicates to me at
least 50%, else there must be leases not owned by anyone. Now default is
10%.

So each of two servers can own up to 10% of the free leases totalling
20% ; who owns the remaining 80%?

I guess examples could help.

Also the "max‐lease‐ownership percentage" is a bit elusive for me at
first reading. Pls. consider an example for the default value. Maybe
formulas will help. Does the default value mean that when server 1 owns
64% of all free leases all is ok and when it owns 66% it will transfer
some to server 2? How many will it transfer? until each has 50%?
(conflicts with "ownership= 10%" each can only own 10%)

How do they work together? if each can only own 10% (is that 10% more
than the other?) how can the other limit be higher? which one will
trigger the transfer? If max-ownership does not trigger any transfer why
is it there?

I tried to read these in a way like I would read any other man page;
very few times, and then the meaning should be clear.

I am sorry if this is not as constructive as I would like it to be, but
I do not understand the mechanism well enough to formulate another proposal.


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

-- 
Best regards

Sten Carlsen

No improvements come from shouting:

       "MALE BOVINE MANURE!!!"