[#3344] Addressed review comments (doc)

Author: msiodelski

doc/sphinx/arm/ctrl-channel.rst

@@ -714,16 +714,28 @@ if the :isccmd:`dhcp-enable` command is not sent before this time elapses.
 Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
 command source. A server administrator should typically omit this parameter
 because the default value "user" indicates that the administrator sent the
-command. This command can also be sent by the partner server running HA hooks
-library. In that case, the partner server sets the parameter to a unique
-integer identifier of an HA service. The integer values are reserved for the
-communication between HA partners and should not be specified in the
-administrator's commands, as it may interfere with HA operation. The
-administrator should either omit this parameter or set it to "user".
+command. In Kea 2.5.5 thru 2.5.7 this parameter was also used in communication
+between the HA partners to specify the identifier of an HA service sending the command
+in a numeric format. However, due to the compatibility issues with the older
+Kea versions that did not properly parse the numeric values, it was necessary
+to introduce the new parameter, ``origin-id``, in Kea 2.5.8.
 
-Introduction of ``origin-id`` in Kea 2.5.8 deprecates the use of the ``origin`` parameter
-in the messages exchanged between the Kea HA partners. The ``origin-id`` parameter
-must not be used in messages sent by the user.
+It holds a numeric value representing the origin of the command. The same value
+can still be passed using the ``origin`` parameter, but it can cause the
+aforementioned compatibility issues between the HA partners running different
+Kea versions. Therefore, new Kea versions favor using ``origin-id`` in communication
+between the HA partners. The ``origin`` parameter can still be used, but the
+``origin-id`` takes precedence. Overall, it is recommended that both parameters be
+omitted from the user commands.
+
+The following codes represent the supported origins in numeric format:
+
+ -  ``1`` - a user command, same as specifying ``"origin": "user"``,
+ -  ``2000``, ``2001``, ``2002`` etc. - origins specified by HA partners where
+    the increments above ``2000`` are distinct HA service identifiers used when
+    the partners have many relationships.
+
+In the following example:
 
 ::
 
@@ -736,6 +748,10 @@ must not be used in messages sent by the user.
        }
    }
 
+the effective origin will be ``2002`` which indicates it is an HA partner
+sending the command for the service with ID of ``2``. The ``origin``
+parameter will be ignored in this case.
+
 .. isccmd:: dhcp-enable
 .. _command-dhcp-enable:
 
@@ -747,27 +763,44 @@ The :isccmd:`dhcp-enable` command globally enables the DHCP service.
 Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
 command source. A server administrator should typically omit this parameter
 because the default value "user" indicates that the administrator sent the
-command. This command can also be sent by the partner server running the HA hook
-library. In that case, the partner server sets the parameter to a unique
-integer identifier of an HA service. The integer values are reserved for the
-communication between HA partners and should not be specified in the
-administrator's commands, as it may interfere with HA operation. The
-administrator should either omit this parameter or set it to
-"user".
-
-Introduction of ``origin-id`` deprecates the use of the ``origin`` parameter
-in the messages exchanged between the Kea HA partners. The ``origin-id`` parameter
-must not be used in messages sent by the user.
+command. In Kea 2.5.5 thru 2.5.7 this parameter was also used in communication
+between the HA partners to specify the identifier of an HA service sending the command
+in a numeric format. However, due to the compatibility issues with the older
+Kea versions that did not properly parse the numeric values, it was necessary
+to introduce the new parameter, ``origin-id``, in Kea 2.5.8.
+
+It holds a numeric value representing the origin of the command. The same value
+can still be passed using the ``origin`` parameter, but it can cause the
+aforementioned compatibility issues between the HA partners running different
+Kea versions. Therefore, new Kea versions favor using ``origin-id`` in communication
+between the HA partners. The ``origin`` parameter can still be used, but the
+``origin-id`` takes precedence. Overall, it is recommended that both parameters be
+omitted from the user commands.
+
+The following codes represent the supported origins in numeric format:
+
+ -  ``1`` - a user command, same as specifying ``"origin": "user"``,
+ -  ``2000``, ``2001``, ``2002`` etc. - origins specified by HA partners where
+    the increments above ``2000`` are distinct HA service identifiers used when
+    the partners have many relationships.
+
+In the following example:
 
 ::
 
    {
        "command": "dhcp-enable",
        "arguments": {
+           "origin-id": 2002,
            "origin": "user"
        }
    }
 
+the effective origin will be ``2002`` which indicates it is an HA partner
+sending the command for the service with ID of ``2``. The ``origin``
+parameter will be ignored in this case.
+
+
 .. isccmd:: status-get
 .. _command-status-get:
 

src/hooks/dhcp/high_availability/command_creator.cc

@@ -267,7 +267,10 @@ CommandCreator::createSyncCompleteNotify(const unsigned int origin_id,
     auto args = Element::createMap();
     args->set("server-name", Element::create(server_name));
     args->set("origin-id", Element::create(origin_id));
-    // Add for backward compatibility with Kea 2.5.5.
+    // Add for backward compatibility with Kea 2.5.5 to Kea 2.5.7.
+    // The origin parameter was introduced for this command in Kea 2.5.5 but
+    // renamed to origin-id to be consistent with the origin-id used in
+    // dhcp-enable and dhcp-disable commands starting from Kea 2.5.8.
     args->set("origin", Element::create(origin_id));
     auto command = config::createCommand("ha-sync-complete-notify", args);
     insertService(command, server_type);

src/share/api/dhcp-disable.json

@@ -2,14 +2,15 @@
     "access": "write",
     "avail": "1.4.0",
     "brief": [
-        "This command globally disables the DHCP service."
+        "This command disables the DHCP service."
     ],
     "cmd-syntax": [
         "{",
         "    \"command\": \"dhcp-disable\",",
         "    \"arguments\": {",
         "        \"max-period\": 20,",
-        "        \"origin\": \"user\"",
+        "        \"origin\": \"ha-partner\",",
+        "        \"origin-id\": 2002",
         "    }",
         "}"
     ],

src/share/api/dhcp-enable.json

@@ -2,13 +2,14 @@
     "access": "write",
     "avail": "1.4.0",
     "brief": [
-        "This command globally enables the DHCP service."
+        "This command enables the DHCP service."
     ],
     "cmd-syntax": [
         "{",
         "    \"command\": \"dhcp-enable\",",
         "    \"arguments\": {",
-        "        \"origin\": \"user\"",
+        "        \"origin\": \"ha-partner\",",
+        "        \"origin-id\": 2002",
         "    }",
         "}"
     ],