From: Marcin Siodelski Date: Thu, 27 Jul 2017 14:44:51 +0000 (+0200) Subject: [5315] Updated Kea User's Guide with subnet_cmds information. X-Git-Tag: trac5124a_base~5^2~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=33c398a71a68e900d8285f4f88e43c3614b4a0be;p=thirdparty%2Fkea.git [5315] Updated Kea User's Guide with subnet_cmds information. --- diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index d706747d0e..df33416953 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -241,6 +241,21 @@ capabilities related to host reservations will be added in the future. + + Subnet Commands + Support customers + Kea 1.3.0 + In deployments in which subnets' configuration needs to + be frequently updated, it is a hard requirement that such updates are + performed without a need for a full DHCP server reconfiguration + or restart. This hooks library allows for incremental changes + to the subnets' configuration such as: adding a subnet, removing + a subnet. It also allows for listing all available subnets and + fetching detailed information about a selected subnet. The + commands exposed by this library do not affect other subnets + or configuration parameters currently used by the server. + + @@ -1112,7 +1127,6 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows } } - lease6-add command requires four @@ -1480,17 +1494,444 @@ as follows: -
User contexts - Hook libraries can have their own configuration parameters. That is - convenient if the parameter applies to the whole library. However, sometimes - it is very useful if certain configuration entities are extended with - additional configuration data. This is where the concept of user contexts - comes in. A sysadmin can define an arbitrary set of data and attach it to - Kea structures, as long as the data is specified as JSON map. In - particular, it is possible to define fields that are integers, strings, - boolean, lists and maps. It is possible to define nested structures of - arbitrary complexity. Kea does not use that data on its own, simply stores - and makes it available for the hook libraries. As of Kea - 1.2, the only structures that allow user contexts are address and prefix - pools, but it is expected to extend other structures with the user context - capability.
+
+ subnet_cmds: Subnet Commands + + This section describes a hook application that offers a number of new + commands used to query and manipulate subnet configurations in Kea. + This application is very useful in deployments with a large number of + subnets being managed by the DHCP servers and when the subnets are + frequently updated. The commands offer lightweight approach for + manipulating subnets without a need to fully reconfigure the server + and without affecting existing servers' configurations. + + + Currently this library is only available to ISC customers with a + support contract. + + The following commands are currently supported: + + + subnet4-list/subnet6-list: lists all configured subnets + + + + + subnet4-get/subnet6-get: retrieves detailed information about a selected subnet + + + + + subnet4-add/subnet6-add: adds new subnet into server's configuration + + + + + subnet4-del/subnet6-del: removes a subnet from the server's configuration + + + + + +
+ subnet4-list command + + This command is used to list all currently configured subnets. The + subnets are returned in a brief form, i.e. a subnet identifier + and subnet prefix is included for each subnet. In order to retrieve + the detailed information about the subnet the + subnet4-get should be used. + + + This command has the simple structure: + +{ + "command": "subnet4-list" +} + + + + The list of subnets returned as a result of this command is returned + in the following format: + +{ + "result": 0, + "text": "2 IPv4 subnets found", + "arguments": { + "subnet-ids": [ + { + "subnet-id": 10, + "subnet": "10.0.0.0/8" + }, + { + "subnet-id": 100, + "subnet": "192.0.2.0/24" + } + ] +} + + + + If no IPv4 subnets are found, an error code is returned along with + the error description. + +
+ +
+ subnet6-list command + + This command is used to list all currently configured subnets. The + subnets are returned in a brief form, i.e. a subnet identifier + and subnet prefix is included for each subnet. In order to retrieve + the detailed information about the subnet the + subnet6-get should be used. + + + This command has the simple structure: + +{ + "command": "subnet6-list" +} + + + + The list of subnets returned as a result of this command is returned + in the following format: + +{ + "result": 0, + "text": "2 IPv6 subnets found", + "arguments": { + "subnet-ids": [ + { + "subnet-id": 11, + "subnet": "2001:db8:1::/64" + }, + { + "subnet-id": 233, + "subnet": "3000::/16" + } + ] +} + + + + If no IPv6 subnets are found, an error code is returned along with + the error description. + +
+
+ +
+ subnet4-get command + This command is used to retrieve detailed information about the + specified subnet. This command usually follows the + subnet4-list, which is used to discover available + subnets with their respective subnet identifiers and prefixes. Any of + those parameters can be then used in subnet4-get + to fetch subnet information: + +{ + "command": "subnet4-get", + "arguments": { + "subnet-id": 10 + } +} + +or + + +{ + "command": "subnet4-get", + "arguments": { + "subnet": "10.0.0.0/8" + } +} + + + + + If the subnet exists the response will be similar to this: + +{ + "result": 0, + "text": "Info about IPv4 subnet 10.0.0.0/8 (subnet-id 10) returned", + "arguments": { + "subnet4": [ + { + "subnet": "10.0.0.0/8", + "id": 1, + "option-data": [ + .... + ] + ... + } + ] + } +} + + + +
+ +
+ subnet6-get command + This command is used to retrieve detailed information about the + specified subnet. This command usually follows the + subnet6-list, which is used to discover available + subnets with their respective subnet identifiers and prefixes. Any of + those parameters can be then used in subnet6-get + to fetch subnet information: + +{ + "command": "subnet6-get", + "arguments": { + "subnet-id": 11 + } +} + + +or + + +{ + "command": "subnet6-get", + "arguments": { + "subnet": "2001:db8:1::/64" + } +} + +If the subnet exists the response will be similar to this: + +{ + "result": 0, + "text": "Info about IPv6 subnet 2001:db8:1::/64 (subnet-id 11) returned", + "arguments": { + "subnet6": [ + { + "subnet": "2001:db8:1::/64", + "id": 1, + "option-data": [ + ... + ] + .... + } + ] + } +} + + +
+ +
+ subnet4-add + + This command is used to create and add new subnet to the existing + server configuration. This operation has no impact on other + subnets. The subnet identifier must be specified and must be + unique among all subnets. If the identifier or a subnet prefix is + not unique an error is reported and the subnet is not added. + + + The subnet information within this command has the same structure + as the subnet information in the server configuration file with the + exception that static host reservations must not be specified + within subnet4-add. The commands described in + should be used to add, remove and + modify static reservations. + +{ + "command": "subnet4-add", + "arguments": { + "subnet4": [ { + "id": 123, + "subnet": "10.20.30.0/24", + ... + } ] + } +} + + + + + The response to this command has the following structure: + +{ + "result": 0, + "text": "IPv4 subnet added", + "arguments": { + "subnet4": [ + { + "id": 123, + "subnet": "10.20.30.0/24" + } + ] + } +} + + +
+ +
+ subnet6-add + + This command is used to create and add new subnet to the existing + server configuration. This operation has no impact on other + subnets. The subnet identifier must be specified and must be + unique among all subnets. If the identifier or a subnet prefix is + not unique an error is reported and the subnet is not added. + + + The subnet information within this command has the same structure + as the subnet information in the server configuration file with the + exception that static host reservations must not be specified + within subnet6-add. The commands described in + should be used to add, remove and + modify static reservations. + +{ + "command": "subnet6-add", + "arguments": { + "subnet6": [ { + "id": 234, + "subnet": "2001:db8:1::/64", + ... + } ] + } +} + + + + + The response to this command has the following structure: + +{ + "result": 0, + "text": "IPv6 subnet added", + "arguments": { + "subnet6": [ + { + "id": 234, + "subnet": "2001:db8:1::/64" + } + ] + } +} + + +
+ +
+ subnet4-del command + + This command is used to remove a subnet from the server's configuration. + This command has no effect on other configured subnets but removing + a subnet has certain implications which the server's administrator + should be aware of. + + + In most cases the server has assigned some leases to the clients + belonging to the subnet. The server may also be configured with + static host reservations which are associated with this subnet. + The current implementation of the subnet4-del + removes neither the leases nor host reservations associated with + a subnet. This is the safest approach because the server doesn't + loose track of leases assigned to the clients from this subnet. + However, removal of the subnet may still cause configuration + errors and conflicts. For example: after removal of the subnet, + the server administrator may add a new subnet with the ID used + previously for the removed subnet. This means that the existing + leases and static reservations will be in conflict with this + new subnet. Thus, we recommend that this command is used with extreme + caution. + + + The command has the following structure: + +{ + "command": "subnet4-del", + "arguments": { + "subnet-id": 123 + } +} + + + + The example successful response may look like this: + +{ + "result": 0, + "text": "IPv4 subnet 192.0.2.0/24 (subnet-id 123) deleted" +} + + +
+ +
+ subnet6-del command + + This command is used to remove a subnet from the server's configuration. + This command has no effect on other configured subnets but removing + a subnet has certain implications which the server's administrator + should be aware of. + + + In most cases the server has assigned some leases to the clients + belonging to the subnet. The server may also be configured with + static host reservations which are associated with this subnet. + The current implementation of the subnet6-del + removes neither the leases nor host reservations associated with + a subnet. This is the safest approach because the server doesn't + loose track of leases assigned to the clients from this subnet. + However, removal of the subnet may still cause configuration + errors and conflicts. For example: after removal of the subnet, + the server administrator may add a new subnet with the ID used + previously for the removed subnet. This means that the existing + leases and static reservations will be in conflict with this + new subnet. Thus, we recommend that this command is used with extreme + caution. + + + The command has the following structure: + +{ + "command": "subnet6-del", + "arguments": { + "subnet-id": 234 + } +} + + + + The example successful response may look like this: + +{ + "result": 0, + "text": "IPv6 subnet 2001:db8:1::/64 (subnet-id 234) deleted" +} + + +
+ + + +
+ User contexts + Hook libraries can have their own configuration parameters. That is + convenient if the parameter applies to the whole library. However, + sometimes it is very useful if certain configuration entities are extended + with additional configuration data. This is where the concept of user + contexts comes in. A sysadmin can define an arbitrary set of data and + attach it to Kea structures, as long as the data is specified as JSON map. + In particular, it is possible to define fields that are integers, strings, + boolean, lists and maps. It is possible to define nested structures of + arbitrary complexity. Kea does not use that data on its own, simply stores + and makes it available for the hook libraries. + + + As of Kea 1.2, the only structures that allow user contexts are address + and prefix pools, but it is expected to extend other structures with the + user context capability. + +
+