From: Suzanne Goldlust Date: Wed, 24 Nov 2021 23:29:04 +0000 (+0000) Subject: [#2202] Text edits X-Git-Tag: Kea-2.1.2~257 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1112e7909a34964a2d5323330c191539d6f26903;p=thirdparty%2Fkea.git [#2202] Text edits --- diff --git a/doc/sphinx/arm/hooks-stat-cmds.rst b/doc/sphinx/arm/hooks-stat-cmds.rst index 4d628eb558..d94ec444a3 100644 --- a/doc/sphinx/arm/hooks-stat-cmds.rst +++ b/doc/sphinx/arm/hooks-stat-cmds.rst @@ -1,7 +1,7 @@ .. _hooks-stat-cmds: -stat_cmds: Supplemental Statistics Commands -=========================================== +``stat_cmds``: Supplemental Statistics Commands +=============================================== This library provides additional commands for retrieving lease statistics from Kea DHCP servers. These commands were added to address @@ -9,12 +9,12 @@ an issue with obtaining accurate lease statistics in deployments running multiple Kea servers that use a shared lease backend. The in-memory statistics kept by individual servers only track lease changes made by that server; thus, in a deployment with multiple servers (e.g. two -kea-dhcp6 servers using the same PostgreSQL database for lease storage), +``kea-dhcp6`` servers using the same PostgreSQL database for lease storage), these statistics are incomplete. The MySQL and PostgreSQL backends in Kea track lease allocation changes as they occur via database triggers. -Additionally, all four lease backends were extended to support -retrieving lease statistics for all subnets, a single subnet, or a range -of subnets. Finally, this library was constructed to provide commands +Additionally, all the lease backends were extended to support +retrieving lease statistics for a single subnet, a range +of subnets, or all subnets. Finally, this library provides commands for retrieving these statistics. .. note:: @@ -28,14 +28,14 @@ The commands currently provided by this library are: - ``stat-lease6-get`` - fetches DHCPv6 lease statistics. -The stat commands library is part of the open source code and is +The statistics commands library is part of the open source code and is available to every Kea user. All commands use JSON syntax and can be issued directly to the servers via either the control channel (see :ref:`ctrl-channel`) or the Control Agent (see :ref:`kea-ctrl-agent`). -This library may be loaded by both the kea-dhcp4 and kea-dhcp6 servers. It +This library may be loaded by both the ``kea-dhcp4`` and ``kea-dhcp6`` servers. It is loaded in the same way as other libraries and currently has no parameters: @@ -51,9 +51,9 @@ parameters: } In a deployment with multiple Kea DHCP servers sharing a common lease -storage, this hooks library may be loaded by any or all of the servers. However, one -thing to keep in mind is that a server's response to a -stat-lease[46]-get command will only contain data for subnets known to +storage, this hook library may be loaded by any or all of the servers. However, +a server's response to a +``stat-lease[46]-get`` command will only contain data for subnets known to that server. In other words, if a subnet does not appear in a server's configuration, Kea will not retrieve statistics for it. @@ -61,36 +61,36 @@ configuration, Kea will not retrieve statistics for it. .. _command-stat-lease6-get: -The stat-lease4-get, stat-lease6-get Commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The ``stat-lease4-get``, ``stat-lease6-get`` Commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``stat-lease4-get`` and ``stat-lease6-get`` commands fetch lease statistics for a range of known subnets. The range of subnets is determined through the use of optional command input parameters: - ``subnet-id`` - the ID of the subnet for which lease statistics - should be fetched. Use this to get statistics for a single subnet. If + should be fetched; used to get statistics for a single subnet. If the subnet does not exist, the command result code is 3 (i.e. - CONTROL_RESULT_EMPTY). + ``CONTROL_RESULT_EMPTY``). - ``subnet-range`` - a pair of subnet IDs which describe an inclusive range of subnets for which statistics should be retrieved. The range may include one or more IDs that correspond to no subnet; in this - case, the command will only output lease statistics for those that + case, the command only outputs lease statistics for those that exist. However, if the range does not include any known subnets, the - command result code is 3 (i.e. CONTROL_RESULT_EMPTY). + command result code is 3 (i.e. ``CONTROL_RESULT_EMPTY``). - ``first-subnet-id`` - the ID of the first subnet in the range. - ``last-subnet-id`` - the ID of the last subnet in the range. -The use of subnet-id and subnet-range are mutually exclusive. If no +The use of ``subnet-id`` and ``subnet-range`` are mutually exclusive. If no parameters are given, the result will contain data for all known -subnets. Note that in configurations with large numbers of subnets, this +subnets. Note that in configurations with many subnets, this can result in a large response. The following command fetches lease statistics for all known subnets -from a kea-dhcp4 server: +from a ``kea-dhcp4`` server: :: @@ -99,7 +99,7 @@ from a kea-dhcp4 server: } The following command fetches lease statistics for subnet ID 10 from a -kea-dhcp6 server: +``kea-dhcp6`` server: :: @@ -111,7 +111,7 @@ kea-dhcp6 server: } The following command fetches lease statistics for all subnets with IDs -in the range 10 through 50 from a kea-dhcp4 server: +in the range 10 through 50 from a ``kea-dhcp4`` server: :: @@ -132,13 +132,13 @@ The response to either command will contain three elements: - ``0`` - the command was successful; - - ``1`` - an error occurred, and an explanation will be the "text" + - ``1`` - an error occurred, and an explanation is the "text" element; or - ``2`` - the fetch found no matching data. - ``text`` - an explanation of the command outcome. When the command - succeeds it will contain the command name along with the number of + succeeds, it contains the command name along with the number of rows returned. - ``arguments`` - a map containing the data returned by the command as @@ -220,9 +220,9 @@ The response to a DHCPv4 command might look as follows: } } -The response to a DHCPv6 command might look as follows (subnet 10 has no +The response to a DHCPv6 command might look as follows, assuming subnet 10 has no prefix pools, subnet 20 has no NA pools, and subnet 30 has both NA and -PD pools): +PD pools: ::