From: Francis Dupont <fdupont@isc.org>
Date: Wed, 15 May 2019 16:34:42 +0000 (+0200)
Subject: [594-new-host-cache-commands] Added cache-get-by-id and cache-size docs
X-Git-Tag: Kea-1.6.0-beta~111
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3753008cc77f71457b5d777560d8e36dc56e7acd;p=thirdparty%2Fkea.git

[594-new-host-cache-commands] Added cache-get-by-id and cache-size docs
---

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4a10675091..18aaeaf90d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -83,8 +83,9 @@ nobase_dist_doc_DATA += examples/netconf/simple-dhcp6.json
 # want to document the API.
 EXTRA_DIST += api/build-report.json
 EXTRA_DIST += api/cache-clear.json api/cache-get.json
-EXTRA_DIST += api/cache-insert.json api/cache-load.json
-EXTRA_DIST += api/cache-remove.json api/cache-write.json
+EXTRA_DIST += api/cache-get-by-id.json api/cache-insert.json
+EXTRA_DIST += api/cache-load.json api/cache-remove.json
+EXTRA_DIST += api/cache-size.json  api/cache-write.json
 EXTRA_DIST += api/class-add.json api/class-del.json
 EXTRA_DIST += api/class-get.json api/class-list.json
 EXTRA_DIST += api/class-update.json
diff --git a/doc/api/cache-get-by-id.json b/doc/api/cache-get-by-id.json
new file mode 100644
index 0000000000..ec7fd55826
--- /dev/null
+++ b/doc/api/cache-get-by-id.json
@@ -0,0 +1,17 @@
+{
+    "name": "cache-get-by-id",
+    "brief": "Returns entries matching the given identifier from  the host cache.",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "avail": "1.6.0",
+    "hook": "host_cache",
+    "cmd-syntax": "{
+    \"command\": \"cache-get-by-id\",
+    \"arguments\": {
+        \"hw-address\": \"01:02:03:04:05:06\"
+    }",
+    "resp-syntax": "{
+    \"result\": 0
+    \"text\": \"2 entries returned.\"
+    \"arguments\": <list of host reservations>
+}"
+}
diff --git a/doc/api/cache-size.json b/doc/api/cache-size.json
new file mode 100644
index 0000000000..d30f9daa38
--- /dev/null
+++ b/doc/api/cache-size.json
@@ -0,0 +1,13 @@
+{
+    "name": "cache-size",
+    "brief": "Returns number of entries of the host cache.",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "avail": "1.6.0",
+    "hook": "host_cache",
+
+    "resp-syntax": "{
+    \"result\": 0
+    \"text\": \"123 entries.\"
+    \"arguments\": { \"size\": 123 }
+}"
+}
diff --git a/doc/docgen/cmds-list b/doc/docgen/cmds-list
index 9aa4be6a80..55db2c753a 100644
--- a/doc/docgen/cmds-list
+++ b/doc/docgen/cmds-list
@@ -1,9 +1,11 @@
 build-report
 cache-clear
 cache-get
+cache-get-by-id
 cache-insert
 cache-load
 cache-remove
+cache-size
 cache-write
 class-add
 class-del
diff --git a/doc/guide/api.xml b/doc/guide/api.xml
index 489250204d..f030825b6b 100644
--- a/doc/guide/api.xml
+++ b/doc/guide/api.xml
@@ -13,9 +13,11 @@
 <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>
+, <command><link linkend="ref-cache-get-by-id">cache-get-by-id</link></command>
 , <command><link linkend="ref-cache-insert">cache-insert</link></command>
 , <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-size">cache-size</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>
@@ -109,9 +111,11 @@
 <para xml:id="commands-kea-dhcp4">Commands supported by kea-dhcp4 daemon: <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>
+, <command><link linkend="ref-cache-get-by-id">cache-get-by-id</link></command>
 , <command><link linkend="ref-cache-insert">cache-insert</link></command>
 , <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-size">cache-size</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>
@@ -167,9 +171,11 @@
 <para xml:id="commands-kea-dhcp6">Commands supported by kea-dhcp6 daemon: <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>
+, <command><link linkend="ref-cache-get-by-id">cache-get-by-id</link></command>
 , <command><link linkend="ref-cache-insert">cache-insert</link></command>
 , <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-size">cache-size</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>
@@ -235,9 +241,11 @@
 .</para>
 <para xml:id="commands-host_cache-lib">Commands supported by host_cache hook library: <command><link linkend="ref-cache-clear">cache-clear</link></command>
 , <command><link linkend="ref-cache-get">cache-get</link></command>
+, <command><link linkend="ref-cache-get-by-id">cache-get-by-id</link></command>
 , <command><link linkend="ref-cache-insert">cache-insert</link></command>
 , <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-size">cache-size</link></command>
 , <command><link linkend="ref-cache-write">cache-write</link></command>
 .</para>
 <para xml:id="commands-host_cmds-lib">Commands supported by host_cmds hook library: <command><link linkend="ref-reservation-add">reservation-add</link></command>
