From: Marcin Siodelski <marcin@isc.org>
Date: Tue, 30 Oct 2018 07:07:18 +0000 (+0100)
Subject: [64-client-class-cmds-hook] Documented class_cmds in API docs.
X-Git-Tag: 66-authoritative-flag-in-kea_base~22
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=879072603d09d2f2eb334e96b0e526c8706b6d0b;p=thirdparty%2Fkea.git

[64-client-class-cmds-hook] Documented class_cmds in API docs.
---

diff --git a/doc/api/class-add.json b/doc/api/class-add.json
new file mode 100644
index 0000000000..86fef27765
--- /dev/null
+++ b/doc/api/class-add.json
@@ -0,0 +1,23 @@
+{
+    "name": "class-add",
+    "brief": "This command is used to create and add a new class to the existing server configuration.",
+    "description": "See <xref linkend=\"command-class-add\"/>",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "avail": "1.5.0",
+    "hook": "class_cmds",
+    "cmd-syntax": "{
+    \"command\": \"class-add\",
+    \"arguments\": {
+        \"client-classes\": [ {
+           \"name\": \"ipxe_efi_x64\",
+           \"test\": \"option[93].hex == 0x0009\",
+            ...
+        } ]
+    }
+}",
+    "cmd-comment": "Only one client class can be added with a single command.",
+    "resp-syntax": "{
+    \"result\": 0,
+    \"text\": \"Class 'ipxe_efi_x64' added.\"
+}"
+}
diff --git a/doc/api/class-del.json b/doc/api/class-del.json
new file mode 100644
index 0000000000..35dc4003da
--- /dev/null
+++ b/doc/api/class-del.json
@@ -0,0 +1,18 @@
+{
+    "name": "class-del",
+    "brief": "This command is used to remove a client class from the server configuration.",
+    "description": "See <xref linkend=\"command-class-del\"/>",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "avail": "1.5.0",
+    "hook": "class_cmds",
+    "cmd-syntax": "{
+    \"command\": \"class-del\",
+    \"arguments\": {
+        \"name\": \"ipxe_efi_x64\",
+    }
+}",
+    "resp-syntax": "{
+    \"result\": 0,
+    \"text\": \"Class 'ipxe_efi_x64' deleted.\"
+}"
+}
diff --git a/doc/api/class-get.json b/doc/api/class-get.json
new file mode 100644
index 0000000000..f631a72327
--- /dev/null
+++ b/doc/api/class-get.json
@@ -0,0 +1,39 @@
+{
+    "name": "class-get",
+    "brief": "This command is used to return detailed information about an existing client class.",
+    "description": "See <xref linkend=\"command-class-get\"/>",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "avail": "1.5.0",
+    "hook": "class_cmds",
+    "cmd-syntax": "{
+    \"command\": \"class-get\",
+    \"arguments\": {
+        \"name\": \"pxeclient\"
+    }
+}",
+    "resp-syntax": "{
+    \"result\": 0,
+    \"text\": \"Class 'pxeclient' definition returned\",
+    \"arguments\": {
+        \"client-classes\": [
+            {
+                \"name\": \"pxeclient\",
+                \"only-if-required\": true,
+                \"test\": \"option[vendor-class-identifier].text == 'PXEClient'\",
+                \"option-def\": [
+                    {
+                        \"name\": \"configfile\",
+                        \"code\": 209,
+                        \"type\": \"string\"
+                    }
+                ],
+                \"option-data\": [ ],
+                \"next-server\": \"0.0.0.0\",
+                \"server-hostname\": \"xfce\",
+                \"boot-file-name\": \"/dev/null\"
+            }
+        ]
+    }
+}",
+    "resp-comment": "The returned information depends on the DHCP server type, i.e. some parameters are specific to DHCPv4 server. Also, some parameters may not be returned if they are not set for the client class. If the class with specified name doesn't exist a result of 3 is returned."
+}
diff --git a/doc/api/class-list.json b/doc/api/class-list.json
new file mode 100644
index 0000000000..6d501be3a0
--- /dev/null
+++ b/doc/api/class-list.json
@@ -0,0 +1,27 @@
+{
+    "name": "class-list",
+    "brief": "This command is used to retrieve a list of all client classes from the server configuration.",
+    "description": "See <xref linkend=\"command-class-list\"/>",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "avail": "1.5.0",
+    "hook": "class_cmds",
+    "cmd-syntax": "{
+    \"command\": \"class-list\"
+}",
+    "cmd-comment": "This command includes no arguments.",
+    "resp-syntax": "{
+    \"result\": 0,
+    \"text\": \"2 classes found\",
+    \"arguments\": {
+        \"client-classes\": [
+            {
+                \"name\": \"ipxe_efi_x64\"
+            },
+            {
+                \"name\": \"pxeclient\"
+            }
+        ]
+    }
+}",
+    "resp-comment": "The returned list of classes merely contains their names. In order to retrieve full information about one of these classes use <xref linkend=\"command-class-get\"/>."
+}
diff --git a/doc/api/class-update.json b/doc/api/class-update.json
new file mode 100644
index 0000000000..c0ea96e989
--- /dev/null
+++ b/doc/api/class-update.json
@@ -0,0 +1,23 @@
+{
+    "name": "class-update",
+    "brief": "This command is used to update an existing client class in the server configuration.",
+    "description": "See <xref linkend=\"command-class-update\"/>",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "avail": "1.5.0",
+    "hook": "class_cmds",
+    "cmd-syntax": "{
+    \"command\": \"class-update\",
+    \"arguments\": {
+        \"client-classes\": [ {
+           \"name\": \"ipxe_efi_x64\",
+           \"test\": \"option[93].hex == 0x0009\",
+            ...
+        } ]
+    }
+}",
+    "cmd-comment": "Only one client class can be updated with a single command..",
+    "resp-syntax": "{
+    \"result\": 0,
+    \"text\": \"Class 'ipxe_efi_x64' updated.\"
+}"
+}
diff --git a/doc/docgen/cmds-list b/doc/docgen/cmds-list
index be78abba5f..64408e552b 100644
--- a/doc/docgen/cmds-list
+++ b/doc/docgen/cmds-list
@@ -5,6 +5,11 @@ cache-insert
 cache-load
 cache-remove
 cache-write
