<section xml:id="hooks-host-cache">
<title>host_cache: Caching Host Reservations</title>
- <para>Some of the database backends, such as RADIUS, are considered
+ <para>Some database backends, such as RADIUS, are considered
slow and may take a long time to respond. Since Kea in general is
synchronous, the backend performance directly affects the DHCP
performance. To minimize the impact and improve performance, the
<para>
<note>
- <para>This library may only be loaded by <command>kea-dhcp4</command>
- or <command>kea-dhcp6</command> process.
+ <para>This library may only be loaded by the <command>kea-dhcp4</command>
+ or the <command>kea-dhcp6</command> process.
</para>
</note>
- In principle it can be used with any backend that may introduce
+ In principle, this hook library can be used with any backend that may introduce
performance degradation (MySQL, PostgreSQL, Cassandra, RADIUS).
- Host Cache is required to be loaded for the RADIUS accounting
+ Host Cache must be loaded for the RADIUS accounting
mechanism to work.
</para>
<para>
- Host Cache hook library is currently very simple. It takes only
+ The Host Cache hook library is currently very simple. It takes only
one optional parameter ("maximum") that defines the maximum number
- of hosts to be cached. If not specified the default value of 0 is
+ of hosts to be cached. If not specified, the default value of 0 is
used, which means there is no limit. The hook library can be
- loaded the same way as any other hook library. For example, this
+ loaded the same way as any other hook library; for example, this
configuration could be used:
<screen>
</para>
<para>
- Once loaded, the Host Cache hook library makes available a number
- of new commands. Those commands can be used either over control
- channel (see <xref linkend="ctrl-channel-client"/>) or REST API
+ Once loaded, the Host Cache hook library provides a number
+ of new commands which can be used either over the control
+ channel (see <xref linkend="ctrl-channel-client"/>) or the REST API
(see <xref linkend="agent-overview"/>). An example REST API client
is described in <xref linkend="shell-overview"/>. The following
sections describe the commands available.
</para>
<section id="command-cache-flush">
- <title>cache-flush command</title>
- <para>This command allows removal of specified number of cached
- host entries. It takes one parameter which defines the number of
+ <title>cache-flush Command</title>
+ <para>This command allows removal of a specified number of cached
+ host entries. It takes one parameter, which defines the number of
hosts to be removed. An example usage looks as follows:
<screen>
{
}</screen>
This command will remove 1000 hosts. If you want to delete all
cached hosts, please use cache-clear instead. The hosts are stored
-in FIFO order, so always the oldest entries are removed.
+in FIFO order, so the oldest entries are always removed.
</para>
</section>
<section id="command-cache-clear">
- <title>cache-clear command</title>
+ <title>cache-clear Command</title>
<para>This command allows removal of all cached
host entries. An example usage looks as follows:
<screen>
{
"command": "cache-clear"
}</screen>
-This command will remove all hosts. If you want to delete only
+This command will remove all hosts. If you want to delete only a
certain number of cached hosts, please use cache-flush instead.
</para>
</section>
<section id="command-cache-write">
- <title>cache-write command</title>
- <para>In general case the cache content is considered a run-time
- state and the server can be shutdown or restarted as usual. The
+ <title>cache-write Command</title>
+ <para>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 repopulated after restart. However, there are
- some cases when it is useful to store contents of the cache. One
- such case is RADIUS (where the cached hosts also retain
- additional cached RADIUS attributes and there is no easy way to
+ 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; there is no easy way to
obtain this information again, because renewing clients send their
- packet to the DHCP server directly. As a result, packets never go
- through relay which doesn't insert relay options, which in turn
- are in some deployment to query the RADIUS server). Another use
+ packet to the DHCP server directly. Another use
case is when you want to restart the server and for performance
reasons you want it to start with a hot (populated) cache.
</para>
- <para>This command allows writing the contents of in-memory cache
- to a file on disk. It takes one parameter which defines the
+ <para>This command allows writing the contents of the in-memory cache
+ to a file on disk. It takes one parameter, which defines the
filename. An example usage looks as follows:
<screen>
{
"command": "cache-write",
"arguments": "/tmp/kea-host-cache.json"
}</screen>
-This command will store the contents to /tmp/kea-host-cache.json file.
-That file can then be loaded with cache-load command or processed by
+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 processed by
any other tool that is able to understand JSON format.
</para>
</section>
<section id="command-cache-load">
- <title>cache-load command</title>
- <para>See previous section for a discussion regarding use cases
+ <title>cache-load Command</title>
+ <para>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.</para>
- <para>This command allows load the contents of a file on disk into
- an in-memory cache. It takes one parameter which defines the
+ <para>This command allows the contents of a file on disk to be loaded into
+ an in-memory cache. It takes one parameter, which defines the
filename. An example usage looks as follows:
<screen>
{
"command": "cache-load",
"arguments": "/tmp/kea-host-cache.json"
}</screen>
-This command will store the contents to /tmp/kea-host-cache.json file.
-That file can then be loaded with cache-load command or processed by
+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 processed by
any other tool that is able to understand JSON format.
</para>
</section>
<section id="command-cache-get">
- <title>cache-get command</title>
+ <title>cache-get Command</title>
<para>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.</para>
- <para>This command allows load the contents of a file on disk into
- an in-memory cache. It takes one parameter which defines the
+ <para>This command allows the contents of a file on disk to be loaded into
+ an in-memory cache. It takes one parameter, which defines the
filename. An example usage looks as follows:
<screen>
{
"command": "cache-get"
}</screen>
-This command will return all the cached hosts. Note the response
+This command will return all the cached hosts. Note that the response
may be large.
</para>
</section>
<section id="command-cache-insert">
- <title>cache-insert command</title>
+ <title>cache-insert Command</title>
<para>This command may be used to manually insert a host into the
- cache. There are very few use cases when this command could be
- useful. This command expects the arguments to follow the usual
+ cache; there are very few use cases when this command could be
+ useful. This command expects its arguments to follow the usual
syntax for specifying host reservations (see <xref
linkend="host-reservation-v4"/> or <xref
- linkend="host-reservation-v6"/>) with one difference: the
+ linkend="host-reservation-v6"/>), with one difference: the
subnet-id value must be specified explicitly.</para>
<para>
- An example command that will insert a IPv4 host into the host
+ An example command that will insert an IPv4 host into the host
cache looks as follows:
<screen>
{
</para>
<para>
- An example command that will insert IPv6 host into the host
+ An example command that will insert an IPv6 host into the host
cache looks as follows:
<screen>
{
</section>
<section id="command-cache-remove">
- <title>cache-remove command</title>
+ <title>cache-remove Command</title>
<para>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 already provided configuration and the host entry is in
+ Kea has already provided configuration, and the host entry is in
cache. As a result of administrative action (e.g. customer hasn't
- paid their bills or perhaps been upgraded to better service), the
+ paid their bills or has perhaps been upgraded to better service), the
information in the backend (e.g. MySQL or RADIUS) is being
updated. However, since cache is in use, Kea does not notice the
- change as the cached values are used. Cache-remove command can
- solve this problem by removing cached entry after administrative
+ change as the cached values are used. The cache-remove command can
+ solve this problem by removing a cached entry after administrative
changes.</para>
<para>
- The cache-remove command works similarly to reservation-get
- command. It allows querying by two parameters. One of them is
- either subnet-id4 or subnet-id6 and the other one is one of:
- ip-address (may be 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
+ hardware/MAC address), duid, circuit-id, client-id, or flex-id.
</para>
<para>
An example command to remove an IPv4 host with reserved address
- 192.0.2.1 from subnet with a subnet-id 123 looks as follows:
+ 192.0.2.1 from a subnet with a subnet-id 123 looks as follows:
<screen>
{
"command": "cache-remove",
}</screen>
</para>
<para>
- Another example that removes IPv6 host identifier by DUID and
+ Another example that removes an IPv6 host identifier by DUID and
specific subnet-id is:
<screen>
{
projects / thirdparty / kea.git / commitdiff
