]> git.ipfire.org Git - thirdparty/kea.git/commitdiff
[#683,!390] Updated Kea ARM with lease6-bulk-apply.
authorMarcin Siodelski <marcin@isc.org>
Fri, 21 Jun 2019 16:26:54 +0000 (18:26 +0200)
committerMarcin Siodelski <marcin@isc.org>
Fri, 21 Jun 2019 20:45:34 +0000 (16:45 -0400)
doc/Makefile.am
doc/api/lease6-bulk-apply.json [new file with mode: 0644]
doc/docgen/cmds-list
doc/guide/api.xml
doc/guide/hooks-lease-cmds.xml

index 2478778f1d1f4cf705f93018b6c7f3f3a9003303..4bfb887e7d91d9f662ec11328c94c3aa646e2f6f 100644 (file)
@@ -98,6 +98,7 @@ EXTRA_DIST += api/ha-sync.json api/lease4-add.json
 EXTRA_DIST += api/lease4-del.json api/lease4-get-all.json
 EXTRA_DIST += api/lease4-get.json api/lease4-update.json
 EXTRA_DIST += api/lease4-wipe.json api/lease6-add.json
+EXTRA_DIST += api/lease6-bulk-apply.json
 EXTRA_DIST += api/lease6-del.json api/lease6-get-all.json
 EXTRA_DIST += api/lease6-get.json api/lease6-update.json
 EXTRA_DIST += api/lease6-wipe.json api/leases-reclaim.json
diff --git a/doc/api/lease6-bulk-apply.json b/doc/api/lease6-bulk-apply.json
new file mode 100644 (file)
index 0000000..aff923b
--- /dev/null
@@ -0,0 +1,65 @@
+{
+    "name": "lease6-bulk-apply",
+    "brief": "The lease6-bulk-apply command can be used to create, update and delete multiple IPv6 leases in a single transaction. This is used to communicate lease changes between the HA peers but may be used in all cases when it is desired to apply multiple lease updates in a single transaction.",
+    "support": [ "kea-dhcp6" ],
+    "avail": "1.6.0",
+    "hook": "lease_cmds",
+    "cmd-syntax": "{
+        \"command\": \"lease6-bulk-apply\",
+        \"arguments\": {
+            \"deleted-leases\": [
+                {
+                    \"subnet-id\": 66,
+                    \"ip-address\": \"2001:db8:abcd::\",
+                    \"type\": \"IA_PD\",
+                    ...
+                },
+                {
+                    \"subnet-id\": 66,
+                    \"ip-address\": \"2001:db8:abcd::234\",
+                    \"type\": \"IA_NA\",
+                    ...
+                }
+            ],
+            \"leases\": [
+                {
+                    \"subnet-id\": 66,
+                    \"ip-address\": \"2001:db8:cafe::\",
+                    \"type\": \"IA_PD\",
+                    ...
+                },
+                {
+                    \"subnet-id\": 66,
+                    \"ip-address\": \"2001:db8:abcd::333\",
+                    \"type\": \"IA_NA\",
+                    ...
+                }
+            ]
+        }
+}",
+    "cmd-comment": "If any of the leases is malformed, all changes are rolled back. If the leases are well formed but the operation fails for one or more leases, the these leases are listed in the response but the changes are preserved for all leases for which the operation was successful. The \"deleted-leases\" and \"leases\" are optional parameters but one of them must be specified.",
+    "resp-syntax": " {
+    {
+        \"result\": 0,
+        \"text\": IPv6 leases bulk apply completed.
+        \"arguments\": {
+            \"failed-deleted-leases\": [
+                {
+                    \"subnet-id\": 66,
+                    \"ip-address\": \"2001:db8:abcd::\",
+                    \"type\": \"IA_PD\"
+                }
+            ],
+            \"failed-leases\": [
+                {
+                    \"subnet-id\": 66,
+                    \"ip-address\": \"2001:db8:cafe::\",
+                    \"type\": \"IA_PD\",
+                    ...
+                }
+            ]
+        }
+    }
+}",
+    "resp-comment": "The \"failed-deleted-leases\" holds the list of leases which failed to delete. This includes leases which were not found in the database. The \"failed-leases\" includes the list of leases which failed to create or update."
+}
index 2a22ef34bb0cf57a983904d1174071aed736d699..b58cd72dff722bf4945485a786aa228b931fd105 100644 (file)
@@ -30,6 +30,7 @@ lease4-get-all
 lease4-update
 lease4-wipe
 lease6-add
+lease6-bulk-apply
 lease6-del
 lease6-get
 lease6-get-all
