From: Marcin Siodelski <marcin@isc.org>
Date: Mon, 15 Jul 2019 17:58:01 +0000 (+0200)
Subject: [#643,!421] Updated API docs for subnets management with tags.
X-Git-Tag: Kea-1.6.0-beta2~26
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0e1abe3bf62314216c6c4a441f7598482521ae32;p=thirdparty%2Fkea.git

[#643,!421] Updated API docs for subnets management with tags.
---

diff --git a/doc/api/remote-subnet4-del-by-id.json b/doc/api/remote-subnet4-del-by-id.json
index 15c0985f83..a28baadd31 100644
--- a/doc/api/remote-subnet4-del-by-id.json
+++ b/doc/api/remote-subnet4-del-by-id.json
@@ -17,7 +17,7 @@
         }
     }
 }",
-    "cmd-comment": "This command includes a list with exactly one id of the subnet to be deleted.",
+    "cmd-comment": "This command includes a list with exactly one id of the subnet to be deleted. The <command>server-tags</command> parameter must not be specified for this command.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"1 IPv4 subnet(s) deleted.\",
diff --git a/doc/api/remote-subnet4-del-by-prefix.json b/doc/api/remote-subnet4-del-by-prefix.json
index 9ba462c1c2..16fe581333 100644
--- a/doc/api/remote-subnet4-del-by-prefix.json
+++ b/doc/api/remote-subnet4-del-by-prefix.json
@@ -17,7 +17,7 @@
         }
     }
 }",
-    "cmd-comment": "This command includes a list with exactly one prefix of the subnet to be deleted.",
+    "cmd-comment": "This command includes a list with exactly one prefix of the subnet to be deleted. The <command>server-tags</command> parameter must not be specified for this command.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"1 IPv4 subnet(s) deleted.\",
diff --git a/doc/api/remote-subnet4-get-by-id.json b/doc/api/remote-subnet4-get-by-id.json
index 4fbe9d0b24..aedc0d591b 100644
--- a/doc/api/remote-subnet4-get-by-id.json
+++ b/doc/api/remote-subnet4-get-by-id.json
@@ -15,7 +15,7 @@
         }
     }
 }",
-    "cmd-comment": "This command includes a list with exactly one id of the subnet to be returned.",
+    "cmd-comment": "This command includes a list with exactly one id of the subnet to be returned. The <command>server-tags</command> parameter must not be specified for this command.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"IPv4 subnet found.\",
@@ -25,7 +25,7 @@
             \"subnet\": <subnet prefix>,
             \"shared-network-name\": <shared network name> | null,
             \"metadata\": {
-                \"server-tag\": <server tag>
+                \"server-tags\": [ <first server tag>, <second server tag>, ... ]
             },
             <the rest of the subnet specification here>
         } ],
diff --git a/doc/api/remote-subnet4-get-by-prefix.json b/doc/api/remote-subnet4-get-by-prefix.json
index 2790245346..bcf74f3b88 100644
--- a/doc/api/remote-subnet4-get-by-prefix.json
+++ b/doc/api/remote-subnet4-get-by-prefix.json
@@ -15,7 +15,7 @@
         }
     }
 }",
-    "cmd-comment": "This command includes a list with exactly one prefix of the subnet to be returned.",
+    "cmd-comment": "This command includes a list with exactly one prefix of the subnet to be returned. The <command>server-tags</command> parameter must not be specified for this command.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"IPv4 subnet found.\",
@@ -26,7 +26,7 @@
                 \"subnet\": <subnet prefix>,
                 \"shared-network-name\": <shared network name> | null,
                 \"metadata\": {
-                    \"server-tag\": <server tag>
+                    \"server-tags\": [ <first server tag>, <second server tag>, ... ]
                 },
                 <the rest of the subnet specification here>
             }
diff --git a/doc/api/remote-subnet4-list.json b/doc/api/remote-subnet4-list.json
index 92ea88e7f0..2cd4bac102 100644
--- a/doc/api/remote-subnet4-list.json
+++ b/doc/api/remote-subnet4-list.json
@@ -9,10 +9,11 @@
     \"arguments\": {
         \"remote\": {
             <specification of the database to connect to>
-        }
+        },
+        \"server-tags\": [ <first server tag>, <second server tag>, ... ]
     }
 }",
-    "cmd-comment": "This command includes no arguments besides the optional <command>remote</command> map.",
+    "cmd-comment": "The <command>server-tags</command> list is required for this command. This list must not be empty. It may either contain one or multiple server tags as strings or a single <command>null</command> value.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"2 IPv4 subnets found.\",
@@ -23,7 +24,7 @@
                 \"subnet\": <first subnet prefix>,
                 \"shared-network-name\": <shared network name> | null,
                 \"metadata\": {
-                    \"server-tag\": <server tag>
+                    \"server-tags\": [ <first server tag>, <second server tag>, ... ]
                 }
             },
             {
@@ -31,12 +32,12 @@
                 \"subnet\": <second subnet prefix>,
                 \"shared-network-name\": <shared network name> | null,
                 \"metadata\": {
-                    \"server-tag\": <server tag>
+                    \"server-tags\": [ <first server tag>, ... ]
                 }
             }
         ],
         \"count\": 2
     }
 }",
