Installing the Kea Premium Hook Libraries from Sources

When you purchase the Kea Premium hooks from the ISC website, you will receive an email with a link to download the source tarball or to install a pre-compiled package for your operating system. This KB article takes you through the process of building and adding the hooks to your Kea configuration if you decide to build from source.

Building and Installing the Hooks

1. Download the Kea Premium hooks packages. The result will be a file with a name similar to kea-premium-2.6.0.tar.gz.

2. If you do not have the sources for the corresponding version of the open-source Kea package on your system, extract the Kea source from the original tarball you downloaded. For example, if you downloaded Kea 2.6.0, you should have a tarball called kea-2.6.0.tar.gz on your system. Unpack this tarball:

$ tar xvfz kea-2.6.0.tar.gz

This will unpack the tarball into the kea-2.6.0 subdirectory of your current working directory.

3. Unpack the Kea Premium tarball into the directory into which Kea was unpacked. For example, assuming that you followed step 2 and that Kea 2.6 has been unpacked into a kea-2.6.0 subdirectory and that the Kea Premium tarball is in your current directory, the following steps will unpack the premium tarball into the correct location.

$ cd kea-2.6.0
$ tar xvfz ../kea-premium-2.6.0.tar.gz

Note that unpacking the Kea Premium package will put the files into a directory named premium.

4. Regenerate the configuration scripts by running autoreconf -i.

5. Rerun configure, using the same configure options as you used when originally building Kea. You can check whether configure has detected the premium package by inspecting the summary printed when it exits.  The first section of the output should look something like:

Package:
  Name:              kea
  Version:           2.6.0
  Extended version:  2.6.0 (tarball)
  Version type:      stable
  OS Family:         Linux

  Prefix:            /usr/local
  Hooks directory:   /usr/local/lib/kea/hooks
  Premium hooks:     yes (tarball)
  Included Hooks:    ddns_tuning forensic_log flex_id host_cmds limits subnet_cmds radius host_cache class_cmds cb_cmds lease_query ping_check gss_tsig rbac

The last two lines indicate whether the premium package has been detected.

6. Rebuild Kea

$ make

7a. If you are building Kea for the first time or want to re-install it, you should run:

$ sudo make install

This will install Kea and its hook libraries.

7b. If you want to install the Kea Premium hook libraries only (if you already have Kea installed), run:

$ cd premium
$ sudo make install

The exact installation location depends on whether you specified the --prefix parameter to the configure script. If you haven't, the default is /usr/local/lib/kea/hooks.  (If you don't change to the premium subdirectory first, this step will overwrite the existing Kea files with the ones just built.)

You can verify the libraries are installed properly with this command:

$ ls -l /usr/local/lib/kea/hooks/*.so

You should see

/usr/local/lib/kea/hooks/libdhcp_flex_id.so
/usr/local/lib/kea/hooks/libdhcp_host_cmds.so
/usr/local/lib/kea/hooks/libdhcp_lease_cmds.so
/usr/local/lib/kea/hooks/libdhcp_legal_log.so

Configuration of the Hook Libraries

Although the hooks have now been installed, Kea will not automatically pick them up; you need to edit your configuration file to tell Kea to load the libraries.

8. Edit your configuration file to load the libraries you want to use. All hook libraries are currently intended to be used by DHCPv4 or DHCPv6 components. Please make sure you edit the right configuration file, i.e. either kea-dhcp4.conf or kea-dhcp6.conf (or both). This means adding statements like the following text to either the Dhcp4 or Dhcp6 sections of the configuration, depending on the hook (the location of the hook also depends on the operating system used):

{
    "Dhcp6": {
        "hooks-libraries": [
            {
                "library": "/usr/local/lib/kea/hooks/libdhcp_host_cmds.so"
            }
        ]
    }
}

Please keep in mind that while some hook libraries - like host_cmds, lease_cmds, and legal_log - can generally run without any parameters, other hook libraries - like flex_id - have mandatory parameter(s), such as identifier-expression for flex_id. (To see the syntax for specifying parameters, please see this section in the Kea Administrator Reference Manual.)

9. You should now verify that the libraries have been correctly configured and installed. If you restart Kea (or just reconfigure it), Kea will load the libraries listed in the configuration file. When loading a library, Kea will log the following messages for each library:

INFO  [kea-dhcp6.host_cmds_hooks/1234] HOST_CMDS_INIT_OK loading Host Commands hooks library successful

INFO  [kea-dhcp6.hooks/1234] HOOKS_LIBRARY_LOADED hooks library /usr/local/lib/kea/hooks/libdhcp_host_cmds.so successfully loaded

(The exact text will, of course, depend on the library being loaded.)

Troubleshooting

Possible problems include:

No messages in the log file

As noted above, you should check your log file for messages stating that HOST_CMDS_INIT_OK and HOOKS_LIBRARY_LOADED. Both of those are printed at the INFO level, so unless you have very a quiet logging setup, you should see them. If in doubt, simply comment out all logging in your configuration file, so Kea will revert to the default logging level, which is to print INFO messages on the standard output.

FLEX_ID_EXPRESSION_NOT_DEFINED message in the log file

If you see these error messages:

ERROR [kea-dhcp6.flex-id/1234] FLEX_ID_EXPRESSION_NOT_DEFINED Expression (identifier-expression) is not defined.

ERROR [kea-dhcp6.hooks/1234] HOOKS_LOAD_ERROR 'load' function in hook library /usr/local/lib/kea/hooks/libdhcp_flex_id.so returned error 1

... followed by these messages:

ERROR [kea-dhcp6.dhcp6/1234] DHCP6_PARSER_COMMIT_FAIL parser failed to commit changes: One or more hook libraries failed to load

ERROR [kea-dhcp6.dhcp6/1234] DHCP6_CONFIG_LOAD_FAIL configuration error using file: /tmp/hooks.json, reason: One or more hook libraries failed to load

ERROR [kea-dhcp6.dhcp6/1234] DHCP6_INIT_FAIL failed to initialize Kea server: configuration error using file '/tmp/hooks.json': One or more hook libraries failed to load

... you have incorrectly configured the flex_id library. In particular, you are most likely to have omitted the identifier-expression parameter. (If you don't know what identifier-expression to use, you most likely don't need flex_id yet).

The libraries are loaded but the commands don't work

• Make sure that you are connecting to the same instance of Kea into which the libraries were loaded.
• Perhaps your ctrl-agent is connected to the wrong instance?
• If only one instance of Kea is running, another possibility is that you are actually running an instance of Kea installed from your Linux distribution.
• You should also verify that the config file you are editing has a control socket specified. It's an entry similar to this:

     "control-socket": {
          "socket-type": "unix",
          "socket-name": "/tmp/kea6-ctrl-socket"
     },

• As a debugging measure you can bypass the whole control agent and talk to Kea directly over a Unix socket, e.g. using the socat tool:

# echo '{ "command": "list-commands" }' | socat - UNIX:/tmp/kea6-ctrl-socket