index a1a37e599f5fbd25d4931fdd197fce5c715c357c..b899b09b6f18c0001502f9edaaf0430d55e6f10c 100644 (file)
@@ -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 121 commands:
+  <para>Kea currently supports 122 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>
@@ -42,6 +42,7 @@
 , <command><link linkend="ref-lease4-update">lease4-update</link></command>
 , <command><link linkend="ref-lease4-wipe">lease4-wipe</link></command>
 , <command><link linkend="ref-lease6-add">lease6-add</link></command>
+, <command><link linkend="ref-lease6-bulk-apply">lease6-bulk-apply</link></command>
 , <command><link linkend="ref-lease6-del">lease6-del</link></command>
 , <command><link linkend="ref-lease6-get">lease6-get</link></command>
 , <command><link linkend="ref-lease6-get-all">lease6-get-all</link></command>
 , <command><link linkend="ref-ha-scopes">ha-scopes</link></command>
 , <command><link linkend="ref-ha-sync">ha-sync</link></command>
 , <command><link linkend="ref-lease6-add">lease6-add</link></command>
+, <command><link linkend="ref-lease6-bulk-apply">lease6-bulk-apply</link></command>
 , <command><link linkend="ref-lease6-del">lease6-del</link></command>
 , <command><link linkend="ref-lease6-get">lease6-get</link></command>
 , <command><link linkend="ref-lease6-get-all">lease6-get-all</link></command>
 , <command><link linkend="ref-lease4-update">lease4-update</link></command>
 , <command><link linkend="ref-lease4-wipe">lease4-wipe</link></command>
 , <command><link linkend="ref-lease6-add">lease6-add</link></command>
+, <command><link linkend="ref-lease6-bulk-apply">lease6-bulk-apply</link></command>
 , <command><link linkend="ref-lease6-del">lease6-del</link></command>
 , <command><link linkend="ref-lease6-get">lease6-get</link></command>
 , <command><link linkend="ref-lease6-get-all">lease6-get-all</link></command>
@@ -1680,6 +1683,82 @@ Result is an integer representation of the status. Currently supported statuses
 </section>
 <!-- end of lease6-add -->
 
+<!-- start of lease6-bulk-apply -->
+<section xml:id="reference-lease6-bulk-apply">
+<title>lease6-bulk-apply reference</title>
+<para xml:id="ref-lease6-bulk-apply"><command>lease6-bulk-apply</command> - The lease6-bulk-apply command can be used to create, update and delete multiple IPv6 leases in a single transaction. This is used to communicate lease changes between the HA peers but may be used in all cases when it is desired to apply multiple lease updates in a single transaction.</para>
+
+<para>Supported by: <command><link linkend="commands-kea-dhcp6">kea-dhcp6</link></command></para>
+
+<para>Availability: 1.6.0 (<link linkend="commands-lease_cmds-lib">lease_cmds</link>  hook)</para>
+
+<para>Description and examples: See <xref linkend="command-lease6-bulk-apply"/></para>
+
+<para>Command syntax:
+  <screen>{
+        "command": "lease6-bulk-apply",
+        "arguments": {
+            "deleted-leases": [
+                {
+                    "subnet-id": 66,
+                    "ip-address": "2001:db8:abcd::",
+                    "type": "IA_PD",
+                    ...
+                },
+                {
+                    "subnet-id": 66,
+                    "ip-address": "2001:db8:abcd::234",
+                    "type": "IA_NA",
+                    ...
+                }
+            ],
+            "leases": [
+                {
+                    "subnet-id": 66,
+                    "ip-address": "2001:db8:cafe::",
+                    "type": "IA_PD",
+                    ...
+                },
+                {
+                    "subnet-id": 66,
+                    "ip-address": "2001:db8:abcd::333",
+                    "type": "IA_NA",
+                    ...
+                }
+            ]
+        }
+}</screen>
+If any of the leases is malformed, all changes are rolled back. If the leases are well formed but the operation fails for one or more leases, the these leases are listed in the response but the changes are preserved for all leases for which the operation was successful. The "deleted-leases" and "leases" are optional parameters but one of them must be specified.</para>
+
+<para>Response syntax:
+  <screen> {
+    {
+        "result": 0,
+        "text": IPv6 leases bulk apply completed.
+        "arguments": {
+            "failed-deleted-leases": [
+                {
+                    "subnet-id": 66,
+                    "ip-address": "2001:db8:abcd::",
+                    "type": "IA_PD"
+                }
+            ],
+            "failed-leases": [
+                {
+                    "subnet-id": 66,
+                    "ip-address": "2001:db8:cafe::",
+                    "type": "IA_PD",
+                    ...
+                }
+            ]
+        }
+    }
+}</screen>
+The "failed-deleted-leases" holds the list of leases which failed to delete. This includes leases which were not found in the database. The "failed-leases" includes the list of leases which failed to create or update.</para>
+
+</section>
+<!-- end of lease6-bulk-apply -->
+
 <!-- start of lease6-del -->
 <section xml:id="reference-lease6-del">
 <title>lease6-del reference</title>
