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
--- /dev/null
+{
+ "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."
+}
lease4-update
lease4-wipe
lease6-add
+lease6-bulk-apply
lease6-del
lease6-get
lease6-get-all
<!-- 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>
, <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>
</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>
<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>
<screen>{ "result": 1, "text": "missing parameter 'ip-address' (<string>: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>