From: Tomek Mrugalski <tomasz@isc.org>
Date: Tue, 12 Jun 2018 22:51:57 +0000 (+0200)
Subject: [5422] reservation-{add,del,get} documented.
X-Git-Tag: 176-update-to-sysrepo-0-7-6-release_base~181
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=49bfad5bef6e99aa1aae49e4975aa5242d3c2553;p=thirdparty%2Fkea.git

[5422] reservation-{add,del,get} documented.
---

diff --git a/doc/api/reservation-add.json b/doc/api/reservation-add.json
new file mode 100644
index 0000000000..80a796e339
--- /dev/null
+++ b/doc/api/reservation-add.json
@@ -0,0 +1,53 @@
+{
+    "name": "reservation-add",
+    "brief": "adds a new host reservation. The reservation may include IPv4 address,
+        IPv6 addresses, IPv6 prefixes, various identifiers, a class
+        the client will be assigned to, DHCPv4 and DHCPv6 options and
+        more.",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "avail": "1.2.0, host_cmds library (premium)",
+    "description": "See <xref linkend=\"cmd-reservation-add\"/>",
+
+    "cmd-syntax": "{
+    \"command\": \"reservation-add\",
+    \"arguments\": {
+        \"reservation\": {
+            \"boot-file-name\": <string>,
+            \"comment\": <string>
+            \"client-id\": <string>,
+            \"circuit-id\": <string>,
+            \"duid\": <string>,
+            \"flex-id\": <string>,
+            \"ip-address\": <string (IPv4 address)>,
+            \"ip-addresses\": [ <comma separated strings> ],
+            \"hw-address\": <string>,
+            \"hostname\": <string>,
+            \"next-server\": <string (IPv4 address)>,
+            \"option-data-list\": [ <comma separated structures defining options> ],
+            \"prefixes\": [ <comma separated IPv6 prefixes> ],
+            \"reservation-client-classes\": [ <comma separated strings> ],
+            \"server-hostname\": <string>,
+            \"subnet-id\": <integer>,
+            \"user-context\": <any valid JSON>,
+        }
+    }
+}",
+    "cmd-comment": "Note the ip-address, client-id, next-server, server-hostname and
+boot-file-name are IPv4 specific. duid, ip-addresses and prefixes are
+IPv6 specific.",
+
+    "resp-syntax": "
+{
+    \"result\": <integer>,
+    \"text\": <string>
+}",
+    "resp-comment": "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>"
+}
+
diff --git a/doc/api/reservation-del.json b/doc/api/reservation-del.json
new file mode 100644
index 0000000000..1300fd28f1
--- /dev/null
+++ b/doc/api/reservation-del.json
@@ -0,0 +1,17 @@
+{
+    "name": "reservation-del",
+    "brief": "Deletes an existing host reservation.",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "avail": "1.2.0, host_cmds library (premium)",
+
+    "cmd-syntax": "{
+    \"command\": \"reservation-del\",
+    \"arguments\": {
+        \"subnet-id\": <integer>,
+        \"ip-address\": <string>,
+        \"identifier-type\": <one of \"hw-address\", \"duid\", \"circuit-id\", \"client-id\" and \"flex-id\">,
+        \"identifier\": <string>
+    }
+}",
+    "cmd-comment": "The host reservation can be identified by either (subnet-id, ip-address) pair or a triplet of (subnet-id, identifier-type, identifier)."
+}
diff --git a/doc/api/reservation-get.json b/doc/api/reservation-get.json
new file mode 100644
index 0000000000..78befb5674
--- /dev/null
+++ b/doc/api/reservation-get.json
@@ -0,0 +1,44 @@
+{
+    "name": "reservation-get",
+    "brief": "attempts to retrieve an existing host reservation",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "avail": "1.2.0, host_cmds library (premium)",
+
+    "cmd-syntax": "{
+    \"command\": \"reservation-get\",
+    \"arguments\": {
+        \"subnet-id\": <integer>,
+        \"identifier-type\": <string with one value out of: hw-address|duid|circuit-id|client-id|flex-id>,
+        \"identifier\": <string>;
+    }
+}",
+
+    "cmd-comment": "The host reservation can be identified by either (subnet-id, ip-address) pair or a triplet of (subnet-id, identifier-type, identifier).",
+
+    "resp-syntax": "{
+    \"result\": <integer>,
+    \"text\": <string>,
+    \"arguments\": {
+        \"boot-file-name\": <string>,
+        \"comment\": <string>
+        \"client-id\": <string>,
+        \"circuit-id\": <string>,
+        \"duid\": <string>,
+        \"flex-id\": <string>,
+        \"ip-address\": <string (IPv4 address)>,
+        \"ip-addresses\": [ <comma separated strings> ],
+        \"hw-address\": <string>,
+        \"hostname\": <string>,
+        \"next-server\": <string (IPv4 address)>,
+        \"option-data-list\": [ <comma separated structures defining options> ],
+        \"prefixes\": [ <comma separated IPv6 prefixes> ],
+        \"reservation-client-classes\": [ <comma separated strings> ],
+        \"server-hostname\": <string>,
+        \"subnet-id\": <integer>,
+        \"user-context\": <any valid JSON>,
+    }
+}",
+
+    "resp-comment": "Arguments object appear only if a host is found. Many fields in the arguments
+object appear only if specific field is set."
+}
diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml
index 3d48fd9ecc..34f0c28dc7 100644
--- a/doc/guide/hooks.xml
+++ b/doc/guide/hooks.xml
@@ -1432,7 +1432,7 @@ Requirements </link> document.</para>
         </para>
         </section>
 
-        <section>
+        <section xml:id="cmd-reservation-add">
           <title>reservation-add command</title>
         <para>
           <command>reservation-add</command> allows for the insertion of a new host.  It
@@ -1524,7 +1524,7 @@ Here is an example of complex IPv6 reservation:
         </para>
         </section>
 
-        <section>
+        <section xml:id="cmd-reservation-get">
           <title>reservation-get command</title>
           <para><command>reservation-get</command> can be used to query the host
           database and retrieve existing reservations. There are two types of
@@ -1560,7 +1560,7 @@ An example query by (subnet-id, identifier-type, identifier) looks as follows:
 <screen>
 {
     "command": "reservation-get",
-    "arguments":
+    "arguments": {
         "subnet-id": 4,
         "identifier-type": "hw-address",
         "identifier": "01:02:03:04:05:06"
@@ -1602,7 +1602,7 @@ An example result returned when the query was malformed:<screen>
 
         </section>
 
-        <section>
+        <section xml:id="cmd-reservation-del">
           <title>reservation-del command</title>
           <para><command>reservation-del</command> can be used to delete a
           reservation from the host database. There are two types of parameters
@@ -2568,4 +2568,4 @@ both the command and the response.
         of server id which is DHCPv6 only.
       </para>
     </section>
-   </chapter>
+</chapter>