From: Suzanne Goldlust Date: Tue, 30 Nov 2021 20:31:21 +0000 (+0000) Subject: [#2202] Text edits X-Git-Tag: Kea-2.1.2~255 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d7d854df8dd2f20d1ea4081ec4a209fc385d4885;p=thirdparty%2Fkea.git [#2202] Text edits --- diff --git a/doc/sphinx/arm/hooks-host-cache.rst b/doc/sphinx/arm/hooks-host-cache.rst index f294bdcb88..5ed37105a2 100644 --- a/doc/sphinx/arm/hooks-host-cache.rst +++ b/doc/sphinx/arm/hooks-host-cache.rst @@ -1,9 +1,9 @@ .. _hooks-host-cache: -host_cache: Caching Host Reservations -===================================== +``host_cache``: Caching Host Reservations +========================================= -Some database backends, such as RADIUS, are considered slow and may take +Some database backends, such as RADIUS, are slow and may take a long time to respond. Since Kea in general is synchronous, backend performance directly affects DHCP performance. To minimize the impact and improve performance, the Host Cache library provides a way to @@ -13,19 +13,19 @@ information in the database. .. note:: - This library may only be loaded by the ``kea-dhcp4`` or + This library can only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` process. -In principle, this hooks library can be used with any backend that may +In principle, this hook library can be used with any backend that may introduce performance degradation (MySQL, PostgreSQL, Cassandra, or RADIUS). Host Cache must be loaded for the RADIUS accounting mechanism to work. -The Host Cache hooks library is currently very simple. It takes only one -optional parameter ("maximum"), which defines the maximum number of hosts +The Host Cache hook library is very simple. It takes only one +optional parameter (``maximum``), which defines the maximum number of hosts to be cached. If not specified, the default value of 0 is used, which -means there is no limit. This hooks library can be loaded the same way as -any other hooks library; for example, this configuration could be used: +means there is no limit. This hook library can be loaded the same way as +any other hook library; for example, this configuration could be used: :: @@ -44,7 +44,7 @@ any other hooks library; for example, this configuration could be used: } } ] -Once loaded, the Host Cache hooks library provides a number of new +Once loaded, the Host Cache hook library provides a number of new commands which can be used either over the control channel (see :ref:`ctrl-channel-client`) or the RESTful API (see :ref:`agent-overview`). An example RESTful API client is described in @@ -53,8 +53,8 @@ available. .. _command-cache-flush: -The cache-flush Command -~~~~~~~~~~~~~~~~~~~~~~~ +The ``cache-flush`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command allows removal of a specified number of cached host entries. It takes one parameter, which defines the number of hosts to be @@ -67,14 +67,14 @@ removed. An example usage looks as follows: "arguments": 1000 } -This command will remove 1000 hosts. To delete all cached -hosts, please use cache-clear instead. The hosts are stored in FIFO +This command removes 1000 hosts; to delete *all* cached +hosts, use ``cache-clear`` instead. The hosts are stored in FIFO (first-in, first-out) order, so the oldest entries are always removed. .. _command-cache-clear: -The cache-clear Command -~~~~~~~~~~~~~~~~~~~~~~~ +The ``cache-clear`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command allows removal of all cached host entries. An example usage looks as follows: @@ -85,13 +85,13 @@ looks as follows: "command": "cache-clear" } -This command will remove all hosts. To delete only a certain -number of cached hosts, please use cache-flush instead. +This command removes all hosts. To delete only a certain +number of cached hosts, please use ``cache-flush`` instead. .. _command-cache-size: -The cache-size Command -~~~~~~~~~~~~~~~~~~~~~~ +The ``cache-size`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~ This command returns the number of host entries. An example usage looks as follows: @@ -104,11 +104,11 @@ as follows: .. _command-cache-write: -The cache-write Command -~~~~~~~~~~~~~~~~~~~~~~~ +The ``cache-write`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~ In general, the cache content is considered a runtime state and the -server can be shut down or restarted as usual; the cache will then be +server can be shut down or restarted as usual; the cache is then repopulated after restart. However, there are some cases when it is useful to store the contents of the cache. One such case is RADIUS, where the cached hosts also retain additional cached RADIUS attributes; @@ -128,14 +128,14 @@ example usage looks as follows: "arguments": "/tmp/kea-host-cache.json" } -This causes the contents to be stored in the /tmp/kea-host-cache.json -file. That file can then be loaded with the cache-load command or +This causes the contents to be stored in the ``/tmp/kea-host-cache.json`` +file. That file can then be loaded with the ``cache-load`` command or processed by any other tool that is able to understand JSON format. .. _command-cache-load: -The cache-load Command -~~~~~~~~~~~~~~~~~~~~~~ +The ``cache-load`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~ See the previous section for a discussion of use cases where it may be useful to write and load contents of the host cache to disk. @@ -151,16 +151,16 @@ example usage looks as follows: "arguments": "/tmp/kea-host-cache.json" } -This command will store the contents to the /tmp/kea-host-cache.json -file. That file can then be loaded with the cache-load command or +This command stores the contents to the ``/tmp/kea-host-cache.json`` +file. That file can then be loaded with the ``cache-load`` command or processed by any other tool that is able to understand JSON format. .. _command-cache-get: -The cache-get Command -~~~~~~~~~~~~~~~~~~~~~ +The ``cache-get`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~ -This command is similar to cache-write, but instead of writing the cache +This command is similar to ``cache-write``, but instead of writing the cache contents to disk, it returns the contents to whoever sent the command. This command allows the contents of a file on disk to be loaded into an @@ -173,15 +173,15 @@ example usage looks as follows: "command": "cache-get" } -This command will return all the cached hosts. Note that the response +This command returns all the cached hosts; the response may be large. .. _command-cache-get-by-id: -The cache-get-by-id Command -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The ``cache-get-by-id`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This command is similar to cache-get, but instead of returning the whole +This command is similar to ``cache-get``, but instead of returning the whole content it returns only the entries matching the given identifier. It takes one parameter, which defines the identifier of wanted cached @@ -196,22 +196,22 @@ host reservations. An example usage looks as follows: } } -This command will return all the cached hosts with the given hardware +This command returns all the cached hosts with the given hardware address. .. _command-cache-insert: -The cache-insert Command -~~~~~~~~~~~~~~~~~~~~~~~~ +The ``cache-insert`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command may be used to manually insert a host into the cache; there are very few use cases when this command might be useful. This command expects its arguments to follow the usual syntax for specifying host reservations (see :ref:`host-reservation-v4` or -:ref:`host-reservation-v6`), with one difference: the subnet-id -value must be specified explicitly. +:ref:`host-reservation-v6`), with one difference: the ``subnet-id`` +value must be explicitly specified. -An example command that will insert an IPv4 host into the host cache +An example command to insert an IPv4 host into the host cache looks as follows: :: @@ -235,7 +235,7 @@ looks as follows: } } -An example command that will insert an IPv6 host into the host cache +An example command to insert an IPv6 host into the host cache looks as follows: :: @@ -262,26 +262,26 @@ looks as follows: .. _command-cache-remove: -The cache-remove Command -~~~~~~~~~~~~~~~~~~~~~~~~ +The ``cache-remove`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sometimes it is useful to remove a single entry from the host cache. A -good use case is a situation where the device is up, Kea has already +Sometimes it is useful to remove a single entry from the host cache: for +example, consider a situation where the device is active, Kea has already provided configuration, and the host entry is in cache. As a result of administrative action (e.g. the customer hasn't paid their bills or has -perhaps been upgraded to better service), the information in the backend +been upgraded to better service), the information in the backend database (e.g. MySQL or RADIUS) is being updated. However, since the cache is in use, Kea does not notice the change as the cached values are used. The -cache-remove command can solve this problem by removing a cached entry +``cache-remove`` command can solve this problem by removing a cached entry after administrative changes. -The cache-remove command works similarly to the reservation-get command. -It allows querying by two parameters: either subnet-id4 or subnet-id6; -or ip-address (may be an IPv4 or IPv6 address), hw-address (specifies -hardware/MAC address), duid, circuit-id, client-id, or flex-id. +The ``cache-remove`` command works similarly to the ``reservation-get`` command. +It allows querying by two parameters: either ``subnet-id4`` or ``subnet-id6``; +or ``ip-address`` (may be an IPv4 or IPv6 address), ``hw-address`` (specifies +a hardware/MAC address), ``duid``, ``circuit-id``, ``client-id``, or ``flex-id``. An example command to remove an IPv4 host with reserved address -192.0.2.1 from a subnet with a subnet-id 123 looks as follows: +192.0.2.1 from a subnet with a ``subnet-id`` 123 looks as follows: :: @@ -294,7 +294,7 @@ An example command to remove an IPv4 host with reserved address } Another example that removes an IPv6 host identifier by DUID and -specific subnet-id is: +specific ``subnet-id`` is: ::