From: Marcin Siodelski <marcin@isc.org>
Date: Tue, 3 Aug 2021 11:51:14 +0000 (+0200)
Subject: [#1403] Documentation for ha-sync-complete-notify
X-Git-Tag: Kea-2.0.0~95
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e37f307a02b7ab64b2eb233fd4b0495f697d1cd2;p=thirdparty%2Fkea.git

[#1403] Documentation for ha-sync-complete-notify
---

diff --git a/doc/sphinx/api-files.txt b/doc/sphinx/api-files.txt
index 359fb3a8d1..4c822ebd05 100644
--- a/doc/sphinx/api-files.txt
+++ b/doc/sphinx/api-files.txt
@@ -37,6 +37,7 @@ src/share/api/ha-maintenance-start.json
 src/share/api/ha-reset.json
 src/share/api/ha-scopes.json
 src/share/api/ha-sync.json
+src/share/api/ha-sync-complete-notify.json
 src/share/api/lease4-add.json
 src/share/api/lease4-del.json
 src/share/api/lease4-get-all.json
diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst
index fe38570932..b00becb13c 100644
--- a/doc/sphinx/arm/hooks-ha.rst
+++ b/doc/sphinx/arm/hooks-ha.rst
@@ -347,8 +347,12 @@ The following is the list of all possible server states:
    fetched. The DHCP service is disabled for a maximum time of 60
    seconds, after which it is automatically re-enabled, in case the
    syncing partner was unable to re-enable the service. If the
-   synchronization is completed, the syncing server issues the
-   ``dhcp-enable`` command to re-enable the DHCP service of its partner.
+   synchronization is completed successfully, the synchronizing server
+   issues the ``ha-sync-complete-notify`` command to notify the partner.
+   In most states, the partner re-enables its DHCP service to continue
+   responding to the DHCP queries. In the ``partner-down`` state, the
+   partner first reassures that the communication between the servers
+   is re-established before enabling the DHCP service.
    The syncing operation is synchronous; the server waits for an answer
    from the partner and does nothing else while the lease
    synchronization takes place. A server that is configured not to
@@ -2207,3 +2211,39 @@ The response:
 
 If the server receiving this command is already in the waiting state,
 the command has no effect.
+
+.. _command-ha-sync-complete-notify:
+
+The ha-sync-complete-notify Command
+-----------------------------------
+
+A server sends this command to its partner to notify that it has completed
+lease database synchronization. The partner may enable its DHCP service if
+it can allocate new leases in its current state. The partner does not enable
+the DHCP service in the partner-down state until it sends a successful
+heartbeat testing connection with the server. If the connection is still
+unavailable, the server in the partner-down state enables the DHCP service
+to continue responding to the clients.
+
+::
+
+   {
+       "command": "ha-sync-complete-notify",
+       "service": [ "dhcp4" ]
+   }
+
+The response:
+
+::
+
+   {
+       "result": 0,
+       "text": "Server successfully notified about the synchronization completion."
+   }
+
+.. warning::
+
+   The ``ha-sync-complete-notify`` command is not meant to be used by the
+   system administrators. It is used for internal communication between
+   a pair of HA enabled DHCP servers. Direct use of this command is not
+   supported and may produce unintended consequences.
diff --git a/src/share/api/api_files.mk b/src/share/api/api_files.mk
index 19e708a8b8..354c5a6dd0 100644
--- a/src/share/api/api_files.mk
+++ b/src/share/api/api_files.mk
@@ -37,6 +37,7 @@ api_files += $(top_srcdir)/src/share/api/ha-maintenance-start.json
 api_files += $(top_srcdir)/src/share/api/ha-reset.json
 api_files += $(top_srcdir)/src/share/api/ha-scopes.json
 api_files += $(top_srcdir)/src/share/api/ha-sync.json
+api_files += $(top_srcdir)/src/share/api/ha-sync-complete-notify.json
 api_files += $(top_srcdir)/src/share/api/lease4-add.json
 api_files += $(top_srcdir)/src/share/api/lease4-del.json
 api_files += $(top_srcdir)/src/share/api/lease4-get-all.json
diff --git a/src/share/api/ha-sync-complete-notify.json b/src/share/api/ha-sync-complete-notify.json
new file mode 100644
index 0000000000..e19466264c
--- /dev/null
+++ b/src/share/api/ha-sync-complete-notify.json
@@ -0,0 +1,19 @@
+{
+    "access": "write",
+    "avail": "1.9.11",
+    "brief": [
+        "A server notifies its partner with this command that it has finished the",
+        "lease database synchronization. If the partner is in the partner-down state",
+        "it temporarily stops allocating new leases until it transitions to a normal",
+        "operation state, e.g. load-balancing. If the partner observes a failing",
+        "heartbeat it can resume allocating new leases in the partner-down state."
+    ],
+    "cmd-comment": [ "This command takes no arguments." ],
+    "description": [ "See <xref linkend=\"command-ha-sync-complete-notify\"/>" ],
+    "hook": "high_availability",
+    "name": "ha-sync-complete-notify",
+    "support": [
+        "kea-dhcp4",
+        "kea-dhcp6"
+    ]
+}