diff --git a/ChangeLog b/ChangeLog index 264a3d164d2639712e58943ebf2dec8fda10d006..09d22fc13af2a1472bad9090ba38a2938dcbf1a9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +1584. [doc] marcin + Documented Kea Configuration Backend in the Kea Administrator + Reference Manual. + (Gitlab #71,!314, git 3a65b7a9104f2a988dacf1acc26312b4259e958d) + 1583. [bug] fdupont, marcin Corrected a bug which caused failures to merge a subnet from the Configuration Backend into the DHCP server's configuration diff --git a/doc/Makefile.am b/doc/Makefile.am index 18aaeaf90de137d41512cf465167d5f582bd654e..8c98c82405b0f5ae35903e37ee0d55d23c3e26a7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -26,6 +26,7 @@ nobase_dist_doc_DATA += examples/kea4/cassandra.json nobase_dist_doc_DATA += examples/kea4/classify.json nobase_dist_doc_DATA += examples/kea4/classify2.json nobase_dist_doc_DATA += examples/kea4/comments.json +nobase_dist_doc_DATA += examples/kea4/config-backend.json nobase_dist_doc_DATA += examples/kea4/dhcpv4-over-dhcpv6.json nobase_dist_doc_DATA += examples/kea4/global-reservations.json nobase_dist_doc_DATA += examples/kea4/ha-load-balancing-primary.json @@ -48,6 +49,7 @@ nobase_dist_doc_DATA += examples/kea6/cassandra.json nobase_dist_doc_DATA += examples/kea6/classify.json nobase_dist_doc_DATA += examples/kea6/classify2.json nobase_dist_doc_DATA += examples/kea6/comments.json +nobase_dist_doc_DATA += examples/kea6/config-backend.json nobase_dist_doc_DATA += examples/kea6/dhcpv4-over-dhcpv6.json nobase_dist_doc_DATA += examples/kea6/duid.json nobase_dist_doc_DATA += examples/kea6/global-reservations.json diff --git a/doc/api/remote-global-parameter4-del.json b/doc/api/remote-global-parameter4-del.json new file mode 100644 index 0000000000000000000000000000000000000000..43cd91544d81f8a28ca6b395649f5d262031a40b --- /dev/null +++ b/doc/api/remote-global-parameter4-del.json @@ -0,0 +1,24 @@ +{ + "name": "remote-global-parameter4-del", + "brief": "This command is used to delete a global DHCPv4 parameter from the configuration database. The server will use the value specified in the configuration file or a default value (if the parameter is not specified in the configuration file) after deleting the parameter from the database.", + "support": [ "kea-dhcp4" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-global-parameter4-del\", + \"arguments\": { + \"parameters\": [ ], + \"remote\": { + + } + } +}", + "cmd-comment": "This command carries the list including exactly one name of the parameter to be deleted.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"DHCPv4 global parameter(s) deleted.\", + \"arguments\": { + \"count\": 1 + } +}" +} diff --git a/doc/api/remote-global-parameter4-get-all.json b/doc/api/remote-global-parameter4-get-all.json new file mode 100644 index 0000000000000000000000000000000000000000..9e6e511a18789fb7aa88f343a8cd3b320482d8cb --- /dev/null +++ b/doc/api/remote-global-parameter4-get-all.json @@ -0,0 +1,38 @@ +{ + "name": "remote-global-parameter4-get-all", + "brief": "This command is used to fetch all global parameters for the server from the specified database.", + "support": [ "kea-dhcp4" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-global-parameter4-get-all\" + \"arguments\": { + \"remote\": { + + } + } +}", + "cmd-comment": "This command contains no arguments besides the optional remote.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"DHCPv4 global parameters found.\", + \"arguments\": { + \"parameters\": [ + { + : , + \"metadata\": { + \"server-tag\": + } + }, + { + : , + \"metadata\": { + \"server-tag\": + } + } + ], + \"count\": 2 + } +}", + "resp-comment": "The returned response contains a list of maps. Each map contains a global parameter name/value pair. The value may be a JSON string, integer, real or boolean. The metadata is appended to each parameter and it provides database specific information associated with the returned objects." +} diff --git a/doc/api/remote-global-parameter4-get.json b/doc/api/remote-global-parameter4-get.json new file mode 100644 index 0000000000000000000000000000000000000000..be62d1910b685d0eb04d2c95fc26f320451e43c1 --- /dev/null +++ b/doc/api/remote-global-parameter4-get.json @@ -0,0 +1,31 @@ +{ + "name": "remote-global-parameter4-get", + "brief": "This command is used to fetch selected global parameter for the server from the specified database.", + "support": [ "kea-dhcp4" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-global-parameter4-get\" + \"arguments\": { + \"parameters\": [ ], + \"remote\": { + + } + } +}", + "cmd-comment": "This command carries a list including exactly one name of the parameter to be fetched.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"DHCPv4 global parameter found.\", + \"arguments\": { + \"parameters\": { + : , + \"metadata\": { + \"server-tag\": + } + }, + \"count\": 1 + } +}", + "resp-comment": "The returned response contains a map with a global parameter name/value pair. The value may be a JSON string, integer, real or boolean. The metadata is included and it provides database specific information associated with the returned object." +} diff --git a/doc/api/remote-global-parameter4-set.json b/doc/api/remote-global-parameter4-set.json new file mode 100644 index 0000000000000000000000000000000000000000..622ca47e324a4517cca3114f7c36ab80e96269af --- /dev/null +++ b/doc/api/remote-global-parameter4-set.json @@ -0,0 +1,24 @@ +{ + "name": "remote-global-parameter4-set", + "brief": "This command is used to create or update one more global parameters in the configuration database.", + "support": [ "kea-dhcp4" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-global-parameter4-set\" + \"arguments\": { + \"parameters\": { + : , + : + }, + \"remote\": { + + } + } +}", + "cmd-comment": "This command carries multiple global parameters with their values. Care should be taken when specifying more than one parameter because in some cases only a subset of the parameters may be successfully stored in the database and other parameters may fail to be stored. In such cases the remote-global-parameter4-get-all may be useful to verify the contents of the database after the update.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"DHCPv4 global parameter(s) successfully set.\" +}" +} diff --git a/doc/api/remote-global-parameter6-del.json b/doc/api/remote-global-parameter6-del.json new file mode 100644 index 0000000000000000000000000000000000000000..faba037271813694e658fc32da0916eaa90df03c --- /dev/null +++ b/doc/api/remote-global-parameter6-del.json @@ -0,0 +1,23 @@ +{ + "name": "remote-global-parameter6-del", + "brief": "This command is used to delete a global DHCPv6 parameter from the configuration database. The server will use the value specified in the configuration file or a default value (if the parameter is not specified in the configuration file) after deleting the parameter from the database.", + "support": [ "kea-dhcp6" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-global-parameter6-del\", + \"arguments\": { + \"parameters\": [ ], + \"remote\": { + + } + } +}", + "cmd-comment": "This command carries the list including exactly one name of the parameter to be deleted.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"DHCPv6 global parameter(s) deleted.\", + \"arguments\": { + \"count\": 1 + }" +} diff --git a/doc/api/remote-global-parameter6-get-all.json b/doc/api/remote-global-parameter6-get-all.json new file mode 100644 index 0000000000000000000000000000000000000000..667c7c8f24fd79a60e4c785f8edef03328dce115 --- /dev/null +++ b/doc/api/remote-global-parameter6-get-all.json @@ -0,0 +1,38 @@ +{ + "name": "remote-global-parameter6-get-all", + "brief": "This command is used to fetch all global parameters for the server from the specified database.", + "support": [ "kea-dhcp6" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-global-parameter6-get-all\" + \"arguments\": { + \"remote\": { + + } + } +}", + "cmd-comment": "This command contains no arguments besides the optional remote.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"DHCPv6 global parameters found.\", + \"arguments\": { + \"parameters\": [ + { + : , + \"metadata\": { + \"server-tag\": + } + }, + { + : , + \"metadata\": { + \"server-tag\": + } + } + ], + \"count\": 2 + } +}", + "resp-comment": "The returned response contains a list of maps. Each map contains a global parameter name/value pair. The value may be a JSON string, integer, real or boolean. The metadata is appended to each parameter and it provides database specific information associated with the returned objects." +} diff --git a/doc/api/remote-global-parameter6-get.json b/doc/api/remote-global-parameter6-get.json new file mode 100644 index 0000000000000000000000000000000000000000..fb94e973e94fe5fef08ffe9485d96ea878fd5e10 --- /dev/null +++ b/doc/api/remote-global-parameter6-get.json @@ -0,0 +1,31 @@ +{ + "name": "remote-global-parameter6-get", + "brief": "This command is used to fetch selected global parameter for the server from the specified database.", + "support": [ "kea-dhcp6" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-global-parameter6-get\" + \"arguments\": { + \"parameters\": [ ], + \"remote\": { + + } + } +}", + "cmd-comment": "This command carries a list including exactly one name of the parameter to be fetched.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"DHCPv6 global parameter found.\", + \"arguments\": { + \"parameters\": { + : , + \"metadata\": { + \"server-tag\": + } + }, + \"count\": 1 + } +}", + "resp-comment": "The returned response contains a map with a global parameter name/value pair. The value may be a JSON string, integer, real or boolean. The metadata is included and it provides database specific information associated with the returned object." +} diff --git a/doc/api/remote-global-parameter6-set.json b/doc/api/remote-global-parameter6-set.json new file mode 100644 index 0000000000000000000000000000000000000000..0ad6d4bf3a91804641076cf3a8698caca420c75d --- /dev/null +++ b/doc/api/remote-global-parameter6-set.json @@ -0,0 +1,24 @@ +{ + "name": "remote-global-parameter6-set", + "brief": "This command is used to create or update one more global DHCP parameters in the configuration database.", + "support": [ "kea-dhcp6" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-global-parameter6-set\" + \"arguments\": { + \"parameters\": { + : , + : + }, + \"remote\": { + + } + } +}", + "cmd-comment": "This command carries multiple global parameters with their values. Care should be taken when specifying more than one parameter because in some cases only a subset of the parameters may be successfully stored in the database and other parameters may fail to be stored. In such cases the remote-global-parameter6-get-all may be useful to verify the contents of the database after the update.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"DHCPv6 global parameter(s) successfully set.\" +}" +} diff --git a/doc/api/remote-network4-del.json b/doc/api/remote-network4-del.json new file mode 100644 index 0000000000000000000000000000000000000000..d72b748e080314bf8bf3c5ed8609e3db023b82cf --- /dev/null +++ b/doc/api/remote-network4-del.json @@ -0,0 +1,29 @@ +{ + "name": "remote-network4-del", + "brief": "This command is used to delete an IPv4 shared network from the configuration database.", + "support": [ "kea-dhcp4" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-network4-del\", + \"arguments\": { + \"shared-networks\": [ + { + \"name\": + } + ], + \"subnets-action\": \"keep\" | \"delete\", + \"remote\": { + + } + } +}", + "cmd-comment": "This command includes a list with exactly one name of the shared network to be deleted. The subnets-action denotes whether the subnets in this shared network should be deleted or not.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"1 IPv4 shared network(s) deleted.\", + \"arguments\": { + \"count\": 1 + } +}" +} diff --git a/doc/api/remote-network4-get.json b/doc/api/remote-network4-get.json new file mode 100644 index 0000000000000000000000000000000000000000..b48ee7a7861691916a5403348b45d7fd753296b5 --- /dev/null +++ b/doc/api/remote-network4-get.json @@ -0,0 +1,39 @@ +{ + "name": "remote-network4-get", + "brief": "This command is used to fetch selected IPv4 shared network for the server from the specified database.", + "support": [ "kea-dhcp4" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-network4-get\" + \"arguments\": { + \"shared-networks\": [ + { + \"name\": + } + ], + \"subnets-include\": \"full\" | \"no\", + \"remote\": { + + } + } +}", + "cmd-comment": "This command includes a list with exactly one name of the shared network to be returned. The subnets-include optional parameter allows for specifying whether the subnets belonging to the shared network should also be returned.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv4 shared network found.\", + \"arguments\": { + \"shared-networks\": [ + { + \"name\": , + \"metadata\": { + \"server-tag\": + }, + + } + ], + \"count\": 1 + } +}", + "resp-comment": "If the subnets are returned with the shared network they are carried in the subnet4 list within the shared network definition. The metadata is included in the returned shared network definition and it provides the database specific information associated with the returned object." +} diff --git a/doc/api/remote-network4-list.json b/doc/api/remote-network4-list.json new file mode 100644 index 0000000000000000000000000000000000000000..e69b5722b7c6246c7eaceb30f75b7e37d61f29ab --- /dev/null +++ b/doc/api/remote-network4-list.json @@ -0,0 +1,38 @@ +{ + "name": "remote-network4-list", + "brief": "This command is used to fetch a list of all IPv4 shared networks from the configuration database.", + "support": [ "kea-dhcp4" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-network4-list\" + \"arguments\": { + \"remote\": { + + } + } +}", + "cmd-comment": "This command contains no arguments besides the optional remote.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"2 IPv4 shared network(s) found.\", + \"arguments\": { + \"shared-networks\": [ + { + \"name\": , + \"metadata\": { + \"server-tag\": + } + }, + { + \"name\": , + \"metadata\": { + \"server-tag\": + } + } + ], + \"count\": 2 + } +}", + "resp-comment": "The returned response contains the list of maps. Each map contains the shared network name and the metadata which provides database specific information associated with the shared network. The returned list does not contain full definitions of the shared networks. Use remote-network4-get to fetch the full information about the selected shared networks." +} diff --git a/doc/api/remote-network4-set.json b/doc/api/remote-network4-set.json new file mode 100644 index 0000000000000000000000000000000000000000..435d3e382ae937b338c9144b3a0bd4f7e9d69bd7 --- /dev/null +++ b/doc/api/remote-network4-set.json @@ -0,0 +1,25 @@ +{ + "name": "remote-network4-set", + "brief": "This command is used to create or replace an IPv4 shared network in the configuration database.", + "support": [ "kea-dhcp4" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-network4-set\", + \"arguments\": { + \"shared-networks\": [ + { + + } + ], + \"remote\": { + + } + } +}", + "cmd-comment": "The provided list must contain exactly one shared network specification. It must not contain subnets (\"subnet4\" parameter). The subnets are added to the shared network using remote-subnet4-set command.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv4 shared network successfully set.\" +}" +} diff --git a/doc/api/remote-network6-del.json b/doc/api/remote-network6-del.json new file mode 100644 index 0000000000000000000000000000000000000000..570a132097805c07447832793f4095ca655c350a --- /dev/null +++ b/doc/api/remote-network6-del.json @@ -0,0 +1,29 @@ +{ + "name": "remote-network6-del", + "brief": "This command is used to delete an IPv6 shared network from the configuration database.", + "support": [ "kea-dhcp6" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-network6-del\", + \"arguments\": { + \"shared-networks\": [ + { + \"name\": + } + ], + \"subnets-action\": \"keep\" | \"delete\", + \"remote\": { + + } + } +}", + "cmd-comment": "This command includes a list with exactly one name of the shared network to be deleted. The subnets-action denotes whether the subnets in this shared network should be deleted or not.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"1 IPv6 shared network(s) deleted.\", + \"arguments\": { + \"count\": 1 + } +}" +} diff --git a/doc/api/remote-network6-get.json b/doc/api/remote-network6-get.json new file mode 100644 index 0000000000000000000000000000000000000000..11ddab120377c7d76a8cf30ba61014a32ac1d292 --- /dev/null +++ b/doc/api/remote-network6-get.json @@ -0,0 +1,39 @@ +{ + "name": "remote-network6-get", + "brief": "This command is used to fetch selected IPv6 shared network for the server from the specified database.", + "support": [ "kea-dhcp6" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-network6-get\" + \"arguments\": { + \"shared-networks\": [ + { + \"name\": + } + ], + \"subnets-include\": \"full\" | \"no\", + \"remote\": { + + } + } +}", + "cmd-comment": "This command includes a list with exactly one name of the shared network to be returned. The subnets-include optional parameter allows for specifying whether the subnets belonging to the shared network should also be returned.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv6 shared network found.\", + \"arguments\": { + \"shared-networks\": [ + { + \"name\": , + \"metadata\": { + \"server-tag\": + }, + + } + ], + \"count\": 1 + } +}", + "resp-comment": "If the subnets are returned with the shared network they are carried in the subnet6 list within the shared network definition. The metadata is included in the returned shared network definition and it provides the database specific information associated with the returned object." +} diff --git a/doc/api/remote-network6-list.json b/doc/api/remote-network6-list.json new file mode 100644 index 0000000000000000000000000000000000000000..9fb1e0edcdce0d2d05e098328fae83431501a34b --- /dev/null +++ b/doc/api/remote-network6-list.json @@ -0,0 +1,38 @@ +{ + "name": "remote-network6-list", + "brief": "This command is used to fetch a list of all IPv6 shared networks from the configuration database.", + "support": [ "kea-dhcp6" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-network6-list\" + \"arguments\": { + \"remote\": { + + } + } +}", + "cmd-comment": "This command contains no arguments besides the optional remote.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"2 IPv6 shared network(s) found.\", + \"arguments\": { + \"shared-networks\": [ + { + \"name\": , + \"metadata\": { + \"server-tag\": + } + }, + { + \"name\": , + \"metadata\": { + \"server-tag\": + } + } + ], + \"count\": 2 + } +}", + "resp-comment": "The returned response contains the list of maps. Each map contains the shared network name and the metadata which provides database specific information associated with the shared network. The returned list does not contain full definitions of the shared networks. Use remote-network6-get to fetch the full information about the selected shared networks." +} diff --git a/doc/api/remote-network6-set.json b/doc/api/remote-network6-set.json new file mode 100644 index 0000000000000000000000000000000000000000..1ed48e25a2ca371b591b6258fa4a70ced9db9d68 --- /dev/null +++ b/doc/api/remote-network6-set.json @@ -0,0 +1,25 @@ +{ + "name": "remote-network6-set", + "brief": "This command is used to create or replace an IPv6 shared network in the configuration database.", + "support": [ "kea-dhcp6" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-network6-set\", + \"arguments\": { + \"shared-networks\": [ + { + + } + ], + \"remote\": { + + } + } +}", + "cmd-comment": "The provided list must contain exactly one shared network specification. It must not contain subnets (\"subnet6\" parameter). The subnets are added to the shared network using remote-subnet6-set command.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv6 shared network successfully set.\" +}" +} diff --git a/doc/api/remote-option-def4-del.json b/doc/api/remote-option-def4-del.json new file mode 100644 index 0000000000000000000000000000000000000000..0eeee2cf5db224047cbcb7237c179a0f3636714f --- /dev/null +++ b/doc/api/remote-option-def4-del.json @@ -0,0 +1,27 @@ +{ + "name": "remote-option-def4-del", + "brief": "This command is used to delete a DHCPv4 option definition from the configuration database.", + "support": [ "kea-dhcp4" ], + "avail": "1.6.0", + "hook": "cb_cmds", + "cmd-syntax": "{ + \"command\": \"remote-option-def4-del\", + \"arguments\": { + \"option-defs\": [ { + \"code\":