Overview
========
-Kea 1.5.0 introduced optional support for a YANG/NETCONF interface with
-the new ``kea-netconf`` NETCONF agent.
-
-This bare-bones documentation is a work in progress. Its current purpose
-is to let engineers joining the project or perhaps advanced early
-adopters to get up to speed quickly.
+Kea provides optional support for a YANG/NETCONF interface with the
+``kea-netconf`` NETCONF agent.
.. _netconf-install:
Installing NETCONF
==================
-Note that to get its NETCONF capabilities, Kea uses Sysrepo, which has
-many dependencies. Unfortunately, some of them are not available as
-packages and need to be compiled manually.
-
-Please note that building libyang requires a minimum gcc version of at
-least 4.9, so on some environments - like CentOS 7.5 - the system
-compiler cannot be used.
+To get its NETCONF capabilities, Kea uses Sysrepo.
The following sections provide installation instructions for Ubuntu
-18.04 and CentOS 7.5. Due to a more modern compiler and many available
-packages, the installation procedure is much simpler on Ubuntu.
+18.04 and CentOS 7.5.
.. _netconf-ubuntu-install:
For detailed installation instructions, see the `CentOS installation notes page <https://gitlab.isc.org/isc-projects/kea/wikis/docs/centos-installation-notes>`__.
-CentOS 7.5's gcc compiler (version 4.8.5) is very old. Some Sysrepo
-dependencies require at least version 4.9, which unfortunately means
-that a new compiler has to be installed. Also, many of the Sysrepo
-dependencies are not available in CentOS as packages, so for the time
-being they must be installed from sources.
-
Quick Sysrepo Overview
======================
XML syntax YIN is defined but less user-friendly. Top-level modules are
named in Kea models (a short version of schema models).
-To list the currently installed YANG modules:
+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.
-.. code-block:: console
+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.
- $ sysrepoctl -l
+To install modules from sources, do the following to install all modules:
-After installation the result should be similar to this:
+.. code-block:: console
-::
+ $ ./src/share/yang/modules/utils/reinstall.sh
- Sysrepo schema directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/yang/
- Sysrepo data directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/data/
- (Do not alter contents of these directories manually)
-
- Module Name | Revision | Conformance | Data Owner | Permissions
- ----------------------------------------------------------------------
- ietf-netconf- | 2012-02-06 | Installed | root:root | 666
- -notifications | | | |
- ietf-netconf | 2011-06-01 | Imported | |
- ietf-netconf-acm | 2012-02-22 | Imported | |
- nc-notifications | 2008-07-14 | Installed | root:root | 666
- notifications | 2008-07-14 | Installed | root:root | 666
- turing-machine | 2013-12-27 | Installed | root:root | 666
- iana-if-type | 2014-05-08 | Installed | |
- ietf-interfaces | 2014-05-08 | Installed | root:root | 666
- ietf-ip | 2014-06-16 | Installed | |
-
-There are two major modules that Kea is able to support:
-kea-dhcp4-server and kea-dhcp6-server. Note that 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. Those three 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``
-after installation.
-
-To install modules from sources, do the following:
+OR if you installed sysrepo in a custom path:
.. code-block:: console
- $ cd src/share/yang/modules
- $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g ietf-dhcpv6-server*.yang
- $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp4-server*.yang
- $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp6-server*.yang
- ...
+ $ ./src/share/yang/modules/utils/reinstall.sh -s /path/to/sysrepo
+
+If you want to individually install all modules:
+
+.. code-block:: console
-Note that the first -s parameter specifies the location of the YANG
-schema repository; it can be verified with sysrepoctl -l. This is a
-parameter that is configured during Sysrepo compilation and is detected
-by the Kea configuration under the SYSREPO_REPO name.
+ $ 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:
.. code-block:: console
- $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g ietf-dhcpv6-server*.yang
- Installing a new module from file 'ietf-dhcpv6-server@2018-11-20.yang'...
- Installing the YANG file to '/home/thomson/devel/sysrepo-0.7.6/build/repository/yang/ietf-dhcpv6-server@2018-07-14.yang'...
- Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-dhcpv6-options'...
- Installing the YANG file to '/home/thomson/devel/sysrepo-0.7.6/build/repository/yang/ietf-dhcpv6-options@2018-07-14.yang'...
- Resolving dependency: 'ietf-dhcpv6-options' imports 'ietf-dhcpv6-types'...
- Installing the YANG file to '/home/thomson/devel/sysrepo-0.7.6/build/repository/yang/ietf-dhcpv6-types@2018-07-14.yang'...
- Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-dhcpv6-types'...
- Installing the YANG file to '/home/thomson/devel/sysrepo-0.7.6/build/repository/yang/ietf-dhcpv6-types@2018-07-14.yang'...
- Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-interfaces'...
- Schema of the module ietf-interfaces is already installed, skipping...
- Installing data files for module 'ietf-dhcpv6-server'...
- Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-dhcpv6-options'...
- Skipping installation of data files for module 'ietf-dhcpv6-options'...
- Resolving dependency: 'ietf-dhcpv6-options' imports 'ietf-dhcpv6-types'...
- Skipping installation of data files for module 'ietf-dhcpv6-types'...
- Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-dhcpv6-types'...
- Skipping installation of data files for module 'ietf-dhcpv6-types'...
- Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-interfaces'...
- Installing data files for module 'ietf-interfaces'...
- Notifying sysrepo about the change...
- Install operation completed successfully.
-
-It is possible to confirm whether the models are imported correctly by using
-sysrepoctl -l:
+ $ ./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:
.. code-block:: console
- $ sysrepoctl -l
- Sysrepo schema directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/yang/
- Sysrepo data directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/data/
- (Do not alter contents of these directories manually)
-
- Module Name | Revision | Conformance | Data Owner | Permissions
- -----------------------------------------------------------------------------------------
- ietf-netconf-notifications | 2012-02-06 | Installed | root:root | 666
- ietf-netconf | 2011-06-01 | Imported | |
- ietf-netconf-acm | 2012-02-22 | Imported | |
- nc-notifications | 2008-07-14 | Installed | root:root | 666
- notifications | 2008-07-14 | Installed | root:root | 666
- turing-machine | 2013-12-27 | Installed | root:root | 666
- iana-if-type | 2014-05-08 | Installed | |
- ietf-interfaces | 2014-05-08 | Installed | root:root | 666
- ietf-ip | 2014-06-16 | Installed | |
- kea-dhcp4-server | 2018-11-20 | Installed | root:root | 666
- kea-dhcp6-server | 2018-11-20 | Installed | root:root | 666
- ietf-dhcpv6-server | 2018-09-04 | Installed | root:root | 666
- ietf-dhcpv6-options | 2018-09-04 | Imported | |
- ietf-dhcpv6-types | 2018-01-30 | Imported | |
-
-To install a new revision of a module it must first be uninstalled, e.g.
-by:
+ $ 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. Othweise, it must first be uninstalled:
.. code-block:: console
- sudo sysrepoctl -u -m kea-dhcp4-server
+ $ sysrepoctl -u kea-dhcp4-server
-If the module is used (i.e. imported) by other modules, it can be
-uninstalled only after those modules have finished using it.
+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.
- ``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_VERIFY event, in the Sysrepo naming convention) stage, Kea
+ 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_APPLY event in the Sysrepo naming
+ 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.
with a minimal configuration which includes only a control socket,
making them manageable. For instance, for the DHCPv4 server:
-::
-
- {
- "Dhcp4": {
- "control-socket": {
- "socket-type": "unix",
- "socket-name": "/tmp/kea4-sock"
- }
- }
- }
+.. code-block:: json
-Note the alternative to boot with full configurations does not allow
-easy tracking of changes or synchronization between the JSON and YANG
-configuration sources; therefore, that setup is not really compatible
-with the YANG/NETCONF configuration management paradigm, where
-everything should be performed in YANG.
+ {
+ "Dhcp4": {
+ "control-socket": {
+ "socket-name": "/tmp/kea-dhcp4-ctrl.sock",
+ "socket-type": "unix"
+ }
+ }
+ }
-With module change subscriptions enabled, the kea-netconf daemon will
+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
``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 ABORT (vs. APPLY)
-event with rollback changes.
+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 APPLY event is ignored, as it is
+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
- ``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
+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
information specified with ``parameters``.
Please consult :ref:`logging` for details on how to configure
-logging. The NETCONF agent's root logger's name is ``kea-netconf``, as
+logging. The name of the NETCONF agent's main logger is ``kea-netconf``, as
given in the example above.
.. _netconf-example:
The following is the example control socket specification for the Kea
DHCPv6 server:
-::
+.. code-block:: json
- {
- "Dhcp6": {
- "control-socket": {
- "socket-type": "unix",
- "socket-name": "/tmp/kea6-sock"
- }
- }
- }
+ {
+ "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:
.. code-block:: console
- # echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea6-sock '-,ignoreeof'
+ # 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":
- {
- "managed-servers":
- {
- "dhcp6":
- {
- "control-socket":
- {
- "socket-type": "unix",
- "socket-name": "/tmp/kea6-sock"
- }
- }
- },
-
- "loggers":
- [
- {
- "name": "kea-netconf",
- "output_options":
- [
- {
- "output": "stderr"
- }
- ],
- "severity": "DEBUG",
- "debuglevel": 99
- }
- ]
- }
- }
+.. code-block:: json
+
+ {
+ "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.
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
- <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
</config>
.. code-block:: console
- # sysrepocfg -d startup -f xml -i startup.xml kea-dhcp6-server
+ $ 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
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
- <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
</config>
.. code-block:: console
- # sysrepocfg -d running -f xml -i BAD-schema.xml kea-dhcp6-server
+ $ 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:
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
- <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
<user-context>bad</user-context>
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
- <socket-name>/tmp/kea6-sock</socket-name>
+ <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. For this reason, please use the ``sysrepocfg`` ``--permanent``
-/ ``-p`` option (or any similar feature of NETCONF clients) with care.
+a backup.
.. _operation-example-2pools:
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
- <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
</config>
.. code-block:: console
- # sysrepocfg -d running -f xml -i twopools.xml kea-dhcp6-server
+ $ sysrepocfg -d running -f xml -m kea-dhcp6-server --edit=twopools.xml
.. _operation-example-2subnets:
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
- <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
</config>
.. code-block:: console
- # sysrepocfg -d running -f xml -i twosubnets.xml kea-dhcp6-server
+ $ sysrepocfg -d running -f xml -m kea-dhcp6-server --edit=twosubnets.xml
.. _operation-example-logging:
<subnet>2001:db8::/64</subnet>
</subnet6>
<control-socket>
- <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-name>/tmp/kea-dhcp6-ctrl.sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
<logger>
The corresponding Kea configuration in JSON is:
-::
+.. code-block:: json
{
"Dhcp6": {
"control-socket": {
- "socket-name": "/tmp/kea6-sock",
+ "socket-name": "/tmp/kea-dhcp6-ctrl.sock",
"socket-type": "unix"
},
"interfaces-config": {
}
}
-Finally, any of the previous examples can be replayed using
+Finally, any of the previous examples can be replayed by using
``sysrepocfg`` in edit mode as follows:
.. code-block:: console
- # sysrepocfg -d running -f xml -e vi kea-dhcp6-server
+ $ sysrepocfg -d running -f xml -m kea-dhcp6-server --edit
-or, of course, using a NETCONF client like ``netopeer2-cli`` from the
+or by using a NETCONF client like ``netopeer2-cli`` from the
`Netopeer2 <https://github.com/CESNET/Netopeer2>`__ NETCONF Toolset.
-// Copyright (C) 2018-2020 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2018-2021 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
@page libyang libkea-yang - Kea YANG Utilities Library
The libkea-yang library was developed to handle base YANG operations,
-such are retrieving YANG schema and configuration and translating
-data between YANG syntax and JSON that is understandable by Kea.
+such as retrieving YANG schema and configuration and translating
+data between YANG data and JSON that is understandable by Kea.
@section yangTranslator Translator between YANG and JSON
to convert certain data structure between YANG and JSON. It is envisaged
that more complex translators will use other translators to handle more
complex data structures. For details, see @ref isc::yang::TranslatorBasic.
+It is also envisioned that translators could do the translation automatically by
+relying on capabilities of iterating through data, retrieving data type
+information and value information from nodes through the libyang and sysrepo
+APIs.
Note that although the initial focus is on translation from YANG to JSON (so
Kea can retrieve its configuration), the opposite translation direction -
-from JSON to YANG - is also very useful, for at least two reasons. First,
+from JSON to YANG - is also very useful, for at least three reasons. First,
in many cases we can use it in tests to check that conversion back and forth
doesn't lose anything: yang = toYang(toJson(yang)). Second, YANG models
cover two major types of data: configuration and run-time state. While
we're initially focusing on getting the configuration, the run-time state
is something that Kea is expected to provide. Kea uses JSON internally in many
-places and that data will have to be exported in YANG format.
+places and that data will have to be exported in YANG format. Thirdly, the
+SR_EV_UPDATE callback allows mid-flight configuration changes before data is
+committed to the sysrepo datastore. If it ever will be used in the future,
+changes applied during this step will most likely come from Kea's current JSON
+configuration. As such, JSON to YANG translation will be necessary. One
+application for this is reverting stuff that is necessary for Kea - Sysrepo
+communication like the unix socket.
All translators take a Session pointer (a structure provided by Sysrepo that
is responsible for maintaining a connection) in constructors and derive from
-the basic / base class and recursively of translators for embedded parts.
+the basic / base class and recursively from translators for embedded parts.
@c isc::yang::TranslatorBasic provides some methods:
- - getItem() gets and translates basic value from YANG to JSON
- - getItems() gets and translates a leaf-list from YANG to JSON
- (for a list please use an iterator)
+ - getItem() retrieves and translates basic value from YANG to JSON
+ - getItems() retrieves and translates a leaf-list from YANG to JSON
+ - getList() retrieves and translates a list from YANG to JSOIN
- setItem() translates and sets a basic value from JSON to YANG
- delItem() deletes a value
- - getIter() gets an iterator over a YANG list
- - getNext() returns the xpath of the next item
+ - forAll() iterates over the top node and its descendants and calls a function
@section yangTranslatorPool Pool translator
model, generic methods of all structure translators throw
@c isc::NotImplemented.
-@c isc::yang::TranslatorPools deals with a list of pools. The getPools
-method iterates over the list in both ways. Look at examples in unit
-tests to understand how can be filled.
-
Note pools show two shortcomings in IETF models:
- option sets make to track changes nearly impossible: the only easy
code is to translate the whole configuration.
YANG configuration (by getXXX) to make it acceptable by a Kea server.
By definition they are not defined for Kea models.
-@section unitTestsSysrepo Running unit-tests with Sysrepo
+@section unitTestsSysrepo Running unit tests with Sysrepo
-To run YANG/NETCONF/Sysrepo tests you obviously need to compile Kea with
-Sysrepo support:
+To run YANG/NETCONF/Sysrepo tests you need to compile Kea with Sysrepo support:
@verbatim
./configure --with-sysrepo
@endverbatim
-For details, see Section 20 "YANG/NETCONF support" in the Kea User's Guide.
+For details, see Section "YANG/NETCONF support" in the Kea Administrator
+Reference Manual: https://kea.readthedocs.io/en/latest/arm/netconf.html.
-You also need to install YANG schemas, so the unit-tests are able to
+You also need to install YANG models, so the unit tests are able to
retrieve, add, update and generally interact with the sysrepo information.
-There are several production Kea models (src/share/yang/modules/kea*.yang)
-and one test specific model (src/share/yang/modules/keatest-module*.yang)
-which is only required if you want to run Kea unit tests, i.e. it is not
-used in production.
+There are several Kea models (src/share/yang/modules/*.yang), mostly usable in
+production, but one called keatest-module is only used in unit tests. To be able
+to run unit tests as a non-root user, which is the recommended way, make sure
+the sysrepo repository and /dev/shm/sr* are owned by said user. One way to
+prevent sporadic chown-ing is to install sysrepo and the Kea models as non-root.
+
+To install all the models, run the following script:
+
+@verbatim
+./src/share/yang/modules/utils/reinstall.sh
+@endverbatim
-To install the test module, issue the following command:
+Alternatively to install each model, issue the following command:
@verbatim
-sudo sysrepoctl --install --yang=src/share/yang/modules/keatest-module*.yang
+sysrepoctl -i "src/share/yang/modules/${model}.yang"
@endverbatim
To verify that you have the schemas installed, do this:
@verbatim
sysrepoctl -l
@endverbatim
+
Make sure that keatest-module and other necessary modules are on the list.
-Note as DHCP modules are still being developed it can be useful to
-deinstall them before reinstalling a more recent version:
+As DHCP modules are still being developed, if the revision has been bumped,
+reinstalling it will update the module automatically . Otherwise, it can be
+useful to uninstall them before reinstalling a more recent version:
+
@verbatim
-sudo sysrepoctl --uninstall --module=<module-name>
+sysrepoctl -u <module-name>
@endverbatim
Tests use these modules you can find in src/share/yang/modules in addition
Those modules are extracted from the IETF DHCPv6 YANG draft too:
- ietf-dhcpv6-client
+ - ietf-dhcpv6-options
- ietf-dhcpv6-relay
+ - ietf-dhcpv6-types
All are available in the src/share/yang/modules directory using the
<module-name>[@<revision>].yang syntax for file names.
and in the file content matches
- check-hashes.sh which detects updates in the file content without
a revision change using the SHA-256 hash of the to YIN translation.
+ Updates hashes automatically if -a is passed to the script.
- gen-revisions.sh which produces the module / revision table of
the yang_revisions.h header file.
-
-Finally, sysrepod daemon must run be running (as root):
-@verbatim
-sudo sysrepod
-@endverbatim
+ - reinstall.sh which installs all the modules.
You can run this tool:
projects / thirdparty / kea.git / commitdiff
