Installing the Kea Premium Hook Libraries from Sources

When you purchase the Kea Subscriber 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 Subscriber hooks packages. The result will be a file with a name similar to kea-subscriber-3.0.0.tar.xz.

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 3.0.0, you should have a tarball called kea-3.0.0.tar.xz on your system. Unpack this tarball:

$ tar -Jxvf kea-3.0.0.tar.xz

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

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

$ cd kea-3.0.0
$ tar -Jxvf ../kea-premium-3.0.0.tar.xz

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

4. Set up the build with meson setup build, using the build options that you need. After running it once, meson configure build shows all the available options. You can check whether Meson 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:            3.0.0
  Extended version:   3.0.0 (tarball)
  Version type:       stable
  OS Family:          Linux

  Prefix:             /usr/local
  Hooks directory:    /usr/local/lib/kea/hooks
  Premium hooks:      yes

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

6. Rebuild Kea

$ meson compile -C build

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

$ sudo meson install -C build

This will install Kea and its hook libraries.

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.

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_cb_cmds.so
/usr/local/lib/kea/hooks/libdhcp_rbac.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 (if you specify the full locationof the hook library, it depends on the operating system used):

{
    "Dhcp6": {
        "hooks-libraries": [
            {
                "library": "libdhcp_cb_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.cb_cmds_hooks/1234] CB_CMDS_INIT_OK loading cb_cmds hooks library successful

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

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

Troubleshooting

Possible problems include:

Subscriber hooks aren't detected by meson

Verify you've unpacked the Kea Subscriber tarball inside the directory into which Kea was unpacked. You should have a premium directory. Afterwards, run meson setup build to set up the build.

No messages in the log file

As noted above, you should check your log file for messages stating that CB_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: /etc/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 '/etc/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 kea-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": "kea6-ctrl-socket"
     },

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

# echo '{ "command": "list-commands" }' | socat - UNIX:/usr/local/lib/var/run/kea6-ctrl-socket