+class-add
+class-del
+class-get
+class-list
+class-update
 config-get
 config-reload
 config-set
diff --git a/doc/guide/api.xml b/doc/guide/api.xml
index 67b82676e7..d0e49f580c 100644
--- a/doc/guide/api.xml
+++ b/doc/guide/api.xml
@@ -9,7 +9,7 @@
 <!-- autogenerated using cmd_docgen. Do not edit by hand! -->
 <appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="api">
   <title>API Reference</title>
-  <para>Kea currently supports 66 commands:
+  <para>Kea currently supports 71 commands:
 <command><link linkend="ref-build-report">build-report</link></command>
 , <command><link linkend="ref-cache-clear">cache-clear</link></command>
 , <command><link linkend="ref-cache-get">cache-get</link></command>
@@ -17,6 +17,11 @@
 , <command><link linkend="ref-cache-load">cache-load</link></command>
 , <command><link linkend="ref-cache-remove">cache-remove</link></command>
 , <command><link linkend="ref-cache-write">cache-write</link></command>
+, <command><link linkend="ref-class-add">class-add</link></command>
+, <command><link linkend="ref-class-del">class-del</link></command>
+, <command><link linkend="ref-class-get">class-get</link></command>
+, <command><link linkend="ref-class-list">class-list</link></command>
+, <command><link linkend="ref-class-update">class-update</link></command>
 , <command><link linkend="ref-config-get">config-get</link></command>
 , <command><link linkend="ref-config-reload">config-reload</link></command>
 , <command><link linkend="ref-config-set">config-set</link></command>
