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.