diff options
Diffstat (limited to 'doc/sphinx/arm/ext-netconf.rst')
| -rw-r--r-- | doc/sphinx/arm/ext-netconf.rst | 1159 |
1 files changed, 1159 insertions, 0 deletions
diff --git a/doc/sphinx/arm/ext-netconf.rst b/doc/sphinx/arm/ext-netconf.rst new file mode 100644 index 0000000..b21e7bb --- /dev/null +++ b/doc/sphinx/arm/ext-netconf.rst @@ -0,0 +1,1159 @@ +.. _netconf: + +YANG/NETCONF +============ + +.. _netconf-overview: + +Overview +-------- + +The Network Configuration Protocol, or NETCONF, is a network management protocol defined +in `RFC 4741 <https://tools.ietf.org/html/rfc4741>`__. It uses the YANG modeling language, +defined in `RFC 6020 <https://tools.ietf.org/html/rfc6020>`__, to provide a uniform way +of handling the configuration syntax of various networking devices. Kea provides optional +support for a YANG/NETCONF interface with the :iscman:`kea-netconf` agent. + +.. _netconf-install: + +Installing NETCONF +------------------ + +To get its NETCONF capabilities, Kea requires the v2 versions of libyang and +Sysrepo. The specific versions that have been thoroughly tested with Kea are: + +* libyang v2.1.4 +* sysrepo v2.2.12 +* libyang-cpp v1.1.0 (ae7d649ea75da081725c119dd553b2ef3121a6f8) +* sysrepo-cpp v1.1.0 (02634174ffc60568301c3d9b9b7cf710cff6a586) + +.. note:: + + For users who are unable to upgrade to one of the versions of libyang + and Sysrepo listed above, these are the oldest versions known to work + reliably with current Kea releases: + + * libyang v2.0.256 (56d4e07ef1cdeab3eb2e6700247f83ec9148edcc) + * sysrepo v2.1.84 + * libyang-cpp v1.1.0 (7824d9a862f2dc1d8ad4f6a90ab6cee9200f7c81) + * sysrepo-cpp v1.1.0 (e66b2f0c53a428eeb743d355cf86fb30e8e491f1) + +.. note:: + + :iscman:`kea-netconf` may be compatible with later versions of libyang and + Sysrepo, but only the versions listed above have been thoroughly + tested by ISC. + +Installing from packages is recommended, if they are provided by the system. If +not, users can build from sources following the directions below, which +should work on all popular operating systems. + +.. _libyang-install-sources: + +Installing ``libyang`` From Sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ git clone https://github.com/CESNET/libyang.git + $ cd libyang + $ git checkout v2.1.4 + $ mkdir build + $ cd build + $ cmake .. + $ make + $ make install + +.. _sysrepo-install-sources: + +Installing ``sysrepo`` From Sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ git clone https://github.com/sysrepo/sysrepo.git + $ cd sysrepo + $ git checkout v2.2.12 + $ mkdir build + $ cd build + $ cmake -DREPO_PATH=/etc/sysrepo .. + $ make + $ make install # without sudo if you're doing development and want to run unit tests + +.. _libyang-cpp-install-sources: + +Installing ``libyang-cpp`` From Sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ git clone https://github.com/CESNET/libyang-cpp.git + $ cd libyang-cpp + $ git checkout ae7d649ea75da081725c119dd553b2ef3121a6f8 + $ mkdir build + $ cd build + $ cmake -DBUILD_TESTING=OFF .. + $ make + $ make install + +.. _sysrepo-cpp-install-sources: + +Installing ``sysrepo-cpp`` From Sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ git clone https://github.com/sysrepo/sysrepo-cpp.git + $ cd sysrepo-cpp + $ git checkout 02634174ffc60568301c3d9b9b7cf710cff6a586 + $ mkdir build + $ cd build + $ cmake -DBUILD_TESTING=OFF .. + $ make + $ make install + +.. _compiling-with-netconf: + +Compiling With NETCONF +---------------------- + +1. Obtain the Kea sources. + +.. code-block:: console + + $ git clone gitlab.isc.org/isc-projects/kea.git + $ cd kea + +2. Configure the build. + +.. code-block:: console + + $ autoreconf -f -i + $ ./configure --with-libyang --with-libyang-cpp --with-sysrepo --with-sysrepo-cpp + +.. note:: + + If any of the libraries are installed in a custom location, the + ``--with`` flags accept the installations paths as values. + +3. Check ``config.report`` to verify NETCONF support. + +:: + + NETCONF: + yes + + libyang: + LIBYANG_CPPFLAGS: + LIBYANG_INCLUDEDIR: -I/usr/local/include + LIBYANG_LIBS: -L/usr/local/lib -lyang -Wl,-R/usr/local/lib -lyang + LIBYANG_PREFIX: /usr/local + LIBYANG_VERSION: 2.1.4 + + libyang-cpp: + LIBYANGCPP_CPPFLAGS: + LIBYANGCPP_INCLUDEDIR: -I/usr/local/include + LIBYANGCPP_LIBS: -L/usr/local/lib -lyang-cpp -Wl,-R/usr/local/lib -lyang-cpp + LIBYANGCPP_PREFIX: /usr/local + LIBYANGCPP_VERSION: 1.1.0 + + sysrepo: + SYSREPO_CPPFLAGS: + SYSREPO_INCLUDEDIR: -I/usr/local/include + SYSREPO_LIBS: -L/usr/local/lib -lsysrepo -Wl,-R/usr/local/lib -lsysrepo + SYSREPO_PREFIX: /usr/local + SYSREPO_VERSION: 2.2.12 + + SR_REPO_PATH: /etc/sysrepo + SR_PLUGINS_PATH: /usr/local/lib/sysrepo/plugins + SRPD_PLUGINS_PATH: /usr/local/lib/sysrepo-plugind/plugins + + sysrepo-cpp: + SYSREPOCPP_CPPFLAGS: + SYSREPOCPP_INCLUDEDIR: -I/usr/local/include + SYSREPOCPP_LIBS: -L/usr/local/lib -lsysrepo-cpp -Wl,-R/usr/local/lib -lsysrepo-cpp + SYSREPOCPP_PREFIX : /usr/local + SYSREPOCPP_VERSION: 1.1.0 + +4. Build as usual. + + $ make + +.. _sysrepo-overview: + +Quick Sysrepo Overview +---------------------- + +This section offers a brief overview of a subset of available +functions in Sysrepo. For more complete information, see the +`Sysrepo homepage <https://www.sysrepo.org>`__. + +In YANG, configurations and state data are described in YANG syntax +in module files named ``<module-name>[@<revision>].yang`` + +The revision part is optional and follows the ``YYYY-MM-DD`` format. An alternate +XML syntax YIN is defined but less user-friendly. Top-level modules are +named in Kea models (a short version of schema models). + +There are two major modules that Kea is able to support: ``kea-dhcp4-server`` and +``kea-dhcp6-server``. While there is an active effort in the DHC working group at +IETF to develop a DHCPv6 YANG model, a similar initiative in the past for DHCPv4 +failed. Therefore, Kea uses its own dedicated models for DHCPv4 and DHCPv6 but +partially supports the IETF model for DHCPv6. + +All of the models have extra modules as dependencies, which are also provided. +All of the modules can be found in ``src/share/yang/modules`` in sources and in +``share/kea/yang/modules`` in the installation directory. This directory is +referred to as `${share_directory}` in the commands below. + +To install modules from sources or upgrade them from older revisions, +run the following command. In the case of a revision upgrade, YANG +data will be migrated automatically to the new module schema. + +.. code-block:: console + + $ ${share_directory}/yang/modules/utils/reinstall.sh + +However, if there are any issues during the upgrade process, and data can be recreated from a NETCONF +client or through other means, Kea modules can be easily uninstalled before installing again +via this command: + +.. code-block:: console + + $ ${share_directory}/yang/modules/utils/reinstall.sh -u + +This script should be able to reinstall Sysrepo. However, the ``-s`` +flag can also be used to specify a path: + +.. code-block:: console + + $ ./src/share/yang/modules/utils/reinstall.sh -s /path/to/sysrepo + +To individually install all modules: + +.. code-block:: console + + $ 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 + + $ ./src/share/yang/modules/utils/reinstall.sh + [INF] Connection 2 created. + [INF] Module "keatest-module" was installed. + [INF] File "keatest-module@2022-11-30.yang" was installed. + [INF] No datastore changes to apply. + [INF] Connection 4 created. + [ERR] Module "ietf-interfaces@2018-02-20" already installed. + [INF] No datastore changes to apply. + [INF] Connection 7 created. + [ERR] Module "ietf-dhcpv6-client" is already in sysrepo. + [INF] No datastore changes to apply. + [INF] Connection 9 created. + [ERR] Module "ietf-dhcpv6-relay" is already in sysrepo. + [INF] No datastore changes to apply. + [INF] Connection 11 created. + [ERR] Module "ietf-dhcpv6-server" is already in sysrepo. + [INF] No datastore changes to apply. + [INF] Connection 13 created. + [ERR] Write permission "ietf-yang-types" check failed. + [INF] No datastore changes to apply. + [INF] Connection 15 created. + [ERR] Module "ietf-dhcpv6-options" is already in sysrepo. + [INF] No datastore changes to apply. + [INF] Connection 17 created. + [ERR] Module "ietf-dhcpv6-types" is already in sysrepo. + [INF] No datastore changes to apply. + [INF] Connection 21 created. + [INF] Module "kea-types" was installed. + [INF] File "kea-types@2019-08-12.yang" was installed. + [INF] No datastore changes to apply. + [INF] Connection 23 created. + [INF] Module "kea-dhcp-types" was installed. + [INF] File "kea-dhcp-types@2022-11-30.yang" was installed. + [INF] No datastore changes to apply. + [INF] Connection 25 created. + [INF] Module "kea-dhcp-ddns" was installed. + [INF] File "kea-dhcp-ddns@2022-07-27.yang" was installed. + [INF] No datastore changes to apply. + [INF] Connection 27 created. + [INF] Module "kea-ctrl-agent" was installed. + [INF] File "kea-ctrl-agent@2019-08-12.yang" was installed. + [INF] No datastore changes to apply. + [INF] Connection 29 created. + [INF] Module "kea-dhcp4-server" was installed. + [INF] File "kea-dhcp4-server@2022-11-30.yang" was installed. + [INF] No datastore changes to apply. + [INF] Connection 31 created. + [INF] Module "kea-dhcp6-server" was installed. + [INF] File "kea-dhcp6-server@2022-11-30.yang" was installed. + [INF] No datastore changes to apply. + +To confirm whether the modules have been imported correctly, check the list of +currently installed YANG modules. It should be similar to this: + +.. code-block:: console + + $ sysrepoctl -l + Sysrepo repository: /etc/sysrepo + + Module Name | Revision | Flags | Owner | Startup Perms | Submodules | Features + --------------------------------------------------------------------------------------------------- + ietf-datastores | 2018-02-14 | I | user:user | 444 | | + ietf-dhcpv6-client | 2018-09-04 | I | user:user | 600 | | + ietf-dhcpv6-options | 2018-09-04 | I | user:user | 600 | | + ietf-dhcpv6-relay | 2018-09-04 | I | user:user | 600 | | + ietf-dhcpv6-server | 2018-09-04 | I | user:user | 600 | | + ietf-dhcpv6-types | 2018-09-04 | I | user:user | 600 | | + ietf-inet-types | 2013-07-15 | I | user:user | 444 | | + ietf-interfaces | 2018-02-20 | I | user:user | 600 | | + ietf-netconf | 2013-09-29 | I | user:user | 644 | | + ietf-netconf-acm | 2018-02-14 | I | user:user | 600 | | + ietf-netconf-notifications | 2012-02-06 | I | user:user | 644 | | + ietf-netconf-with-defaults | 2011-06-01 | I | user:user | 444 | | + ietf-origin | 2018-02-14 | I | user:user | 444 | | + ietf-yang-library | 2019-01-04 | I | user:user | 644 | | + ietf-yang-metadata | 2016-08-05 | i | | | | + ietf-yang-schema-mount | 2019-01-14 | I | user:user | 644 | | + ietf-yang-types | 2013-07-15 | I | user:user | 444 | | + kea-ctrl-agent | 2019-08-12 | I | user:user | 600 | | + kea-dhcp-ddns | 2022-07-27 | I | user:user | 600 | | + kea-dhcp-types | 2022-11-30 | I | user:user | 600 | | + kea-dhcp4-server | 2022-11-30 | I | user:user | 600 | | + kea-dhcp6-server | 2022-11-30 | I | user:user | 600 | | + kea-types | 2019-08-12 | I | user:user | 600 | | + keatest-module | 2022-11-30 | I | user:user | 600 | | + sysrepo-monitoring | 2022-04-08 | I | user:user | 600 | | + sysrepo-plugind | 2022-03-10 | I | user:user | 644 | | + yang | 2022-06-16 | I | user:user | 444 | | + + Flags meaning: I - Installed/i - Imported; R - Replay support + +To reinstall a module, if the revision YANG entry was bumped, simply installing +it will update it automatically. Otherwise, it must first be uninstalled: + +.. code-block:: console + + $ sysrepoctl -u kea-dhcp4-server + +If the module is used (i.e. imported) by other modules, it can be uninstalled +only after the dependent modules have first been uninstalled. +Installation and uninstallation must be done in dependency order and +reverse-dependency order, as appropriate. + +.. _netconf-models: + +Supported YANG Models +--------------------- + +The currently supported models are ``kea-dhcp4-server`` and +``kea-dhcp6-server``. There is partial support for +``ietf-dhcpv6-server``, but the primary focus of testing has been on Kea DHCP +servers. Other models (:iscman:`kea-dhcp-ddns` and :iscman:`kea-ctrl-agent`) +are currently not supported. + +.. _using-netconf: + +Using the NETCONF Agent +----------------------- + +The NETCONF agent follows this algorithm: + +- For each managed server, get the initial configuration from the + server through the control socket. + +- Open a connection with the Sysrepo environment and establish two + sessions with the startup and running datastores. + +- Check that the used (not-essential) and required (essential) modules are + installed in the Sysrepo repository at the right revision. If an + essential module - that is, a module where the configuration schema for a + managed server is defined - is not installed, raise a fatal error. + +- For each managed server, get the YANG configuration from the startup + datastore, translate it to JSON, and load it onto the server being + configured. + +- For each managed server, subscribe a module change callback using its + model name. + +- When a running configuration is changed, try to validate or load the + updated configuration via the callback to the managed server. + +.. _netconf-configuration: + +Configuration +------------- + +The behavior described in :ref:`using-netconf` +is controlled by several configuration flags, which can be set in the +global scope or in a specific managed-server scope. If the latter, +the value defined in the managed-server scope takes precedence. These +flags are: + +- ``boot-update`` - controls the initial configuration phase; when + ``true`` (the default), the initial configuration retrieved from the + classic Kea server JSON configuration file is loaded first, and then + the startup YANG model is loaded. This setting lets administrators + define a control socket in the local JSON file and then download the + configuration from YANG. When set to ``false``, this phase is skipped. + +- ``subscribe-changes`` - controls the module change + subscription; when ``true`` (the default), a module change callback is + subscribed, but when ``false`` the phase is skipped and running + configuration updates are disabled. When set to ``true``, the running + datastore is used to subscribe for changes. + +- ``validate-changes`` - controls how Kea monitors changes in + the Sysrepo configuration. Sysrepo offers two stages where Kea can + interact: validation and application. At the validation (or + ``SR_EV_CHANGE`` event, in the Sysrepo naming convention) stage, Kea + retrieves the newly committed configuration and verifies it. If the + configuration is incorrect for any reason, the Kea servers reject it + and the error is propagated back to the Sysrepo, which then returns + an error. This step only takes place if ``validate-changes`` is set to + ``true``. In the application (or ``SR_EV_UPDATE`` event in the Sysrepo naming + convention) stage, the actual configuration is applied. At this stage + Kea can receive the configuration, but it is too late to signal back + any errors as the configuration has already been committed. + +The idea behind the initial configuration phase is to boot Kea servers +with a minimal configuration which includes only a control socket, +making them manageable. For instance, for the DHCPv4 server: + +.. code-block:: json + + { + "Dhcp4": { + "control-socket": { + "socket-name": "/tmp/kea-dhcp4-ctrl.sock", + "socket-type": "unix" + } + } + } + +With module change subscriptions enabled, the :iscman:`kea-netconf` daemon +monitors any configuration changes as they appear in the Sysrepo. Such +changes can be done using the ``sysrepocfg`` tool or remotely using any +NETCONF client. For details, please see the Sysrepo documentation or +:ref:`operation-example`. +Those tools can be used to modify YANG configurations in the running +datastore. Note that committed configurations are only updated in the +running datastore; to keep them between server reboots they must be +copied to the startup datastore. + +When module changes are tracked (using ``subscribe-changes`` set to +``true``) and the running configuration has changed (e.g. using +``sysrepocfg`` or any NETCONF client), the callback validates the +modified configuration (if ``validate-changes`` was not set to ``false``) +and runs a second time to apply the new configuration. If the validation +fails, the callback is still called again but with an ``SR_EV_ABORT`` +(vs. ``SR_EV_DONE``) event with rollback changes. + +The returned code of the callback on an ``SR_EV_DONE`` event is ignored, as it is +too late to refuse a bad configuration. + +There are four ways in which a modified YANG configuration might +be incorrect: + +1. It could be non-compliant with the schema, e.g. an unknown entry, missing a + mandatory entry, a value with a bad type, or not matching a constraint. + +2. It could fail to be translated from YANG to JSON, e.g. an invalid user + context. + +3. It could fail Kea server sanity checks, e.g. an out-of-subnet-pool range + or an unsupported database type. + +4. The syntax may be correct and pass server sanity checks but the + configuration could fail to run, e.g. the configuration specifies database + credentials but the database refuses the connection. + +The first case is handled by Sysrepo. The second and third cases are +handled by :iscman:`kea-netconf` in the validation phase (if not disabled by +setting ``validate-changes`` to ``true``). The last case causes the +application phase to fail without a sensible report to Sysrepo. + +The managed Kea servers and agents are described in the +``managed-servers`` section. Each sub-section begins with the service +name: ``dhcp4``, ``dhcp6``, ``d2`` (the DHCP-DDNS server does not +support the control-channel feature yet), and ``ca`` (the control +agent). + +Each managed server entry may contain: + +- control flags - ``boot-update``, ``subscribe-changes``, and/or ``validate-changes``. + +- ``model`` - specifies the YANG model/module name. For each service, + the default is the corresponding Kea YANG model, e.g. for ``"dhcp4"`` + it is ``"kea-dhcp4-server"``. + +- ``control-socket`` - specifies the control socket for managing the + service configuration. + +A control socket is specified by: + +- ``socket-type`` - the socket type is either ``stdout``, ``unix``, or ``http``. + ``stdout`` is the default; + it is not really a socket, but it allows :iscman:`kea-netconf` to run in + debugging mode where everything is printed on stdout, and it can also be + used to redirect commands easily. ``unix`` is the standard direct + server control channel, which uses UNIX sockets; ``http`` uses + a control agent, which accepts HTTP connections. + +- ``socket-name`` - the local socket name for the ``unix`` socket type + (default empty string). + +- ``socket-url`` - the HTTP URL for the ``http`` socket type (default + ``http://127.0.0.1:8000/``). + +User contexts can store arbitrary data as long as they are in valid JSON +syntax and their top-level element is a map (i.e. the data must be +enclosed in curly brackets). They are accepted at the NETCONF entry, +i.e. below the top-level, managed-service entry, and control-socket +entry scopes. + +Hook libraries can be loaded by the NETCONF agent just as with other +servers or agents; however, currently no hook points are defined. The +``hooks-libraries`` list contains the list of hook libraries that +should be loaded by :iscman:`kea-netconf`, along with their configuration +information specified with ``parameters``. + +Please consult :ref:`logging` for details on how to configure +logging. The name of the NETCONF agent's main logger is :iscman:`kea-netconf`, as +given in the example above. + +.. _netconf-example: + +A :iscman:`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. + +.. code-block:: javascript + + // This is a simple example of a configuration for the NETCONF agent. + // This server provides a YANG interface for all Kea servers and the agent. + { + "Netconf": + { + // Control flags can be defined in the global scope or + // in a managed server scope. Precedences are: + // - use the default value (true) + // - use the global value + // - use the local value. + // So this overwrites the default value: + "boot-update": false, + + // This map specifies how each server is managed. For each server there + // is a name of the YANG model to be used and the control channel. + // Currently three control channel types are supported: + // "stdout" which outputs the configuration on the standard output, + // "unix" which uses the local control channel supported by the + // "dhcp4" and "dhcp6" servers ("d2" support is not yet available), + // and "http" which uses the Control Agent "ca" to manage itself or + // to forward commands to "dhcp4" or "dhcp6". + "managed-servers": + { + // This is how kea-netconf can communicate with the DHCPv4 server. + "dhcp4": + { + "comment": "DHCPv4 server", + "model": "kea-dhcp4-server", + "control-socket": + { + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket" + } + }, + + // DHCPv6 parameters. + "dhcp6": + { + "model": "kea-dhcp6-server", + "control-socket": + { + "socket-type": "unix", + "socket-name": "/tmp/kea6-ctrl-socket" + } + }, + + // Currently the DHCP-DDNS (nicknamed D2) server does not support + // a command channel. + "d2": + { + "model": "kea-dhcp-ddns", + "control-socket": + { + "socket-type": "stdout", + "user-context": { "in-use": false } + } + }, + + // Of course the Control Agent (CA) supports HTTP. + "ca": + { + "model": "kea-ctrl-agent", + "control-socket": + { + "socket-type": "http", + "socket-url": "http://127.0.0.1:8000/" + } + } + }, + + // kea-netconf is able to load hook libraries that augment its operation. + // Currently there are no hook points defined in kea-netconf + // processing. + "hooks-libraries": [ + // The hook libraries list may contain more than one library. + { + // The only necessary parameter is the library filename. + "library": "/opt/local/custom_hooks_example.so", + + // Some libraries may support parameters. Make sure you + // type this section carefully, as kea-netconf does not + // validate it (because the format is library-specific). + "parameters": { + "param1": "foo" + } + } + ], + + // Similar to other Kea components, NETCONF also uses logging. + "loggers": [ + { + "name": "kea-netconf", + "output-options": [ + { + "output": "/var/log/kea-netconf.log", + // Several additional parameters are possible in + // addition to the typical output. + // Flush determines whether logger flushes output + // to a file. + // Maxsize determines maximum filesize before + // the file is rotated. + // Maxver specifies the maximum number of + // rotated files to be kept. + "flush": true, + "maxsize": 204800, + "maxver": 4 + } + ], + "severity": "INFO", + "debuglevel": 0 + } + ] + } + } + +.. _netconf-start-stop: + +Starting and Stopping the NETCONF Agent +--------------------------------------- + +:iscman:`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. + :iscman:`kea-netconf` attempts to load it and conducts sanity checks; + certain checks are possible only while running the actual server. The + actual status is reported with exit code (0 = configuration appears valid, + 1 = error encountered). Kea prints out log messages to standard + output and error to standard error when testing the configuration. + +- ``-v`` - displays the version of :iscman:`kea-netconf` and exits. + +- ``-V`` - displays the extended version information for :iscman:`kea-netconf` + and exits. The listing includes the versions of the libraries + dynamically linked to Kea. + +- ``-W`` - displays the Kea configuration report and exits. The report + is a copy of the ``config.report`` file produced by ``./configure``; + it is embedded in the executable binary. + + The contents of the ``config.report`` file may also be accessed by examining + certain libraries in the installation tree or in the source tree. + + .. code-block:: shell + + # from installation using libkea-process.so + $ strings ${prefix}/lib/libkea-process.so | sed -n 's/;;;; //p' + + # from sources using libkea-process.so + $ strings src/lib/process/.libs/libkea-process.so | sed -n 's/;;;; //p' + + # from sources using libkea-process.a + $ strings src/lib/process/.libs/libkea-process.a | sed -n 's/;;;; //p' + + # from sources using libcfgrpt.a + $ strings src/lib/process/cfgrpt/.libs/libcfgrpt.a | sed -n 's/;;;; //p' + +.. _operation-example: + +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``. + +.. _operation-example-setup: + +Setup of NETCONF Agent Operation Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The test box has an Ethernet interface named eth1. On some systems it is +possible to rename interfaces; for instance, on Linux with an ens38 +interface: + +.. code-block:: console + + # 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: + +.. code-block:: console + + # 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 :iscman:`kea-netconf` +process uses this socket to communicate with the DHCPv6 server, i.e. it +pushes translated configurations to that server using control commands. +The following is an example control socket specification for the Kea +DHCPv6 server: + +.. code-block:: json + + { + "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 + + # kea-dhcp6 -d -c boot.json + +The current configuration of the server can be fetched via a control +socket by running: + +.. code-block:: console + + # echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea-dhcp6-ctrl.sock '-,ignoreeof' + +The following is the example ``netconf.json`` configuration for +:iscman:`kea-netconf`, to manage the Kea DHCPv6 server: + +.. 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. + +The Kea NETCONF agent is launched by: + +.. code-block:: console + + # kea-netconf -d -c netconf.json + +Now that both :iscman:`kea-netconf` and :iscman:`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``: + +.. code-block:: 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: + +.. code-block:: console + + $ sysrepocfg -d startup -f xml -m kea-dhcp6-server --import=startup.xml + +:iscman:`kea-netconf` pushes the configuration found in the Sysrepo startup +datastore to all Kea servers during its initialization phase, after it +subscribes to module changes in the Sysrepo running datastore. This +action copies the configuration from the startup datastore to the +running datastore and enables the running datastore, making it +available. + +Changes to the running datastore are applied after validation to the Kea +servers. Note that they are not by default copied back to the startup +datastore, i.e. changes are not permanent. + +.. note:: + + :iscman:`kea-netconf` fetches the entire configuration from any Sysrepo datastore in a + single ``get-config`` NETCONF operation. Prior to Kea 2.3.2, a ``get-config`` operation + was done for each leaf and leaf-list node. Because of the significant changes, + :iscman:`kea-netconf` is considered experimental. + +.. _operation-example-errors: + +Example of Error Handling in NETCONF Operation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are four classes of issues with configurations applied via +NETCONF: + +1. The configuration does not comply with the YANG schema. + +2. The configuration cannot be translated from YANG to the Kea JSON. + +3. The configuration is rejected by the Kea server. + +4. The configuration was validated by the Kea server but cannot be + applied. + +In the first case, consider the following ``BAD-schema.xml`` +configuration file: + +.. code-block:: xml + + <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``: + +.. code-block:: console + + $ sysrepocfg -d running -f xml -m kea-dhcp6-server --import=BAD-schema.xml + +In the second case, the configuration is rejected by :iscman:`kea-netconf`. +For example, consider this ``BAD-translator.xml`` file: + +.. code-block:: 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> + <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: + +.. code-block:: 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> + +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. + +.. _operation-example-2pools: + +NETCONF Operation Example with Two Pools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example adds a second pool to the initial (i.e. startup) +configuration in the ``twopools.xml`` file: + +.. code-block:: 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> + <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: + +.. code-block:: console + + $ sysrepocfg -d running -f xml -m kea-dhcp6-server --import=twopools.xml + +.. _operation-example-2subnets: + +NETCONF Operation Example with Two Subnets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example specifies two subnets in the ``twosubnets.xml`` file: + +.. code-block:: xml + + <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: + +.. code-block:: console + + $ sysrepocfg -d running -f xml -m kea-dhcp6-server --import=twosubnets.xml + +.. _operation-example-logging: + +NETCONF Operation Example With Logging +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example adds a logger entry to the initial (i.e. startup) +configuration in the ``logging.xml`` file: + +.. code-block:: xml + + <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: + +.. code-block:: json + + { + "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: + +.. code-block:: console + + $ sysrepocfg -d running -f xml -m kea-dhcp6-server --edit + +or by using a NETCONF client like ``netopeer2-cli`` from the +`Netopeer2 <https://github.com/CESNET/Netopeer2>`__ NETCONF Toolset. + +.. _migrating-yang-data: + +Migrating YANG Data From a Prior Sysrepo Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Shut down :iscman:`kea-netconf`. This ensures that backups for both datastores +are done at the same configuration state and that no change happens between exporting them. + +2. Make data backups for all YANG modules, with one XML for each datastore. + +.. code-block:: console + + $ sysrepocfg --datastore running --export=save.xml --format=xml + $ sysrepocfg --datastore startup --export=save.xml --format=xml + +.. note:: + + Sysrepo v0 does not support import/export of all YANG modules; this capability was added in + Sysrepo v1. Users that are migrating from Sysrepo v0 will need to do per-module backups. This has + the added benefit of isolating potential failures and preventing them from affecting all + modules. The command is the same, except it has the module name added to it at the end. + + .. code-block:: console + + $ sysrepocfg --datastore running --export=save.xml --format=xml kea-dhcp6-server + $ sysrepocfg --datastore startup --export=save.xml --format=xml kea-dhcp6-server + +3. Upgrade Sysrepo to the newer version and then run: + +.. code-block:: console + + $ sysrepocfg --datastore running --import=save.xml + $ sysrepocfg --datastore startup --import=save.xml |