[kea-dev] Hooks libraries and configuration information

[Stephen Morris]

Plans for Kea include the extension of the hooks capability, in
particular the provision of a way for configuration information to be
passed into hooks code.  This email opens a discussion about the form
this access should take.

We currently have two tickets in Trac for the passing of configuration
information to hooks libraries:

#3259 - Need ability to pass configuration parameters to hook libraries
#3456 - Hooks should be able to access current configuration

The idea of #3259 was that in the specification of the hooks libraries,
 it would be possible to specify library-specific configuration
parameters.  At the moment, the hooks libraries are specified as follows:

"Dhcp4": {
    :
    "hooks-libraries": [
       "/opt/charging.so",
       "/opt/local/notification.so"
    ]
    :
}

It was envisaged that this would be extended to something like:

"Dhcp4": {
    :
    "hooks-libraries": [
        [
            "/opt/charging.so", {"alpha": "beta", "foo": "bar", ...}
        ],
        [
            "/opt/local/notification.so", {"param": "value", ...}
        ]
    ]
    :
}

In other words, each hooks library is passed a map of name/value pairs
associated with it, probably somewhere during the library
initialization.  It would be up to the library to store the information
for later use.

Ticket #3456 was created later on when it was realised that it would be
helpful for the hooks libraries have access to the general
configuration.  For example, it could be useful for a server's hook
library to be able to know what address pools the server is configured with.

There is a clear overlap here, as general access to the configuration
would also allow access to the hooks libraries parameter lists. It seems
pointless to provide two means to get the same information, so a joint
approach to the tickets is indicated.  The first step is to draw up the
requirements for such a system and the following are proposed as a start
to the discussion:

1. No information is explicitly passed to the hooks libraries during
their initialization.  Instead, they are able to access parameter
information by reading the configuration.

2. Rather than include library-specific parameters as part of the
"hooks-libraries" element, a separate "hooks-parameters" map is
included.  This holds parameters for all libraries, it being up to the
library author to adopt a naming scheme to minimise clashes, e.g.

"Dhcp4": {
    :
    "hooks-libraries": [
        "/opt/charging.so", "/opt/local/notification.so"
    ],
    "hooks-parameters": {
       "charging-alpha": "beta",
       "charging-foo": "bar",
       "notification-param", "value"
    }
    :
}

(The above example prefixes parameter names with the name of the
library, but any scheme could be used.)  True, there is the possibility
of a name clash between libraries, but realistically that chance is
small if some form of prefix scheme is used in naming.

3. It should be possible for hooks libraries to determine the component
of Kea in which they are running.  To explain this, at the top level,
the Kea configuration file is a JSON map of the form:

{
    "Dhcp4": {...},
    "Dhcp6": {...},
    "DhcpDdns": {...}.
    "Logging": {...}
}

It is feasible that a general-purpose library might be written that
could be included into more than one component.  In that case, it needs
to know the component in which the configuration for that particular
instance is included.

4. The configuration access interface should allow access to data
through a simple naming scheme, e.g.

Dhcp4/hooks-libraries[0] = "/opt/charging.so"
Dhcp4/hooks-parameters/charging-alpha = "beta"

(BIND 10 used slashes to separate components, but we can choose another
separator.)

5. The configuration interface should:
a. Allow counts of elements in lists and maps to be returned.
b. Allow iteration over the elements of a list and a map.

6. Depending how sophisticated we want to get, the interface should
allow sub-trees of the configuration to be passed around.  For example,
accessing "Dhcp4/hooks-parameters" should return a subtree representing
the map of parameters.  With this as the data on which the parser
operates, accessing "charging-foo" (rather than
Dhcp4/hooks-parameters/charging-foo) should return the value "bar".

Thoughts?

Stephen