[5621] Updated User's Guide with sync-leases HA parameter.

doc/guide/hooks-ha.xml

@@ -200,7 +200,13 @@
           </command> to re-enable the DHCP service of the partner. The
           syncing operation is synchronous. The server is waiting for an
           answer from the partner and is not doing anything else while the
-          leases synchronization takes place.</para></listitem>
+          leases synchronization takes place. A server which is configured
+          to not synchronize its database with the partner, i.e. when the
+          <command>sync-leases</command> configuration parameter is set to
+          <command>false</command>, will never transition to this state.
+          Instead, it will transition directly from the
+          <command>waiting</command> to <command>ready</command> state.
+          </para></listitem>
 
           <listitem><para><command>terminated</command> - an active server
           transitions to this state when the High Availability  hooks library
@@ -228,12 +234,14 @@
           An active server will send heartbeat to its partner to check its
           state. If the partner appears to be unavailable the server will
           transition to the <command>partner-down</command>, otherwise it
-          will transition to the <command>syncing</command> state and attempt
+          will transition to the <command>syncing</command> or
-          to synchronize the lease database. If both servers appear to be
+          <command>ready</command> state (depending on the setting of the
-          in this state (concurrent startup) the primary server will
+          <command>sync-leases</command> configuration parameter). If
-          synchronize first. The secondary or standby server will remain
+          both servers appear to be in the <command>waiting</command>
+          state (concurrent startup) the primary server will transition to
+          the next state first. The secondary or standby server will remain
           in the <command>waiting</command> state until the primary
-          synchronizes the database.</para></listitem>.
+          transitions to the <command>ready</command> state.</para></listitem>.
         </itemizedlist></para>
 
         <note>
@@ -875,28 +883,31 @@
         hot standby and load balancing mode of operation.</para>
       </section> <!-- end of ha-hot-standby-config -->
 
-      <section xml:id="ha-send-lease-updates">
+      <section xml:id="ha-sharing-lease-info">
-        <title>Controlling Lease Updates</title>
+        <title>Lease Information Sharing</title>
         <para>The HA enabled server informs its active partner about allocated
         or renewed leases by sending appropriate control commands. The partner
-        updates the lease information in its own database. This guarantees
+        updates the lease information in its own database. When the server starts
-        consistency of the lease information between the servers and allows for
+        up for the first time or recovers after a failure it synchronizes its
+        lease database with the partner. These two mechanisms  guarantee
+        consistency of the lease information between the servers and allow for
         designating one of the servers to handle the entire DHCP traffic in
         case the other server becomes unavailable.</para>
 
         <para>In some cases, though, it is desired to disable lease updates
-        between the active servers if the exchange of information about the
+        and/or database synchronization between the active servers if the
-        allocated leases is performed using some other mechanism. Kea supports
+        exchange of information about the allocated leases is performed
-        various types of databases to be used as a storage for leases, e.g.
+        using some other mechanism. Kea supports various types of databases
-        MySQL, Postgres, Cassandra. Those databases include builtin solutions
+        to be used as a storage for leases, e.g. MySQL, Postgres, Cassandra.
-        for data replication which are often used by Kea users to provide
+        Those databases include builtin solutions for data replication which
-        redundancy.</para>
+        are often used by Kea users to provide redundancy.</para>
 
         <para>The HA hook library supports such scenarios by allowing to
-        disable lease updates over the control channel, leaving the server
+        disable lease updates over the control channel and/or lease database
-        to rely on the database replication mechanism. This is controlled by
+        synchronization, leaving the server to rely on the database replication
-        the <command>send-lease-updates</command> boolean parameter, which
+        mechanism. This is controlled by the two boolean parameters:
-        value defaults to true:
+        <command>send-lease-updates</command> and <command>sync-leases</command>,
+        which values default to true:
 
 <screen>
 {
@@ -916,6 +927,7 @@
                     "this-server-name": "server1",
                     "mode": "load-balancing",
                     "send-lease-updates": false,
+                    "sync-leases": false,
                     "peers": [
                         {
                             "name": "server1",
@@ -939,6 +951,23 @@
 </screen>
         </para>
 
+        <para>
+          In the most typical use case, both parameters are set to the same
+          value, i.e. both are <command>false</command> if the database
+          replication is in use, or both are <command>true</command> otherwise.
+          Introducing two separate parameters to control lease updates and
+          lease database synchronization is aimed at possible special use
+          cases, e.g. synchronization is performed by copying a lease file
+          (therefore the <command>sync-leases</command> is set to
+          <command>false</command>), but lease updates should be conducted
+          as usual (<command>send-lease-updates</command> set to
+          <command>true</command>). It should be noted that Kea doesn't
+          natively support such use case, but users may develop their own
+          scripts and tools around Kea to provide such mechanisms. The HA
+          hooks library configuration is designed to maximize the administration
+          flexibility.
+        </para>
+
       </section>
 
       <section xml:id="ha-ctrl-agent-config">