[5396] Documentation for new shared network commands written.

diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml
index eaa5d131e26b72f48b212268b4e8ef3fa8e8c820..fb9dce08c4a5a10da2249950f5b750f3972f0bf5 100644 (file)
--- a/doc/guide/hooks.xml
+++ b/doc/guide/hooks.xml
@@ -1670,12 +1670,15 @@ as follows:
         <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.
+          commands used to query and manipulate subnet and shared network
+          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. An ability to manage shared networks (listing,
+          retrieving details, adding new ones, removing existing ones, adding
+          subnets to and removing from shared networks) is also provided.
         </para>
 
         <para>Currently this library is only available to ISC customers with a
@@ -1689,7 +1692,7 @@ as follows:
           </listitem>
           <listitem>
           <simpara>
-            <command>subnet4-get/subnet6-get</command>: retrieves detailed information about a selected subnet
+            <command>subnet4-get/subnet6-get</command>: retrieves detailed information about a specified subnet
           </simpara>
           </listitem>
           <listitem>
@@ -1702,6 +1705,45 @@ as follows:
             <command>subnet4-del/subnet6-del</command>: removes a subnet from the server's configuration
           </simpara>
           </listitem>
+
+          <listitem>
+          <simpara>
+            <command>network4-list/network6-list</command>: lists all configured
+            shared networks
+          </simpara>
+          </listitem>
+          <listitem>
+          <simpara>
+            <command>network4-get/network6-get</command>: retrieves detailed
+            information about specified shared network
+          </simpara>
+          </listitem>
+          <listitem>
+          <simpara>
+            <command>network4-add/network6-add</command>: adds a new shared
+            network to the server's configuration
+          </simpara>
+          </listitem>
+          <listitem>
+          <simpara>
+            <command>network4-del/network6-del</command>: removes a shared
+            network from the server's configuration
+          </simpara>
+          </listitem>
+          <listitem>
+          <simpara>
+            <command>network4-subnet-add/network6-subnet-add</command>: adds
+            existing subnet to existing shared network
+          </simpara>
+          </listitem>
+          <listitem>
+          <simpara>
+            <command>network4-subnet-del/network6-subnet-del</command>: removes
+            a subnet from existing shared network and demotes it to a plain
+            subnet.
+          </simpara>
+          </listitem>
+
         </itemizedlist>
         </para>
 
@@ -2125,8 +2167,303 @@ If the subnet exists the response will be similar to this:
         </para>
       </section>
 