@@ -92,6 +97,11 @@
 , <command><link linkend="ref-cache-load">cache-load</link></command>
 , <command><link linkend="ref-cache-remove">cache-remove</link></command>
 , <command><link linkend="ref-cache-write">cache-write</link></command>
+, <command><link linkend="ref-class-add">class-add</link></command>
+, <command><link linkend="ref-class-del">class-del</link></command>
+, <command><link linkend="ref-class-get">class-get</link></command>
+, <command><link linkend="ref-class-list">class-list</link></command>
+, <command><link linkend="ref-class-update">class-update</link></command>
 , <command><link linkend="ref-config-get">config-get</link></command>
 , <command><link linkend="ref-config-reload">config-reload</link></command>
 , <command><link linkend="ref-config-set">config-set</link></command>
@@ -142,6 +152,11 @@
 , <command><link linkend="ref-cache-load">cache-load</link></command>
 , <command><link linkend="ref-cache-remove">cache-remove</link></command>
 , <command><link linkend="ref-cache-write">cache-write</link></command>
+, <command><link linkend="ref-class-add">class-add</link></command>
+, <command><link linkend="ref-class-del">class-del</link></command>
+, <command><link linkend="ref-class-get">class-get</link></command>
+, <command><link linkend="ref-class-list">class-list</link></command>
+, <command><link linkend="ref-class-update">class-update</link></command>
 , <command><link linkend="ref-config-get">config-get</link></command>
 , <command><link linkend="ref-config-reload">config-reload</link></command>
 , <command><link linkend="ref-config-set">config-set</link></command>
@@ -185,6 +200,12 @@
 , <command><link linkend="ref-subnet6-list">subnet6-list</link></command>
 , <command><link linkend="ref-version-get">version-get</link></command>
 .</para>
+<para xml:id="commands-class_cmds-lib">Commands supported by class_cmds hook library: <command><link linkend="ref-class-add">class-add</link></command>
+, <command><link linkend="ref-class-del">class-del</link></command>
+, <command><link linkend="ref-class-get">class-get</link></command>
+, <command><link linkend="ref-class-list">class-list</link></command>
+, <command><link linkend="ref-class-update">class-update</link></command>
+.</para>
 <para xml:id="commands-high_availability-lib">Commands supported by high_availability hook library: <command><link linkend="ref-ha-continue">ha-continue</link></command>
 , <command><link linkend="ref-ha-heartbeat">ha-heartbeat</link></command>
 , <command><link linkend="ref-ha-scopes">ha-scopes</link></command>
@@ -524,6 +545,212 @@ Result is an integer representation of the status. Currently supported statuses
 </section>
 <!-- end of cache-write -->
 
