21. Integration With External Systems

Kea provides optional support for a variety of external systems, such as RADIUS, NETCONF, YANG, and GSS-TSIG. The following sections describe how to compile Kea with those additional capabilities and how to configure them.

21.1. YANG/NETCONF

21.1.1. Overview

The Network Configuration Protocol, or NETCONF, is a network management protocol defined in RFC 4741. It uses the YANG modeling language, defined in RFC 6020, to provide a uniform way of handling the configuration syntax of various networking devices. Kea provides optional support for a YANG/NETCONF interface with the kea-netconf agent.

21.1.2. Installing NETCONF

To get its NETCONF capabilities, Kea requires the v2 versions of libyang and Sysrepo. The specific versions that have been thoroughly tested with Kea are:

  • libyang v2.1.4

  • sysrepo v2.2.12

  • libyang-cpp v1.1.0 (ae7d649ea75da081725c119dd553b2ef3121a6f8)

  • sysrepo-cpp v1.1.0 (02634174ffc60568301c3d9b9b7cf710cff6a586)

Note

For users who are unable to upgrade to one of the versions of libyang and Sysrepo listed above, these are the oldest versions known to work reliably with current Kea releases:

  • libyang v2.0.256 (56d4e07ef1cdeab3eb2e6700247f83ec9148edcc)

  • sysrepo v2.1.84

  • libyang-cpp v1.1.0 (7824d9a862f2dc1d8ad4f6a90ab6cee9200f7c81)

  • sysrepo-cpp v1.1.0 (e66b2f0c53a428eeb743d355cf86fb30e8e491f1)

Note

kea-netconf may be compatible with later versions of libyang and Sysrepo, but only the versions listed above have been thoroughly tested by ISC.

Installing from packages is recommended, if they are provided by the system. If not, users can build from sources following the directions below, which should work on all popular operating systems.

21.1.2.1. Installing libyang From Sources

$ git clone https://github.com/CESNET/libyang.git
$ cd libyang
$ git checkout v2.1.4
$ mkdir build
$ cd build
$ cmake ..
$ make
$ make install

21.1.2.2. Installing sysrepo From Sources

$ git clone https://github.com/sysrepo/sysrepo.git
$ cd sysrepo
$ git checkout v2.2.12
$ mkdir build
$ cd build
$ cmake -DREPO_PATH=/etc/sysrepo ..
$ make
$ make install  # without sudo if you're doing development and want to run unit tests

21.1.2.3. Installing libyang-cpp From Sources

$ git clone https://github.com/CESNET/libyang-cpp.git
$ cd libyang-cpp
$ git checkout ae7d649ea75da081725c119dd553b2ef3121a6f8
$ mkdir build
$ cd build
$ cmake -DBUILD_TESTING=OFF ..
$ make
$ make install

21.1.2.4. Installing sysrepo-cpp From Sources

$ git clone https://github.com/sysrepo/sysrepo-cpp.git
$ cd sysrepo-cpp
$ git checkout 02634174ffc60568301c3d9b9b7cf710cff6a586
$ mkdir build
$ cd build
$ cmake -DBUILD_TESTING=OFF ..
$ make
$ make install

21.1.3. Compiling With NETCONF

  1. Obtain the Kea sources.

$ git clone gitlab.isc.org/isc-projects/kea.git
$ cd kea
  1. Configure the build.

$ autoreconf -f -i
$ ./configure --with-libyang --with-libyang-cpp --with-sysrepo --with-sysrepo-cpp

Note

If any of the libraries are installed in a custom location, the --with flags accept the installations paths as values.

  1. Check config.report to verify NETCONF support.

NETCONF:
  yes

  libyang:
    LIBYANG_CPPFLAGS:
    LIBYANG_INCLUDEDIR:    -I/usr/local/include
    LIBYANG_LIBS:          -L/usr/local/lib -lyang -Wl,-R/usr/local/lib -lyang
    LIBYANG_PREFIX:        /usr/local
    LIBYANG_VERSION:       2.1.4

  libyang-cpp:
    LIBYANGCPP_CPPFLAGS:
    LIBYANGCPP_INCLUDEDIR: -I/usr/local/include
    LIBYANGCPP_LIBS:       -L/usr/local/lib -lyang-cpp -Wl,-R/usr/local/lib -lyang-cpp
    LIBYANGCPP_PREFIX:     /usr/local
    LIBYANGCPP_VERSION:    1.1.0

  sysrepo:
    SYSREPO_CPPFLAGS:
    SYSREPO_INCLUDEDIR:    -I/usr/local/include
    SYSREPO_LIBS:          -L/usr/local/lib -lsysrepo -Wl,-R/usr/local/lib -lsysrepo
    SYSREPO_PREFIX:        /usr/local
    SYSREPO_VERSION:       2.2.12

    SR_REPO_PATH:          /etc/sysrepo
    SR_PLUGINS_PATH:       /usr/local/lib/sysrepo/plugins
    SRPD_PLUGINS_PATH:     /usr/local/lib/sysrepo-plugind/plugins

  sysrepo-cpp:
    SYSREPOCPP_CPPFLAGS:
    SYSREPOCPP_INCLUDEDIR: -I/usr/local/include
    SYSREPOCPP_LIBS:       -L/usr/local/lib -lsysrepo-cpp -Wl,-R/usr/local/lib -lsysrepo-cpp
    SYSREPOCPP_PREFIX :    /usr/local
    SYSREPOCPP_VERSION:    1.1.0
  1. Build as usual.

    $ make

21.1.4. Quick Sysrepo Overview

This section offers a brief overview of a subset of available functions in Sysrepo. For more complete information, see the Sysrepo homepage.

In YANG, configurations and state data are described in YANG syntax in module files named <module-name>[@<revision>].yang

The revision part is optional and follows the YYYY-MM-DD format. An alternate XML syntax YIN is defined but less user-friendly. Top-level modules are named in Kea models (a short version of schema models).

There are two major modules that Kea is able to support: kea-dhcp4-server and kea-dhcp6-server. While there is an active effort in the DHC working group at IETF to develop a DHCPv6 YANG model, a similar initiative in the past for DHCPv4 failed. Therefore, Kea uses its own dedicated models for DHCPv4 and DHCPv6 but partially supports the IETF model for DHCPv6.

All of the models have extra modules as dependencies, which are also provided. All of the modules can be found in src/share/yang/modules in sources and in share/kea/yang/modules in the installation directory. This directory is referred to as ${share_directory} in the commands below.

To install modules from sources or upgrade them from older revisions, run the following command. In the case of a revision upgrade, YANG data will be migrated automatically to the new module schema.

$ ${share_directory}/yang/modules/utils/reinstall.sh

However, if there are any issues during the upgrade process, and data can be recreated from a NETCONF client or through other means, Kea modules can be easily uninstalled before installing again via this command:

$ ${share_directory}/yang/modules/utils/reinstall.sh -u

This script should be able to reinstall Sysrepo. However, the -s flag can also be used to specify a path:

$ ./src/share/yang/modules/utils/reinstall.sh -s /path/to/sysrepo

To individually install all modules:

$ cd ./src/share/yang/modules
$ sysrepoctl -i ./ietf-dhcpv6-server*.yang
$ sysrepoctl -i ./kea-dhcp4-server*.yang
$ sysrepoctl -i ./kea-dhcp6-server*.yang
...

The installation should look similar to the following:

$ ./src/share/yang/modules/utils/reinstall.sh
[INF] Connection 2 created.
[INF] Module "keatest-module" was installed.
[INF] File "keatest-module@2022-11-30.yang" was installed.
[INF] No datastore changes to apply.
[INF] Connection 4 created.
[ERR] Module "ietf-interfaces@2018-02-20" already installed.
[INF] No datastore changes to apply.
[INF] Connection 7 created.
[ERR] Module "ietf-dhcpv6-client" is already in sysrepo.
[INF] No datastore changes to apply.
[INF] Connection 9 created.
[ERR] Module "ietf-dhcpv6-relay" is already in sysrepo.
[INF] No datastore changes to apply.
[INF] Connection 11 created.
[ERR] Module "ietf-dhcpv6-server" is already in sysrepo.
[INF] No datastore changes to apply.
[INF] Connection 13 created.
[ERR] Write permission "ietf-yang-types" check failed.
[INF] No datastore changes to apply.
[INF] Connection 15 created.
[ERR] Module "ietf-dhcpv6-options" is already in sysrepo.
[INF] No datastore changes to apply.
[INF] Connection 17 created.
[ERR] Module "ietf-dhcpv6-types" is already in sysrepo.
[INF] No datastore changes to apply.
[INF] Connection 21 created.
[INF] Module "kea-types" was installed.
[INF] File "kea-types@2019-08-12.yang" was installed.
[INF] No datastore changes to apply.
[INF] Connection 23 created.
[INF] Module "kea-dhcp-types" was installed.
[INF] File "kea-dhcp-types@2022-11-30.yang" was installed.
[INF] No datastore changes to apply.
[INF] Connection 25 created.
[INF] Module "kea-dhcp-ddns" was installed.
[INF] File "kea-dhcp-ddns@2022-07-27.yang" was installed.
[INF] No datastore changes to apply.
[INF] Connection 27 created.
[INF] Module "kea-ctrl-agent" was installed.
[INF] File "kea-ctrl-agent@2019-08-12.yang" was installed.
[INF] No datastore changes to apply.
[INF] Connection 29 created.
[INF] Module "kea-dhcp4-server" was installed.
[INF] File "kea-dhcp4-server@2022-11-30.yang" was installed.
[INF] No datastore changes to apply.
[INF] Connection 31 created.
[INF] Module "kea-dhcp6-server" was installed.
[INF] File "kea-dhcp6-server@2022-11-30.yang" was installed.
[INF] No datastore changes to apply.

To confirm whether the modules have been imported correctly, check the list of currently installed YANG modules. It should be similar to this:

$ sysrepoctl -l
Sysrepo repository: /etc/sysrepo

