From c16e2343b4102808e22ddb6efde1c0e5b080292f Mon Sep 17 00:00:00 2001
From: Marcin Siodelski <marcin@isc.org>
Date: Wed, 15 May 2019 11:43:40 +0200
Subject: [PATCH] [#71,!314] Documented remote commands for DHCPv4 options.

---
 doc/api/remote-option-def4-get.json    |   3 +-
 doc/api/remote-option4-global-get.json |  43 ++++--
 doc/guide/api.xml                      |  46 ++++--
 doc/guide/hooks-cb-cmds.xml            | 198 ++++++++++++++++++++++++-
 4 files changed, 267 insertions(+), 23 deletions(-)

diff --git a/doc/api/remote-option-def4-get.json b/doc/api/remote-option-def4-get.json
index 15b66d7fc2..8bfc87cf8c 100644
--- a/doc/api/remote-option-def4-get.json
+++ b/doc/api/remote-option-def4-get.json
@@ -6,8 +6,7 @@
     "avail": "1.6.0",
     "hook": "cb_cmds",
     "cmd-syntax": "{
-    \"command\": \"remote-option-def4-get\"
-    \"service\": [ \"dhcp4\" ],
+    \"command\": \"remote-option-def4-get\",
     \"arguments\": {
         \"option-defs\": [ {
             \"code\": <option code>,
diff --git a/doc/api/remote-option4-global-get.json b/doc/api/remote-option4-global-get.json
index 8b8ed2f140..8a1bd73f4a 100644
--- a/doc/api/remote-option4-global-get.json
+++ b/doc/api/remote-option4-global-get.json
@@ -1,12 +1,37 @@
 {
     "name": "remote-option4-global-get",
-    "brief": "a sentence or two explaining what this command does",
-    "description": "See <xref linkend=\"cmd-\"/>",
-    "support": [ "undocumented" ],
-    "avail": "0.0.0",
-    "hook": "undocumented",
-    "cmd-syntax": "Syntax of the command",
-    "cmd-comment": "Possibly some extra comments after the syntax.",
-    "resp-syntax": "Syntax of the response",
-    "resp-comment": "Optional extra comments after the resposne syntax."
+    "brief": "This command is used to fetch a global DHCPv4 option for the server from the specified database.",
+    "description": "See <xref linkend=\"cmd-remote-option4-global-get\"/>",
+    "support": [ "kea-dhcp4" ],
+    "avail": "1.6.0",
+    "hook": "cb_cmds",
+    "cmd-syntax": "{
+    \"command\": \"remote-option4-global-get\",
+    \"arguments\": {
+        \"options\": [
+            {
+                \"code\": <option code>,
+                \"space\": <option space>
+            }
+        ],
+        \"remote\": {
+            <specification of the database to connect to>
+        }
+}",
+    "cmd-comment": "The option is identified by the pair of option code/space values. The <command>remote</command> map contains specification of the backend from which the option should be fetched. Typically it contains \"type\": \"mysql\".",
+    "resp-syntax": "{
+    \"result\": 0,
+    \"text\": \"DHCPv4 option <option code> in <option space> found.\",
+    \"arguments\": {
+        \"options\": [
+            {
+                <option information>,
+                \"metadata\": {
+                    \"server-tag\": <server tag>
+                }
+            }
+        ]
+    }
+}",
+    "resp-comment": "The metadata is included and it provides database specific information associated with the returned object."
 }
diff --git a/doc/guide/api.xml b/doc/guide/api.xml
index aa1f98c956..44d433b651 100644
--- a/doc/guide/api.xml
+++ b/doc/guide/api.xml
@@ -205,6 +205,7 @@
 , <command><link linkend="ref-remote-option-def4-get-all">remote-option-def4-get-all</link></command>
 , <command><link linkend="ref-remote-option-def4-set">remote-option-def4-set</link></command>
 , <command><link linkend="ref-remote-option4-global-del">remote-option4-global-del</link></command>
+, <command><link linkend="ref-remote-option4-global-get">remote-option4-global-get</link></command>
 , <command><link linkend="ref-remote-option4-global-get-all">remote-option4-global-get-all</link></command>
 , <command><link linkend="ref-remote-option4-global-set">remote-option4-global-set</link></command>
 , <command><link linkend="ref-remote-subnet4-del-by-id">remote-subnet4-del-by-id</link></command>
@@ -305,7 +306,6 @@
 , <command><link linkend="ref-remote-option-def6-get">remote-option-def6-get</link></command>
 , <command><link linkend="ref-remote-option-def6-get-all">remote-option-def6-get-all</link></command>
 , <command><link linkend="ref-remote-option-def6-set">remote-option-def6-set</link></command>
-, <command><link linkend="ref-remote-option4-global-get">remote-option4-global-get</link></command>
 , <command><link linkend="ref-remote-option6-global-del">remote-option6-global-del</link></command>
 , <command><link linkend="ref-remote-option6-global-get">remote-option6-global-get</link></command>
 , <command><link linkend="ref-remote-option6-global-get-all">remote-option6-global-get-all</link></command>
