From: Marcin Siodelski Date: Wed, 17 Jul 2019 17:45:03 +0000 (+0200) Subject: [#643,!421] Extended cb_cmds hook documentation with the server tags. X-Git-Tag: Kea-1.6.0-beta2~18 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bbd63f69a3669edbbe7858218e7d61f36dae6a9c;p=thirdparty%2Fkea.git [#643,!421] Extended cb_cmds hook documentation with the server tags. Each command description now comes with more examples of server tags usage and the doc explicitly states when the server-tags are mandaotry and when they must not be included in the command. --- diff --git a/doc/guide/hooks-cb-cmds.xml b/doc/guide/hooks-cb-cmds.xml index e05a66ada1..ca3660b425 100644 --- a/doc/guide/hooks-cb-cmds.xml +++ b/doc/guide/hooks-cb-cmds.xml @@ -374,7 +374,8 @@ specified in the configuration file for this parameter or a default value if the parameter is not specified in the configuration file. The following command attempts to delete the DHCPv4 - renew-timer parameter from the database: + renew-timer parameter common for all servers from + the database: { "command": "remote-global-parameter4-del", @@ -382,11 +383,18 @@ "parameters": [ "renew-timer" ], "remote": { "type": "mysql" - } + }, + "server-tags": [ "all" ] } } + + + If the server specific parameter is to be deleted, the server-tags + list must contain the tag of the appropriate server. There must be exactly one + server tag specified in this list. +
@@ -394,7 +402,7 @@ These commands are used to fetch a scalar global DHCP parameter from the configuration database. The following command attempts to fetch the - boot-file-name parameter: + boot-file-name parameter for the "server1": { "command": "remote-global-parameter4-get", @@ -402,7 +410,8 @@ "parameters": [ "boot-file-name" ], "remote": { "type": "mysql" - } + }, + "server-tags": [ "server1" ] } } @@ -421,7 +430,7 @@ "parameters": { "boot-file-name": "/dev/null", "metadata": { - "server-tag": "all" + "server-tags": [ "all" ] } }, "count": 1 @@ -430,6 +439,14 @@ + + Note that the response above indicates that the returned parameter is associated + with "all" servers rather than "server1" used in the command. This indicates + that there is no server1 specific value in the database. Therefore, the value + shared by all servers is returned. If there was the server1 specific value + in the database this value would be returned instead. + + The example response for the integer value is: @@ -440,7 +457,7 @@ "parameters": { "renew-timer": 2000, "metadata": { - "server-tag": "all" + "server-tags": [ "server1" ] } }, "count": 1 @@ -459,7 +476,7 @@ "parameters": { "t1-percent": 0.85, "metadata": { - "server-tag": "all" + "server-tags": [ "all" ] } }, "count": 1 @@ -478,7 +495,7 @@ "parameters": { "match-client-id": true, "metadata": { - "server-tag": "all" + "server-tags": [ "server2" ] } }, "count": 1 @@ -491,8 +508,68 @@
remote-global-parameter4-get-all, remote-global-parameter6-get-all commands These commands are used to - fetch all global DHCP parameters from the database. They include no arguments - besides the optional remote map. + fetch all global DHCP parameters from the database for the specified server. + The following example demonstrates how to fetch all global parameters to be + used by the server "server1": + +{ + \"command\": \"remote-global-parameter4-get-all\", + \"arguments\": { + \"remote\": { + "type": "mysql" + }, + \"server-tags\": [ "server1" ] + } +} + + + + + The example response may look as follows: + +{ + "result": 0, + "text": "DHCPv4 global parameters found.", + "arguments": { + "parameters": [ + { + "boot-file-name": "/dev/null", + "metadata": { + "server-tags": [ "server1" ] + } + }, + { + "match-client-id": true, + "metadata": { + "server-tags": [ "all" ] + } + } + ], + "count": 2 + } +} + + + + + The example response contains two parameters, one string parameter and one + boolean parameter. The metadata returned for each parameter indicates + if this parameter is specific to the "server1" or all servers. Since the + match-client-id value is associated with "all" servers + it indicates that there is no server1 specific setting for this parameter. + Each parameter always has exactly one server tag associated with it, because + the global parameters are non-shareable configuration elements. + + + + + If the server tag is set to "all" in the command, the response will + contain only the global parameters associated with the logical server + "all". When the server tag points to the specific server (as in the + example above), the returned list combines parameters associated with + this server and all servers, but the former take precedence. + +
@@ -501,7 +578,7 @@ create scalar global DHCP parameters in the database. If any of the parameters already exists, its value is replaced as a result of this command. It is possible to set multiple parameters within a single command, each having - one of the four types: a string, integer, real and boolean. For example: + one of the four types: a string, integer, real or boolean. For example: { "command": "remote-global-parameter4-set" @@ -514,7 +591,8 @@ }, "remote": { "type": "mysql" - } + }, + "server-tags": [ "server1" ] } } @@ -527,6 +605,11 @@ recommended to use remote-global-parameter[46]-get-all to check which of the parameters have been stored/updated successfully and which failed. + + The server-tags list is mandatory and it must + contain a single server tag or the keyword "all". In the example above, + all specified parameters are associated with the "server1" server. +
@@ -562,6 +645,11 @@ network[46]-del commands with respect to the subnets-action. + + + Note that the server-tags parameter must not be used + for this command. +
@@ -593,20 +681,131 @@ } + + + Note that the server-tags parameter must not be used + for this command. +
remote-network4-list, remote-network6-list commands These commands are used to list all - IPv4 or IPv6 shared networks in the particular database. The returned information - about each shared network merely contains the shared network name and the metadata. In - order to fetch the detailed information about the selected shared network, - use the remote-network[46]-get command. + IPv4 or IPv6 shared networks for a server. - The remote-network[46]-list takes no argument except - the optional remote map. + The following command retrieves all shared networks to be used by the + "server1" and "server2": + +{ + "command": "remote-network4-list" + "arguments": { + "remote": { + "type": "mysql" + }, + "server-tags": [ "server1", "server2" ] + } +} + + + The server-tags parameter is mandatory and it contains + one or more server tags. It may contain the keyword "all" to fetch the shared + networks associated with all servers. When the server-tags + list contains the null value the returned response contains + a list of unassigned shared networks, i.e. the networks which are associated + with no servers. For example: + + +{ + "command": "remote-network4-list" + "arguments": { + "remote": { + "type": "mysql" + }, + "server-tags": [ null ] + } +} + + + + + The example response to this command when non-null server tags are specified + looks similar to this: + +{ + "result": 0, + "text": "3 IPv4 shared network(s) found.", + "arguments": { + "shared-networks": [ + { + "name": "ground floor", + "metadata": { + "server-tags": [ "all" ] + } + }, + { + "name": "floor2", + "metadata": { + "server-tags": [ "server1" ] + } + }, + { + "name": "floor3", + "metadata": { + "server-tags": [ "server2" ] + } + } + ], + "count": 3 + } +} + + + + + The returned information about each shared network merely contains the + shared network name and the metadata. In order to fetch the detailed + information about the selected shared network, use the + remote-network[46]-get command. + + + + The example response above contains three shared networks. One of the + shared networks is associated will all servers, so it is included in + the list of shared networks to be used by the "server1" and "server2". + The remaining two shared networks are returned because one of them + is associated with the "server1" and another one is associated with + the "server2". + + + + When listing unassigned shared networks, the response will look similar + to this: + +{ + "result": 0, + "text": "1 IPv4 shared network(s) found.", + "arguments": { + "shared-networks": [ + { + "name": "fancy", + "metadata": { + "server-tags": [ null ] + } + } + ], + "count": 3 + } +} + + + + + The null value in the metadata indicates that the + returned shared network is unassigned. + +
@@ -644,7 +843,8 @@ ], "remote": { "type": "mysql" - } + }, + "server-tags": [ "all" ] } } @@ -658,6 +858,13 @@ the default values will be used. + + The server-tags list is mandatory for this command + and it must include one or more server tags. As a result the shared network + is associated with all listed servers. The shared network may be associated + with all servers connecting to the database when the keyword "all" is included. + + Same as for other "set" commands, this command replaces the entire @@ -688,14 +895,20 @@ ], "remote": { "type": "mysql" - } + }, + "server-tags": [ "server1" ] } } - deletes the definition of the option having the code of 1 and - belonging to the option space "isc". The default option spaces - are "dhcp4" and "dhcp6" for the DHCPv4 and DHCPv6 top level options - respectively. + deletes the definition of the option associated with the "server1", + having the code of 1 and belonging to the option space "isc". The + default option spaces are "dhcp4" and "dhcp6" for the DHCPv4 and + DHCPv6 top level options respectively. If there is no such option + explicitly associated with the server1, no option is deleted. In + order to delete an option belonging to "all" servers, the keyword + "all" must be used as server tag. The server-tags + list must contain exactly one tag. It must not include the + null value.
@@ -708,7 +921,8 @@ options respectively. The following command retrieves a DHCPv4 option definition - having the code of 1 and belonging to option space "isc": + associated with all servers, having the code of 1 and belonging to + the option space "isc": { "command": "remote-option-def4-get" @@ -721,18 +935,69 @@ ], "remote": { "type": "mysql" - } + }, + "server-tags": [ "all" ] } } + + The server-tags list must include exactly + one server tag or the keyword "all". It must not contain the + null value. +
remote-option-def4-get-all, remote-option-def6-get-all commands These commands are used to - fetch all DHCP option definitions from the database. It takes no - arguments except the optional remote map. + fetch all DHCP option definitions from the database for the particular + server or all servers. For example: + +{ + "command": "remote-option-def6-get-all" + "arguments": { + "remote": { + "type": "mysql" + }, + "server-tags": [ "all" ] + } +} + + + This command attempts to fetch all DHCPv6 option definitions associated + with "all" servers. The server-tags list is mandatory for + this command and it must include exactly one server tag or the keyword "all". + It must not include the null value. + + The following is the example response to this command: + +{ + \"result\": 0, + \"text\": \"1 DHCPv6 option definition(s) found.\", + \"arguments\": { + \"option-defs\": [ + { + "name": "bar", + "code": 1012, + "space": "dhcp6", + "type": "record", + "array": true, + "record-types": "ipv6-address, uint16", + "encapsulate": "", + "metadata": { + "server-tags": [ "all" ] + } + } + ], + \"count\": 1 + } +} + + + The response contains an option definition associated with all servers + as indicated by the metadata. +
@@ -743,7 +1008,7 @@ same as in the Kea configuration file (see and ). The following command creates the DHCPv4 option definition in the top - level "dhcp4" option space: + level "dhcp4" option space and associates it with the "server1": { "command": "remote-option-def4-set", @@ -761,11 +1026,16 @@ ], "remote": { "type": "mysql" - } + }, + "server-tags": [ "server1" ] } } + + The server-tags list must include exactly one + server tag or the keyword "all". It must not contain the + null value.
@@ -785,14 +1055,21 @@ ], "remote": { "type": "mysql" - } + }, + "server-tags": [ "server1" ] } } The "dhcp4" is the top level option space where the standard DHCPv4 - options belong. + options belong. The server-tags is mandatory and + it must include a single option tag or the keyword "all". If the + explicit server tag is specified then this command attempts to delete + a global option associated with this server. If there is no such option + associated with the given server, no option is deleted. In order to + delete the option associated with all servers, the keyword "all" + must be specified.
@@ -805,7 +1082,8 @@ respectively. - The following command retrieves the IPv6 "DNS Servers" (code 23) option: + The following command retrieves the IPv6 "DNS Servers" (code 23) option + associated with all servers: { "command": remote-option6-global-get", @@ -818,18 +1096,63 @@ ], "remote": { "type": "mysql" - } + }, + "server-tags": [ "all" ] } } + + The server-tags is mandatory and it must include + exactly one server tag or the keyword "all". It must not contain the + null value. +
remote-option4-global-get-all, remote-option6-global-get-all commands These commands are used to fetch - all global DHCP options from the configuration database. It takes no arguments - except the optional remote map. + all global DHCP options from the configuration database for the particular server + or for all servers. The following command fetches all global DHCPv4 options for + the "server1": + +{ + \"command\": \"remote-option6-global-get-all\", + \"arguments\": { + \"remote\": { + "type": "mysql" + }, + \"server-tags\": [ "server1" ] + } +} + + + The server-tags list is mandatory for this command and + it must contain exactly one server tag or a keyword "all". It must not contain + the null value. The following is the example response to this + command with a single option being associated with the "server1" returned: + +{ + "result": 0, + "text": "DHCPv4 options found.", + "arguments": { + "options": [ + { + "name": "domain-name-servers", + "code": 6, + "space": "dhcp4", + "csv-format": false, + "data": "192.0.2.3", + "metadata": { + "server-tags": [ "server1" ] + } + } + ], + "count": 1 + } +} + +
@@ -851,17 +1174,22 @@ ], "remote": { "type": "mysql" - } + }, + "server-tags": [ "server1" ] } } - - Note that specifying an option name instead of the option code only works - reliably for the standard DHCP options. When specifying a value for the - user defined DHCP option, the option code should be specified instead of - the name. For example: - + The server-tags list is mandatory for this command + and it must include exactly one server tag or the keyword "all". It must + not include the null value. The command above associates + the option with the "server1" server. + + Note that specifying an option name instead of the option code only works + reliably for the standard DHCP options. When specifying a value for the + user defined DHCP option, the option code should be specified instead of + the name. For example: + { "command": "remote-option6-global-set", "arguments": { @@ -871,10 +1199,11 @@ "space": "isc", "data": "2001:db8:1::1" } - ] + ], + "server-tags": [ "server1" ] } } - +
@@ -900,6 +1229,9 @@ } + The server-tags parameter must not be used + with this command. +
@@ -923,6 +1255,8 @@ } + The server-tags parameter must not be used with + this command.
@@ -946,6 +1280,8 @@ } + The server-tags parameter must not be used with + this command.
@@ -969,19 +1305,111 @@ } + The server-tags parameter must not be used with + this command.
remote-subnet4-list, remote-subnet6-list commands These commands are used to list - all IPv4 or IPv6 subnets from the database. It takes no parameters - except the optional remote map. - The returned information about each subnet is limited to subnet identifier, + all IPv4 or IPv6 subnets from the database for selected servers or all + servers. The following command retrieves all servers to be used by the + "server1" and "server2": + +{ + \"command\": \"remote-subnet4-list\" + \"arguments\": { + \"remote\": { + "type": "mysql" + }, + \"server-tags\": [ "server1", "server2" ] + } +} + + + The server-tags parameter is mandatory and it contains + one or more server tags. It may contain the keyword "all" to fetchg the subnets + associated with all servers. When the server-tags list contains + the null value the returned response contains a list of + unassigned subnets, i.e. the subnets which are associated with no servers. + For example: + +{ + \"command\": \"remote-subnet4-list\" + \"arguments\": { + \"remote\": { + "type": "mysql" + }, + \"server-tags\": [ null ] + } +} + + + The example response to this command when non-null server tags are specified + looks similar to this: + +{ + "result": 0, + "text": "2 IPv4 subnet(s) found.", + "arguments": { + "subnets": [ + { + "id": 1, + "subnet": "192.0.2.0/24", + "shared-network-name": null, + "metadata": { + "server-tags": [ "server1", "server2" ] + } + }, + { + "id": 2, + "subnet": "192.0.3.0/24", + "shared-network-name": null, + "metadata": { + "server-tags": [ "all" ] + } + } + ], + "count": 2 + } +} + + + The returned information about each subnet is limited to subnet identifier, prefix and associated shared network name. In order to retrieve full information about the selected subnet use the remote-subnet[46]-get-by-id or remote-subnet[46]-get-by-prefix. + The example response above contains two subnets. One of the subnets is + associated with both servers: "server1" and "server2". The second subnet is + associated with all servers, thus it is also present in the configuration for + the "server1" and "server2". + + When listing unassigned subnets, the response will look similar to this: + +{ + "result": 0, + "text": "1 IPv4 subnet(s) found.", + "arguments": { + "subnets": [ + { + "id": 3, + "subnet": "192.0.4.0/24", + "shared-network-name": null, + "metadata": { + "server-tags": [ null ] + } + } + ], + "count": 1 + } +} + + + The null value in the metadata indicates that the + returned subnet is unassigned. +
@@ -1018,7 +1446,8 @@ ], "remote": { "type": "mysql" - } + }, + "server-tags": [ "all" ] } } @@ -1047,7 +1476,8 @@ "data": "192.0.2.1" } ] } - ] + ], + "server-tags": [ "all" ] } } @@ -1057,7 +1487,12 @@ new subnet having the same parameters but it becomes global. The shared-network-name parameter is mandatory - for the remote-subnet4-set command. + for the remote-subnet4-set command. The + server-tags list is mandatory and it must include + one or more server tags. As a result, the subnet is associated with + all of the listed servers. It may also be associated with "all" servers + connecting to the database when the keyword "all" is used as the server + tag.