Knowledge Base ISC Main Website Ask a Question/Contact ISC
Installing the Kea Premium Hooks Package
Author: vicky risk Reference Number: AA-01587 Views: 1521 Created: 2018-02-28 18:42 Last Updated: 2018-06-06 16:02 0 Rating/ Voters

If you purchase the Kea Premium hooks from the ISC web site, you will receive an email with a link to download the package.  This KB article takes you through the process of adding the hooks to your Kea configuration. (Please note that for Kea 1.4 and later versions, the instructions have changed slightly. For these versions please consult the User Guide at https://kea.isc.org/docs/kea-guide.html#idp58545072)

Building and Installing the Hooks

1. Download the package.  This will be a file with a name similar to kea-premium-1.3.0.tar.gz.

2. If you have the sources for the corresponding version of the open-source Kea package still on your system (from when you installed Kea), skip this step.  Otherwise extract the Kea source from the original tarball you downloaded.  For example, if you downloaded Kea 1.3.0., you should have a tarball called kea-1.3.0.tar.gz on your system. Unpack this tarball:

$ tar xvf kea-1.3.0.tar.gz

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

$ tar xvf ../kea-premium-1.3.0.tar.gz

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

4. Rerun configure, using the same configure options as you used when originally building Kea. If you have subscription package, please add --with-tier2=yes to your configure options. 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.3.0
  Extended version:1.3.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. Choose this step if this is the first time you are building Kea or want to re-install it again. You can simply do the following:

$ sudo make install

This will install Kea and its hook libraries.

6a. Install the Kea premium hooks libraries only. Choose this step if you already have Kea installed and want to install only the hook libraries.

$ 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. The control agent has the capability to load hook libraries, but there are currently no such libraries available. The DHCP-DDNS component will get the capability in the near future. 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:

"hooks-libraries": {
    {
        
/usr/local/lib/hooks/libdhcp_host_cmds.so
    },
    {
        
/usr/local/lib/hooks/libdhcp_lease_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 identifer-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 your 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, an possibility is that you actually running an instance of Kea installed from your Linux distribution.  These could use different locations of the 
  • 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


© 2001-2018 Internet Systems Consortium

For assistance with problems and questions for which you have not been able to find an answer in our Knowledge Base, we recommend searching our community mailing list archives and/or posting your question there (you will need to register there first for your posts to be accepted). The bind-users and the dhcp-users lists particularly have a long-standing and active membership.

ISC relies on the financial support of the community to fund the development of its open source software products. If you would like to support future product evolution and maintenance as well having peace of mind knowing that our team of experts are poised to provide you with individual technical assistance whenever you call upon them, then please consider our Professional Subscription Support services - details can be found on our main website.

Feedback
  • There is no feedback for this article
Quick Jump Menu