diff options
Diffstat (limited to 'doc/sphinx/arm/ext-netconf.rst')
| -rw-r--r-- | doc/sphinx/arm/ext-netconf.rst | 1058 |
1 files changed, 1058 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..46725e1 --- /dev/null +++ b/doc/sphinx/arm/ext-netconf.rst @@ -0,0 +1,1058 @@ +.. _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 YANG modeling language, +defined in `RFC 6020 <https://tools.ietf.org/html/rfc6020>`__, to provide a uniform way +of handling the configuration syntax of varied networking devices. Kea provides optional +support for a YANG/NETCONF interface with the ``kea-netconf`` agent. + +.. _netconf-install: + +Installing NETCONF +------------------ + +To get its NETCONF capabilities, Kea uses libyang v1.0.240 and Sysrepo v1.4.140. +Use packages if they are provided by the system. If not, users can +build from sources, which should work on all popular OSes: + +.. _libyang-install-sources: + +Installing libyang From Sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ 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 + +.. _sysrepo-install-sources: + +Installing Sysrepo From Sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ 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 + +.. _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 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: + +.. code-block:: console + + $ ./src/share/yang/modules/utils/reinstall.sh + +If Sysrepo is installed in a custom path, use: + +.. 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]: 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 + +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: + +.. 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 accordingly. + +.. _netconf-models: + +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. Other models (``kea-dhcp-ddns`` and ``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 ``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 ``kea-netconf`` in the validation phase (if not disabled by +setting ``validate-changes`` to ``true``). The last case causes the +application phase to fail without a sensible report to Sysrepo. + +The managed Kea servers and agents are described in the +``managed-servers`` section. Each sub-section begins with the service +name: ``dhcp4``, ``dhcp6``, ``d2`` (the DHCP-DDNS server does not +support the control-channel feature yet), and ``ca`` (the control +agent). + +Each managed server entry may contain: + +- control flags - ``boot-update``, ``subscribe-changes``, and/or ``validate-changes``. + +- ``model`` - specifies the YANG model/module name. For each service, + the default is the corresponding Kea YANG model, e.g. for ``"dhcp4"`` + it is ``"kea-dhcp4-server"``. + +- ``control-socket`` - specifies the control socket for managing the + service configuration. + +A control socket is specified by: + +- ``socket-type`` - the socket type is either ``stdout``, ``unix``, or ``http``. + ``stdout`` is the default; + it is not really a socket, but it allows ``kea-netconf`` to run in + debugging mode where everything is printed on stdout, and it can also be + used to redirect commands easily. ``unix`` is the standard direct + server control channel, which uses UNIX sockets; ``http`` uses + a control agent, which accepts HTTP connections. + +- ``socket-name`` - the local socket name for the ``unix`` socket type + (default empty string). + +- ``socket-url`` - the HTTP URL for the ``http`` socket type (default + ``http://127.0.0.1:8000/``). + +User contexts can store arbitrary data as long as they are in valid JSON +syntax and their top-level element is a map (i.e. the data must be +enclosed in curly brackets). They are accepted at the NETCONF entry, +i.e. below the top-level, managed-service entry, and control-socket +entry scopes. + +Hook libraries can be loaded by the NETCONF agent just as with other +servers or agents; however, currently no hook points are defined. The +``hooks-libraries`` list contains the list of hook libraries that +should be loaded by ``kea-netconf``, along with their configuration +information specified with ``parameters``. + +Please consult :ref:`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. + +.. _netconf-example: + +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. + +.. 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": "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 hook 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 + } + ] + } + } + +.. _netconf-start-stop: + +Starting and Stopping the NETCONF Agent +--------------------------------------- + +``kea-netconf`` accepts the following command-line switches: + +- ``-c file`` - specifies the configuration file. + +- ``-d`` - specifies whether the agent logging should be switched to + debug/verbose mode. In verbose mode, the logging severity and + debuglevel specified in the configuration file are ignored and + "debug" severity and the maximum debuglevel (99) are assumed. The + flag is convenient for temporarily switching the server into maximum + verbosity, e.g. when debugging. + +- ``-t file`` - specifies the configuration file to be tested. + ``kea-netconf`` attempts to load it and conducts sanity checks; + certain checks are possible only while running the actual server. The + actual status is reported with exit code (0 = configuration appears valid, + 1 = error encountered). Kea prints out log messages to standard + output and error to standard error when testing the configuration. + +- ``-v`` - displays the version of ``kea-netconf`` and exits. + +- ``-V`` - displays the extended version information for ``kea-netconf`` + and exits. The listing includes the versions of the libraries + dynamically linked to Kea. + +- ``-W`` - displays the Kea configuration report and exits. The report + is a copy of the ``config.report`` file produced by ``./configure``; + it is embedded in the executable binary. + +.. _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 ``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 +``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 ``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``: + +.. 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 --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. + +.. _operation-example-errors: + +Error Handling in NETCONF Operation Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 --edit=BAD-schema.xml + +In the second case, the configuration is rejected by ``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 --edit=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 --edit=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-v0-to-v1: + +Migrating YANG Data from Sysrepo v0.x to v1.x +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Start the migration after turning off ``kea-netconf`` to make sure that backups +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, so users of earlier versions will need to do per-module backup. +This has the added benefit of isolating potential failures and preventing them from +affecting all modules. + +With Sysrepo v0.x: + +.. 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 + +Install Sysrepo v1.x and then: + +.. code-block:: console + + $ 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. +If necessary, they can be provided with the ``--format xml`` and +``--module kea-dhcp6-server`` flags. + +If upgrading from a very old version of Sysrepo, there may also be changes to the YANG +modules themselves. In that case, the backups will need some minor massaging, as would +be required with normal periodic maintenance. |