path: root/doc/guide/hooks-host-cache.xml

<section xml:id="hooks-host-cache">
  <title>host_cache: Caching Host Reservations</title>
  <para>Some of the 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
  Host Cache library provides a way to cache responses from other
  hosts. This includes negative caching, i.e. the ability to remember
  that there is no client information in the database.</para>


  <para>

  </para>

  <para>
    The RADIUS Host cache is a library that has to be loaded by either
    DHCPv4 or DHCPv6 Kea servers. In principle it 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 mechanism to work.
  </para>

  <para>
    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
    used, which means there is no limit. The hook library can be
    loaded the same way as any other hook library. For example, this
    configuration could be used:

<screen>
  "Dhcp4": {

  // Your regular DHCPv4 configuration parameters here.

  "hooks-libraries": [
  {
      "library": "/usr/local/lib/hooks/libdhc_host_cache.so",
      "parameters": {

          // Tells Kea to never cache more than 1000 hosts.
          "maximum: "1000"

      }
  } ]</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
    (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="cache-flush-cmd">
    <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
    hosts to be removed. An example usage looks as follows:
<screen>
{
    "command": "cache-flush",
    "arguments": 1000
}</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.
    </para>
  </section>

  <section id="cache-clear-cmd">
    <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
certain number of cached hosts, please use cache-flush instead.
    </para>
  </section>

  <section id="cache-write-cmd">
    <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
    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
    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
    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
    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
any other tool that is able to understand JSON format.
    </para>


  </section>

  <section id="cache-load-cmd">
    <title>cache-load command</title>
    <para>See previous section for a discussion regarding 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
    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
any other tool that is able to understand JSON format.
    </para>

  </section>

  <section id="cache-get-cmd">
    <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
    filename. An example usage looks as follows:
<screen>
{
    "command": "cache-get"
}</screen>
This command will return all the cached hosts. Note the response
may be large.
    </para>
  </section>

  <section id="cache-insert-cmd">
    <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
    syntax for specifying host reservations (see <xref
    linkend="host-reservation-v4"/> or <xref
    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
      cache looks as follows:
<screen>
{
    "command": "cache-insert",
    "arguments": {
        "hw-address": "01:02:03:04:05:06",
        "subnet-id4": 4,
        "subnet-id6": 0,
        "ip-address": "192.0.2.100",
        "hostname": "somehost.example.org",
        "client-classes4": [ ],
        "client-classes6": [ ],
        "option-data4": [ ],
        "option-data6": [ ],
        "next-server": "192.0.0.2",
        "server-hostname": "server-hostname.example.org",
        "boot-file-name": "bootfile.efi",
        "host-id": 0
    }
}</screen>

    </para>

    <para>
      An example command that will insert IPv6 host into the host
      cache looks as follows:
<screen>
{
    "command": "cache-insert",
    "arguments": {
        "hw-address": "01:02:03:04:05:06",
        "subnet-id4": 0,
        "subnet-id6": 6,
        "ip-addresses": [ "2001:db8::cafe:babe" ],
        "prefixes": [ "2001:db8:dead:beef::/64" ],
        "hostname": "",
        "client-classes4": [ ],
        "client-classes6": [ ],
        "option-data4": [ ],
        "option-data6": [ ],
        "next-server": "0.0.0.0",
        "server-hostname": "",
        "boot-file-name": "",
        "host-id": 0
    }
}</screen>
    </para>
  </section>

  <section id="cache-remove-cmd">
    <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
    cache. As a result of administrative action (e.g. customer hasn't
    paid their bills or 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
    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.
    </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:
<screen>
{
    "command": "cache-remove",
    "arguments": {
        "ip-address": "192.0.2.1",
        "subnet-id": 123
    }
}</screen>
    </para>
    <para>
      Another example that removes IPv6 host identifier by DUID and
      specific subnet-id is:
<screen>
{
    "command": "cache-remove",
    "arguments": {
        "duid": "00:01:ab:cd:f0:a1:c2:d3:e4",
        "subnet-id": 123
    }
}</screen>
    </para>

  </section>



</section>