Module Name                | Revision   | Flags | Owner     | Startup Perms | Submodules | Features
---------------------------------------------------------------------------------------------------
ietf-datastores            | 2018-02-14 | I     | user:user | 444           |            |
ietf-dhcpv6-client         | 2018-09-04 | I     | user:user | 600           |            |
ietf-dhcpv6-options        | 2018-09-04 | I     | user:user | 600           |            |
ietf-dhcpv6-relay          | 2018-09-04 | I     | user:user | 600           |            |
ietf-dhcpv6-server         | 2018-09-04 | I     | user:user | 600           |            |
ietf-dhcpv6-types          | 2018-09-04 | I     | user:user | 600           |            |
ietf-inet-types            | 2013-07-15 | I     | user:user | 444           |            |
ietf-interfaces            | 2018-02-20 | I     | user:user | 600           |            |
ietf-netconf               | 2013-09-29 | I     | user:user | 644           |            |
ietf-netconf-acm           | 2018-02-14 | I     | user:user | 600           |            |
ietf-netconf-notifications | 2012-02-06 | I     | user:user | 644           |            |
ietf-netconf-with-defaults | 2011-06-01 | I     | user:user | 444           |            |
ietf-origin                | 2018-02-14 | I     | user:user | 444           |            |
ietf-yang-library          | 2019-01-04 | I     | user:user | 644           |            |
ietf-yang-metadata         | 2016-08-05 | i     |           |               |            |
ietf-yang-schema-mount     | 2019-01-14 | I     | user:user | 644           |            |
ietf-yang-types            | 2013-07-15 | I     | user:user | 444           |            |
kea-ctrl-agent             | 2019-08-12 | I     | user:user | 600           |            |
kea-dhcp-ddns              | 2022-07-27 | I     | user:user | 600           |            |
kea-dhcp-types             | 2022-11-30 | I     | user:user | 600           |            |
kea-dhcp4-server           | 2022-11-30 | I     | user:user | 600           |            |
kea-dhcp6-server           | 2022-11-30 | I     | user:user | 600           |            |
kea-types                  | 2019-08-12 | I     | user:user | 600           |            |
keatest-module             | 2022-11-30 | I     | user:user | 600           |            |
sysrepo-monitoring         | 2022-04-08 | I     | user:user | 600           |            |
sysrepo-plugind            | 2022-03-10 | I     | user:user | 644           |            |
yang                       | 2022-06-16 | I     | user:user | 444           |            |

Flags meaning: I - Installed/i - Imported; R - Replay support

To reinstall a module, if the revision YANG entry was bumped, simply installing it will update it automatically. Otherwise, it must first be uninstalled:

$ sysrepoctl -u kea-dhcp4-server

If the module is used (i.e. imported) by other modules, it can be uninstalled only after the dependent modules have first been uninstalled. Installation and uninstallation must be done in dependency order and reverse-dependency order, as appropriate.

21.1.5. Supported YANG Models

The currently supported models are kea-dhcp4-server and kea-dhcp6-server. There is partial support for ietf-dhcpv6-server, but the primary focus of testing has been on Kea DHCP servers. Other models (kea-dhcp-ddns and kea-ctrl-agent) are currently not supported.

21.1.6. Using the NETCONF Agent

The NETCONF agent follows this algorithm:

  • For each managed server, get the initial configuration from the server through the control socket.

  • Open a connection with the Sysrepo environment and establish two sessions with the startup and running datastores.

  • Check that the used (not-essential) and required (essential) modules are installed in the Sysrepo repository at the right revision. If an essential module - that is, a module where the configuration schema for a managed server is defined - is not installed, raise a fatal error.

  • For each managed server, get the YANG configuration from the startup datastore, translate it to JSON, and load it onto the server being configured.

  • For each managed server, subscribe a module change callback using its model name.

  • When a running configuration is changed, try to validate or load the updated configuration via the callback to the managed server.

21.1.7. Configuration

The behavior described in Using the NETCONF Agent is controlled by several configuration flags, which can be set in the global scope or in a specific managed-server scope. If the latter, the value defined in the managed-server scope takes precedence. These flags are:

  • boot-update - controls the initial configuration phase; when true (the default), the initial configuration retrieved from the classic Kea server JSON configuration file is loaded first, and then the startup YANG model is loaded. This setting lets administrators define a control socket in the local JSON file and then download the configuration from YANG. When set to false, this phase is skipped.

  • subscribe-changes - controls the module change subscription; when true (the default), a module change callback is subscribed, but when false the phase is skipped and running configuration updates are disabled. When set to true, the running datastore is used to subscribe for changes.

  • validate-changes - controls how Kea monitors changes in the Sysrepo configuration. Sysrepo offers two stages where Kea can interact: validation and application. At the validation (or SR_EV_CHANGE event, in the Sysrepo naming convention) stage, Kea retrieves the newly committed configuration and verifies it. If the configuration is incorrect for any reason, the Kea servers reject it and the error is propagated back to the Sysrepo, which then returns an error. This step only takes place if validate-changes is set to true. In the application (or SR_EV_UPDATE event in the Sysrepo naming convention) stage, the actual configuration is applied. At this stage Kea can receive the configuration, but it is too late to signal back any errors as the configuration has already been committed.

The idea behind the initial configuration phase is to boot Kea servers with a minimal configuration which includes only a control socket, making them manageable. For instance, for the DHCPv4 server:

{
    "Dhcp4": {
        "control-socket": {
           "socket-name": "/tmp/kea-dhcp4-ctrl.sock",
           "socket-type": "unix"
        }
    }
}

With module change subscriptions enabled, the kea-netconf daemon monitors any configuration changes as they appear in the Sysrepo. Such changes can be done using the sysrepocfg tool or remotely using any NETCONF client. For details, please see the Sysrepo documentation or A Step-by-Step NETCONF Agent Operation Example. Those tools can be used to modify YANG configurations in the running datastore. Note that committed configurations are only updated in the running datastore; to keep them between server reboots they must be copied to the startup datastore.

When module changes are tracked (using subscribe-changes set to true) and the running configuration has changed (e.g. using sysrepocfg or any NETCONF client), the callback validates the modified configuration (if validate-changes was not set to false) and runs a second time to apply the new configuration. If the validation fails, the callback is still called again but with an SR_EV_ABORT (vs. SR_EV_DONE) event with rollback changes.

The returned code of the callback on an SR_EV_DONE event is ignored, as it is too late to refuse a bad configuration.

There are four ways in which a modified YANG configuration might be incorrect:

  1. It could be non-compliant with the schema, e.g. an unknown entry, missing a mandatory entry, a value with a bad type, or not matching a constraint.

  2. It could fail to be translated from YANG to JSON, e.g. an invalid user context.

  3. It could fail Kea server sanity checks, e.g. an out-of-subnet-pool range or an unsupported database type.

  4. The syntax may be correct and pass server sanity checks but the configuration could fail to run, e.g. the configuration specifies database credentials but the database refuses the connection.

The first case is handled by Sysrepo. The second and third cases are handled by kea-netconf in the validation phase (if not disabled by setting validate-changes to true). The last case causes the application phase to fail without a sensible report to Sysrepo.

The managed Kea servers and agents are described in the managed-servers section. Each sub-section begins with the service name: dhcp4, dhcp6, d2 (the DHCP-DDNS server does not support the control-channel feature yet), and ca (the control agent).

Each managed server entry may contain:

  • control flags - boot-update, subscribe-changes, and/or validate-changes.

  • model - specifies the YANG model/module name. For each service, the default is the corresponding Kea YANG model, e.g. for "dhcp4" it is "kea-dhcp4-server".

  • control-socket - specifies the control socket for managing the service configuration.

