[5315] Updated Kea User's Guide with subnet_cmds information.

1 files changed, 456 insertions, 15 deletions

diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml
index d706747d0e..df33416953 100644
--- a/doc/guide/hooks.xml
+++ b/doc/guide/hooks.xml
@@ -241,6 +241,21 @@
               capabilities related to host reservations will be added in the
               future.</entry>
             </row>
+            <row>
+              <entry>Subnet Commands</entry>
+              <entry>Support customers</entry>
+              <entry>Kea 1.3.0</entry>
+              <entry>In deployments in which subnets' configuration needs to
+              be frequently updated, it is a hard requirement that such updates are
+              performed without a need for a full DHCP server reconfiguration
+              or restart. This hooks library allows for incremental changes
+              to the subnets' configuration such as: adding a subnet, removing
+              a subnet. It also allows for listing all available subnets and
+              fetching detailed information about a selected subnet. The
+              commands exposed by this library do not affect other subnets
+              or configuration parameters currently used by the server.
+              </entry>
+            </row>
           </tbody>
           </tgroup>
           </table>
@@ -1112,7 +1127,6 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows
     }
 }
 </screen>
-
         </para>
 
         <para><command>lease6-add</command> command requires four
@@ -1480,17 +1494,444 @@ as follows:
       </section>
     </section>
 
-    </section> <section id="user-context"> <title>User contexts</title>
-    <para>Hook libraries can have their own configuration parameters. That is
-    convenient if the parameter applies to the whole library. However, sometimes
-    it is very useful if certain configuration entities are extended with
-    additional configuration data. This is where the concept of user contexts
-    comes in. A sysadmin can define an arbitrary set of data and attach it to
-    Kea structures, as long as the data is specified as JSON map.  In
-    particular, it is possible to define fields that are integers, strings,
-    boolean, lists and maps. It is possible to define nested structures of
-    arbitrary complexity. Kea does not use that data on its own, simply stores
-    and makes it available for the hook libraries.  </para> <para> As of Kea
-    1.2, the only structures that allow user contexts are address and prefix
-    pools, but it is expected to extend other structures with the user context
-    capability.  </para> </section> </chapter> <!-- hooks-libraries -->
+      <section id="subnet-cmds">
+        <title>subnet_cmds: Subnet Commands</title>
+        <para>
+          This section describes a hook application that offers a number of new
+          commands used to query and manipulate subnet configurations in Kea.
+          This application is very useful in deployments with a large number of
+          subnets being managed by the DHCP servers and when the subnets are
+          frequently updated. The commands offer lightweight approach for
+          manipulating subnets without a need to fully reconfigure the server
+          and without affecting existing servers' configurations.
+        </para>
+
+        <para>Currently this library is only available to ISC customers with a
+        support contract.</para>
+
+        <para>The following commands are currently supported:
+        <itemizedlist mark='bullet'>
+          <listitem>
+            <simpara><command>subnet4-list/subnet6-list</command>: lists all configured subnets
+            </simpara>
+          </listitem>
+          <listitem>
+          <simpara>
+            <command>subnet4-get/subnet6-get</command>: retrieves detailed information about a selected subnet
+          </simpara>
+          </listitem>
+          <listitem>
+          <simpara>
+            <command>subnet4-add/subnet6-add</command>: adds new subnet into server's configuration
+          </simpara>
+          </listitem>
+          <listitem>
+          <simpara>
+            <command>subnet4-del/subnet6-del</command>: removes a subnet from the server's configuration
+          </simpara>
+          </listitem>
+        </itemizedlist>
+        </para>
+
+        <section>
+          <title>subnet4-list command</title>
+          <para>
+            This command is used to list all currently configured subnets. The
+            subnets are returned in a brief form, i.e. a subnet identifier
+            and subnet prefix is included for each subnet. In order to retrieve
+            the detailed information about the subnet the
+            <command>subnet4-get</command> should be used.
+          </para>
+          <para>
+            This command has the simple structure:
+<screen>
+{
+    "command": "subnet4-list"
+}
+</screen>
+          </para>
+          <para>
+            The list of subnets returned as a result of this command is returned
+            in the following format:
+<screen>
+{
+    "result": 0,
+    "text": "2 IPv4 subnets found",
+    "arguments": {
+    "subnet-ids": [
+        {
+            "subnet-id": 10,
+            "subnet": "10.0.0.0/8"
+        },
+        {
+            "subnet-id": 100,
+            "subnet": "192.0.2.0/24"
+        }
+    ]
+}
+</screen>
+          </para>
+          <para>
+            If no IPv4 subnets are found, an error code is returned along with
+            the error description.
+          </para>
+        </section>
+
+        <section>
+          <title>subnet6-list command</title>
+          <para>
+            This command is used to list all currently configured subnets. The
+            subnets are returned in a brief form, i.e. a subnet identifier
+            and subnet prefix is included for each subnet. In order to retrieve
+            the detailed information about the subnet the
+            <command>subnet6-get</command> should be used.
+          </para>
+          <para>
+            This command has the simple structure:
+<screen>
+{
+    "command": "subnet6-list"
+}
+</screen>
+          </para>
+          <para>
+            The list of subnets returned as a result of this command is returned
+            in the following format:
+<screen>
+{
+    "result": 0,
+    "text": "2 IPv6 subnets found",
+    "arguments": {
+    "subnet-ids": [
+        {
+            "subnet-id": 11,
+            "subnet": "2001:db8:1::/64"
+        },
+        {
+            "subnet-id": 233,
+            "subnet": "3000::/16"
+        }
+    ]
+}
+</screen>
+          </para>
+          <para>
+            If no IPv6 subnets are found, an error code is returned along with
+            the error description.
+          </para>
+        </section>
+      </section>
+
+      <section>
+        <title>subnet4-get command</title>
+        <para>This command is used to retrieve detailed information about the
+        specified subnet. This command usually follows the
+        <command>subnet4-list</command>, which is used to discover available
+        subnets with their respective subnet identifiers and prefixes. Any of
+        those parameters can be then used in <command>subnet4-get</command>
+        to fetch subnet information:
+<screen>
+{
+    "command": "subnet4-get",
+    "arguments": {
+        "subnet-id": 10
+    }
+}</screen>
+
+or
+
+<screen>
+{
+    "command": "subnet4-get",
+    "arguments": {
+        "subnet": "10.0.0.0/8"
+    }
+}
+</screen>
+        </para>
+
+        <para>
+          If the subnet exists the response will be similar to this:
+<screen>
+{
+    "result": 0,
+    "text": "Info about IPv4 subnet 10.0.0.0/8 (subnet-id 10) returned",
+    "arguments": {
+        "subnet4": [
+            {
+                "subnet": "10.0.0.0/8",
+                "id": 1,
+                "option-data": [
+                    ....
+                ]
+                ...
+            }
+        ]
+    }
+}
+
+</screen>
+        </para>
+      </section>
+
+      <section>
+        <title>subnet6-get command</title>
+        <para>This command is used to retrieve detailed information about the
+        specified subnet. This command usually follows the
+        <command>subnet6-list</command>, which is used to discover available
+        subnets with their respective subnet identifiers and prefixes. Any of
+        those parameters can be then used in <command>subnet6-get</command>
+        to fetch subnet information:
+<screen>
+{
+    "command": "subnet6-get",
+    "arguments": {
+        "subnet-id": 11
+    }
+}
+</screen>
+
+or
+
+<screen>
+{
+    "command": "subnet6-get",
+    "arguments": {
+        "subnet": "2001:db8:1::/64"
+    }
+}</screen>
+
+If the subnet exists the response will be similar to this:
+<screen>
+{
+    "result": 0,
+    "text": "Info about IPv6 subnet 2001:db8:1::/64 (subnet-id 11) returned",
+    "arguments": {
+        "subnet6": [
+            {
+                "subnet": "2001:db8:1::/64",
+                "id": 1,
+                "option-data": [
+                    ...
+                ]
+                ....
+            }
+        ]
+    }
+}
+</screen> 
+        </para>
+      </section>
+
+      <section>
+        <title>subnet4-add</title>
+        <para>
+          This command is used to create and add new subnet to the existing
+          server configuration. This operation has no impact on other
+          subnets. The subnet identifier must be specified and must be
+          unique among all subnets. If the identifier or a subnet prefix is
+          not unique an error is reported and the subnet is not added.
+        </para>
+        <para>
+          The subnet information within this command has the same structure
+          as the subnet information in the server configuration file with the
+          exception that static host reservations must not be specified
+          within <command>subnet4-add</command>. The commands described in
+          <xref linkend="host-cmds"/> should be used to add, remove and
+          modify static reservations.
+<screen>
+{
+    "command": "subnet4-add",
+    "arguments": {
+        "subnet4": [ {
+            "id": 123,
+            "subnet": "10.20.30.0/24",
+            ...
+        } ]
+    }
+}
+</screen>
+        </para>
+
+        <para>
+          The response to this command has the following structure:
+<screen>
+{
+    "result": 0,
+    "text": "IPv4 subnet added",
+    "arguments": {
+        "subnet4": [
+            {
+                "id": 123,
+                "subnet": "10.20.30.0/24"
+            }
+        ]
+    }
+}
+</screen>
+        </para>
+      </section>
+
+      <section>
+        <title>subnet6-add</title>
+        <para>
+          This command is used to create and add new subnet to the existing
+          server configuration. This operation has no impact on other
+          subnets. The subnet identifier must be specified and must be
+          unique among all subnets. If the identifier or a subnet prefix is
+          not unique an error is reported and the subnet is not added.
+        </para>
+        <para>
+          The subnet information within this command has the same structure
+          as the subnet information in the server configuration file with the
+          exception that static host reservations must not be specified
+          within <command>subnet6-add</command>. The commands described in
+          <xref linkend="host-cmds"/> should be used to add, remove and
+          modify static reservations.
+<screen>
+{
+    "command": "subnet6-add",
+    "arguments": {
+        "subnet6": [ {
+            "id": 234,
+            "subnet": "2001:db8:1::/64",
+            ...
+        } ]
+    }
+}
+</screen>
+        </para>
+
+        <para>
+          The response to this command has the following structure:
+<screen>
+{
+    "result": 0,
+    "text": "IPv6 subnet added",
+    "arguments": {
+        "subnet6": [
+            {
+                "id": 234,
+                "subnet": "2001:db8:1::/64"
+            }
+        ]
+    }
+}
+</screen>
+        </para>
+      </section>
+
+      <section>
+        <title>subnet4-del command</title>
+        <para>
+          This command is used to remove a subnet from the server's configuration.
+          This command has no effect on other configured subnets but removing
+          a subnet has certain implications which the server's administrator
+          should be aware of.
+        </para>
+        <para>
+          In most cases the server has assigned some leases to the clients
+          belonging to the subnet. The server may also be configured with
+          static host reservations which are associated with this subnet.
+          The current implementation of the <command>subnet4-del</command>
+          removes neither the leases nor host reservations associated with
+          a subnet. This is the safest approach because the server doesn't
+          loose track of leases assigned to the clients from this subnet.
+          However, removal of the subnet may still cause configuration
+          errors and conflicts. For example: after removal of the subnet,
+          the server administrator may add a new subnet with the ID used
+          previously for the removed subnet. This means that the existing
+          leases and static reservations will be in conflict with this
+          new subnet. Thus, we recommend that this command is used with extreme
+          caution.
+        </para>
+
+        <para>The command has the following structure:
+<screen>
+{
+    "command": "subnet4-del",
+    "arguments": {
+        "subnet-id": 123
+    }
+}
+</screen>
+        </para>
+        <para>
+          The example successful response may look like this:
+<screen>
+{
+    "result": 0,
+    "text": "IPv4 subnet 192.0.2.0/24 (subnet-id 123) deleted"
+}
+</screen>
+        </para>
+      </section>
+
+      <section>
+        <title>subnet6-del command</title>
+        <para>
+          This command is used to remove a subnet from the server's configuration.
+          This command has no effect on other configured subnets but removing
+          a subnet has certain implications which the server's administrator
+          should be aware of.
+        </para>
+        <para>
+          In most cases the server has assigned some leases to the clients
+          belonging to the subnet. The server may also be configured with
+          static host reservations which are associated with this subnet.
+          The current implementation of the <command>subnet6-del</command>
+          removes neither the leases nor host reservations associated with
+          a subnet. This is the safest approach because the server doesn't
+          loose track of leases assigned to the clients from this subnet.
+          However, removal of the subnet may still cause configuration
+          errors and conflicts. For example: after removal of the subnet,
+          the server administrator may add a new subnet with the ID used
+          previously for the removed subnet. This means that the existing
+          leases and static reservations will be in conflict with this
+          new subnet. Thus, we recommend that this command is used with extreme
+          caution.
+        </para>
+
+        <para>The command has the following structure:
+<screen>
+{
+    "command": "subnet6-del",
+    "arguments": {
+        "subnet-id": 234
+    }
+}
+</screen>
+        </para>
+        <para>
+          The example successful response may look like this:
+<screen>
+{
+    "result": 0,
+    "text": "IPv6 subnet 2001:db8:1::/64 (subnet-id 234) deleted"
+}
+</screen>
+        </para>
+      </section>
+
+    </section>
+
+    <section id="user-context">
+      <title>User contexts</title>
+      <para>Hook libraries can have their own configuration parameters. That is
+      convenient if the parameter applies to the whole library. However,
+      sometimes it is very useful if certain configuration entities are extended
+      with additional configuration data. This is where the concept of user
+      contexts comes in. A sysadmin can define an arbitrary set of data and
+      attach it to Kea structures, as long as the data is specified as JSON map.
+      In particular, it is possible to define fields that are integers, strings,
+      boolean, lists and maps. It is possible to define nested structures of
+      arbitrary complexity. Kea does not use that data on its own, simply stores
+      and makes it available for the hook libraries.
+      </para>
+      <para>
+        As of Kea 1.2, the only structures that allow user contexts are address
+        and prefix pools, but it is expected to extend other structures with the
+        user context capability.
+      </para>
+    </section>
+   </chapter> <!-- hooks-libraries -->