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 YANG modeling language,
defined in RFC 6020, to provide a uniform way
of handling configuration syntax of varied 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 uses libyang v1.0.240 and sysrepo v1.4.140. Use packages if they are provided on your system. There is always the alternative method of building from sources which should work on all popular OSs:
21.1.2.1. Installing libyang From Sources¶
$ git clone https://github.com/CESNET/libyang.git
$ cd libyang
$ git checkout v1.0.240
$ mkdir build
$ cd build
$ cmake .. -DGEN_CPP_BINDINGS=ON -DGEN_LANGUAGE_BINDINGS=ON -DGEN_PYTHON_BINDINGS=OFF
$ make
$ make install # without sudo if you're doing development and want to run unit tests
21.1.2.2. Installing sysrepo From Sources¶
$ git clone https://github.com/sysrepo/sysrepo.git
$ cd sysrepo
$ git checkout v1.4.140
$ mkdir build
$ cd build
$ cmake .. -DGEN_CPP_BINDINGS=ON -DGEN_LANGUAGE_BINDINGS=ON -DGEN_PYTHON_BINDINGS=OFF
$ make
$ make install # without sudo if you're doing development and want to run unit tests
21.1.3. Quick Sysrepo Overview¶
This section offers a rather 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 the YANG syntax
in module files named: "module-name"[@"revision"].yang
The revision part is optional and has 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. The dependency modules are
also provided in src/share/yang/modules in sources and in
share/kea/yang/modules in the installation directory.
To install modules from sources, do the following to install all modules:
$ ./src/share/yang/modules/utils/reinstall.sh
OR if you installed sysrepo in a custom path:
$ ./src/share/yang/modules/utils/reinstall.sh -s /path/to/sysrepo
If you want 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]: Libyang internal module "yang" was installed.
[INF]: File "ietf-datastores@2018-02-14.yang" was installed.
[INF]: Sysrepo internal dependency module "ietf-datastores" was installed.
[INF]: File "ietf-yang-library@2019-01-04.yang" was installed.
[INF]: Sysrepo internal module "ietf-yang-library" was installed.
[INF]: File "sysrepo-monitoring@2021-01-15.yang" was installed.
[INF]: Sysrepo internal module "sysrepo-monitoring" was installed.
[INF]: File "sysrepo-plugind@2020-12-10.yang" was installed.
[INF]: Sysrepo internal module "sysrepo-plugind" was installed.
[INF]: File "ietf-netconf@2011-06-01.yang" was installed.
[INF]: Sysrepo internal dependency module "ietf-netconf" was installed.
[INF]: File "ietf-netconf-with-defaults@2011-06-01.yang" was installed.
[INF]: Sysrepo internal module "ietf-netconf-with-defaults" was installed.
[INF]: File "ietf-netconf-notifications@2012-02-06.yang" was installed.
[INF]: Sysrepo internal module "ietf-netconf-notifications" was installed.
[INF]: File "ietf-origin@2018-02-14.yang" was installed.
[INF]: Sysrepo internal module "ietf-origin" was installed.
[INF]: Connection 20 created.
[INF]: Module "keatest-module" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: File "keatest-module@2018-11-20.yang" was installed.
[INF]: Module "keatest-module" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 21 created.
[INF]: Module "ietf-interfaces" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: File "ietf-interfaces@2018-02-20.yang" was installed.
[INF]: Module "ietf-interfaces" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 22 created.
[INF]: Module "ietf-dhcpv6-client" scheduled for installation.
[INF]: File "ietf-dhcpv6-options@2018-09-04.yang" was installed.
[INF]: File "ietf-dhcpv6-types@2018-09-04.yang" was installed.
[INF]: Applying scheduled changes.
[INF]: File "ietf-dhcpv6-client@2018-09-04.yang" was installed.
[INF]: Module "ietf-dhcpv6-client" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 23 created.
[INF]: Module "ietf-dhcpv6-relay" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: File "ietf-dhcpv6-relay@2018-09-04.yang" was installed.
[INF]: Module "ietf-dhcpv6-relay" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 24 created.
[INF]: Module "ietf-dhcpv6-server" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: File "ietf-dhcpv6-server@2018-09-04.yang" was installed.
[INF]: Module "ietf-dhcpv6-server" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 25 created.
[INF]: Module "ietf-yang-types" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: Module "ietf-yang-types" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 26 created.
[INF]: Module "ietf-dhcpv6-options" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: Module "ietf-dhcpv6-options" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 27 created.
[INF]: Module "ietf-dhcpv6-types" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: Module "ietf-dhcpv6-types" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 28 created.
[INF]: Module "ietf-inet-types" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: Module "ietf-inet-types" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 29 created.
[INF]: Module "kea-types" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: File "kea-types@2019-08-12.yang" was installed.
[INF]: Module "kea-types" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 30 created.
[INF]: Module "kea-dhcp-types" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: File "kea-dhcp-types@2019-08-12.yang" was installed.
[INF]: Module "kea-dhcp-types" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 31 created.
[INF]: Module "kea-dhcp-ddns" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: File "kea-dhcp-ddns@2019-08-12.yang" was installed.
[INF]: Module "kea-dhcp-ddns" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 32 created.
[INF]: Module "kea-ctrl-agent" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: File "kea-ctrl-agent@2019-08-12.yang" was installed.
[INF]: Module "kea-ctrl-agent" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 33 created.
[INF]: Module "kea-dhcp4-server" scheduled for installation.
[INF]: Applying scheduled changes.
[INF]: File "kea-dhcp4-server@2019-08-12.yang" was installed.
[INF]: Module "kea-dhcp4-server" was installed.
[INF]: Scheduled changes applied.
[INF]: Connection 34 created.
[INF]: Module "kea-dhcp6-server" scheduled for installation.
It is possible to confirm whether the models are imported correctly. To list the currently installed YANG modules:
$ sysrepoctl -l
After installation the result should be similar to this:
Sysrepo repository: /etc/sysrepo
Module Name | Revision | Flags | Owner | Permissions | Submodules | Features
-----------------------------------------------------------------------------------------------------
ietf-datastores | 2018-02-14 | I | user:user | 664 | |
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 | 664 | |
ietf-interfaces | 2018-02-20 | I | user:user | 600 | |
ietf-netconf | 2011-06-01 | I | user:user | 664 | |
ietf-netconf-notifications | 2012-02-06 | I | user:user | 664 | |
ietf-netconf-with-defaults | 2011-06-01 | I | user:user | 664 | |
ietf-origin | 2018-02-14 | I | user:user | 664 | |
ietf-yang-library | 2019-01-04 | I | user:user | 664 | |
ietf-yang-metadata | 2016-08-05 | i | | | |
ietf-yang-types | 2013-07-15 | I | user:user | 664 | |
kea-ctrl-agent | 2019-08-12 | I | user:user | 600 | |
kea-dhcp-ddns | 2019-08-12 | I | user:user | 600 | |
kea-dhcp-types | 2019-08-12 | I | user:user | 600 | |
kea-dhcp4-server | 2019-08-12 | I | user:user | 600 | |
kea-dhcp6-server | 2019-08-12 | I | user:user | 600 | |
kea-types | 2019-08-12 | I | user:user | 600 | |
keatest-module | 2018-11-20 | I | user:user | 600 | |
sysrepo-monitoring | 2021-01-15 | I | user:user | 600 | |
sysrepo-plugind | 2020-12-10 | I | user:user | 664 | |
yang | 2017-02-20 | I | user:user | 664 | |
Flags meaning: I - Installed/i - Imported; R - Replay support; N - New/X - Removed/U - Updated; F - Feature changes
Features: ! - Means that the feature is effectively disabled because of its false if-feature(s)
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 dependant modules have been uninstalled first. Installation and uninstallation must be done in dependency order and reverse-dependency order accordingly.
21.1.4. Supported YANG Models¶
The only 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. Several other models (kea-dhcp-ddns and kea-ctrl-agent)
are currently not supported.
21.1.5. 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 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.6. Configuration¶
The behavior described in Using the NETCONF Agent is controlled by a few configuration flags, which can be set in the global scope or in a specific managed-server scope. In the second case, 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 will
monitor 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 could possibly be incorrect:
- It can 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.
- It can fail to be translated from YANG to JSON, e.g. an invalid user context.
- It can fail Kea server sanity checks, e.g. an out-of-subnet-pool range or an unsupported database type.
- The syntax may be correct and pass server sanity checks but the configuration fails 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 or agents are described in the
managed-servers section. Each sub-section begins by 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 contains optionally:
boot-update,subscribe-changes, andvalidate-changes- control flags.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 eitherstdout,unix, orhttp.stdoutis the default; it is not really a socket, but it allowskea-netconfto run in debugging mode where everything is printed on stdout, and it can also be used to redirect commands easily.unixis the standard direct server control channel, which uses UNIX sockets, andhttpuses a control agent, which accepts HTTP connections.socket-name- the local socket name for theunixsocket type (default empty string).socket-url- the HTTP URL for thehttpsocket type (defaulthttp://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.
Hooks 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 hooks 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.7. 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": "DHCP4 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 hooks libraries that augment its operation.
// Currently there are no hook points defined in kea-netconf
// processing.
"hooks-libraries": [
// The hooks libraries list may contain more than one library.
{
// The only necessary parameter is the library filename.
"library": "/opt/local/netconf-commands.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 being rotated.
// Maxver specifies the maximum number of
// rotated files being kept.
"flush": true,
"maxsize": 204800,
"maxver": 4
}
],
"severity": "INFO",
"debuglevel": 0
}
]
}
}
21.1.8. 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; note that certain checks are possible only while running the actual server. The actual status is reported with exit code (0 = configuration looks ok, 1 = error encountered). Kea will print out log messages to standard output and error to standard error when testing 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 theconfig.reportfile produced by./configure; it is embedded in the executable binary.
21.1.9. 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.9.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 a 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 the 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 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 --edit=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.
21.1.9.2. Error Handling in NETCONF Operation Example¶
There are four classes of issues with the configurations applied via NETCONF:
- The configuration does not comply with the YANG schema.
- The configuration cannot be translated from YANG to the Kea JSON.
- The configuration is rejected by the Kea server.
- 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 --edit=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.9.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 --edit=twopools.xml
21.1.9.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 --edit=twosubnets.xml
21.1.9.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.9.6. Migrating YANG data from sysrepo v0.x to v1.x¶
Start the migration after turning off kea-netconf to make sure that backups done for both datastores are done at the same configuration state and no change happens between exporting them.
Unfortunately, sysrepo v0.x does not support import/export of all YANG modules. This was added in sysrepo v1.x. You will need to do per-module backup. It’s probably for the best, for isolating potential failures and preventing them from affecting all your modules.
With sysrepo v0.x:
$ sysrepocfg --datastore running --export=save.xml --format=xml kea-dhcp6-server
$ sysrepocfg --datastore startup --export=save.xml --format=xml kea-dhcp6-server
Install sysrepo v1.x and then:
$ sysrepocfg --datastore running --edit=save.xml
$ sysrepocfg --datastore startup --edit=save.xml
Module name and format are optional for v1.x, they are detected automatically.
In case of trouble, they can be provided with the --format xml and
--module kea-dhcp6-server flags.
If you upgraded after a long time, there might also be changes to the YANG modules themselves. In that case the backups will need some minor massaging. But this will be a dilligence that will have to be carried out occasionally and completely independent of sysrepo upgrades.
21.2. GSS-TSIG¶
21.2.1. GSS-TSIG Overview¶
Kea provides a 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, chose to adopt more complex GSS-TSIG approach that offers additional capabilities as using negotiated dynamic keys.
Kea provides the support of GSS-TSIG to protect DNS updates sent by the Kea DHCP-DDNS (aka D2) server in a premium hook, called gss_tsig.
The 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 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 the DNS update protection;
- TKEY (Secret Key Establishment for DNS) RFC 2930 which establishes secret keys for TSIG by transmitting crypto payloads between DNS parties;
- 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:
The security context is then used by GSS-TSIG to protect updates:
The Kea implementation of GSS-TSIG uses a GSS-API for Kerberos 5 with 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. Similar approach can be applied to other systems.
- Obtain the kea sources and premium packages, extract kea sources, then extract premium packages into premium/ directory within Kea source tree.
- Run autoreconf:
autoreconf -i
- Make sure
./configure --helpshows the--with-gssapioption. - Install either MIT (
libkrb5-dev) or Heimdal (heimdal-dev) library, for instance:
sudo apt install libkrb5-dev
- Run configure with the
--with-gssapioption:
./configure --with-gssapi
The --with-gssapi requires krb5-config tool to be present. This
tool is provided by both MIT Kerberos 5 and Heimdal, on some systems
where both Kerberos 5 and Heimdal are installed it is a symbolic link
to one of them. If it’s not in your standard location, you may specify
it with --with-gssapi=/path/to/krb5-config. It is strongly recommended
to use default installation locations as provided by 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
- Compile as usual
make -jXwhere X is the number of CPU cores available. - After compilation, the gss_tsig hook is available in the
premium/src/hooks/d2/gss_tsigdirectory. It can be loaded by the Kea DHCP-DDNS (D2) daemon.
The gss_tsig was developed using the MIT Kerberos 5 implementation but Heimdal is supported too. 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 as 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: in any report about the GSS-TSIG report
please add the result of the --all option of the krb5-config used
to configure Kea.
21.2.3. GSS-TSIG Deployment¶
Before using GSS-TSIG, a GSS-TSIG capable DNS server, such as BIND 9 or alternatively Microsoft Active Directory, must be deployed. Other GSS-TSIG capable implementations may work, but were not 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 ACL (Access Control List) 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 admin password for the default realm must be set:
krb5_newrealm
The following message will be displayed and you will be required to type 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:
You will be required to retype the password:
Re-enter KDC database master key to verify:
If successfully applied, the following message will be 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.
Next step consists in creating the principals for the Bind9 DNS server (the service protected by the GSS-TSIG TKEY) and for the DNS client (the Kea DHCP-DDNS server).
The Bind9 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 will be 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 is 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 will be 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 will be 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 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 status or restart 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 describes only the steps used for GSS-TSIG deployment (for complete configuration process please refer to Microsoft 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, for instance the client key table of Kea
- the second account will be 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 problem was that Kea DDNS was trying to perform update of reverse DNS zone while it was not configured. Easy solution was to add reverse DNS zone similar to the one configured in Kea. To do it open DNS Manager choose DNS from the list, from drop down list choose Reverse Lookup Zones click Action and New Zone then follow New Zone Wizard to add new zone.
21.2.4. Using GSS-TSIG¶
There is a number of steps required to enable the GSS-TSIG mechanism:
- the gss_tsig hook library has to be loaded by the D2 server
- the GSS-TSIG capable DNS servers have to be specified with their parameters
An excerpt from D2 server is provided below. More examples are available in the
doc/examples/ddns directory in the Kea sources.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | {
"DhcpDdns": {
// The following parameters are used to receive NCRs (NameChangeRequests)
// from the local Kea DHCP server. Make sure your kea-dhcp4 and kea-dhcp6
// matches this.
"ip-address": "127.0.0.1",
"port": 53001,
"dns-server-timeout" : 1000,
// Forward zone: secure.example.org. It uses GSS-TSIG. It is served
// by two DNS servers, which listen for DDNS requests at 192.0.2.1
// and 192.0.2.2.
"forward-ddns":
{
"ddns-domains":
[
// DdnsDomain for zone "secure.example.org."
{
"name": "secure.example.org.",
"comment": "DdnsDomain example",
"dns-servers":
[
{ // This server has an entry in gss/servers and
// thus will use GSS-TSIG.
"ip-address": "192.0.2.1"
},
{ // This server also has an entry there, so will
// use GSS-TSIG, too.
"ip-address": "192.0.2.2",
"port": 5300
}
]
}
]
},
// Reverse zone: we want to update the reverse zone "2.0.192.in-addr.arpa".
"reverse-ddns":
{
"ddns-domains":
[
{
"name": "2.0.192.in-addr.arpa.",
"dns-servers":
[
{
// There is GSS-TSIG definition for this server (see
// DhcpDdns/gss-tsig/servers), so it will use
// Krb/GSS-TSIG.
"ip-address": "192.0.2.1"
}
]
}
]
},
// Need to add gss-tsig hook here
"hooks-libraries": [
{
"library": "/opt/lib/libddns_gss_tsig.so",
"parameters": {
// This section governs the GSS-TSIG integration. Each server
// mentioned in forward-ddns and/or reverse-ddns needs to have
// an entry here to be able to use GSS-TSIG defaults (optional,
// if specified they apply to all the GSS-TSIG servers, unless
// overwritten on specific server level).
"server-principal": "DNS/server.example.org@EXAMPLE.ORG",
"client-principal": "DHCP/admin.example.org@EXAMPLE.ORG",
"client-keytab": "FILE:/etc/dhcp.keytab", // toplevel only
"credentials-cache": "FILE:/etc/ccache", // toplevel only
"tkey-lifetime": 3600, // 1 hour
"rekey-interval": 2700, // 45 minutes
"retry-interval": 120, // 2 minutes
"tkey-protocol": "TCP",
"fallback": false,
// The list of GSS-TSIG capable servers
"servers": [
{
// First server (identification is required)
"id": "server1",
"domain-names": [ ], // if not specified or empty, will
// match all domains that want to
// use this IP+port pair
"ip-address": "192.0.2.1",
"port": 53,
"server-principal": "DNS/server1.example.org@EXAMPLE.ORG",
"client-principal": "DHCP/admin1.example.org@EXAMPLE.ORG",
"tkey-lifetime": 7200, // 2 hours
"rekey-interval": 5400, // 90 minutes
"retry-interval": 240, // 4 minutes
"tkey-protocol": "TCP",
"fallback": true // if no key is available fallback to the
// standard behavior (vs skip this server)
},
{
// The second server (it has most of the parameters missing
// as those are using the defaults specified above)
"id": "server2",
"ip-address": "192.0.2.2",
"port": 5300
}
]
}
}
]
// Additional parameters, such as logging, control socket and
// others omitted for clarity.
}
}
|
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 port is not specified, the default of 53 is assumed. This is similar to basic mode with no authentication or authentication done using TSIG keys, with the exception that static TSIG keys are not referenced by name.
Second, the libddns_gss_tsig.so library has to 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 parameters scope as defaults. In the example above, the defaults that apply
to all servers unless otherwise specified on per server scope, are defined in
lines 63 through 68. The defaults can be skipped if there is only one server
defined or all servers have different values.
| 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 |
| 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 (will not be 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-keytabspecifies 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 theKRB5_CLIENT_KTNAMEenvironment variable. The empty value is silently ignored.credentials-cachespecifies the Kerberos credentials cache. For instanceFILE:<filename>can be used to point to a file or if using a directory which supports more than one principalDIR:<directory-path>. This parameter can be specified only once, in the parameters scope, and is the equivalent of setting theKRB5CCNAMEenvironment variable. The empty value is silently ignored.server-principalis the Kerberos principal name of the DNS server that will receive updates. In plain words, this is the DNS server’s name in the Kerberos system. This parameter is mandatory. It uses the typical Kerberos notation:<SERVICE-NAME>/<server-domain-name>@<REALM>.client-principalis the Kerberos principal name of the Kea D2 service. It is optional. It uses the typical Kerberos notation:<SERVICE-NAME>/<server-domain-name>@<REALM>.tkey-protocoldetermines 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-lifetimedetermines the lifetime of GSS-TSIG keys in the TKEY protocol. The value must be greater than therekey-intervalvalue. It is expressed in seconds and it default to 3600 seconds (one hour) if not specified.rekey-intervalgoverns the time interval the keys for each configured server are checked for rekeying, i.e. a new key is created to replace the current usable one when its age is greater than therekey-intervalvalue. The value must be smaller than thetkey-lifetimevalue (it is recommend between 50% and 80% of thetkey-lifetimevalue). It is expressed in seconds and it defaults to 2700 seconds (45 minutes, 75% of one hour) if not specified.retry-intervalgoverns the time interval to retry to create a key if any error occurred previously for any configured server. The value must be smaller than therekey-intervalvalue, and should be at most 1/3 of the difference betweentkey-lifetimeandrekey-interval. It is expressed in seconds and it defaults to 120 seconds (2 minutes) if not specified.fallbackgoverns the behavior when GSS-TSIG should be used (a matching DNS server is configured) but no GSS-TSIG key is available. If configured to false (the default) this server is skipped, if configured 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-timeoutgoverns the time used to wait for the GSS-TSIG TKEY exchange to finish before it timeouts. It is expressed in milliseconds and it defaults to 3000 milliseconds (3 seconds) if not specified.user-contextis an optional parameter (see Comments and User Context for a general description of user contexts in Kea).commentis allowed but currently ignored.serversspecifies the list of DNS servers where GSS-TSIG is enabled.
The server map parameters are described below:
idassigns an identifier to a DNS server. It is used for statistics and commands. It is required, must be not empty and unique.domain-namesgoverns the many to one relationship between D2 DNS servers and GSS-TSIG DNS servers: for each domain name of this list, a D2 DNS server for this domain with the IP address and port is looked for. An empty list (the default) means that all domains match.ip-addressspecifies the IP address at which the GSS-TSIG DNS server listens for DDNS and TKEY requests. It is a mandatory parameter.portspecifies the DNS transport port at which the GSS-TSIG DNS server listens for DDNS and TKEY requests. It defaults to 53.server-principalis the Kerberos principal name of the DNS server that will receive updates. The server principal parameter per server takes precedence. It is a mandatory parameter which must be specified at least at the global or the server level.client-principalis the Kerberos principal name of the Kea D2 service for this DNS server. The client principal parameter per server takes precedence. It is an optional parameter i.e. to not specify it at both the global and the server level is accepted.tkey-protocoldetermines which protocol is used to establish the security context with the DNS server. The TKEY protocol parameter per server takes precedence. Default and supported values are the same as for the global level parameter.tkey-lifetimedetermines the lifetime of GSS-TSIG keys in the TKEY protocol for the DNS server. The TKEY lifetime parameter per server takes precedence. Default and supported values are the same as for the global level parameter.rekey-intervalgoverns the time interval the keys for this particular server are checked for rekeying, i.e. a new key is created to replace the current usable one when its age is greater than therekey-intervalvalue. The value must be smaller than thetkey-lifetimevalue (it is recommend between 50% and 80% of thetkey-lifetimevalue). The rekey interval parameter per server takes precedence. Default and supported values are the same as for the global level parameter.retry-intervalgoverns the time interval to retry to create a key if any error occurred previously for this particular server. The value must be smaller than therekey-intervalvalue, and should be at most 1/3 of the difference betweentkey-lifetimeandrekey-interval. The retry interval parameter per server takes precedence. Default and supported values are the same as for the global level parameter.fallbackgoverns the behavior when GSS-TSIG should be used (a matching DNS server is configured) but no GSS-TSIG key is available. The fallback parameter per server takes precedence. Default and supported values are the same as for the global level parameter.exchange-timeoutgoverns the time used to wait for the GSS-TSIG TKEY exchange to finish before it timeouts. The exchange timeout parameter per server takes precedence. Default and supported values are the same as for the global level parameter.user-contextis an optional parameter (see Comments and User Context for a general description of user contexts in Kea).commentis allowed but currently ignored.
21.2.4.1. GSS-TSIG Automatic Key Removal¶
The server will periodically delete keys which expired more than 3 times the
maximum key lifetime (tkey-lifetime parameter).
The user has the option to purge keys on demand by using gss-tsig-purge-all
command (see The gss-tsig-purge-all Command) or gss-tsig-purge command
(see The gss-tsig-purge Command).
21.2.4.2. GSS-TSIG Configuration for Deployment¶
When using the Kerberos 5 and Bind9 setup of GSS-TSIG Deployment
the local resolver must point to the Bind9 named server address and
local Kerberos be configured by putting in 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. AD also provides
the Kerberos service and 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 to get and cache credentials.
This can be done manually by:
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).
The server principal will be “DNS/server.example.org@EXAMPLE.ORG¨ or for AD “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- number of created GSS-TSIG keystkey-sent- sent TKEY exchange initial requeststkey-success- TKEY exchanges which completed with a successtkey-timeout- TKEY exchanges which completed on timeouttkey-error- TKEY exchanges which completed with an error other than timeout
The relationship between keys and DNS servers are 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 used only 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 GSS-TSIG servers and keys.
An example command invocation looks like this:
{
"command": "gss-tsig-get-all"
}
An example response returning 1 GSS-TSIG servers and 1 keys:
{
"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"
}
}
An example response returning information about 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 lists GSS-TSIG server IDs and key names.
An example command invocation looks like this:
{
"command": "gss-tsig-list"
}
An example response returning 2 GSS-TSIG servers and 3 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."
}
}
An example 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."
}
}
An example response informing about GSS-TSIG key ‘1234.sig-foo.com.’ being 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."
}
}
An example response informing about GSS-TSIG key ‘1234.sig-foo.com.’ being 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 not usable GSS-TSIG keys.
An example command invocation looks like this:
{
"command": "gss-tsig-purge-all"
}
An example response informing about 2 GSS-TSIG keys being purged:
{
"result": 0,
"text": "2 purged GSS-TSIG keys"
}
21.2.6.8. The gss-tsig-purge Command¶
This command removes not usable GSS-TSIG keys for the specified server.
An example command invocation looks like this:
{
"command": "gss-tsig-purge",
"arguments": {
"server-id": "foo"
}
}
An example response informing about 2 GSS-TSIG keys for server ‘foo’ being purged:
{
"result": 0,
"text": "2 purged keys for GSS-TSIG server[foo]"
}
21.2.6.9. The gss-tsig-rekey-all Command¶
The command rekeys i.e. unconditionally creates new GSS-TSIG keys for all DNS servers.
An example command invocation looks like this:
{
"command": "gss-tsig-rekey-all"
}
An example response informing that a rekey was scheduled:
{
"result": 0,
"text": "rekeyed"
}
This command should be use for instance when the DHCP-DDNS server is reconnected to the network.
21.2.6.10. The gss-tsig-rekey Command¶
The command rekeys i.e. unconditionally creates new GSS-TSIG keys for a specified DNS server.
An example command invocation looks like this:
{
"command": "gss-tsig-purge",
"arguments": {
"server-id": "foo"
}
}
An example response informing that a rekey was scheduled:
{
"result": 0,
"text": "GSS-TSIG server[foo] rekeyed"
}
A typical usage of this command is when a DNS server was rebooted so existing GSS-TSIG keys shared with this server can no longer be used.