-    "resp-comment": "The returned response contains a list of maps. Each map contains a subnet identifier, prefix and shared network name to which the subnet belongs. If the subnet does not belong to a shared netork the name is null. The metadata includes database specific information associated with the subnets. The returned list does not contain full subnet definitions. Use <command>remote-subnet4-get</command> to fetch the full information about the selected subnets."
+    "resp-comment": "The returned response contains a list of maps. Each map contains a subnet identifier, prefix and shared network name to which the subnet belongs. If the subnet does not belong to a shared netork the name is null. The metadata includes database specific information associated with the subnets. The returned list does not contain full subnet definitions. Use <command>remote-subnet4-get</command> to fetch the full information about the selected subnets. If the command includes explicit server tags as strings (including the special server tag \"all\"), the list contains all subnets which are associated with any of the specified tags. A subnet is returned even if it is associated with multiple servers and only one of the specified tags matches. If the command includes the <command>null</command> value in the <command>server-tags</command> list, the response contains all subnets which are assigned to no servers (unassigned)."
 }
diff --git a/doc/api/remote-subnet4-set.json b/doc/api/remote-subnet4-set.json
index b4b409ce77..072f74f32c 100644
--- a/doc/api/remote-subnet4-set.json
+++ b/doc/api/remote-subnet4-set.json
@@ -17,10 +17,11 @@
         ],
         \"remote\": {
             <specification of the database to connect to>
-        }
+        },
+        \"server-tags\": [ <first server tag>, <second server tag>, ... ]
     }
 }",
-    "cmd-comment": "The provided list must contain exactly one subnet specification. The <command>shared-network-name</command> parameter is required for these commands. It associates the subnet with the shared network by its name. If the subnet must not belong to any shared network (global subnet), the <command>null</command> value must be specified for the shared network name.",
+    "cmd-comment": "The provided list must contain exactly one subnet specification. The <command>shared-network-name</command> parameter is required for these commands. It associates the subnet with the shared network by its name. If the subnet must not belong to any shared network (global subnet), the <command>null</command> value must be specified for the shared network name. The <command>server-tags</command> list is mandatory and it must contain one or more server tags as strings to explicitly associate the subnet with one or more user defined servers. It may include the special server tag \"all\" to associate the subnet with all servers.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"IPv4 subnet successfully set.\",
diff --git a/doc/api/remote-subnet6-del-by-id.json b/doc/api/remote-subnet6-del-by-id.json
index 194552b66f..7f9e487217 100644
--- a/doc/api/remote-subnet6-del-by-id.json
+++ b/doc/api/remote-subnet6-del-by-id.json
@@ -17,7 +17,7 @@
         }
     }
 }",
-    "cmd-comment": "This command includes a list with exactly one id of the subnet to be deleted.",
+    "cmd-comment": "This command includes a list with exactly one id of the subnet to be deleted. The <command>server-tags</command> parameter must not be specified for this command.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"1 IPv6 subnet(s) deleted.\",
diff --git a/doc/api/remote-subnet6-del-by-prefix.json b/doc/api/remote-subnet6-del-by-prefix.json
index 0909b7bbfe..fbad1cf7f4 100644
--- a/doc/api/remote-subnet6-del-by-prefix.json
+++ b/doc/api/remote-subnet6-del-by-prefix.json
@@ -17,7 +17,7 @@
         }
     }
 }",
-    "cmd-comment": "This command includes a list with exactly one prefix of the subnet to be deleted.",
+    "cmd-comment": "This command includes a list with exactly one prefix of the subnet to be deleted. The <command>server-tags</command> parameter must not be specified for this command.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"1 IPv6 subnet(s) deleted.\",
diff --git a/doc/api/remote-subnet6-get-by-id.json b/doc/api/remote-subnet6-get-by-id.json
index b260eec7fc..1e439d1317 100644
--- a/doc/api/remote-subnet6-get-by-id.json
+++ b/doc/api/remote-subnet6-get-by-id.json
@@ -17,7 +17,7 @@
         }
     }
 }",
-    "cmd-comment": "This command includes a list with exactly one id of the subnet to be returned.",
+    "cmd-comment": "This command includes a list with exactly one id of the subnet to be returned. The <command>server-tags</command> parameter must not be specified for this command.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"IPv6 subnet found.\",
@@ -28,7 +28,7 @@
                 \"subnet\": <subnet prefix>,
                 \"shared-network-name\": <shared network name> | null,
                 \"metadata\": {
-                    \"server-tag\": <server tag>
+                    \"server-tags\": [ <first server tag>, <second server tag>, ... ]
                 },
                 <the rest of the subnet specification here>
             }