+<!-- start of class-add -->
+<section xml:id="reference-class-add">
+<title>class-add reference</title>
+<para xml:id="ref-class-add"><command>class-add</command> - This command is used to create and add a new class to the existing server configuration.</para>
+
+<para>Supported by: <command><link linkend="commands-kea-dhcp4">kea-dhcp4</link></command>, <command><link linkend="commands-kea-dhcp6">kea-dhcp6</link></command></para>
+
+<para>Availability: 1.5.0 (<link linkend="commands-class_cmds-lib">class_cmds</link>  hook)</para>
+
+<para>Description and examples: See <xref linkend="command-class-add"/></para>
+
+<para>Command syntax:
+  <screen>{
+    "command": "class-add",
+    "arguments": {
+        "client-classes": [ {
+           "name": "ipxe_efi_x64",
+           "test": "option[93].hex == 0x0009",
+            ...
+        } ]
+    }
+}</screen>
+Only one client class can be added with a single command.</para>
+
+<para>Response syntax:
+  <screen>{
+    "result": 0,
+    "text": "Class 'ipxe_efi_x64' added."
+}</screen>
+Result is an integer representation of the status. Currently supported statuses are:
+<itemizedlist>
+  <listitem><para>0 - success</para></listitem>
+  <listitem><para>1 - error</para></listitem>
+  <listitem><para>2 - unsupported</para></listitem>
+  <listitem><para>3 - empty (command was completed successfully, but no data was affected or returned)</para></listitem>
+</itemizedlist>
+</para>
+
+</section>
+<!-- end of class-add -->
+
+<!-- start of class-del -->
+<section xml:id="reference-class-del">
+<title>class-del reference</title>
+<para xml:id="ref-class-del"><command>class-del</command> - This command is used to remove a client class from the server configuration.</para>
+
+<para>Supported by: <command><link linkend="commands-kea-dhcp4">kea-dhcp4</link></command>, <command><link linkend="commands-kea-dhcp6">kea-dhcp6</link></command></para>
+
+<para>Availability: 1.5.0 (<link linkend="commands-class_cmds-lib">class_cmds</link>  hook)</para>
+
+<para>Description and examples: See <xref linkend="command-class-del"/></para>
+
+<para>Command syntax:
+  <screen>{
+    "command": "class-del",
+    "arguments": {
+        "name": "ipxe_efi_x64",
+    }
+}</screen>
+</para>
+
+<para>Response syntax:
+  <screen>{
+    "result": 0,
+    "text": "Class 'ipxe_efi_x64' deleted."
+}</screen>
+Result is an integer representation of the status. Currently supported statuses are:
+<itemizedlist>
+  <listitem><para>0 - success</para></listitem>
+  <listitem><para>1 - error</para></listitem>
+  <listitem><para>2 - unsupported</para></listitem>
+  <listitem><para>3 - empty (command was completed successfully, but no data was affected or returned)</para></listitem>
+</itemizedlist>
+</para>
+
+</section>
+<!-- end of class-del -->
+
+<!-- start of class-get -->
+<section xml:id="reference-class-get">
+<title>class-get reference</title>
+<para xml:id="ref-class-get"><command>class-get</command> - This command is used to return detailed information about an existing client class.</para>
+
+<para>Supported by: <command><link linkend="commands-kea-dhcp4">kea-dhcp4</link></command>, <command><link linkend="commands-kea-dhcp6">kea-dhcp6</link></command></para>
+
+<para>Availability: 1.5.0 (<link linkend="commands-class_cmds-lib">class_cmds</link>  hook)</para>
+
+<para>Description and examples: See <xref linkend="command-class-get"/></para>
+
+<para>Command syntax:
+  <screen>{
+    "command": "class-get",
+    "arguments": {
+        "name": "pxeclient"
+    }
+}</screen>
+</para>
+
+<para>Response syntax:
+  <screen>{
+    "result": 0,
+    "text": "Class 'pxeclient' definition returned",
+    "arguments": {
+        "client-classes": [
+            {
+                "name": "pxeclient",
+                "only-if-required": true,
+                "test": "option[vendor-class-identifier].text == 'PXEClient'",
+                "option-def": [
+                    {
+                        "name": "configfile",
+                        "code": 209,
+                        "type": "string"
+                    }
+                ],
+                "option-data": [ ],
+                "next-server": "0.0.0.0",
+                "server-hostname": "xfce",
+                "boot-file-name": "/dev/null"
+            }
+        ]
+    }
+}</screen>
+The returned information depends on the DHCP server type, i.e. some parameters are specific to DHCPv4 server. Also, some parameters may not be returned if they are not set for the client class. If the class with specified name doesn't exist a result of 3 is returned.</para>
+
+</section>
+<!-- end of class-get -->
+
+<!-- start of class-list -->
+<section xml:id="reference-class-list">
+<title>class-list reference</title>
+<para xml:id="ref-class-list"><command>class-list</command> - This command is used to retrieve a list of all client classes from the server configuration.</para>
+
+<para>Supported by: <command><link linkend="commands-kea-dhcp4">kea-dhcp4</link></command>, <command><link linkend="commands-kea-dhcp6">kea-dhcp6</link></command></para>
+
+<para>Availability: 1.5.0 (<link linkend="commands-class_cmds-lib">class_cmds</link>  hook)</para>
+
+<para>Description and examples: See <xref linkend="command-class-list"/></para>
+
+<para>Command syntax:
+  <screen>{
+    "command": "class-list"
+}</screen>
+This command includes no arguments.</para>
+
+<para>Response syntax:
+  <screen>{
+    "result": 0,
+    "text": "2 classes found",
+    "arguments": {
+        "client-classes": [
+            {
+                "name": "ipxe_efi_x64"
+            },
+            {
+                "name": "pxeclient"
+            }
+        ]
+    }
+}</screen>
+The returned list of classes merely contains their names. In order to retrieve full information about one of these classes use <xref linkend="command-class-get"/>.</para>
+
+</section>
+<!-- end of class-list -->
+
+<!-- start of class-update -->
+<section xml:id="reference-class-update">
+<title>class-update reference</title>
+<para xml:id="ref-class-update"><command>class-update</command> - This command is used to update an existing client class in the server configuration.</para>
+
+<para>Supported by: <command><link linkend="commands-kea-dhcp4">kea-dhcp4</link></command>, <command><link linkend="commands-kea-dhcp6">kea-dhcp6</link></command></para>
+
+<para>Availability: 1.5.0 (<link linkend="commands-class_cmds-lib">class_cmds</link>  hook)</para>
+
+<para>Description and examples: See <xref linkend="command-class-update"/></para>
+
+<para>Command syntax:
+  <screen>{
+    "command": "class-update",
+    "arguments": {
+        "client-classes": [ {
+           "name": "ipxe_efi_x64",
+           "test": "option[93].hex == 0x0009",
+            ...
+        } ]
+    }
+}</screen>
+Only one client class can be updated with a single command..</para>
+
+<para>Response syntax:
+  <screen>{
+    "result": 0,
+    "text": "Class 'ipxe_efi_x64' updated."
+}</screen>
+Result is an integer representation of the status. Currently supported statuses are:
+<itemizedlist>
+  <listitem><para>0 - success</para></listitem>
+  <listitem><para>1 - error</para></listitem>
+  <listitem><para>2 - unsupported</para></listitem>
+  <listitem><para>3 - empty (command was completed successfully, but no data was affected or returned)</para></listitem>
+</itemizedlist>
+</para>
+
+</section>
+<!-- end of class-update -->
+
 <!-- start of config-get -->
 <section xml:id="reference-config-get">
 <title>config-get reference</title>