A control socket is specified by:

  • socket-type - the socket type is either stdout, unix, or http. stdout is the default; it is not really a socket, but it allows kea-netconf to run in debugging mode where everything is printed on stdout, and it can also be used to redirect commands easily. unix is the standard direct server control channel, which uses UNIX sockets; http uses a control agent, which accepts HTTP connections.

  • socket-name - the local socket name for the unix socket type (default empty string).

  • socket-url - the HTTP URL for the http socket type (default http://127.0.0.1:8000/).

User contexts can store arbitrary data as long as they are in valid JSON syntax and their top-level element is a map (i.e. the data must be enclosed in curly brackets). They are accepted at the NETCONF entry, i.e. below the top-level, managed-service entry, and control-socket entry scopes.

Hook libraries can be loaded by the NETCONF agent just as with other servers or agents; however, currently no hook points are defined. The hooks-libraries list contains the list of hook libraries that should be loaded by kea-netconf, along with their configuration information specified with parameters.

Please consult Logging for details on how to configure logging. The name of the NETCONF agent's main logger is kea-netconf, as given in the example above.

21.1.8. A kea-netconf Configuration Example

The following example demonstrates the basic NETCONF configuration. More examples are available in the doc/examples/netconf directory in the Kea sources.

// This is a simple example of a configuration for the NETCONF agent.
// This server provides a YANG interface for all Kea servers and the agent.
{
    "Netconf":
    {
        // Control flags can be defined in the global scope or
        // in a managed server scope. Precedences are:
        // - use the default value (true)
        // - use the global value
        // - use the local value.
        // So this overwrites the default value:
        "boot-update": false,

        // This map specifies how each server is managed. For each server there
        // is a name of the YANG model to be used and the control channel.
        // Currently three control channel types are supported:
        // "stdout" which outputs the configuration on the standard output,
        // "unix" which uses the local control channel supported by the
        // "dhcp4" and "dhcp6" servers ("d2" support is not yet available),
        // and "http" which uses the Control Agent "ca" to manage itself or
        // to forward commands to "dhcp4" or "dhcp6".
        "managed-servers":
        {
            // This is how kea-netconf can communicate with the DHCPv4 server.
            "dhcp4":
            {
                "comment": "DHCPv4 server",
                "model": "kea-dhcp4-server",
                "control-socket":
                {
                    "socket-type": "unix",
                    "socket-name": "/tmp/kea4-ctrl-socket"
                }
            },

            // DHCPv6 parameters.
            "dhcp6":
            {
                "model": "kea-dhcp6-server",
                "control-socket":
                {
                    "socket-type": "unix",
                    "socket-name": "/tmp/kea6-ctrl-socket"
                }
            },

            // Currently the DHCP-DDNS (nicknamed D2) server does not support
            // a command channel.
            "d2":
            {
                "model": "kea-dhcp-ddns",
                "control-socket":
                {
                    "socket-type": "stdout",
                    "user-context": { "in-use": false }
                }
            },

            // Of course the Control Agent (CA) supports HTTP.
            "ca":
            {
                "model": "kea-ctrl-agent",
                "control-socket":
                {
                    "socket-type": "http",
                    "socket-url": "http://127.0.0.1:8000/"
                }
            }
        },

        // kea-netconf is able to load hook libraries that augment its operation.
        // Currently there are no hook points defined in kea-netconf
        // processing.
        "hooks-libraries": [
            // The hook libraries list may contain more than one library.
            {
                // The only necessary parameter is the library filename.
                "library": "/opt/local/custom_hooks_example.so",

                // Some libraries may support parameters. Make sure you
                // type this section carefully, as kea-netconf does not
                // validate it (because the format is library-specific).
                "parameters": {
                    "param1": "foo"
                }
            }
        ],

        // Similar to other Kea components, NETCONF also uses logging.
        "loggers": [
            {
                "name": "kea-netconf",
                "output-options": [
                    {
                        "output": "/var/log/kea-netconf.log",
                        // Several additional parameters are possible in
                        // addition to the typical output.
                        // Flush determines whether logger flushes output
                        //  to a file.
                        // Maxsize determines maximum filesize before
                        // the file is rotated.
                        // Maxver specifies the maximum number of
                        //  rotated files to be kept.
                        "flush": true,
                        "maxsize": 204800,
                        "maxver": 4
                    }
                ],
                "severity": "INFO",
                "debuglevel": 0
            }
        ]
    }
}

21.1.9. Starting and Stopping the NETCONF Agent

kea-netconf accepts the following command-line switches:

  • -c file - specifies the configuration file.

  • -d - specifies whether the agent logging should be switched to debug/verbose mode. In verbose mode, the logging severity and debuglevel specified in the configuration file are ignored and "debug" severity and the maximum debuglevel (99) are assumed. The flag is convenient for temporarily switching the server into maximum verbosity, e.g. when debugging.

  • -t file - specifies the configuration file to be tested. kea-netconf attempts to load it and conducts sanity checks; certain checks are possible only while running the actual server. The actual status is reported with exit code (0 = configuration appears valid, 1 = error encountered). Kea prints out log messages to standard output and error to standard error when testing the configuration.

  • -v - displays the version of kea-netconf and exits.

  • -V - displays the extended version information for kea-netconf and exits. The listing includes the versions of the libraries dynamically linked to Kea.

  • -W - displays the Kea configuration report and exits. The report is a copy of the config.report file produced by ./configure; it is embedded in the executable binary.

    The contents of the config.report file may also be accessed by examining certain libraries in the installation tree or in the source tree.

    # from installation using libkea-process.so
    $ strings ${prefix}/lib/libkea-process.so | sed -n 's/;;;; //p'
    
    # from sources using libkea-process.so
    $ strings src/lib/process/.libs/libkea-process.so | sed -n 's/;;;; //p'
    
    # from sources using libkea-process.a
    $ strings src/lib/process/.libs/libkea-process.a | sed -n 's/;;;; //p'
    
    # from sources using libcfgrpt.a
    $ strings src/lib/process/cfgrpt/.libs/libcfgrpt.a | sed -n 's/;;;; //p'
    

21.1.10. A Step-by-Step NETCONF Agent Operation Example

Note

Copies of example configurations presented within this section can be found in the Kea source code, under doc/examples/netconf/kea-dhcp6-operations.

21.1.10.1. Setup of NETCONF Agent Operation Example

The test box has an Ethernet interface named eth1. On some systems it is possible to rename interfaces; for instance, on Linux with an ens38 interface:

# ip link set down dev ens38
# ip link set name eth1 dev ens38
# ip link set up dev eth1

The interface must have an address in the test prefix:

# ip -6 addr add 2001:db8::1/64 dev eth1

The Kea DHCPv6 server must be launched with the configuration specifying a control socket used to receive control commands. The kea-netconf process uses this socket to communicate with the DHCPv6 server, i.e. it pushes translated configurations to that server using control commands. The following is an example control socket specification for the Kea DHCPv6 server:

{
    "Dhcp6": {
        "control-socket": {
           "socket-name": "/tmp/kea-dhcp6-ctrl.sock",
           "socket-type": "unix"
        }
    }
}

In order to launch the Kea DHCPv6 server using the configuration contained within the boot.json file, run:

# kea-dhcp6 -d -c boot.json

The current configuration of the server can be fetched via a control socket by running:

# echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea-dhcp6-ctrl.sock '-,ignoreeof'

The following is the example netconf.json configuration for kea-netconf, to manage the Kea DHCPv6 server:

{
  "Netconf": {
    "loggers": [
      {
        "debuglevel": 99,
        "name": "kea-netconf",
        "output-options": [
          {
            "output": "stderr"
          }
        ],
        "severity": "DEBUG"
      }
    ],
    "managed-servers": {
      "dhcp6": {
        "control-socket": {
          "socket-name": "/tmp/kea-dhcp6-ctrl.sock",
          "socket-type": "unix"
        }
      }
    }
  }
}

Note that in production there should not be a need to log at the DEBUG level.

The Kea NETCONF agent is launched by:

# kea-netconf -d -c netconf.json

Now that both kea-netconf and kea-dhcp6 are running, it is possible to populate updates to the configuration to the DHCPv6 server. The following is the configuration extracted from startup.xml:

<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
  <subnet6>
    <id>1</id>
    <pool>
      <start-address>2001:db8::1:0</start-address>
      <end-address>2001:db8::1:ffff</end-address>
      <prefix>2001:db8::1:0/112</prefix>
    </pool>
    <subnet>2001:db8::/64</subnet>
  </subnet6>
  <interfaces-config>
    <interfaces>eth1</interfaces>
  </interfaces-config>
  <control-socket>
    <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
    <socket-type>unix</socket-type>
  </control-socket>
</config>

To populate this new configuration:

$ sysrepocfg -d startup -f xml -m kea-dhcp6-server --import=startup.xml

kea-netconf pushes the configuration found in the Sysrepo startup datastore to all Kea servers during its initialization phase, after it subscribes to module changes in the Sysrepo running datastore. This action copies the configuration from the startup datastore to the running datastore and enables the running datastore, making it available.

Changes to the running datastore are applied after validation to the Kea servers. Note that they are not by default copied back to the startup datastore, i.e. changes are not permanent.

Note

kea-netconf fetches the entire configuration from any Sysrepo datastore in a single get-config NETCONF operation. Prior to Kea 2.3.2, a get-config operation was done for each leaf and leaf-list node. Because of the significant changes, kea-netconf is considered experimental.

21.1.10.2. Example of Error Handling in NETCONF Operation

There are four classes of issues with configurations applied via NETCONF:

  1. The configuration does not comply with the YANG schema.

  2. The configuration cannot be translated from YANG to the Kea JSON.

  3. The configuration is rejected by the Kea server.

  4. The configuration was validated by the Kea server but cannot be applied.

In the first case, consider the following BAD-schema.xml configuration file:

<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
  <subnet4>
    <id>1</id>
    <pool>
      <start-address>2001:db8::1:0</start-address>
      <end-address>2001:db8::1:ffff</end-address>
      <prefix>2001:db8::1:0/112</prefix>
    </pool>
    <subnet>2001:db8::/64</subnet>
  </subnet6>
  <interfaces-config>
    <interfaces>eth1</interfaces>
  </interfaces-config>
  <control-socket>
    <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
    <socket-type>unix</socket-type>
  </control-socket>
</config>

It is directly rejected by sysrepocfg:

$ sysrepocfg -d running -f xml -m kea-dhcp6-server --import=BAD-schema.xml

In the second case, the configuration is rejected by kea-netconf. For example, consider this BAD-translator.xml file:

<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
  <subnet6>
    <id>1</id>
    <pool>
      <start-address>2001:db8::1:0</start-address>
      <end-address>2001:db8::1:ffff</end-address>
      <prefix>2001:db8::1:0/112</prefix>
    </pool>
    <subnet>2001:db8::/64</subnet>
  </subnet6>
  <interfaces-config>
    <interfaces>eth1</interfaces>
  </interfaces-config>
  <control-socket>
    <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
    <socket-type>unix</socket-type>
  </control-socket>
  <user-context>bad</user-context>
</config>

In the third case, the configuration is presented to the Kea DHCPv6 server and fails to validate, as in this BAD-config.xml file:

<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
  <subnet6>
    <id>1</id>
    <pool>
      <start-address>2001:db8:1::0</start-address>
      <end-address>2001:db8:1::ffff</end-address>
      <prefix>2001:db8:1::0/112</prefix>
    </pool>
    <subnet>2001:db8::/64</subnet>
  </subnet6>
  <interfaces-config>
    <interfaces>eth1</interfaces>
  </interfaces-config>
  <control-socket>
    <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
    <socket-type>unix</socket-type>
  </control-socket>
</config>

In the last case, the misconfiguration is detected too late and the change must be reverted in Sysrepo, e.g. using the startup datastore as a backup.

21.1.10.3. NETCONF Operation Example with Two Pools

This example adds a second pool to the initial (i.e. startup) configuration in the twopools.xml file:

<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
  <subnet6>
    <id>1</id>
    <pool>
      <start-address>2001:db8::1:0</start-address>
      <end-address>2001:db8::1:ffff</end-address>
      <prefix>2001:db8::1:0/112</prefix>
    </pool>
    <pool>
      <start-address>2001:db8::2:0</start-address>
      <end-address>2001:db8::2:ffff</end-address>
      <prefix>2001:db8::2:0/112</prefix>
    </pool>
    <subnet>2001:db8::/64</subnet>
  </subnet6>
  <interfaces-config>
    <interfaces>eth1</interfaces>
  </interfaces-config>
  <control-socket>
    <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
    <socket-type>unix</socket-type>
  </control-socket>
</config>

This configuration is installed by:

$ sysrepocfg -d running -f xml -m kea-dhcp6-server --import=twopools.xml

21.1.10.4. NETCONF Operation Example with Two Subnets

This example specifies two subnets in the twosubnets.xml file:

<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
  <subnet6>
    <id>1</id>
    <pool>
      <start-address>2001:db8:1::</start-address>
      <end-address>2001:db8:1::ffff</end-address>
      <prefix>2001:db8:1::/112</prefix>
    </pool>
    <subnet>2001:db8:1::/64</subnet>
  </subnet6>
  <subnet6>
    <id>2</id>
    <pool>
      <start-address>2001:db8:2::</start-address>
      <end-address>2001:db8:2::ffff</end-address>
      <prefix>2001:db8:2::/112</prefix>
    </pool>
    <subnet>2001:db8:2::/64</subnet>
  </subnet6>
  <interfaces-config>
    <interfaces>eth1</interfaces>
  </interfaces-config>
  <control-socket>
    <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
    <socket-type>unix</socket-type>
  </control-socket>
</config>

This configuration is installed by:

$ sysrepocfg -d running -f xml -m kea-dhcp6-server --import=twosubnets.xml

21.1.10.5. NETCONF Operation Example With Logging

This example adds a logger entry to the initial (i.e. startup) configuration in the logging.xml file:

<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
  <interfaces-config>
    <interfaces>eth1</interfaces>
  </interfaces-config>
  <subnet6>
    <id>1</id>
    <pool>
      <start-address>2001:db8::1:0</start-address>
      <end-address>2001:db8::1:ffff</end-address>
      <prefix>2001:db8::1:0/112</prefix>
    </pool>
    <subnet>2001:db8::/64</subnet>
  </subnet6>
  <control-socket>
    <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
    <socket-type>unix</socket-type>
  </control-socket>
  <logger>
    <name>kea-dhcp6</name>
    <output-option>
      <output>stderr</output>
    </output-option>
    <debuglevel>99</debuglevel>
    <severity>DEBUG</severity>
  </logger>
</config>

The corresponding Kea configuration in JSON is:

{
  "Dhcp6": {
    "control-socket": {
      "socket-name": "/tmp/kea-dhcp6-ctrl.sock",
      "socket-type": "unix"
    },
    "interfaces-config": {
      "interfaces": [ "eth1" ]
    },
    "subnet6": [
      {
        "id": 1,
        "pools": [
          {
            "pool": "2001:db8::1:0/112"
          }
        ],
        "subnet": "2001:db8::/64"
      }
    ],
    "loggers": [
      {
        "name": "kea-dhcp6",
        "output-options": [
          {
            "output": "stderr"
          }
        ],
        "severity": "DEBUG",
        "debuglevel": 99
      }
    ]
  }
}

Finally, any of the previous examples can be replayed by using sysrepocfg in edit mode as follows:

$ sysrepocfg -d running -f xml -m kea-dhcp6-server --edit

or by using a NETCONF client like netopeer2-cli from the Netopeer2 NETCONF Toolset.

21.1.10.6. Migrating YANG Data From a Prior Sysrepo Version

1. Shut down kea-netconf. This ensures that backups for both datastores are done at the same configuration state and that no change happens between exporting them.

  1. Make data backups for all YANG modules, with one XML for each datastore.

$ sysrepocfg --datastore running --export=save.xml --format=xml
$ sysrepocfg --datastore startup --export=save.xml --format=xml

Note

Sysrepo v0 does not support import/export of all YANG modules; this capability was added in Sysrepo v1. Users that are migrating from Sysrepo v0 will need to do per-module backups. This has the added benefit of isolating potential failures and preventing them from affecting all modules. The command is the same, except it has the module name added to it at the end.

$ sysrepocfg --datastore running --export=save.xml --format=xml kea-dhcp6-server
$ sysrepocfg --datastore startup --export=save.xml --format=xml kea-dhcp6-server
  1. Upgrade Sysrepo to the newer version and then run:

$ sysrepocfg --datastore running --import=save.xml
$ sysrepocfg --datastore startup --import=save.xml

21.2. GSS-TSIG

21.2.1. GSS-TSIG Overview

Kea provides support for DNS updates, which can be protected using Transaction Signatures (or TSIG). This protection is often adequate. However, some systems, in particular Active Directory (AD) on Microsoft Windows servers, have chosen to adopt a more complex GSS-TSIG approach that offers additional capabilities, such as using negotiated dynamic keys.

Kea supports GSS-TSIG to protect DNS updates sent by the Kea DHCP-DDNS (D2) server in a premium hook, called libddns_gss_tsig.so.

GSS-TSIG is defined in RFC 3645. The GSS-TSIG protocol itself is an implementation of generic GSS-API v2 services, defined in RFC 2743.

Many protocols are involved in this mechanism:

  • Kerberos 5 - RFC 4120, which provides the security framework;

  • GSS-API (Generic Security Services Application Program Interface) - RFC 2743 for the API, RFC 2744 for the C bindings, and RFC 4121 for the application to Kerberos 5;

  • SPNEGO (Simple and Protected GSS-API Negotiation Mechanism) - RFC 4178 for the negotiation;

  • DNS update RFC 2136;

  • TSIG (Secret Key Transaction Authentication for DNS) - RFC 8945, which protects DNS exchanges;

  • Secure Domain Name System (DNS) Dynamic Update - RFC 3007, which is the application of TSIG to DNS update protection;

  • TKEY (Secret Key Establishment for DNS) - RFC 2930, which establishes secret keys for TSIG by transmitting crypto payloads between DNS parties; and

  • GSS-TSIG - RFC 3645, which is the application of GSS-API to TSIG.

To summarize, GSS-API for Kerberos 5 with SPNEGO and TKEY are used to negotiate a security context between the Kea D2 server and a DNS server:

../_images/tkey.svg

The security context is then used by GSS-TSIG to protect updates:

../_images/update.svg

The Kea implementation of GSS-TSIG uses a GSS-API for Kerberos 5 with the SPNEGO library. Two implementations meet this criteria: MIT Kerberos 5 and Heimdal.

21.2.2. GSS-TSIG Compilation

The following procedure was tested on Ubuntu 20.10 and 21.04. A similar approach can be applied to other systems.

  1. Obtain the Kea sources and premium packages, extract the Kea sources, and then extract the premium packages into the premium/ directory within the Kea source tree.

  2. Run autoreconf:

autoreconf -i
  1. Make sure ./configure --help shows the --with-gssapi option.

  2. Install either the MIT (libkrb5-dev) or the Heimdal (heimdal-dev) library, for instance:

sudo apt install libkrb5-dev
  1. Run configure with the --with-gssapi option:

./configure --with-gssapi

The --with-gssapi parameter requires the krb5-config tool to be present. This tool is provided by both MIT Kerberos 5 and Heimdal; however, on some systems where both Kerberos 5 and Heimdal are installed, it is a symbolic link to one of them. If the tool is not in the standard location, it can be specified with --with-gssapi=/path/to/krb5-config. It is strongly recommended to use the default installation locations provided by the packages.

The ./configure script should complete with a successful GSS-API detection, similar to this:

GSS-API support:
  GSSAPI_CFLAGS:         -isystem /usr/include/mit-krb5
  GSSAPI_LIBS:           -L/usr/lib/x86_64-linux-gnu/mit-krb5 -Wl,-Bsymbolic-functions -Wl,-z,relro -lgssapi_krb5 -lkrb5 -lk5crypto -lcom_err
  1. Compile make -jX, where X is the number of CPU cores available.

  2. After compilation, libddns_gss_tsig.so is available in the premium/src/hooks/d2/gss_tsig directory. It can be loaded by kea-dhcp-ddns.

libddns_gss_tsig.so was developed using the MIT Kerberos 5 implementation, but Heimdal is also supported. Note that Heimdal is picky about security-sensitive file permissions and is known to emit an unclear error message. It is a good idea to keep these files plain, with one link and no access for the group or other users.

The krb5-config script should provide an --all option which identifies the implementation.

21.2.3. GSS-TSIG Deployment

Before using GSS-TSIG, a GSS-TSIG capable DNS server, such as BIND 9 or Microsoft Active Directory (AD), must be deployed. Other GSS-TSIG capable implementations may work, but have not been tested.

21.2.3.1. Kerberos 5 Setup

There are two kinds of key tables (keytab files): the system one used by servers, and client tables used by clients. For Kerberos 5, Kea is a client.

Install the Kerberos 5 client library and kadmin tool:

sudo apt install krb5-kdc krb5-admin-server

The following examples use the EXAMPLE.ORG realm to demonstrate required configuration steps and settings.

The Kerberos 5 client library must be configured to accept incoming requests for the realm EXAMPLE.ORG by updating the krb5.conf file (e.g. on Linux: /etc/krb5.conf):

[libdefaults]
    default_realm = EXAMPLE.ORG
    kdc_timesync = 1
    ccache_type = 4
    forwardable = true
    proxiable = true

[realms]
    EXAMPLE.ORG = {
            kdc = kdc.example.org
            admin_server = kdc.example.org
    }

In addition to the krb5.conf file, the kdc.conf file can be used (e.g. on Linux: /etc/krb5kdc/kdc.conf):

[kdcdefaults]
    kdc_ports = 750,88

[realms]
    EXAMPLE.ORG = {
        database_name = /var/lib/krb5kdc/principal
        admin_keytab = FILE:/etc/krb5kdc/kadm5.keytab
        acl_file = /etc/krb5kdc/kadm5.acl
        key_stash_file = /etc/krb5kdc/stash
        kdc_ports = 750,88
        max_life = 10h 0m 0s
        max_renewable_life = 7d 0h 0m 0s
        master_key_type = des3-hmac-sha1
        #supported_enctypes = aes256-cts:normal aes128-cts:normal
        default_principal_flags = +preauth
    }

The kadmind daemon Access Control List (ACL) must be configured to give permissions to the DNS client principal to access the Kerberos 5 database (e.g. on Linux: /etc/krb5kdc/kadm5.acl):

DHCP/admin.example.org@EXAMPLE.ORG       *

The administrator password for the default realm must be set:

krb5_newrealm

After the following message is displayed, enter the password for the default realm:

This script should be run on the master KDC/admin server to initialize
a Kerberos realm.  It will ask you to type in a master key password.
This password will be used to generate a key that is stored in
/etc/krb5kdc/stash.  You should try to remember this password, but it
is much more important that it be a strong password than that it be
remembered.  However, if you lose the password and /etc/krb5kdc/stash,
you cannot decrypt your Kerberos database.
Loading random data
Initializing database '/var/lib/krb5kdc/principal' for realm 'EXAMPLE.ORG',
master key name 'K/M@EXAMPLE.ORG'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key:

Then retype the password:

Re-enter KDC database master key to verify:

If successfully applied, the following message is displayed:

Now that your realm is set up you may wish to create an administrative
principal using the addprinc subcommand of the kadmin.local program.
Then, this principal can be added to /etc/krb5kdc/kadm5.acl so that
you can use the kadmin program on other computers.  Kerberos admin
principals usually belong to a single user and end in /admin.  For
example, if jruser is a Kerberos administrator, then in addition to
the normal jruser principal, a jruser/admin principal should be
created.

Don't forget to set up DNS information so your clients can find your
KDC and admin servers.  Doing so is documented in the administration
guide.

The next step is to create the principals for the BIND 9 DNS server (the service protected by the GSS-TSIG TKEY) and for the DNS client (the Kea DHCP-DDNS server).

The BIND 9 DNS server principal (used for authentication) is created the following way:

kadmin.local -q "addprinc -randkey DNS/server.example.org"

If successfully created, the following message is displayed:

No policy specified for DNS/server.example.org@EXAMPLE.ORG; defaulting to no policy
Authenticating as principal root/admin@EXAMPLE.ORG with password.
Principal "DNS/server.example.org@EXAMPLE.ORG" created.

The DNS server principal must be exported so that it can be used by the BIND 9 DNS server. Only this principal is required, and it is exported to the keytab file with the name dns.keytab.

kadmin.local -q "ktadd -k /tmp/dns.keytab DNS/server.example.org"

If successfully exported, the following message is displayed:

Authenticating as principal root/admin@EXAMPLE.ORG with password.
Entry for principal DNS/server.example.org with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/dns.keytab.
Entry for principal DNS/server.example.org with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/dns.keytab.

The DHCP client principal (used by the Kea DHCP-DDNS server) is created the following way:

kadmin.local -q "addprinc -randkey DHCP/admin.example.org"

If successfully created, the following message is displayed:

No policy specified for DHCP/admin.example.org@EXAMPLE.ORG; defaulting to no policy
Authenticating as principal root/admin@EXAMPLE.ORG with password.
Principal "DHCP/admin.example.org@EXAMPLE.ORG" created.

The DHCP client principal must be exported so that it can be used by the Kea DHCP-DDNS server and the GSS-TSIG hook library. It is exported to the client keytab file with the name dhcp.keytab.

kadmin.local -q "ktadd -k /tmp/dhcp.keytab DHCP/admin.example.org"

Finally, the krb5-admin-server must be restarted:

systemctl restart krb5-admin-server.service

21.2.3.2. BIND 9 with GSS-TSIG Configuration

The BIND 9 DNS server must be configured to use GSS-TSIG, and to use the previously exported DNS server principal from the keytab file dns.keytab. Updating the named.conf file is required:

options {
    ...
    directory "/var/cache/bind";
    dnssec-validation auto;
    listen-on-v6 { any; };
    tkey-gssapi-keytab "/etc/bind/dns.keytab";
};
zone "example.org" {
    type master;
    file "/var/lib/bind/db.example.org";
    update-policy {
        grant "DHCP/admin.example.org@EXAMPLE.ORG" zonesub any;
    };
};
zone "84.102.10.in-addr.arpa" {
    type master;
    file "/etc/bind/db.10";
};

The zone files should have an entry for the server principal FQDN server.example.org.

The /etc/bind/db.10 file needs to be created or updated:

;
; BIND reverse data file for local loopback interface
;
$TTL    604800                      ; 1 week
@       IN      SOA      server.example.org. root.example.org. (
                         2          ; Serial
                         604800     ; Refresh
                         86400      ; Retry
                         2419200    ; Expire
                         604800     ; Negative Cache TTL
                         )
;
@       IN      NS      ns.
40      IN      PTR     ns.example.org.

The /var/lib/bind/db.example.org file needs to be created or updated:

$ORIGIN .
$TTL                604800             ; 1 week
example.org         IN SOA  server.example.org. root.example.org. (
                            8          ; serial
                            604800     ; refresh (1 week)
                            86400      ; retry (1 day)
                            2419200    ; expire (4 weeks)
                            604800     ; minimum (1 week)
                            )
                    NS      example.org.
                    A       ${BIND9_IP_ADDR}
                    AAAA    ::1
$ORIGIN example.org.
kdc                 A       ${KDC_IP_ADDR}
server              A       ${BIND9_IP_ADDR}

After any configuration change the server must be reloaded or restarted:

systemctl restart named.service

It is possible to get the status or restart the logs:

systemctl status named.service
journalctl -u named | tail -n 30

21.2.3.3. Windows Active Directory Configuration

This sub-section is based on an Amazon AWS provided Microsoft Windows Server 2016 with Active Directory pre-installed, so it describes only the steps used for GSS-TSIG deployment. (For the complete configuration process, please refer to Microsoft's documentation or other external resources. We found this tutorial very useful during configuration of our internal QA testing systems.)

Two Active Directory (AD) user accounts are needed:
  • the first account is used to download AD information, such as the client key table of Kea

  • the second account is mapped to the Kea DHCP client principal

Kea needs to know:
  • the server IP address

  • the domain/realm name: the domain is in lower case, the realm in upper case, both without a final dot

  • the server name

The second account (named kea below) is used to create a Service Principal Name (SPN):

setspn -S DHCP/kea.<domain> kea

After a shared secret key is generated and put in a key table file:

ktpass -princ DHCP/kea.<domain>@<REALM> -mapuser kea +rndpass -mapop set -ptype KRB5_NT_PRINCIPAL -out dhcp.keytab

The dhcp.keytab takes the same usage as for UNIX Kerberos.

21.2.3.4. GSS-TSIG Troubleshooting

While testing GSS-TSIG integration with Active Directory we came across one very cryptic error:

INFO  [kea-dhcp-ddns.gss-tsig-hooks/4678.139690935890624] GSS_TSIG_VERIFY_FAILED GSS-TSIG verify failed: gss_verify_mic failed with GSSAPI error:
Major = 'A token had an invalid Message Integrity Check (MIC)' (393216), Minor = 'Packet was replayed in wrong direction' (100002).

In our case, the problem was that the Kea D2 server was trying to perform an update of a reverse DNS zone while it was not configured. An easy solution is to add a reverse DNS zone similar to the one configured in Kea. To do that, open the "DNS Manager" and choose "DNS" from the list; from the dropdown list, choose "Reverse Lookup Zones"; then click "Action" and "New Zone"; finally, follow the New Zone Wizard to add a new zone.

The standard requires both anti-replay and sequence services. Experiences with the BIND 9 nsupdate showed the sequence service led to problems so it is disabled by default in the hook. It seems the anti-replay service can also lead to problems with Microsoft DNS servers so it is now configurable. Note that these security services are useless for DNS dynamic update which was designed to run over UDP so with out of order and duplicated messages.

21.2.4. Using GSS-TSIG

There are a number of steps required to enable the GSS-TSIG mechanism:

  1. libddns_gss_tsig.so must be loaded by kea-dhcp-ddns.

  2. The GSS-TSIG-capable DNS servers must be specified with their parameters.

An excerpt from a D2 server configuration is provided below; more examples are available in the doc/examples/ddns directory in the Kea sources.

  1 {
  2 "DhcpDdns": {
  3     // The following parameters are used to receive NCRs (NameChangeRequests)
  4     // from the local Kea DHCP server. Make sure your kea-dhcp4 and kea-dhcp6
  5     // matches this.
  6     "ip-address": "127.0.0.1",
  7     "port": 53001,
  8     "dns-server-timeout" : 1000,
  9
 10     // Forward zone: secure.example.org. It uses GSS-TSIG. It is served
 11     // by two DNS servers, which listen for DDNS requests at 192.0.2.1
 12     // and 192.0.2.2.
 13     "forward-ddns":
 14     {
 15         "ddns-domains":
 16         [
 17             // DdnsDomain for zone "secure.example.org."
 18             {
 19                 "name": "secure.example.org.",
 20                 "comment": "DdnsDomain example",
 21                 "dns-servers":
 22                 [
 23                     { // This server has an entry in gss/servers and
 24                       // thus will use GSS-TSIG.
 25                         "ip-address": "192.0.2.1"
 26                     },
 27                     { // This server also has an entry there, so will
 28                       // use GSS-TSIG, too.
 29                         "ip-address": "192.0.2.2",
 30                         "port": 5300
 31                     }
 32                 ]
 33             }
 34         ]
 35     },
 36
 37     // Reverse zone: we want to update the reverse zone "2.0.192.in-addr.arpa".
 38     "reverse-ddns":
 39     {
 40         "ddns-domains":
 41         [
 42             {
 43                 "name": "2.0.192.in-addr.arpa.",
 44                 "dns-servers":
 45                 [
 46                     {
 47                         // There is a GSS-TSIG definition for this server (see
 48                         // DhcpDdns/gss-tsig/servers), so it will use
 49                         // Krb/GSS-TSIG.
 50                         "ip-address": "192.0.2.1"
 51                     }
 52                 ]
 53             }
 54         ]
 55     },
 56
 57     // The GSS-TSIG hook is loaded and its configuration is specified here.
 58     "hooks-libraries": [
 59     {
 60         "library": "/opt/lib/libddns_gss_tsig.so",
 61         "parameters": {
 62             // This section governs the GSS-TSIG integration. Each server
 63             // mentioned in forward-ddns and/or reverse-ddns needs to have
 64             // an entry here to be able to use GSS-TSIG defaults (optional,
 65             // if specified they apply to all the GSS-TSIG servers, unless
 66             // overwritten on specific server level).
 67
 68             "server-principal": "DNS/server.example.org@EXAMPLE.ORG",
 69             "client-principal": "DHCP/admin.example.org@EXAMPLE.ORG",
 70
 71             // client-keytab and credentials-cache can both be used to
 72             // store client keys. As credentials cache is more flexible,
 73             // it is recommended to use it. Typically, using both at the
 74             // same time may cause problems.
 75             // "client-keytab": "FILE:/etc/dhcp.keytab", // toplevel only
 76             "credentials-cache": "FILE:/etc/ccache", // toplevel only
 77             "gss-replay-flag": true, // GSS anti replay service
 78             "gss-sequence-flag": false, // no GSS sequence service
 79             "tkey-lifetime": 3600, // 1 hour
 80             "rekey-interval": 2700, // 45 minutes
 81             "retry-interval": 120, // 2 minutes
 82             "tkey-protocol": "TCP",
 83             "fallback": false,
 84
 85             // The list of GSS-TSIG capable servers
 86             "servers": [
 87                 {
 88                     // First server (identification is required)
 89                     "id": "server1",
 90                     "domain-names": [ ], // if not specified or empty, will
 91                                          // match all domains that want to
 92                                          // use this IP+port pair
 93                     "ip-address": "192.0.2.1",
 94                     "port": 53,
 95                     "server-principal": "DNS/server1.example.org@EXAMPLE.ORG",
 96                     "client-principal": "DHCP/admin1.example.org@EXAMPLE.ORG",
 97                     "gss-replay-flag": false, // no GSS anti replay service
 98                     "gss-sequence-flag": false, // no GSS sequence service
 99                     "tkey-lifetime": 7200, // 2 hours
100                     "rekey-interval": 5400, // 90 minutes
101                     "retry-interval": 240, // 4 minutes
102                     "tkey-protocol": "TCP",
103                     "fallback": true // if no key is available fallback to the
104                                      // standard behavior (vs skip this server)
105                 },
106                 {
107                     // The second server (it has most of the parameters missing
108                     // as those are using the defaults specified above)
109                     "id": "server2",
110                     "ip-address": "192.0.2.2",
111                     "port": 5300
112                 }
113             ]
114         }
115     }
116     ]
117
118     // Additional parameters, such as logging, control socket and
119     // others omitted for clarity.
120 }
121
122 }

This configuration file contains a number of extra elements.

First, a list of forward and/or reverse domains with related DNS servers identified by their IP+port pairs is defined. If the port is not specified, the default of 53 is assumed. This is similar to basic mode, with no authentication done using TSIG keys, with the exception that static TSIG keys are not referenced by name.

Second, libddns_gss_tsig.so must be specified on the hooks-libraries list. This hook takes many parameters. The most important one is servers, which is a list of GSS-TSIG-capable servers. If there are several servers and they share some characteristics, the values can be specified in the parameters scope as defaults. In the example above, the defaults that apply to all servers, unless otherwise specified on a per-server scope, are defined in lines 63 through 68. The defaults can be skipped if there is only one server defined, or if all servers have different values.

List of available parameters

Name

Scope

Type

Default value

Description

client-keytab

global / server

string

empty

the Kerberos client key table

credentials-cache

global / server

string

empty

the Kerberos credentials cache

server-principal

global / server

string

empty

the Kerberos principal name of the DNS server that will receive updates

client-principal

global / server

string

empty

the Kerberos principal name of the Kea D2 service

gss-replay-flag

global / server

true / false

true

require the GSS anti replay service (GSS_C_REPLAY_FLAG)

gss-sequence-flag

global / server

true / false

false

require the GSS sequence service (GSS_C_SEQUENCE_FLAG)

tkey-protocol

global / server

string "TCP" / "UDP"

"TCP"

the protocol used to establish the security context with the DNS servers

tkey-lifetime

global / server

uint32

3600 seconds
( 1 hour )

the lifetime of GSS-TSIG keys

rekey-interval

global / server

uint32

2700 seconds
( 45 minutes )

the time interval the keys are checked for rekeying

retry-interval

global / server

uint32

120 seconds
( 2 minutes )

the time interval to retry to create a key if any error occurred previously

fallback

global / server

true / false

false

the behavior to fallback to non-GSS-TSIG when GSS-TSIG should be used but no GSS-TSIG key is available.

exchange-timeout

global / server

uint32

3000 milliseconds
( 3 seconds )

the time used to wait for the GSS-TSIG TKEY exchange to finish before it timeouts

user-context

global / server

string

empty

the user-provided data in JSON format (not used by the GSS-TSIG hook)

comment

global / server

string

empty

ignored

id

server

string

empty

identifier to a DNS server (required)

domain-names

server

list of strings

empty

the many-to-one relationship between D2 DNS servers and GSS-TSIG DNS servers

ip-address

server

IPv4 / IPv6 address

empty

the IP address at which the GSS-TSIG DNS server listens for DDNS and TKEY requests (required)

port

server

uint16

53

the DNS transport port at which the GSS-TSIG DNS server listens for DDNS and TKEY requests

The global parameters are described below:

  • client-keytab specifies the Kerberos client key table. For instance, FILE:<filename> can be used to point to a specific file. This parameter can be specified only once, in the parameters scope, and is the equivalent of setting the KRB5_CLIENT_KTNAME environment variable. An empty value is silently ignored.

  • credentials-cache specifies the Kerberos credentials cache. For instance, FILE:<filename> can be used to point to a file or, if using a directory which supports more than one principal, DIR:<directory-path>. This parameter can be specified only once, in the parameters scope, and is the equivalent of setting the KRB5CCNAME environment variable. An empty value is silently ignored.

  • server-principal is the Kerberos principal name of the DNS server that receives updates. In other words, this is the DNS server's name in the Kerberos system. This parameter is mandatory, and uses the typical Kerberos notation: <SERVICE-NAME>/<server-domain-name>@<REALM>.

  • client-principal is the Kerberos principal name of the Kea D2 service. It is optional, and uses the typical Kerberos notation: <SERVICE-NAME>/<server-domain-name>@<REALM>.

  • gss-replay-flag determines if the GSS anti replay service is required. It is by default but this can be disabled.

  • gss-sequence-flag determines if the GSS sequence service is required. It is not by default but is required by the standard so it can be enabled.

  • tkey-protocol determines which protocol is used to establish the security context with the DNS servers. Currently, the only supported values are TCP (the default) and UDP.

  • tkey-lifetime determines the lifetime of GSS-TSIG keys in the TKEY protocol. The value must be greater than the rekey-interval value. It is expressed in seconds and defaults to 3600 (one hour).

  • rekey-interval governs the time interval at which the keys for each configured server are checked for rekeying, i.e. when a new key is created to replace the current usable one if its age is greater than the rekey-interval value. The value must be smaller than the tkey-lifetime value (it is recommended to be set between 50% and 80% of the tkey-lifetime value). It is expressed in seconds and defaults to 2700 (45 minutes, or 75% of one hour).

  • retry-interval governs the time interval at which to retry to create a key if any error occurred previously for any configured server. The value must be smaller than the rekey-interval value, and should be at most 1/3 of the difference between tkey-lifetime and rekey-interval. It is expressed in seconds and defaults to 120 (2 minutes).

  • fallback governs the behavior when GSS-TSIG should be used (a matching DNS server is configured) but no GSS-TSIG key is available. If set to false (the default), this server is skipped; if set to true, the DNS server is ignored and the DNS update is sent with the configured DHCP-DDNS protection (e.g. TSIG key), or without any protection when none was configured.

  • exchange-timeout governs the amount of time to wait for the GSS-TSIG TKEY exchange to finish before the process times out. It is expressed in milliseconds and defaults to 3000 (3 seconds).

  • user-context is an optional parameter (see Comments and User Context for a general description of user contexts in Kea).

  • comment is allowed but currently ignored.

  • servers specifies the list of DNS servers where GSS-TSIG is enabled.

The server map parameters are described below:

  • id assigns an identifier to a DNS server. It is used for statistics and commands. It is required, and must be both not empty and unique.

  • domain-names governs the many-to-one relationship between D2 DNS servers and GSS-TSIG DNS servers: for each domain name on this list, Kea looks for a D2 DNS server for this domain with the specified IP address and port. An empty list (the default) means that all domains match.

  • ip-address specifies the IP address at which the GSS-TSIG DNS server listens for DDNS and TKEY requests. It is a mandatory parameter.

  • port specifies the DNS transport port on which the GSS-TSIG DNS server listens for DDNS and TKEY requests. It defaults to 53.

  • server-principal is the Kerberos principal name of the DNS server that receives updates. The server-principal parameter set at the per-server level takes precedence over one set at the global level. It is a mandatory parameter which must be specified at either the global or the server level.

  • client-principal is the Kerberos principal name of the Kea D2 service for this DNS server. The client-principal parameter set at the per-server level takes precedence over one set at the global level. It is an optional parameter.

  • gss-replay-flag determines if the GSS anti replay service is required. The gss-replay-flag parameter set at the per-server level takes precedence over one set at the global level. It is an optional parameter which defaults to true.

  • gss-sequence-flag determines if the GSS sequence service is required. The gss-sequence-flag parameter set at the per-server level takes precedence over one set at the global level. It is an optional parameter which defaults to false.

  • tkey-protocol determines which protocol is used to establish the security context with the DNS server. The tkey-protocol parameter set at the per-server level takes precedence over one set at the global level. The default and supported values for the per-server level parameter are the same as for the global-level parameter.

  • tkey-lifetime determines the lifetime of GSS-TSIG keys in the TKEY protocol for the DNS server. The tkey-lifetime parameter set at the per-server level takes precedence over one set at the global level. The default and supported values for the per-server level parameter are the same as for the global-level parameter.

  • rekey-interval governs the time interval at which the keys for this particular server are checked for rekeying, i.e. when a new key is created to replace the current usable one if its age is greater than the rekey-interval value. The value must be smaller than the tkey-lifetime value (it is recommended to be set between 50% and 80% of the tkey-lifetime value). The rekey-interval parameter set at the per-server level takes precedence over one set at the global level. The default and supported values for the per-server level parameter are the same as for the global-level parameter.

  • retry-interval governs the time interval at which to retry to create a key if any error occurred previously for this particular server. The value must be smaller than the rekey-interval value, and should be at most 1/3 of the difference between tkey-lifetime and rekey-interval. The retry-interval parameter set at the per-server level takes precedence over one set at the global level. The default and supported values for the per-server level parameter are the same as for the global-level parameter.

  • fallback governs the behavior when GSS-TSIG should be used (a matching DNS server is configured) but no GSS-TSIG key is available. The fallback parameter set at the per-server level takes precedence over one set at the global level. The default and supported values for the per-server level parameter are the same as for the global-level parameter..

  • exchange-timeout governs the amount of time to wait for the GSS-TSIG TKEY exchange to finish before the process times out. The exchange-timeout parameter set at the per-server level takes precedence over one set at the global level. The default and supported values for the per-server level parameter are the same as for the global-level parameter.

  • user-context is an optional parameter (see Comments and User Context for a general description of user contexts in Kea).

  • comment is allowed but currently ignored.

Note

Generally it is not recommended to specify both the client keytab (client-keytab) and the credentials cache (credentials-cache), although this may differ between Kerberos implementations. The client keytab is just for the client key and is typically used to specify the key explicitly in more static manner, while the credentials cache can be used to store multiple credentials and can be dynamically updated by the Kerberos library. As such, the credentials-cache is more flexible and thus the recommended alternative.

Also note that only the read access right is needed to use the cache. Fetching credentials and updating the cache requires the write access right.

21.2.4.1. GSS-TSIG Automatic Key Removal

The server periodically deletes keys after they have been expired more than three times the length of the maximum key lifetime (the tkey-lifetime parameter). The user has the option to purge keys on demand by using the gss-tsig-purge-all command or the gss-tsig-purge command.

21.2.4.2. GSS-TSIG Configuration for Deployment

When using Kerberos 5 and BIND 9 as described in GSS-TSIG Deployment, the local resolver must point to the BIND 9 named server address. The local Kerberos must also be configured by putting the following text into the krb5.conf file:

[libdefaults]
    default_realm = EXAMPLE.ORG
    kdc_timesync = 1
    ccache_type = 4
    forwardable = true
    proxiable = true
[realms]
    EXAMPLE.ORG = {
            kdc = kdc.example.org
            admin_server = kdc.example.org
    }

With Windows AD, the DNS service is provided by AD, which also provides the Kerberos service. The required text in the krb5.conf file becomes:

[libdefaults]
    default_realm = <REALM>
    kdc_timesync = 1
    ccache_type = 4
    forwardable = true
    proxiable = true
[realms]
    ${REALM} = {
            kdc = <AD_IP_ADDR>
            admin_server = <AD_IP_ADDR>
    }

Even when the GSS-API library can use the secret from the client key table, it is far better for performance to get and cache credentials.

This can be done manually via the command:

kinit -k -t /tmp/dhcp.keytab DHCP/admin.example.org

or, when using AD:

kinit -k -t /tmp/dhcp.keytab DHCP/kea.<domain>

The credential cache can be displayed using klist.

In production, it is better to rely on a Kerberos Credential Manager as the System Security Services Daemon (sssd).

When using BIND 9, the server principal is in the form "DNS/server.example.org@EXAMPLE.ORG¨; with AD, the format is "DNS/<server>.<domain>@<REALM>".

21.2.5. GSS-TSIG Statistics

The GSS-TSIG hook library introduces new statistics at global and per-DNS-server levels:

  • gss-tsig-key-created - the number of created GSS-TSIG keys

  • tkey-sent - the number of sent TKEY exchange initial requests

  • tkey-success - the number of TKEY exchanges which completed with a success

  • tkey-timeout - the number of TKEY exchanges which completed on timeout

  • tkey-error - the number of TKEY exchanges which completed with an error other than a timeout

The relationship between keys and DNS servers is very different between the D2 code and static TSIG keys, and GSS-TSIG keys and DNS servers:

  • a static TSIG key can be shared between many DNS servers;

  • a GSS-TSIG key is only used by one DNS server inside a dedicated set of keys.

21.2.6. GSS-TSIG Commands

The GSS-TSIG hook library supports some commands, which are described below.

21.2.6.1. The gss-tsig-get-all Command

This command lists all the GSS-TSIG servers and keys.

An example command invocation looks like this:

{
    "command": "gss-tsig-get-all"
}

Here is an example of a response returning one GSS-TSIG server and one key:

{
    "result": 0,
    "text": "1 GSS-TSIG servers and 1 keys",
    "arguments": {
        "gss-tsig-servers": [
            {
                "id": "foo",
                "ip-address": "192.1.2.3",
                "port": 53,
                "server-principal": "DNS/foo.com@FOO.COM",
                "key-name-suffix": "foo.com.",
                "tkey-lifetime": 3600,
                "tkey-protocol": "TCP",
                "keys": [
                    {
                        "name": "1234.sig-foo.com.",
                        "inception-date": "2021-09-05 12:23:36.281176",
                        "server-id": "foo",
                        "expire-date": "2021-09-05 13:23:36.281176",
                        "status": "not yet ready",
                        "tkey-exchange": true
                    }
                ]
            },
            {
                "id": "bar",
                "ip-address": "192.1.2.4",
                "port": 53,
                "server-principal": "DNS/bar.com@FOO.COM",
                "key-name-suffix": "bar.com.",
                "tkey-lifetime": 7200,
                "tkey-protocol": "UDP",
                "keys": [ ]
            }
        ]
    }
}

21.2.6.2. The gss-tsig-get Command

This command retrieves information about the specified GSS-TSIG server.

An example command invocation looks like this:

{
    "command": "gss-tsig-get",
    "arguments": {
        "server-id": "foo"
    }
}

Here is an example of a response returning information about the server "foo":

{
    "result": 0,
    "text": "GSS-TSIG server[foo] found",
    "arguments": {
        "id": "foo",
        "ip-address": "192.1.2.3",
        "port": 53,
        "server-principal": "DNS/foo.com@FOO.COM",
        "key-name-suffix": "foo.com.",
        "tkey-lifetime": 3600,
        "tkey-protocol": "TCP",
        "keys": [
            {
                "name": "1234.sig-foo.com.",
                "server-id": "foo",
                "inception-date": "2021-09-05 12:23:36.281176",
                "expire-date": "2021-09-05 13:23:36.281176",
                "status": "not yet ready",
                "tkey-exchange": true
            }
        ]
    }
}

21.2.6.3. The gss-tsig-list Command

This command generates a list of GSS-TSIG server IDs and key names.

An example command invocation looks like this:

{
    "command": "gss-tsig-list"
}

Here is an example of a response returning two GSS-TSIG servers and three keys:

{
    "result": 0,
    "text": "2 GSS-TSIG servers and 3 keys",
    "arguments": {
        "gss-tsig-servers": [
            "foo",
            "bar"
        ],
        "gss-tsig-keys": [
            "1234.example.com.",
            "5678.example.com.",
            "43888.example.org."
        ]
    }
}

21.2.6.4. The gss-tsig-key-get Command

This command retrieves information about the specified GSS-TSIG key.

An example command invocation looks like this:

{
    "command": "gss-tsig-key-get",
    "arguments": {
        "key-name": "1234.sig-foo.com."
    }
}

Here is an example of a response returning information about GSS-TSIG key "1234.sig-foo.com.":

{
    "result": 0,
    "text": "GSS-TSIG key '1234.sig-foo.com.' found",
    "arguments": {
        "name": "1234.sig-foo.com.",
        "server-id": "foo",
        "inception-date": "2021-09-05 12:23:36.281176",
        "expire-date": "2021-09-05 13:23:36.281176",
        "status": "not yet ready",
        "tkey-exchange": true
    }
}

21.2.6.5. The gss-tsig-key-expire Command

This command expires the specified GSS-TSIG key.

An example command invocation looks like this:

{
    "command": "gss-tsig-key-expire",
    "arguments": {
        "key-name": "1234.sig-foo.com."
    }
}

Here is an example of a response indicating that GSS-TSIG key "1234.sig-foo.com." has been expired:

{
    "result": 0,
    "text": "GSS-TSIG key '1234.sig-foo.com.' expired"
}

21.2.6.6. The gss-tsig-key-del Command

This command deletes the specified GSS-TSIG key.

An example command invocation looks like this:

{
    "command": "gss-tsig-key-del",
    "arguments": {
        "key-name": "1234.sig-foo.com."
    }
}

Here is an example of a response indicating that GSS-TSIG key "1234.sig-foo.com." has been deleted:

{
    "result": 0,
    "text": "GSS-TSIG key '1234.sig-foo.com.' deleted"
}

21.2.6.7. The gss-tsig-purge-all Command

This command removes all unusable GSS-TSIG keys.

An example command invocation looks like this:

{
    "command": "gss-tsig-purge-all"
}

Here is an example of a response indicating that two GSS-TSIG keys have been purged:

{
    "result": 0,
    "text": "2 purged GSS-TSIG keys"
}

21.2.6.8. The gss-tsig-purge Command

This command removes unusable GSS-TSIG keys for the specified server.

An example command invocation looks like this:

{
    "command": "gss-tsig-purge",
    "arguments": {
        "server-id": "foo"
    }
}

Here is an example of a response indicating that two GSS-TSIG keys for server "foo" have been purged:

{
    "result": 0,
    "text": "2 purged keys for GSS-TSIG server[foo]"
}

21.2.6.9. The gss-tsig-rekey-all Command

This command unconditionally creates new GSS-TSIG keys (rekeys) for all DNS servers.

An example command invocation looks like this:

{
    "command": "gss-tsig-rekey-all"
}

Here is an example of a response indicating that a rekey was performed:

{
    "result": 0,
    "text": "rekeyed"
}

This command is useful when, for instance, the DHCP-DDNS server is reconnected to the network.

21.2.6.10. The gss-tsig-rekey Command

This command unconditionally creates new GSS-TSIG keys (rekeys) for a specified DNS server.

An example command invocation looks like this:

{
    "command": "gss-tsig-rekey",
    "arguments": {
        "server-id": "foo"
    }
}

Here is an example of a response indicating that a rekey was performed:

{
    "result": 0,
    "text": "GSS-TSIG server[foo] rekeyed"
}

This command is typically used when a DNS server has been rebooted, so that existing GSS-TSIG keys shared with this server can no longer be used.

21.3. RADIUS

21.3.1. RADIUS Overview

This hook library allows Kea to interact with two types of RADIUS services: access and accounting. Although the most common DHCP and RADIUS integration is done on the DHCP relay-agent level (DHCP clients send DHCP packets to DHCP relays; those relays contact the RADIUS server and depending on the response either send the packet to the DHCP server or drop it), it does require DHCP relay hardware to support RADIUS communication. Also, even if the relay has the necessary support, it is often not flexible enough to send and receive additional RADIUS attributes. As such, the alternative looks more appealing: to extend the DHCP server to talk to RADIUS directly. That is the goal of this library.

Note

This library can only be loaded by the kea-dhcp4 or the kea-dhcp6 process.

The major feature of this hook library is the ability to use RADIUS authorization. When a DHCP packet is received, the Kea server sends an Access-Request to the RADIUS server and waits for a response. The server then sends back either an Access-Accept with specific client attributes, or an Access-Reject. There are two cases supported here: first, the Access-Accept includes a Framed-IP-Address attribute (for DHCPv4) or a Framed-IPv6-Address attribute (for DHCPv6), which are interpreted by Kea as instructions to assign the specified IPv4 or IPv6 address. This effectively means RADIUS can act as an address-reservation database.

The second supported case is the ability to assign clients to specific pools based on a RADIUS response. In this case, the RADIUS server sends back an Access-Accept with a Framed-Pool attribute. For both DHCPv4 and DHCPv6, Kea interprets this attribute as a client class. With the addition of the ability to limit access to pools to specific classes (see Configuring Pools With Class Information), RADIUS can be used to force the client to be assigned a dynamic address from a specific pool. Furthermore, the same mechanism can be used to control what kind of options the client gets if there are DHCP options specified for a particular class.

21.3.2. RADIUS Hook Library Configuration

The RADIUS hook is a library that must be loaded by either kea-dhcp4 or kea-dhcp6 servers. Unlike some other available hook libraries, this one takes many parameters. For example, this configuration can be used:

{
  "Dhcp4": {

    // Your regular DHCPv4 configuration parameters goes here.

    "hooks-libraries": [
      {
        // Note that RADIUS requires host-cache for proper operation,
        // so that library is loaded as well.
        "library": "/usr/local/lib/kea/hooks/libdhcp_host_cache.so"
      },
      {
        "library": "/usr/local/lib/kea/hooks/libdhcp_radius.so",
        "parameters": {

          // Specify where the dictionary is located.
          "dictionary": "/etc/kea/radius/dictionary",

          // Specify which address to use to communicate with RADIUS servers
          "bindaddr": "*"

          // More RADIUS parameters go here.
        }
      }
    ]
  }
}

RADIUS is a complicated environment. As such, it is not feasible to provide a default configuration that works for everyone. However, we do have an example that showcases some of the more common features. Please see doc/examples/kea4/hooks-radius.json in the Kea sources.

The RADIUS hook library supports the following global configuration flags:

  • bindaddr (default "*") - specifies the address to be used by the hook library in communication with RADIUS servers. The "*" special value tells the kernel to choose the address at hook library load time.

  • canonical-mac-address (default false) - specifies whether MAC addresses in attributes follow the canonical RADIUS format (lowercase pairs of hexadecimal digits separated by -).

  • client-id-pop0 (default false) - is used with libdhcp_flex_id.so. Removes the leading zero (or pair of zeroes in DHCPv6) type in the client id (duid in DHCPv6). See client-id-printable for any value implications when used in conjunction with it.

  • client-id-printable (default false) - checks whether the client-id/duid content is printable and uses it as is instead of in hexadecimal. Implies client-id-pop0 and extract-duid as 0 and 255 are not printable.

  • deadtime (default 0) - is a mechanism that helps in sorting the servers such that the servers that have proved responsive so far are inquired first, and the servers that have proved unresponsive are left at the end. The deadtime value specifies the number of seconds after which a server is considered unresponsive. 0 disables the mechanism.

  • dictionary (default "/etc/kea/radius/dictionary") - is the attribute and value dictionary. Note that it is a critical parameter. A dictionary is provided by Kea and is set by default.

  • extract-duid (default true) - extracts the embedded duid from an RFC-4361-compliant DHCPv4 client id. See client-id-printable for any value implications when used in conjunction with it.

  • identifier-type4 (default "client-id") - specifies the identifier type to build the User-Name attribute. It should be the same as the host identifier. When libdhcp_flex_id.so is used, then replace-client-id must be set to true and client-id must be used with client-id-pop0 enabled.

  • identifier-type6 (default "duid") - specifies the identifier type to build the User-Name attribute. It should be the same as the host identifier. When libdhcp_flex_id.so is used, then replace-client-id must be set to true and duid must be used with client-id-pop0 enabled.

  • nas-ports (default []), specifies the NAS port to use in place of a subnet ID (default behavior). It is an array of maps, each map having two elements at most: the mandatory NAS port value, and, optionally, a selector consisting of either a subnet id, a subnet prefix, or a shared-network name. If the selector is applied to the packet, the NAS port is used instead of the subnet id. When the subnet id is 0 or missing, the specified NAS port acts as a default. Its substition happens for all packets that did not match a selector.

  • realm (default "") - is the default realm.

  • reselect-subnet-address (default false) - enables subnet reselection according to the value of the Framed-IP-Address or, respectively, the Framed-IPv6-Address attribute from the RADIUS access response. With this flag enabled, if the IP address is not in range of the currently selected subnet, but is in range of another subnet that is selectable with regards to other criteria, the latter subnet is selected and used further in the lease assignment process.

  • reselect-subnet-pool (default false) - enables subnet reselection according to the value of the Framed-Pool attribute from the RADIUS access response. With this flag enabled, if the currently selected subnet is not guarded by the client class represented by the attribute value, but there is another selectable subnet that is guarded by it, the latter subnet is selected and used further in the lease assignment process. This reselection is attempted first, and if successful, it prevents the function of reselect-subnet-address from coming into effect.

  • retries (default 3) - is the number of retries before trying the next server.

  • session-history (default "") - is the name of the file providing persistent storage for accounting session history.

  • thread-pool-size (default 0) indicates the number of threads that is used for sending RADIUS requests and processing RADIUS responses for both access and accounting services before passing it to the core thread pool. A value of 0 instructs the RADIUS hook library to use the same number of threads used for core DHCP processing. This value is only relevant if Kea core is configured as multi-threaded. Single-threaded Kea core results in single-threaded RADIUS processing.

  • timeout (default 10) - is the number of seconds during which a response is awaited.

Two services are supported:

  • access - the authorization service.

  • accounting - the accounting service.

At the service level, three sections can be configured:

  • Servers that define RADIUS services that the library is expected to contact. Each server may have the following items specified:

    • name - specifies the IP address of the server. A domain name may be used and will be resolved at hook library load time.

    • port - specifies the UDP port of the server. By default, it is 1812 for access and 1813 for accounting.

    • secret - authenticates messages.

    When no server is specified, the service is disabled.

  • Attributes which define additional information that the Kea server sends to a RADIUS server. The parameter must be identified either by a name or type. Its value can be specified in one of three possible ways: data (which defines a plain text value), raw (which defines the value in hex), or expr (which defines an expression that is evaluated for each incoming packet independently).

    • name - the name of the attribute.

    • type - the type of the attribute. Either the type or the name must be provided, and the attribute must be defined in the dictionary.

    • data - the first of three ways to specify the attribute content. It specifies the textual representation of the attribute content.

    • raw - the second of three ways to specify the attribute content. It specifies the content in hexadecimal.

    • expr - the last of the three ways to specify the attribute content. It specifies an evaluation expression on the DHCP query packet. Currently this is restricted to the access service.

    Attributes are supported only for the access service.

  • The peer-updates boolean flag (default true) controls whether lease updates coming from an active High-Availability (HA) partner should result in an accounting request. This may be desirable to remove duplicates if HA partners are configured to send request to the same RADIUS server. The flag is only supported by the accounting service. The lease synchronization process at the startup of an HA node does not trigger a RADIUS accounting request, regardless of the value of this flag.

  • The max-pending-requests positive integer (default 0) limits the number of pending RADIUS requests. The value 0 means no limit. It is supported only by the access service. 64 can be a good value to set it to.

For example, to specify a single access server available on localhost that uses "xyz123" as a secret, and tell Kea to send three additional attributes (User-Password, Connect-Info, and Configuration-Token), the following snippet could be used:

{
  "parameters": {

    // Other RADIUS parameters here

    "access": {

      // This starts the list of access servers.
      "servers": [
        {
          // These are parameters for the first (and only) access server
          "name": "127.0.0.1",
          "port": 1812,
          "secret": "xyz123"
        }
      // Additional access servers could be specified here.
      ],

      // This defines a list of additional attributes Kea will send to each
      // access server in Access-Request.
      "attributes": [
        {
          // This attribute is identified by name (must be present in the
          // dictionary) and has static value (i.e. the same value will be
          // sent to every server for every packet).
          "name": "User-Password",
          "data": "mysecretpassword"
        },
        {
          // It is also possible to specify an attribute using its type,
          // rather than a name. 77 is Connect-Info. The value is specified
          // using hex. Again, this is a static value. It will be sent the
          // same for every packet and to every server.
          "type": 77,
          "raw": "65666a6a71"
        },
        {
           // This example shows how an expression can be used to send dynamic value.
           // The expression (see Using Expressions in Classification) may take any
           // value from the incoming packet or even its metadata e.g. the
           // interface it was received over from.
           "name": "Configuration-Token",
           "expr": "hexstring(pkt4.mac,':')"
        }
      ] // End of attributes
    }, // End of access

    // Accounting parameters.
    "accounting": {
      // This starts the list of accounting servers.
      "servers": [
        {
          // These are parameters for the first (and only) accounting server
          "name": "127.0.0.1",
          "port": 1813,
          "secret": "sekret"
        }
        // Additional accounting servers could be specified here.
      ]
    }
  }
}

Customization is sometimes required for certain attributes by devices belonging to various vendors. This is a great way to leverage the expression evaluation mechanism. For example, MAC addresses which might be used as a convenience value for the User-Password attribute are most likely to appear in colon-hexadecimal notation (de:ad:be:ef:ca:fe), but they might need to be expressed in hyphen-hexadecimal notation (de-ad-be-ef-ca-fe). Here's how to specify that:

{
   "parameters": {
      "access": {
         "attributes": [
            {
               "name": "User-Password",
               "expr": "hexstring(pkt4.mac, '-')"
            }
         ]
      }
   }
}

And here's how to specify period-separated hexadecimal notation (dead.beef.cafe), preferred by Cisco devices:

{
   "parameters": {
      "access": {
         "attributes": [
            {
               "name": "User-Password",
               "expr": "substring(hexstring(pkt4.mac, ''), 0, 4) + '.' + substring(hexstring(pkt4.mac, ''), 4, 4) + '.' + substring(hexstring(pkt4.mac, ''), 8, 4)"
            }
         ]
      }
   }
}

For libdhcp_radius.so to operate properly in DHCPv4, libdhcp_host_cache.so must also be loaded. The reason for this is somewhat complex. In a typical deployment, the DHCP clients send their packets via DHCP relay, which inserts certain Relay Agent Information options, such as circuit-id or remote-id. The values of those options are then used by the Kea DHCP server to formulate the necessary attributes in the Access-Request message sent to the RADIUS server. However, once the DHCP client gets its address, it then renews by sending packets directly to the DHCP server. As a result, the relays are not able to insert their RAI options, and the DHCP server cannot send the Access-Request queries to the RADIUS server by using just the information from incoming packets. Kea needs to keep the information received during the initial Discover/Offer exchanges and use it again later when sending accounting messages.

This mechanism is implemented based on user context in host reservations. (See Comments and User Context and User Contexts in Hooks for details.) The host-cache mechanism allows the information retrieved by RADIUS to be stored and later used for sending access and accounting queries to the RADIUS server. In other words, the host-cache mechanism is mandatory, unless administrators do not want RADIUS communication for messages other than Discover and the first Request from each client.

Note

Currently the RADIUS hook library is incompatible with the early-global-reservations-lookup global parameter i.e. setting the parameter to true raises an error when the hook library is loaded.

Note

Currently the RADIUS hook library is incompatible with the multi-subnet shared networks that have host reservations other than global. Loading the RADIUS hook library in a Kea DHCP server that has this configuration raises an error.

21.3.3. RADIUS Server Setup Example

The RADIUS hook library requires at least one RADIUS server to function. One popular open-source implementation is FreeRADIUS. This is how it can be set up to enable basic functionality in Kea.

  1. Install FreeRADIUS through the package manager or from the tarballs available on [the freeradius.org download page](https://freeradius.org/releases/).

  2. Establish the FreeRADIUS configuration directory. It's commonly /etc/freeradius, but it may be /etc/raddb.

  3. Generate certificates. Go to /etc/freeradius/certs. Run ./bootstrap or make. Wait until finished. It should take a few seconds.

  4. Check that the server is able to start. Running with the -X flag is a good way to display potential errors. Run radiusd -X or freeradius -X, whichever is available. It should display Ready to process requests on the final line.

  5. If the Kea DHCP server and the RADIUS server are on different machines, edit /etc/freeradius/clients.conf with the proper address under ipadddr. This file is also where the secret is set, which needs to match the one set in the hook library's configuration.

  6. If RADIUS is used for the purpose of authorizing DHCP clients, each DHCP client needs to have an entry in the authorize file, which can be commonly found at:

    • /etc/raddb/mods-config/files/authorize

    • /etc/freeradius/3.0/mods-config/files/authorize

    • /etc/freeradius/users (for RADIUS 2.x series)

    Entries need to have the password set which needs to match the password configured in the configuration of the RADIUS hook library under the User-Password attribute. Each entry can have zero, one or multiple attributes.

    In the following example, there are 6 entries with the password set to the client ID, which would need to be dynamically set in the hook library's configuration. Here's how the entries can look like:

    01:00:0c:01:02:03:04    Cleartext-password := "00:0c:01:02:03:04"
    
    01:00:0c:01:02:03:05    Cleartext-password := "00:0c:01:02:03:05"
        Framed-IP-Address = "192.0.2.5"
    
    01:00:0c:01:02:03:06    Cleartext-password := "00:0c:01:02:03:06"
        Framed-IP-Address = "192.0.2.6",
        Framed-Pool = "classical"
    
    00:03:00:01:00:0c:01:02:03:07    Cleartext-password := "00:0c:01:02:03:07"
    
    00:03:00:01:00:0c:01:02:03:08    Cleartext-password := "00:0c:01:02:03:08"
        Framed-IPv6-Address = "2001:db8::8"
    
    00:03:00:01:00:0c:01:02:03:09    Cleartext-password := "00:0c:01:02:03:09"
        Framed-IPv6-Address = "2001:db8::9",
        Framed-Pool = "classroom"
    
  7. Accounting should work out of the box with Kea, but customizations are possible in the accounting file, which can be commonly found at:

    • /etc/radius-config/mods-config/files/accounting

    • /etc/freeradius/3.0/mods-config/files/accounting

21.3.4. RADIUS Workflows for Lease Allocation

The following diagrams show a high level view of how RADIUS assists with the lease allocation process in kea-dhcp4 and kea-dhcp6.

../_images/radius.svg

Somewhat tangential to lease allocation, and not shown in the diagrams above, is the command_processed callout, which sends Accounting-Request messages when a lease command is received.

21.3.5. Differences Between RADIUS Hook Libraries Prior To 2.4.0 and As Of 2.6.0

The RADIUS hook library in 2.4.0 and prior versions relied on the FreeRADIUS client library to function. Starting with 2.6.0 and onwards, the RADIUS hook library is standalone with its own RADIUS client implementation and its own RADIUS dictionary. There are differences:

Feature

Old

New

Support for Attribute Data Types

string, ipaddr, ipv4prefix, integer, integer64, date, ifid, ipv6addr, ipv6prefix, tlv, abinary, byte, ether, short, signed, octets

string (can simulate any other unsupported data type too), ipaddr, integer, date (interpreted as integer), ipv6addr, ipv6prefix

Names of Standard Attributes

Taken from the FreeRADIUS dictionary.

Taken from the Kea RADIUS dictionary and the IANA registry. There is an aliasing mechanism built into the library that ensures backward compatibility e.g. Password translates to the standard name of the attribute User-Password.

Resolution of RADIUS Server Domain Names

At run time.

At hook library load time.

Automatic Deduction of Source Address for Reaching RADIUS Servers (configured with bindaddr: "*")

At run time.

At hook library load time.

RADIUS Server Limit per Service

8

Unlimited

Support for Including Dictionaries Inside Dictionaries

Yes

No

Support for Vendor Attributes

Yes

No

Attribute Names and Attribute Values

Case-insensitive

Case-sensitive

Integer Values

Do not require an attribute definition.

Must have an associated attribute definition in the dictionary.

Reply-Message Presence in the Kea Logs

Only as part of the aggregated list of attributes in RADIUS_AUTHENTICATION_ACCEPTED, RADIUS_ACCESS_CACHE_INSERT, RADIUS_ACCESS_CACHE_GET log messages.

Also has a dedicated RADIUS_REPLY_MESSAGE_ATTRIBUTE message per each Reply-Message attribute logged after a valid RADIUS reply is received.

Behavior of Multiple Attributes of the Same Type (except Reply-Message)

Experimentally, only the first attribute on the wire from an Access-Accept message is considered.

Experimentally, only the last attribute on the wire from an Access-Accept message is considered.