diff --git a/doc/api/remote-subnet6-get-by-prefix.json b/doc/api/remote-subnet6-get-by-prefix.json
index 86dbfcb3fe..e4f7eb18e2 100644
--- a/doc/api/remote-subnet6-get-by-prefix.json
+++ b/doc/api/remote-subnet6-get-by-prefix.json
@@ -17,7 +17,7 @@
         }
     }
 }",
-    "cmd-comment": "This command includes a list with exactly one prefix of the subnet to be returned.",
+    "cmd-comment": "This command includes a list with exactly one prefix of the subnet to be returned. The <command>server-tags</command> parameter must not be specified for this command.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"IPv6 subnet found.\",
@@ -27,7 +27,7 @@
             \"subnet\": <subnet prefix>,
             \"shared-network-name\": <shared network name> | null,
             \"metadata\": {
-                \"server-tag\": <server tag>
+                \"server-tags\": [ <first server tag>, <second server tag>, ... ]
             },
             <the rest of the subnet specification here>
         } ],
diff --git a/doc/api/remote-subnet6-list.json b/doc/api/remote-subnet6-list.json
index ea27951298..c68cb48d49 100644
--- a/doc/api/remote-subnet6-list.json
+++ b/doc/api/remote-subnet6-list.json
@@ -9,10 +9,11 @@
     \"arguments\": {
         \"remote\": {
             <specification of the database to connect to>
-        }
+        },
+        \"server-tags\": [ <first server tag>, <second server tag>, ... ]
     }
 }",
-    "cmd-comment": "This command includes no arguments besides the optional <command>remote</command> map.",
+    "cmd-comment": "The <command>server-tags</command> list is required for this command. This list must not be empty. It may either contain one or multiple server tags as strings or a single <command>null</command> value.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"2 IPv6 subnets found.\",
@@ -23,7 +24,7 @@
                 \"subnet\": <first subnet prefix>,
                 \"shared-network-name\": <shared network name> | null,
                 \"metadata\": {
-                    \"server-tag\": <server tag>
+                    \"server-tags\": [ <first server tag>, <second server tag>, ... ]
                 }
             },
             {
@@ -31,12 +32,12 @@
                 \"subnet\": <second subnet prefix>,
                 \"shared-network-name\": <shared network name> | null,
                 \"metadata\": {
-                    \"server-tag\": <server tag>
+                    \"server-tags\": [ <first server tag>, ... ]
                 }
             }
         ],
         \"count\": 2
     }
 }",
-    "resp-comment": "The returned response contains a list of maps. Each map contains a subnet identifier, prefix and shared network name to which the subnet belongs. If the subnet does not belong to a shared netork the name is null. The metadata includes database specific information associated with the subnets. The returned list does not contain full subnet definitions. Use <command>remote-subnet6-get</command> to fetch the full information about the selected subnets."
+    "resp-comment": "The returned response contains a list of maps. Each map contains a subnet identifier, prefix and shared network name to which the subnet belongs. If the subnet does not belong to a shared netork the name is null. The metadata includes database specific information associated with the subnets. The returned list does not contain full subnet definitions. Use <command>remote-subnet6-get</command> to fetch the full information about the selected subnets. If the command includes explicit server tags as strings (including the special server tag \"all\"), the list contains all subnets which are associated with any of the specified tags. A subnet is returned even if it is associated with multiple servers and only one of the specified tags matches. If the command includes the <command>null</command> value in the <command>server-tags</command> list, the response contains all subnets which are assigned to no servers (unassigned)."
 }
diff --git a/doc/api/remote-subnet6-set.json b/doc/api/remote-subnet6-set.json
index f0545b95b8..819fa4fa92 100644
--- a/doc/api/remote-subnet6-set.json
+++ b/doc/api/remote-subnet6-set.json
@@ -1,6 +1,6 @@
 {
     "name": "remote-subnet6-set",
-    "brief": "This command is used to create or replace an IPv4 subnet the configuration database.",
+    "brief": "This command is used to create or replace an IPv6 subnet the configuration database.",
     "support": [ "kea-dhcp6" ],
     "avail": "1.6.0",
     "hook": "cb_cmds",
@@ -17,10 +17,11 @@
         ],
         \"remote\": {
             <specification of the database to connect to>
-        }
+        },
+        \"server-tags\": [ <first server tag>, <second server tag>, ... ]
     }
 }",
-    "cmd-comment": "The provided list must contain exactly one subnet specification. The <command>shared-network-name</command> parameter is required for these commands. It associates the subnet with the shared network by its name. If the subnet must not belong to any shared network (global subnet), the <command>null</command> value must be specified for the shared network name.",
+    "cmd-comment": "The provided list must contain exactly one subnet specification. The <command>shared-network-name</command> parameter is required for these commands. It associates the subnet with the shared network by its name. If the subnet must not belong to any shared network (global subnet), the <command>null</command> value must be specified for the shared network name. The <command>server-tags</command> list is mandatory and it must contain one or more server tags as strings to explicitly associate the subnet with one or more user defined servers. It may include the special server tag \"all\" to associate the subnet with all servers.",
     "resp-syntax": "{
     \"result\": 0,
     \"text\": \"IPv6 subnet successfully set.\",