diff options
Diffstat (limited to 'doc/guide/hooks.xml')
| -rw-r--r-- | doc/guide/hooks.xml | 471 |
1 files changed, 456 insertions, 15 deletions
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.</entry> </row> + <row> + <entry>Subnet Commands</entry> + <entry>Support customers</entry> + <entry>Kea 1.3.0</entry> + <entry>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. + </entry> + </row> </tbody> </tgroup> </table> @@ -1112,7 +1127,6 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows } } </screen> - </para> <para><command>lease6-add</command> command requires four @@ -1480,17 +1494,444 @@ as follows: </section> </section> - </section> <section id="user-context"> <title>User contexts</title> - <para>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. </para> <para> 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. </para> </section> </chapter> <!-- hooks-libraries --> + <section id="subnet-cmds"> + <title>subnet_cmds: Subnet Commands</title> + <para> + 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. + </para> + + <para>Currently this library is only available to ISC customers with a + support contract.</para> + + <para>The following commands are currently supported: + <itemizedlist mark='bullet'> + <listitem> + <simpara><command>subnet4-list/subnet6-list</command>: lists all configured subnets + </simpara> + </listitem> + <listitem> + <simpara> + <command>subnet4-get/subnet6-get</command>: retrieves detailed information about a selected subnet + </simpara> + </listitem> + <listitem> + <simpara> + <command>subnet4-add/subnet6-add</command>: adds new subnet into server's configuration + </simpara> + </listitem> + <listitem> + <simpara> + <command>subnet4-del/subnet6-del</command>: removes a subnet from the server's configuration + </simpara> + </listitem> + </itemizedlist> + </para> + + <section> + <title>subnet4-list command</title> + <para> + 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 + <command>subnet4-get</command> should be used. + </para> + <para> + This command has the simple structure: +<screen> +{ + "command": "subnet4-list" +} +</screen> + </para> + <para> + The list of subnets returned as a result of this command is returned + in the following format: +<screen> +{ + "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" + } + ] +} +</screen> + </para> + <para> + If no IPv4 subnets are found, an error code is returned along with + the error description. + </para> + </section> + + <section> + <title>subnet6-list command</title> + <para> + 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 + <command>subnet6-get</command> should be used. + </para> + <para> + This command has the simple structure: +<screen> +{ + "command": "subnet6-list" +} +</screen> + </para> + <para> + The list of subnets returned as a result of this command is returned + in the following format: +<screen> +{ + "result": 0, + "text": "2 IPv6 subnets found", + "arguments": { + "subnet-ids": [ + { + "subnet-id": 11, + "subnet": "2001:db8:1::/64" + }, + { + "subnet-id": 233, + "subnet": "3000::/16" + } + ] +} +</screen> + </para> + <para> + If no IPv6 subnets are found, an error code is returned along with + the error description. + </para> + </section> + </section> + + <section> + <title>subnet4-get command</title> + <para>This command is used to retrieve detailed information about the + specified subnet. This command usually follows the + <command>subnet4-list</command>, which is used to discover available + subnets with their respective subnet identifiers and prefixes. Any of + those parameters can be then used in <command>subnet4-get</command> + to fetch subnet information: +<screen> +{ + "command": "subnet4-get", + "arguments": { + "subnet-id": 10 + } +}</screen> + +or + +<screen> +{ + "command": "subnet4-get", + "arguments": { + "subnet": "10.0.0.0/8" + } +} +</screen> + </para> + + <para> + If the subnet exists the response will be similar to this: +<screen> +{ + "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": [ + .... + ] + ... + } + ] + } +} + +</screen> + </para> + </section> + + <section> + <title>subnet6-get command</title> + <para>This command is used to retrieve detailed information about the + specified subnet. This command usually follows the + <command>subnet6-list</command>, which is used to discover available + subnets with their respective subnet identifiers and prefixes. Any of + those parameters can be then used in <command>subnet6-get</command> + to fetch subnet information: +<screen> +{ + "command": "subnet6-get", + "arguments": { + "subnet-id": 11 + } +} +</screen> + +or + +<screen> +{ + "command": "subnet6-get", + "arguments": { + "subnet": "2001:db8:1::/64" + } +}</screen> + +If the subnet exists the response will be similar to this: +<screen> +{ + "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": [ + ... + ] + .... + } + ] + } +} +</screen> + </para> + </section> + + <section> + <title>subnet4-add</title> + <para> + 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. + </para> + <para> + 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 <command>subnet4-add</command>. The commands described in + <xref linkend="host-cmds"/> should be used to add, remove and + modify static reservations. +<screen> +{ + "command": "subnet4-add", + "arguments": { + "subnet4": [ { + "id": 123, + "subnet": "10.20.30.0/24", + ... + } ] + } +} +</screen> + </para> + + <para> + The response to this command has the following structure: +<screen> +{ + "result": 0, + "text": "IPv4 subnet added", + "arguments": { + "subnet4": [ + { + "id": 123, + "subnet": "10.20.30.0/24" + } + ] + } +} +</screen> + </para> + </section> + + <section> + <title>subnet6-add</title> + <para> + 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. + </para> + <para> + 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 <command>subnet6-add</command>. The commands described in + <xref linkend="host-cmds"/> should be used to add, remove and + modify static reservations. +<screen> +{ + "command": "subnet6-add", + "arguments": { + "subnet6": [ { + "id": 234, + "subnet": "2001:db8:1::/64", + ... + } ] + } +} +</screen> + </para> + + <para> + The response to this command has the following structure: +<screen> +{ + "result": 0, + "text": "IPv6 subnet added", + "arguments": { + "subnet6": [ + { + "id": 234, + "subnet": "2001:db8:1::/64" + } + ] + } +} +</screen> + </para> + </section> + + <section> + <title>subnet4-del command</title> + <para> + 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. + </para> + <para> + 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 <command>subnet4-del</command> + 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. + </para> + + <para>The command has the following structure: +<screen> +{ + "command": "subnet4-del", + "arguments": { + "subnet-id": 123 + } +} +</screen> + </para> + <para> + The example successful response may look like this: +<screen> +{ + "result": 0, + "text": "IPv4 subnet 192.0.2.0/24 (subnet-id 123) deleted" +} +</screen> + </para> + </section> + + <section> + <title>subnet6-del command</title> + <para> + 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. + </para> + <para> + 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 <command>subnet6-del</command> + 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. + </para> + + <para>The command has the following structure: +<screen> +{ + "command": "subnet6-del", + "arguments": { + "subnet-id": 234 + } +} +</screen> + </para> + <para> + The example successful response may look like this: +<screen> +{ + "result": 0, + "text": "IPv6 subnet 2001:db8:1::/64 (subnet-id 234) deleted" +} +</screen> + </para> + </section> + + </section> + + <section id="user-context"> + <title>User contexts</title> + <para>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. + </para> + <para> + 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. + </para> + </section> + </chapter> <!-- hooks-libraries --> |