From: Marcin Siodelski Date: Fri, 26 Apr 2024 10:59:09 +0000 (+0200) Subject: [#3344] Addressed review comments (doc) X-Git-Tag: Kea-2.5.8~25 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a22f6975316cd5ff56037d34ca26dafd9f9353fb;p=thirdparty%2Fkea.git [#3344] Addressed review comments (doc) --- diff --git a/doc/sphinx/arm/ctrl-channel.rst b/doc/sphinx/arm/ctrl-channel.rst index c2eb46607b..613e0f783a 100644 --- a/doc/sphinx/arm/ctrl-channel.rst +++ b/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: diff --git a/src/hooks/dhcp/high_availability/command_creator.cc b/src/hooks/dhcp/high_availability/command_creator.cc index f3b572090a..b5d079897c 100644 --- a/src/hooks/dhcp/high_availability/command_creator.cc +++ b/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); diff --git a/src/share/api/dhcp-disable.json b/src/share/api/dhcp-disable.json index a12764c444..60c114b255 100644 --- a/src/share/api/dhcp-disable.json +++ b/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", " }", "}" ], diff --git a/src/share/api/dhcp-enable.json b/src/share/api/dhcp-enable.json index d7a9959405..7cdff22731 100644 --- a/src/share/api/dhcp-enable.json +++ b/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", " }", "}" ],