index 7b7d6c8133fb5e6d0fcb0998089f51306c5f3672..fbad82e81b387740afebcc798510ded69454be92 100644 (file)
             <listitem>
               <para><command>lease6-add</command> - adds a new IPv6 lease;</para>
             </listitem>
+            <listitem>
+              <para><command>lease6-bulk-apply</command> - creates, updates and/or
+              deletes multiple IPv6 leases in a single transaction;</para>
+            </listitem>
             <listitem>
               <para><command>lease4-get</command> - checks whether an IPv4 lease with
               the specified parameters exists and returns it if it does;</para>
@@ -281,6 +285,112 @@ The commands can take a number of additional optional parameters:
           <screen>{ "result": 1, "text": "missing parameter 'ip-address' (&lt;string&gt;:3:19)" }</screen>
         </para>
 
+        <section id="command-lease6-bulk-apply">
+          <title>lease6-bulk-apply</title>
+          <para>The <command>lease6-bulk-apply</command> was implemented to address
+          the performance penalty in the High Availability when a single DHCPv6
+          transaction resulted in multiple lease updates sent to the partner if
+          multiple address and/or prefix leases were allocated. Consider the case
+          when a DHCPv6 client requests the assignment of two IPv6 addresses and two IPv6
+          prefixes. That may result in allocation of 4 leases. In addition, the
+          DHCPv6 may assign different address than requested by the client during
+          the renew or rebind and delete the leases previously used by this client.
+          The are 6 of lease changes sent between the HA partners is in this case.
+          Sending these updates in individual commands, e.g. <command>lease6-update</command>
+          is highly inefficient and produces unnecessary delays in communication
+          between the HA partners and in sending the response to the DHCPv6 client.
+          </para>
+
+          <para>The <command>lease6-bulk-apply</command> command deals with this
+          problem by aggregating all lease changes in a single command. Both
+          deleted leases and new/updated leases are conveyed in a single command.
+          The receiving server iterates over the deleted leases and deletes them
+          from its lease database. Next, it iterates over the new/updated leases
+          and adds them to the database or updates them if they already exist.
+          </para>
+
+          <para>Even though the High Avialability is the major application for
+          this command, it can be freely used in all cases when it is desired to
+          send multiple lease changes in a single command.</para>
+
+          <para>In the following example, we ask to delete two leases and to add
+          or update two other leases in the database:
+<screen>
+{
+    "command": "lease6-bulk-apply",
+    "arguments": {
+        "deleted-leases": [
+            {
+                "subnet-id": 66,
+                "ip-address": "2001:db8:abcd::",
+                "type": "IA_PD",
+                 ...
+            },
+            {
+                "subnet-id": 66,
+                "ip-address": "2001:db8:abcd::234",
+                "type": "IA_NA",
+                ...
+            }
+        ],
+        "leases": [
+           {
+                "subnet-id": 66,
+                "ip-address": "2001:db8:cafe::",
+                "type": "IA_PD",
+                 ...
+           },
+           {
+                "subnet-id": 66,
+                "ip-address": "2001:db8:abcd::333",
+                "type": "IA_NA",
+                ...
+            }
+        ]
+    }
+}
+</screen>
+          </para>
+
+          <para>If any of the leases is malformed, no leases changes are applied
+          to the lease database. If the leases are well formed but there is a
+          failure to apply any of the lease changes to the database, the command
+          will continue to be processed for other leases. All the leases for which
+          the command was unable to apply the changes in the database will be
+          listed in the response.
+          </para>
+
+          <para>For example:
+<screen>
+{
+    "result": 0,
+    "text": "Bulk apply of 2 IPv6 leases completed".
+    "arguments": {
+        "failed-deleted-leases": [
+            {
+                "subnet-id": 66,
+                "ip-address": "2001:db8:abcd::",
+                "type": "IA_PD"
+            }
+        ],
+        "failed-leases": [
+            {
+                "subnet-id": 66,
+                "ip-address": "2001:db8:cafe::",
+                "type": "IA_PD",
+                ...
+            }
+        ]
+    }
+}
+</screen>
+          </para>
+          <para>The response above indicates that the hooks library was unable to
+          delete the lease for prefix "2001:db8:abcd::" and add or update the lease
+          for prefix "2001:db8:cafe::". However, there are two other lease changes
+          which have been applied as indicated by the text message.
+          </para>
+        </section>
 
         <section id="command-lease4-get">
           <title>lease4-get, lease6-get Commands</title>