@@ -382,6 +390,44 @@ Result is an integer representation of the status. Currently supported statuses
 </section>
 <!-- end of cache-get -->
 
+<!-- start of cache-get-by-id -->
+<section xml:id="reference-cache-get-by-id">
+<title>cache-get-by-id reference</title>
+<para xml:id="ref-cache-get-by-id"><command>cache-get-by-id</command> - Returns entries matching the given identifier from the host cache.</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.6.0 (<link linkend="commands-host_cache-lib">host_cache</link>  hook)</para>
+
+<para>Description and examples: See <xref linkend="command-cache-get-by-id"/></para>
+
+<para>Command syntax:
+  <screen>{
+    "command": "cache-get-by-id",
+    "arguments": {
+        "hw-address": "01:02:03:04:05:06"
+    }
+}</screen>
+</para>
+
+<para>Response syntax:
+  <screen>{
+    "result": 0
+    "text": "2 entries returned."
+    "arguments": &lt;list of cashed host&gt;
+}</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 cache-get-by-id -->
+
 <!-- start of cache-insert -->
 <section xml:id="reference-cache-insert">
 <title>cache-insert reference</title>
@@ -535,6 +581,42 @@ Result is an integer representation of the status. Currently supported statuses
 </section>
 <!-- end of cache-remove -->
 
+<!-- start of cache-size -->
+<section xml:id="reference-cache-size">
+<title>cache-size reference</title>
+<para xml:id="ref-cache-size"><command>cache-size</command> - This command returns the number of cached host reservations.</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.6.0 (<link linkend="commands-host_cache-lib">host_cache</link>  hook)</para>
+
+<para>Description and examples: See <xref linkend="command-cache-size"/></para>
+
+<para>Command syntax:
+  <screen>{
+    "command": "cache-size"
+}</screen>
+</para>
+
+<para>Response syntax:
+  <screen>{
+    "result": 0,
+    "text": "123 entries.",
+    "arguments": { "size": 123 }
+}
+</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 cache-size -->
+
 <!-- start of cache-write -->
 <section xml:id="reference-cache-write">
 <title>cache-write reference</title>
@@ -1161,8 +1243,8 @@ Result is an integer representation of the status. Currently supported statuses
 <!-- start of ha-sync -->
 <section xml:id="reference-ha-sync">
 <title>ha-sync reference</title>
-<para xml:id="ref-ha-sync"><command>ha-sync</command> - The command is issued to instruct the server running in HA mode to 
-              synchronize its local lease database with the selected peer.</para>
+<para xml:id="ref-ha-sync"><command>ha-sync</command> - The command is issued to instruct the server running in HA mode to
+synchronize its local lease database with the selected peer.</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>
 
@@ -1459,7 +1541,7 @@ lease6-add can be also used to add leases for IPv6 prefixes..</para>
 
 <para>Response syntax:
   <screen>{ "result": 0,
-	    "text": "Lease added." }
+            "text": "Lease added." }
 
           { "result": 1,
             "text": "missing parameter 'ip-address' (&lt;string&gt;:3:19)" }</screen>
diff --git a/doc/guide/hooks-host-cache.xml b/doc/guide/hooks-host-cache.xml
index 7cf475675f..4790fafae3 100644
--- a/doc/guide/hooks-host-cache.xml
+++ b/doc/guide/hooks-host-cache.xml
@@ -45,7 +45,7 @@
       "parameters": {
 
           // Tells Kea to never cache more than 1000 hosts.
-          "maximum: "1000"
+          "maximum": 1000
 
       }
   } ]</screen>
@@ -89,6 +89,17 @@ certain number of cached hosts, please use cache-flush instead.
     </para>
   </section>
 
+  <section id="command-cache-size">
+    <title>cache-size Command</title>
+    <para>This command returns the number of host entries.
+    An example usage looks as follows:
+<screen>
+{
+    "command": "cache-size"
+}</screen>
+    </para>
+  </section>
+
   <section id="command-cache-write">
     <title>cache-write Command</title>
     <para>In general, the cache content is considered a runtime
@@ -157,6 +168,24 @@ may be large.
     </para>
   </section>
 
+  <section id="command-cache-get-by-id">
+    <title>cache-get-by-id Command</title>
+    <para>This command is similar to cache-get, but instead of
+    returning the whole content it returns only the entries matching
+    the given identifier.</para>
+    <para>It takes one parameter, which defines the identifier of
+    wanted cached host reservations. An example usage looks as follows:
+<screen>
+{
+    "command": "cache-get-by-id",
+    "arguments": {
+        "hw-address": "01:02:03:04:05:06"
+    }
+}</screen>
+This command will return all the cached hosts with the given hardware address.
+    </para>
+  </section>
+
   <section id="command-cache-insert">
     <title>cache-insert Command</title>
     <para>This command may be used to manually insert a host into the