@@ -330,6 +330,7 @@
 , <command><link linkend="ref-remote-option-def4-get-all">remote-option-def4-get-all</link></command>
 , <command><link linkend="ref-remote-option-def4-set">remote-option-def4-set</link></command>
 , <command><link linkend="ref-remote-option4-global-del">remote-option4-global-del</link></command>
+, <command><link linkend="ref-remote-option4-global-get">remote-option4-global-get</link></command>
 , <command><link linkend="ref-remote-option4-global-get-all">remote-option4-global-get-all</link></command>
 , <command><link linkend="ref-remote-option4-global-set">remote-option4-global-set</link></command>
 , <command><link linkend="ref-remote-subnet4-del-by-id">remote-subnet4-del-by-id</link></command>
@@ -416,7 +417,6 @@
 , <command><link linkend="ref-remote-option-def6-get">remote-option-def6-get</link></command>
 , <command><link linkend="ref-remote-option-def6-get-all">remote-option-def6-get-all</link></command>
 , <command><link linkend="ref-remote-option-def6-set">remote-option-def6-set</link></command>
-, <command><link linkend="ref-remote-option4-global-get">remote-option4-global-get</link></command>
 , <command><link linkend="ref-remote-option6-global-del">remote-option6-global-del</link></command>
 , <command><link linkend="ref-remote-option6-global-get">remote-option6-global-get</link></command>
 , <command><link linkend="ref-remote-option6-global-get-all">remote-option6-global-get-all</link></command>