diff --git a/doc/guide/hooks-class-cmds.xml b/doc/guide/hooks-class-cmds.xml
index 7201621ac2..2792eb6aab 100644
--- a/doc/guide/hooks-class-cmds.xml
+++ b/doc/guide/hooks-class-cmds.xml
@@ -25,7 +25,7 @@
         customers only</para>
       </para>
 
-      <section>
+      <section xml:id="command-class-add">
         <title>class-add command</title>
         <para>The <command>class-add</command> command is used to add a new client
         class to the DHCP server configuration. This class is appended at the
@@ -69,7 +69,7 @@
         </para>
       </section>
 
-      <section>
+      <section xml:id="command-class-update">
         <title>class-update command</title>
         <para>
           The <command>class-update</command> command is used to update an existing
@@ -120,7 +120,7 @@
         </para>
       </section>
 
-      <section>
+      <section xml:id="command-class-del">
         <title>class-del command</title>
         <para>The <command>class-del</command> is used to remove a particular class
         from the server configuration. The class to be removed is identified by name.
@@ -151,7 +151,7 @@
         <para>If the class doesn't exist, the result of 3 is returned.</para>
       </section>
 
-      <section>
+      <section xml:id="command-class-list">
         <title>class-list command</title>
         <para>The <command>class-list</command> is used to retrieve a list of all
         client classes. This command includes no arguments:
@@ -188,7 +188,7 @@
         </para>
       </section>
 
-      <section>
+      <section xml:id="command-class-get">
         <title>class-get command</title>
         <para>The <command>class-get</command> is used to retrieve detail information
         about specified class. The command structure is very simple: