Installing the Kea Premium Hooks Package

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 premium hooks package. The result will be a file with a name similar to kea-premium-1.8.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 1.5.0, you should have a tarball called kea-1.5.0.tar.gz on your system. Unpack this tarball:

$ tar xvfz kea-1.8.0.tar.gz

This will unpack the tarball into the kea-1.8.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 1.8 has been unpacked into a kea-1.8.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-1.8.0

$ tar xvfz ../kea-premium-1.8.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 -if

5. Rerun configure, using the same configure options as you used when originally building Kea. You can check if 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:         1.8.0
     Extended version:1.8.0 (tarball) 
     OS Family:       Linux
     Using GNU sed:   yes
     Premium package: yes

The last line indicates whether the premium package has been detected.

5. Rebuild Kea

$ make

6a. 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.

6b. If you want to install the Kea premium hooks libraries only (if you already have Kea installed), run:

$ cd premium
$ sudo make install

The exact installation location depends whether you specified --prefix parameter to the configure script. If you haven't, the default is /usr/local/lib/hooks.  (If you don't change directory to the premium subdirectory first, the 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/hooks/*.so

You should see

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

Configuration of the Hooks 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 library.

7. Edit your configuration file to load the libraries you want to use. As of today, all hook libraries are 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):

"Dhcp4": {
    "hooks-libraries": [
        {
            "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_host_cmds.so"
        }
   ]

Please keep in mind that while the host_cmds, lease_cmds and legal_log libraries can in general run without any parameters, the flex_id library has one mandatory parameter, identifier-expression. (To see the syntax for specifying parameters, see the section in the Kea User's Guide about configuring hooks libraries).

8. 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-dhcp4.host_cmds_hooks/19862] HOST_CMDS_INIT_OK loading Host Commands hooks library successful

INFO  [kea-dhcp4.hooks/19862] HOOKS_LIBRARY_LOADED hooks library /usr/local/lib/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-dhcp4.flex-id/19862] FLEX_ID_EXPRESSION_NOT_DEFINED Expression (identifier-expression) is not defined.

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

... followed by these messages:

ERROR [kea-dhcp4.dhcp4/20144] DHCP4_PARSER_COMMIT_FAIL parser failed to commit changes: One or more hook libraries failed to load

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

ERROR [kea-dhcp4.dhcp4/20144] DHCP4_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/kea4-ctrl-socket"
     },

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

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