+      <section>
+        <title>network4-list, network6-list commands</title>
+        <para>
+          These commands are used to retrieve full list of currently configured
+          shared networks. The list contains only very basic information about
+          each shared network. If more details are needed, please use
+          <command>network4-get</command> or <command>network6-get</command> to
+          retrieve all information available. This command does not require any
+          parameters and its invocation is very simple:
+<screen>
+{
+    "command": "network4-list"
+}
+</screen>
+An example response for <command>network4-list</command> looks as follows:
+<screen>
+{
+    "arguments": {
+        "shared-networks": [
+            { "name": "floor1" },
+            { "name": "office" }
+        ]
+    },
+    "result": 0,
+    "text": "2 IPv4 network(s) found"
+}</screen>
+<command>network6-list</command> follows exactly the same syntax for
+both the query and the response.
+        </para>
+    </section>
+
+    <section>
+        <title>network4-get, network6-get commands</title>
+        <para>
+          These commands are used to retrieve detailed information
+          about shared networks, including subnets currently
+          being part of a given network. Both commands take one
+          mandatory parameter <command>name</command>, which specify
+          the name of shared network. An example command to retrieve
+          details about IPv4 shared network with a name "floor13"
+          looks as follows:
+<screen>
+{
+    "command": "network4-get",
+    "arguments": {
+        "name": "floor13"
+    }
+}</screen>
+An example response could look as follows:
+<screen>
+{
+    "result": 0,
+    "text": "Info about IPv4 shared network 'floor13' returned",
+    "arguments": {
+        "shared-networks": [
+        {
+            "match-client-id": true,
+            "name": "floor13",
+            "option-data": [ ],
+            "rebind-timer": 90,
+            "relay": {
+                "ip-address": "0.0.0.0"
+            },
+            "renew-timer": 60,
+            "reservation-mode": "all",
+            "subnet4": [
+                {
+                    "subnet": "192.0.2.0/24",
+                    "id": 5,
+                    // many other subnet specific details here
+                },
+                {
+                    "id": 6,
+                    "subnet": "192.0.3.0/31",
+                    // many other subnet specific details here
+                }
+            ],
+            "valid-lifetime": 120
+        }
+        ]
+    }
+}
+</screen>
+Note that actual response contains many additional fields that are
+omitted here for clarity. The response format is exactly the same as
+used in <command>config-get</command>, just is limited to returning
+shared networks information.
+        </para>
+    </section>
+
+    <section>
+        <title>network4-add, network6-add commands</title>
+        <para>
+          These commands are used to add a new shared network. New
+          network has to have unique name. This command requires one parameter
+          <command>shared-networks</command>, which is a list and
+          should contain exactly one entry that defines the
+          network. The only mandatory element for a network is its
+          name. Although it does not make operational sense, it is
+          allowed to add an empty shared network that does not have
+          any subnets in it. That is allowed for testing purposes, but
+          having empty networks (or with only one subnet) is
+          discouraged in production environments. For details regarding
+          syntax, see <xref linkend="shared-network4"/> and <xref
+          linkend="shared-network6"/>.
+        </para>
+        <note><para>As opposed to parameter inheritance during full
+          new configuration processing, this command does not fully handle
+          parameter inheritance and any missing parameters will be
+          filled with default values, rather than inherited from
+          global scope.</para></note>
+        <para>
+          An example that showcases how to add a new IPv4 shared network looks
+          as follows:
+<screen>
+{
+    "command": "network4-add",
+    "arguments": {
+        "shared-networks": [ {
+            "name": "floor13",
+            "subnet4": [
+            {
+                "id": 100,
+                "pools": [ { "pool": "192.0.2.2-192.0.2.99" } ],
+                "subnet": "192.0.2.0/24",
+                "option-data": [
+                    {
+                        "name": "routers",
+                        "data": "192.0.2.1"
+                    }
+                ]
+            },
+            {
+                "id": 101,
+                "pools": [ { "pool": "192.0.3.2-192.0.3.99" } ],
+                "subnet": "192.0.3.0/24",
+                "option-data": [
+                    {
+                        "name": "routers",
+                        "data": "192.0.3.1"
+                    }
+                ]
+            } ]
+        } ]
+    }
+}
+</screen>
+Assuming there was no shared network with a name floor13 and no subnets with id
+100 and 101 previously configured, the command will be successful and will
+return the following response:
+<screen>
+{
+    "arguments": {
+        "shared-networks": [ { "name": "floor13" } ]
+    },
+    "result": 0,
+    "text": "A new IPv4 shared network 'floor13' added"
+}
+</screen>
+The <command>network6-add</command> uses the same syntax for both the query and
+the response. However, there are some parameters that are IPv4-only
+(e.g. match-client-id) and some are IPv6-only (e.g. interface-id). The same
+applies to subnets within the network.
+        </para>
+    </section>
+    <section>
+        <title>network4-del, network6-del commands</title>
+        <para>
+          These commands are used to delete existing shared networks. Each
+          subnet within the network being removed will be demoted to a plain
+          network. If you want to competely remove the subnets, please use
+          <command>subnet4-del</command> or <command>subnet6-del</command>
+          commands. Both commands take exactly one parameter 'name' that
+          specifies the name of the network to be removed. An example invocation
+          of <command>network4-del</command> command looks as follows:
+<screen>
+{
+    "command": "network4-del",
+    "arguments": {
+        "name": "floor13"
+    }
+}
+</screen>
+Assuming there was such a network configured, the response will look similar to
+the following:
+<screen>
+{
+    "arguments": {
+        "shared-networks": [
+            {
+                "name": "floor1"
+            }
+        ]
+    },
+    "result": 0,
+    "text": "IPv4 shared network 'floor13' deleted"
+}</screen>
+The <command>network6-del</command> command uses exactly the same syntax for
+both the command and the response.
+        </para>
+
+    </section>
+    <section>
+        <title>network4-subnet-add, network6-subnet-add commands</title>
+        <para>
+          These commands are used to add existing subnets to existing shared
+          networks. There are several ways to add new shared network. System
+          administrator can add the whole shared network at once, either by
+          editing a configuration file or by calling
+          <command>network4-add</command> or <command>network6-add</command>
+          commands with desired subnets in it. This approach works better for completely
+          new shared subnets. However, there may be cases when an existing
+          subnet is running out of addresses and needs to be extended with
+          additional address space. In other words another subnet has to be
+          added on top of it. For this scenario, a system administrator can use
+          <command>network4-add</command> or <command>network6-add</command> and
+          then add existing subnet to this newly created shared network  using
+          <command>network4-subnet-add</command> or
+          <command>network6-subnet-add</command>.
+        </para>
+        <para>
+          The <command>network4-subnet-add</command> and
+          <command>network6-subnet-add</command> commands take two parameters:
+          <command>id</command>, which is an integer and specifies subnet-id of existing subnet to
+          be added to a shared network; and <command>name</command>, which
+          specifies name of the shared network the subnet will be added to. The
+          subnet must not belong to any existing network. In case you want to
+          reassign a subnet from one shared network to another, please use
+          <command>network4-subnet-del</command> or
+          <command>network6-subnet-del</command> commands first.
+        </para>
+        <para>
+          An example invocation of <command>network4-subnet-add</command>
+          command looks as follows:
+<screen>
+{
+    "command": "network4-subnet-add",
+    "arguments": {
+        "name": "floor13",
+        "id": 5
+    }
+}</screen>
+Assuming there is a network named 'floor13', there is a subnet with subnet-id 5
+and it is not a part of existing network, the command will return a response
+similar to the following:
+<screen>
+{
+    "result": 0,
+    "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'"
+}</screen>
+        The <command>network6-subnet-add</command> command uses exactly the same syntax for
+both the command and the response.
+        </para>
+
+        <note><para>As opposed to parameter inheritance during full
+          new configuration processing or when adding a new shared network with
+          new subnets, this command does not fully handle
+          parameter inheritance and any missing parameters will be
+          filled with default values, rather than inherited from
+          global scope or from the shared network.</para></note>
+    </section>
+    <section>
+        <title>network4-subnet-del, network6-subnet-del commands</title>
+        <para>
+          These commands are used to remove a subnet that is part of existing shared
+          network and demote it to a plain, stand-alone subnet.  The
+          <command>network4-subnet-del</command> and
+          <command>network6-subnet-del</command> commands take two parameters:
+          <command>id</command>, which is an integer and specifies subnet-id of
+          existing subnet to be removed from a shared network; and
+          <command>name</command>, which specifies name of the shared network
+          the subnet will be removed from.
+        </para>
+        <para>An example invocation of the
+        <command>network4-subnet-del</command> command looks as follows:
+ <screen>
+ {
+    "command": "network4-subnet-del",
+    "arguments": {
+        "name": "floor13",
+        "id": 5
+    }
+ }</screen>
+ Assuming there was a subnet with subnet-id equal to 5 that was part of a shared
+ network named 'floor13', the response would look similar to the following:
+<screen>
+{
+    "result": 0,
+    "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
+}</screen>
+The <command>network6-subnet-del</command> command uses exactly the same syntax for
+both the command and the response.
+        </para>
+    </section>
+
     </section>
-</section> <!-- end of subnet commands -->
+  </section> <!-- end of subnet commands -->
 
     <section id="user-context">
       <title>User contexts</title>