From: Marcin Siodelski Date: Fri, 21 Jun 2019 16:26:54 +0000 (+0200) Subject: [#683,!390] Updated Kea ARM with lease6-bulk-apply. X-Git-Tag: Kea-1.6.0-beta2~260 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ce489f0e3ace53ca9ba937579a55458ecc4d878f;p=thirdparty%2Fkea.git [#683,!390] Updated Kea ARM with lease6-bulk-apply. --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 2478778f1d..4bfb887e7d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 index 0000000000..aff923b53f --- /dev/null +++ b/doc/api/lease6-bulk-apply.json @@ -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." +} diff --git a/doc/docgen/cmds-list b/doc/docgen/cmds-list index 2a22ef34bb..b58cd72dff 100644 --- a/doc/docgen/cmds-list +++ b/doc/docgen/cmds-list @@ -30,6 +30,7 @@ lease4-get-all lease4-update lease4-wipe lease6-add +lease6-bulk-apply lease6-del lease6-get lease6-get-all diff --git a/doc/guide/api.xml b/doc/guide/api.xml index a1a37e599f..b899b09b6f 100644 --- a/doc/guide/api.xml +++ b/doc/guide/api.xml @@ -9,7 +9,7 @@ API Reference - Kea currently supports 121 commands: + Kea currently supports 122 commands: build-report , cache-clear , cache-get @@ -42,6 +42,7 @@ , lease4-update , lease4-wipe , lease6-add +, lease6-bulk-apply , lease6-del , lease6-get , lease6-get-all @@ -260,6 +261,7 @@ , ha-scopes , ha-sync , lease6-add +, lease6-bulk-apply , lease6-del , lease6-get , lease6-get-all @@ -394,6 +396,7 @@ , lease4-update , lease4-wipe , lease6-add +, lease6-bulk-apply , lease6-del , lease6-get , lease6-get-all @@ -1680,6 +1683,82 @@ Result is an integer representation of the status. Currently supported statuses + +
+lease6-bulk-apply reference +lease6-bulk-apply - 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. + +Supported by: kea-dhcp6 + +Availability: 1.6.0 (lease_cmds hook) + +Description and examples: See + +Command 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", + ... + } + ] + } +} +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. + +Response 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", + ... + } + ] + } + } +} +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. + +
+ +
lease6-del reference diff --git a/doc/guide/hooks-lease-cmds.xml b/doc/guide/hooks-lease-cmds.xml index 7b7d6c8133..fbad82e81b 100644 --- a/doc/guide/hooks-lease-cmds.xml +++ b/doc/guide/hooks-lease-cmds.xml @@ -47,6 +47,10 @@ lease6-add - adds a new IPv6 lease; + + lease6-bulk-apply - creates, updates and/or + deletes multiple IPv6 leases in a single transaction; + lease4-get - checks whether an IPv4 lease with the specified parameters exists and returns it if it does; @@ -281,6 +285,112 @@ The commands can take a number of additional optional parameters: { "result": 1, "text": "missing parameter 'ip-address' (<string>:3:19)" } +
+ lease6-bulk-apply + The lease6-bulk-apply 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. lease6-update + is highly inefficient and produces unnecessary delays in communication + between the HA partners and in sending the response to the DHCPv6 client. + + + The lease6-bulk-apply 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. + + + 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. + + In the following example, we ask to delete two leases and to add + or update two other leases in the database: + +{ + "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", + ... + } + ] + } +} + + + + 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. + + + For example: + +{ + "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", + ... + } + ] + } +} + + + 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. + +
lease4-get, lease6-get Commands