From: Andrei Pavel <andrei@isc.org>
Date: Wed, 5 Apr 2023 15:17:32 +0000 (+0300)
Subject: [#549] document the overwrite behavior in the other update commands
X-Git-Tag: Kea-2.3.7~17
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d9c86120f46eec2b34d1974eba1f312ff99cf4fb;p=thirdparty%2Fkea.git

[#549] document the overwrite behavior in the other update commands
---

diff --git a/doc/sphinx/arm/hooks-class-cmds.rst b/doc/sphinx/arm/hooks-class-cmds.rst
index d98c398c36..7d698c8ea1 100644
--- a/doc/sphinx/arm/hooks-class-cmds.rst
+++ b/doc/sphinx/arm/hooks-class-cmds.rst
@@ -108,6 +108,15 @@ be removed with the ``class-del`` command and then added again with a
 different name using ``class-add``. Note, however, that the class with
 the new name will be added at the end of the list of configured classes.
 
+As with other update commands, this command overwrites all the contents of the
+entry. If the client class previously had a resource assigned to it, and the
+``class-update`` command is missing the resource, it is deleted from the server
+configuration. If an incremental update of the class is desired, then this can
+be achieved by doing a `class-get <command-class-get_>`_ to get the full picture
+of the client class, picking the client class out of the response, modifying it
+to the required outcome, and then issuing the ``client-update`` command with the
+resulting client class attached.
+
 .. _command-class-del:
 
 The ``class-del`` Command
diff --git a/doc/sphinx/arm/hooks-lease-cmds.rst b/doc/sphinx/arm/hooks-lease-cmds.rst
index 6f1f237ca9..cd5c671c18 100644
--- a/doc/sphinx/arm/hooks-lease-cmds.rst
+++ b/doc/sphinx/arm/hooks-lease-cmds.rst
@@ -79,9 +79,9 @@ This library provides the following commands:
 
 -  ``lease6-del`` - deletes an IPv6 lease with the specified parameters.
 
--  ``lease4-update`` - updates an IPv4 lease.
+-  ``lease4-update`` - updates (replaces) an existing IPv4 lease.
 
--  ``lease6-update`` - updates an IPv6 lease.
+-  ``lease6-update`` - updates (replaces) an existing IPv6 lease.
 
 -  ``lease4-wipe`` - removes all leases from a specific IPv4 subnet or
    from all subnets.
@@ -902,6 +902,16 @@ An example of a command to update an IPv6 lease is:
      }
    }
 
+As with other update commands, this command overwrites all the contents of the
+entry. If the lease previously had a resource assigned to it, and the
+``lease4-update``/``lease6-update`` command is missing the resource, it is
+deleted from the lease database. If an incremental update of the lease is
+desired, then this can be achieved by doing a
+`lease4-get <command-lease4-get_>`_ / `lease6-get <command-lease6-get_>`_
+command to get the full picture of the lease, picking the lease out of the
+response, modifying it to the required outcome, and then issuing the
+``lease4-update``/``lease6-update`` command with the resulting lease attached.
+
 .. _command-lease4-wipe:
 
 .. _command-lease6-wipe:
diff --git a/doc/sphinx/arm/hooks-subnet-cmds.rst b/doc/sphinx/arm/hooks-subnet-cmds.rst
index 45a9db7592..ff5b01423b 100644
--- a/doc/sphinx/arm/hooks-subnet-cmds.rst
+++ b/doc/sphinx/arm/hooks-subnet-cmds.rst
@@ -412,6 +412,12 @@ The response to this command has the following structure:
        }
    }
 
+As with other update commands, this command overwrites all the contents of the
+entry. If the IPv4 subnet previously had a resource assigned to it, and the
+``subnet4-update`` command is missing the resource, it is deleted from the
+server configuration. If an incremental update of the subnet is desired, then
+this can be achieved with `subnet4-delta-add <command-subnet4-delta-add_>`_.
+
 .. _command-subnet6-update:
 
 The ``subnet6-update`` Command
@@ -459,6 +465,12 @@ The response to this command has the following structure:
        }
    }
 
+As with other update commands, this command overwrites all the contents of the
+entry. If the IPv4 subnet previously had a resource assigned to it, and the
+``subnet6-update`` command is missing the resource, it is deleted from the
+server configuration. If an incremental update of the subnet is desired, then
+this can be achieved with `subnet6-delta-add <command-subnet6-delta-add_>`_.
+
 .. _command-subnet4-del:
 
 The ``subnet4-del`` Command