@@ -3177,8 +3177,7 @@ Result is an integer representation of the status. Currently supported statuses
 
 <para>Command syntax:
   <screen>{
-    "command": "remote-option-def4-get"
-    "service": [ "dhcp4" ],
+    "command": "remote-option-def4-get",
     "arguments": {
         "option-defs": [ {
             "code": &lt;option code&gt;,
@@ -3438,21 +3437,46 @@ Result is an integer representation of the status. Currently supported statuses
 <!-- start of remote-option4-global-get -->
 <section xml:id="reference-remote-option4-global-get">
 <title>remote-option4-global-get reference</title>
-<para xml:id="ref-remote-option4-global-get"><command>remote-option4-global-get</command> - a sentence or two explaining what this command does</para>
+<para xml:id="ref-remote-option4-global-get"><command>remote-option4-global-get</command> - This command is used to fetch a global DHCPv4 option for the server from the specified database.</para>
 
-<para>Supported by: <command><link linkend="commands-undocumented">undocumented</link></command></para>
+<para>Supported by: <command><link linkend="commands-kea-dhcp4">kea-dhcp4</link></command></para>
 
-<para>Availability: 0.0.0 (<link linkend="commands-undocumented-lib">undocumented</link>  hook)</para>
+<para>Availability: 1.6.0 (<link linkend="commands-cb_cmds-lib">cb_cmds</link>  hook)</para>
 
 <para>Description and examples: See <xref linkend="command-remote-option4-global-get"/></para>
 
 <para>Command syntax:
-  <screen>Syntax of the command</screen>
-Possibly some extra comments after the syntax.</para>
+  <screen>{
+    "command": "remote-option4-global-get",
+    "arguments": {
+        "options": [
+            {
+                "code": &lt;option code&gt;,
+                "space": &lt;option space&gt;
+            }
+        ],
+        "remote": {
+            &lt;specification of the database to connect to&gt;
+        }
+}</screen>
+The option is identified by the pair of option code/space values. The <command>remote</command> map contains specification of the backend from which the option should be fetched. Typically it contains "type": "mysql".</para>
 
 <para>Response syntax:
-  <screen>Syntax of the response</screen>
-Optional extra comments after the resposne syntax.</para>
+  <screen>{
+    "result": 0,
+    "text": "DHCPv4 option &lt;option code&gt; in &lt;option space&gt; found.",
+    "arguments": {
+        "options": [
+            {
+                &lt;option information&gt;,
+                "metadata": {
+                    "server-tag": &lt;server tag&gt;
+                }
+            }
+        ]
+    }
+}</screen>
+The metadata is included and it provides database specific information associated with the returned object.</para>
 
 </section>
 <!-- end of remote-option4-global-get -->
diff --git a/doc/guide/hooks-cb-cmds.xml b/doc/guide/hooks-cb-cmds.xml
index 4b1f73311e..fad5c5cd04 100644
--- a/doc/guide/hooks-cb-cmds.xml
+++ b/doc/guide/hooks-cb-cmds.xml
@@ -318,7 +318,7 @@
 
         <section xml:id="command-remote-network4-set">
           <title>remote-network4-set</title>
-          <para>This command creates a new IPv4 shared network or updates an existing
+          <para>This command creates a new IPv4 shared network or replaces an existing
           shared network in the database. The structure of the shared network information
           is the same as in the Kea configuration file (see <xref linkend="shared-network4"/>),
           with the exception that the <command>subnet4</command> parameter is not allowed
@@ -372,6 +372,202 @@
           </note>
         </section>
 
+        <section xml:id="command-remote-option-def4-del">
+          <title>remote-option-def4-del</title>
+          <para>This command is used to delete DHCPv4 option definition from the
+          database. The option definition is identified by an option code and
+          option space. For example:
+          <screen>
+{
+    "command": "remote-option-def4-del",
+    "arguments": {
+        "option-defs": [ {
+            "code": 1,
+            "space": "isc"
+        } ],
+        "remote": {
+            "type": "mysql"
+        }
+    }
+}
+          </screen>
+             deletes the definition of the option having the code of 1 and
+             belonging to the option space "isc". The top level option space
+             where standard DHCPv4 options belong is called "dhcp4".
+          </para>
+        </section>
+
+        <section xml:id="command-remote-option-def4-get">
+          <title>remote-option-def4-get</title>
+          <para>This comamnd is used to fetch a specified DHCPv4 option
+          definition from the database. The option definition is identified
+          by option code and option space. The top level option space
+          where DHCPv4 standard options belong is called "dhcp4".
+          </para>
+          <para>The following command retrieves an option definition
+          having the code of 1 and belonging to option space "isc":
+          <screen>
+{
+    "command": "remote-option-def4-get"
+    "arguments": {
+        "option-defs": [ {
+            "code": 1,
+            "space": "isc"
+        } ],
+        "remote": {
+            "type": "mysql"
+        }
+    }
+}
+          </screen>
+          </para>
+        </section>
+
+        <section xml:id="command-remote-option-def4-get-all">
+          <title>remote-option-def4-get-all</title>
+          <para>This command is used to fetch all DHCPv4 option definitions
+          from the database. It takes no arguments except an optional
+          <command>remote</command> map.</para>
+        </section>
+
+        <section xml:id="command-remote-option-def4-set">
+          <title>remote-option-def4-set</title>
+          <para>This command creates a new DHCPv4 option definition or
+          replaces an existing option definition in the database. The structure
+          of the option definition information is the same as in the Kea
+          configuration file (see <xref linkend="dhcp4-custom-options"/>).
+          For example:
+          <screen>
+{
+    "command": "remote-option-def4-set",
+    "arguments": {
+        "option-defs": [
+            {
+                "name": "foo",
+                "code": 222,
+                "type": "uint32",
+                "array": false,
+                "record-types": "",
+                "space": "dhcp4",
+                "encapsulate": ""
+            }
+        ],
+        "remote": {
+            "type": "mysql"
+        }
+    }
+}
+          </screen>
+          </para>
+        </section>
+
+        <section xml:id="command-remote-option4-global-del">
+          <title>remote-option4-global-del</title>
+          <para>This command is used to delete global DHCPv4 option from the database.
+          The option is identified by an option code and option space. For example:
+          <screen>
+{
+    "command": "remote-option4-global-del",
+    "arguments": {
+        "options": [
+            {
+                "code": 5
+                "space": "dhcp4"
+            }
+        ],
+        "remote": {
+            "type": "mysql"
+        }
+    }
+}
+          </screen>
+          </para>
+          <para>
+            The "dhcp4" is the top level option space where the standard DHCPv4
+            options belong.
+          </para>
+        </section>
+
+        <section xml:id="command-remote-option4-global-get">
+          <title>remote-option4-global-get</title>
+          <para>This command is used to fetch a global DHCPv4 option from the
+          database. The option is identified by code and option space. The top
+          level option space where DHCPv4 standard options belong is called
+          "dhcp4".
+          </para>
+          <para>
+            The following command retrieves the "Domain Name" (code 5) option:
+{
+    "command": remote-option4-global-get",
+    "arguments": {
+        "options": [
+            {
+                "code": 5,
+                "space": "dhcp4"
+            }
+        ],
+        "remote": {
+            "type": "mysql"
+        }
+    }
+}
+          </para>
+        </section>
+
+        <section xml:id="command-remote-option4-global-get-all">
+          <title>remote-option4-global-get-all</title>
+          <para>This command is used to fetch all global DHCPv4 options from the
+          database. It takes no arguments except the optional <command>remote</command>
+          map.</para>
+        </section>
+
+        <section xml:id="command-remote-option4-global-set">
+          <title>remote-option4-global-set</title>
+          <para>This command creates a new global DHCPv4 option or replaces
+          an existing option in the database. The structure of the option
+          information is the same as in the Kea configuration file
+          (see <xref linkend="dhcp4-std-options"/>). For example:
+          <screen>
+{
+    "command": "remote-option4-global-set",
+    "arguments": {
+        "options": [
+            {
+                "name": "dns-servers",
+                "data": "2001:db8:1::1"
+            }
+        ],
+        "remote": {
+            "type": "mysql"
+        }
+    }
+}
+          </screen>
+          </para>
+          <para>
+            Note that specifying an option name rather than option code only works
+            reliably for the standard DHCP options. When specifying a value for the
+            user defined DHCP option, the option code should be specified instead of
+            the name. For example:
+            <screen>
+{
+    "command": "remote-option4-global-set",
+    "arguments": {
+        "options": [
+            {
+                "code": 1,
+                "space": "isc",
+                "data": "2001:db8:1::1"
+            }
+        ]
+    }
+
+}
+            </screen>
+          </para>
+        </section>
+
+
       </section>
 
       <section xml:id="cb-cmds6">