Commit d259f330 authored by Thomas Markwalder's avatar Thomas Markwalder

[5315] Documented subnet_cmds library in the Kea User's Guide

    Merge branch 'trac5315_rebase'
parents c885228d 98196abc
......@@ -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 subnet configuration needs to
be frequently updated, it is a hard requirement that such updates be
performed without the need for a full DHCP server reconfiguration
or restart. This hooks library allows for incremental changes
to the subnet 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
......@@ -1423,7 +1437,7 @@ as follows:
}
}</screen>
</para>
<para>
An example command updating IPv6 lease looks as follows:
<screen>{
......@@ -1476,21 +1490,491 @@ as follows:
<para>Note: not all backends support this command.</para>
</section>
</section>
</section>
<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": {
"subnets": [
{
"id": 10,
"subnet": "10.0.0.0/8"
},
{
"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": {
"subnets": [
{
"id": 11,
"subnet": "2001:db8:1::/64"
},
{
"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>
<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": {
"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 (id 10) returned",
"arguments": {
"subnets": [
{
"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": {
"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 (id 11) returned",
"arguments": {
"subnets": [
{
"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": {
"subnets": [ {
"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": {
"subnets": [
{
"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>
<para>
It is recommended, but not mandatory to specify subnet
id. If not specified, Kea will try to assign the next
subnet-id value. This automatic ID value generator is
simple. It returns a previously automatically assigned value
increased by 1. This works well, unless you manually create
a subnet with a value bigger than previously used. For
example, if you call subnet4-add five times, each without
id, Kea will assign IDs: 1,2,3,4 and 5 and it will work just
fine. However, if you try to call subnet4-add five times,
with the first subnet having subnet-id of value 3 and
remaining ones having no subnet-id, it will fail. The first
command (with explicit value) will use subnet-id 3, the
second command will create a subnet with id of 1, the third
will use value of 2 and finally the fourth will have the
subnet-id value auto-generated as 3. However, since there is
already a subnet with that id, it will fail.
</para>
<para>
The general recommendation is to either: never use explicit
values (so the auto-generated values will always work) or
always use explicit values (so the auto-generation is never
used). You can mix those two approaches only if you
understand how the internal automatic subnet-id generation works.
</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": {
"id": 123
}
}
</screen>
</para>
<para>
The example successful response may look like this:
<screen>
{
"result": 0,
"text": "IPv4 subnet 192.0.2.0/24 (id 123) deleted",
"arguments": {
"subnets": [
{
"id": 123,
"subnet": "192.0.2.0/24"
}
]
}
}
</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": {
"id": 234
}
}
</screen>
</para>
<para>
The example successful response may look like this:
<screen>
{
"result": 0,
"text": "IPv6 subnet 2001:db8:1::/64 (id 234) deleted",
"subnets": [
{
"id": 234,
"subnet": "2001:db8:1::/64"
}
]
}
</screen>
</para>
</section>
</section>
</section> <!-- end of subnet commands -->
<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>
</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 -->
</chapter> <!-- hooks-libraries -->
......@@ -66,7 +66,6 @@ libdhcp4_la_SOURCES += dhcp4to6_ipc.cc dhcp4to6_ipc.h
libdhcp4_la_SOURCES += dhcp4_lexer.ll location.hh position.hh stack.hh
libdhcp4_la_SOURCES += dhcp4_parser.cc dhcp4_parser.h
libdhcp4_la_SOURCES += parser_context.cc parser_context.h parser_context_decl.h
libdhcp4_la_SOURCES += simple_parser4.cc simple_parser4.h
nodist_libdhcp4_la_SOURCES = dhcp4_messages.h dhcp4_messages.cc
EXTRA_DIST += dhcp4_messages.mes
......
......@@ -8,7 +8,6 @@
#include <cc/command_interpreter.h>
#include <dhcp4/dhcp4_log.h>
#include <dhcp4/simple_parser4.h>
#include <dhcp/libdhcp++.h>
#include <dhcp/option_definition.h>
#include <dhcpsrv/cfg_option.h>
......@@ -21,6 +20,8 @@
#include <dhcpsrv/parsers/host_reservation_parser.h>
#include <dhcpsrv/parsers/host_reservations_list_parser.h>
#include <dhcpsrv/parsers/ifaces_config_parser.h>
#include <dhcpsrv/parsers/option_data_parser.h>
#include <dhcpsrv/parsers/simple_parser4.h>
#include <dhcpsrv/timer_mgr.h>
#include <hooks/hooks_parser.h>
#include <config/command_mgr.h>
......@@ -46,273 +47,6 @@ using namespace isc::hooks;
namespace {
/// @brief Parser for IPv4 pool definitions.
///
/// This is the IPv4 derivation of the PoolParser class and handles pool
/// definitions, i.e. a list of entries of one of two syntaxes: min-max and
/// prefix/len for IPv4 pools. Pool4 objects are created and stored in chosen
/// PoolStorage container.
///
/// It is useful for parsing Dhcp4/subnet4[X]/pool parameters.
class Pool4Parser : public PoolParser {
protected:
/// @brief Creates a Pool4 object given a IPv4 prefix and the prefix length.
///
/// @param addr is the IPv4 prefix of the pool.
/// @param len is the prefix length.
/// @param ignored dummy parameter to provide symmetry between the
/// PoolParser derivations. The V6 derivation requires a third value.
/// @return returns a PoolPtr to the new Pool4 object.
PoolPtr poolMaker (IOAddress &addr, uint32_t len, int32_t) {
return (PoolPtr(new Pool4(addr, len)));
}
/// @brief Creates a Pool4 object given starting and ending IPv4 addresses.
///
/// @param min is the first IPv4 address in the pool.
/// @param max is the last IPv4 address in the pool.
/// @param ignored dummy parameter to provide symmetry between the
/// PoolParser derivations. The V6 derivation requires a third value.
/// @return returns a PoolPtr to the new Pool4 object.
PoolPtr poolMaker (IOAddress &min, IOAddress &max, int32_t) {
return (PoolPtr(new Pool4(min, max)));
}
};
/// @brief Specialization of the pool list parser for DHCPv4
class Pools4ListParser : PoolsListParser {
public:
/// @brief parses the actual structure
///
/// This method parses the actual list of pools.
///
/// @param pools storage container in which to store the parsed pool.
/// @param pools_list a list of pool structures
/// @throw isc::dhcp::DhcpConfigError when pool parsing fails
void parse(PoolStoragePtr pools,
isc::data::ConstElementPtr pools_list) {
BOOST_FOREACH(ConstElementPtr pool, pools_list->listValue()) {
Pool4Parser parser;
parser.parse(pools, pool, AF_INET);
}
}
};
/// @anchor Subnet4ConfigParser
/// @brief This class parses a single IPv4 subnet.
///
/// This is the IPv4 derivation of the SubnetConfigParser class and it parses
/// the whole subnet definition. It creates parsersfor received configuration
/// parameters as needed.
class Subnet4ConfigParser : public SubnetConfigParser {
public:
/// @brief Constructor
///
/// stores global scope parameters, options, option definitions.
Subnet4ConfigParser()