Commit 33c398a7 authored by Marcin Siodelski's avatar Marcin Siodelski Committed by Tomek Mrugalski

[5315] Updated Kea User's Guide with subnet_cmds information.

parent 03e1804d
......@@ -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 -->
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment