<section xml:id="netconf-overview">
<title>Overview</title>
<para>Kea 1.5.0 introduced an optional support for YANG/NETCONF
- interface. </para>
+ interface with the new <command>kea-netconf</command>
+ Netconf agent. </para>
<para>This bare bones documentation is a work in progress. Its
current purpose is to let engineers joining the project or perhaps
</para>
</section>
+
+ <section xml:id="using-netconf">
+ <title>Using the Netconf agent</title>
+
+ <para>
+ The Netconf agent follows this algorithm:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Open a connection with the sysrepo enviroment and establish
+ two sessions with the startup and running datastores.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ For each managed server get the initial configuration from
+ the server through the control scoket.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ For each managed server get the YANG configuration from the
+ startup datastore, translate it to JSON and load it in the server.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ For each managed server subscribe a module change callback
+ using its model name.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ When a running configuration is changed, the callback tries
+ to validate or load the updated configuration to the managed
+ server.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section xml:id="netconf-configuration">
+ <title>Configuration</title>
+
+ <para>
+ The behavior described in <xref linkend="using-netconf"/> is
+ controlled by a few configuration flags which can be set in
+ the global scope or in a specific managed server scope.
+ In the second case the value takes precedence.
+ These flags are:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ The <command>boot-update</command> controls the initial
+ configuration phase: when true (the default) the initial
+ configuration is got from the server and the startup YANG
+ one is loaded, when false this phase is skipped.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ The <command>subscribe-changes</command> controls the
+ module change subscription: when true (the default)
+ a module change callback is subscribed, when false
+ the phase is skipped and running configuration updates
+ are disabled.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ The <command>validate-changes</command> controls the subscription
+ option: when true (the default) a module change callback
+ is subscribed for both validation and application, when false
+ it is suscribed only for application.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ Other configuration flags are under study, for instance for loading
+ updated configurations directly in the validation callback so
+ syntactically correct but invalid configurations can be rejected
+ as soon as possible.
+ </para>
+
+ <para>
+ 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:
+<screen>
+{
+ "Dhcp4": {
+ "control-socket": {
+ "socket-type": "unix",
+ "socket-name": "/tmp/kea4-sock"
+ }
+ }
+}
+</screen>
+ Note the alternative to boot with full configurations does not
+ allow an easy track of changes so it not really compatible with
+ the YANG / Netconf configuration management paradigm.
+ </para>
+
+ <para>
+ With module change subscriptions the <command>sysrepocfg</command>
+ command is used to modify YANG configurations in the running
+ datastore. Note committed configurations are only updated in
+ the running datastore: to keep them between server reboots
+ they must be copied to the startup datastore.
+ </para>
+
+ <para>
+ A modified YANG configuration has four ways to be incorrect:
+ <orderedlist>
+ <listitem>
+ <simpara>
+ It can be not schema compliant, e.g. unknown entry,
+ missing mandatory entry, value with a bad type or
+ not matching a constraint.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ It can fail to be translated from YANG to JSON, e.g.
+ invalid user context.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ It can fail Kea server sanity checks, e.g. out of subnet
+ pool range.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ Syntax is correct and pass server sanity checks but
+ the configuration fails to be run.
+ </simpara>
+ </listitem>
+ </orderedlist>
+ The first case is handled by sysrepo. The second and third cases
+ are handled by Netconf in the validation phase (if not disabled
+ by setting <command>validate-changes</command> to true). The last
+ case makes the application phase to fail without a sensible report
+ to sysrepo.
+ </para>
+
+ <para>
+ The managed Kea servers or agents are described in the
+ <command>managed-servers</command> section. Each sub-section
+ begins by the service name: <command>dhcp4</command>,
+ <command>dhcp6</command>, <command>d2</command>
+ (the DHCP-DDNS server which not yet suppors the control channel
+ feature), and <command>ca</command> (the control agent).
+ </para>
+
+ <para>
+ Each managed server entry contains optionally:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>boot-update</command>,
+ <command>subscribe-changes</command> and
+ <command>validate-changes</command> control flags.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>model</command> specifies the model / module name
+ (default the corresponding service Kea one).
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>control-socket</command> specifies the control
+ socket for managing the service configuration.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ A control socket is specified by:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>socket-type</command>: the socket type is either
+ <command>stdout</command> (the default, not really a socket),
+ <command>unix</command> (standard direct server control channel),
+ and <command>http</command> (using a control agent).
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>socket-name</command>: the local socket name for
+ the <command>unix</command> socket type (default empty string).
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>socket-url</command>: the HTTP URL for the
+ <command>http</command> socket type (default
+ <userinput>http://127.0.0.1:8000/</userinput>).
+ </simpara>
+ </listitem>
+ </itemizedlist>
+
+ The <command>stdout</command> socket type displays modified
+ configurations on the standard output.
+ </para>
+
+ <para>
+ User contexts can store arbitrary data as long as it is valid JSON
+ syntax and its top level element is a map (i.e. the data must be
+ enclosed in curly brackets). They are accepted at the Netconf,
+ managed service entry and control socket scopes.
+ </para>
+
+ <para>
+ Hooks libraries can be loaded by the Netconf agent just like to
+ other servers or agents. It currently supports no hook point.
+ The <command>hooks-libraries</command> list contains the list of hooks
+ libraries that should be loaded by netconf, along with their
+ configuration information specified with <command>parameters</command>.
+ </para>
+
+ <para>
+ Please consult <xref linkend="logging"/> for the details how to
+ configure logging. The Netconf's root logger's name is
+ <command>kea-netconf</command> as given in the example above.
+ </para>
+ </section>
+
+ <section xml:id="netconf-example">
+ <title>Example</title>
+ <para>
+ The following example demonstrates the basic Netconf configuration.
+ </para>
+ <para>
+<screen>
+// This is a simple example of a configuration for Netconf.
+// This server provides YANG interface for all Kea servers and agent.
+{
+ "Netconf":
+ {
+ // Control flags can be defined in the global scope or
+ // in a managed server scope. Precedence 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:
+ // the YANG model to use and the control channel.
+ // Currently three control channel types are supported:
+ // "stdout" which output the configuration on the standard output,
+ // "unix" which uses the local control channel supported by
+ // "dhcp4" and "dhcp6" servers ("d2" support is not yet merged),
+ // and "http" which uses the Control agent "ca" to manage itself or
+ // to forward commands to "dhcp4" or "dhcp6" (same comment about "d2").
+ "managed-servers":
+ {
+ // This is how Netconf can communicate with the DHCPv4 server.
+ "dhcp4":
+ {
+ "comment": "DHCP4 server",
+ "model": "kea-dhcp4-server",
+ "control-socket":
+ {
+ "socket-type": "unix",
+ "socket-name": "/path/to/the/unix/socket-v4"
+ }
+ },
+
+ // DHCPv6 parameters.
+ "dhcp6":
+ {
+ "model": "kea-dhcp6-server",
+ "control-socket":
+ {
+ "socket-type": "unix",
+ "socket-name": "/path/to/the/unix/socket-v6"
+ }
+ },
+
+ // Currently the DHCP-DDNS (nicknamed D2) server does not support
+ // command channel yet.
+ "d2":
+ {
+ "model": "kea-dhcp-ddns",
+ "control-socket":
+ {
+ "socket-type": "stdout",
+ "user-context": { "in-use": false }
+ }
+ },
+
+ // Of course the Control Agent (nicknamed CA) supports HTTP.
+ "ca":
+ {
+ "model": "kea-ctrl-agent",
+ "control-socket":
+ {
+ "socket-type": "http",
+ "socket-url": "http://127.0.0.1:8000/"
+ }
+ }
+ },
+
+ // Netconf is able to load hook libraries that augment its operation.
+ // The primary functionality is the ability to add new commands.
+ "hooks-libraries": [
+ // Hook 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 the CA does not validate
+ // it (because the format is library specific).
+ "parameters": {
+ "param1": "foo"
+ }
+ }
+ ]
+
+ },
+
+ // Similar to other Kea components, Netconf also uses logging.
+ "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
+ }
+ ]
+ }
+}
+</screen>
+ </para>
+ </section>
+
+ <section xml:id="netconf-start-stop">
+ <title>Starting and Stopping the Netconf Agent</title>
+ <para>
+<!-- no keactrl yet -->
+ Netconf accepts the following command-line switches:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>-c <replaceable>file</replaceable></command> -
+ specifies the configuration file.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>-d</command> - 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.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>-t <replaceable>file</replaceable></command> -
+ specifies the configuration file to be tested. Kea-netconf
+ will attempt to load it, and will conduct sanity
+ checks. Note that certain checks are possible only while
+ running the actual server. The actual status is reported
+ with exit code (0 = configuration looks ok, 1 = error
+ encountered). Kea will print out log messages to standard
+ output and error to standard error when testing
+ configuration.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>-v</command> - prints out the Kea version and exits.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>-V</command> - prints out the Kea extended version
+ with additional parameters and exits. The listing includes
+ the versions of the libraries dynamically linked to Kea.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>-W</command> - prints out the Kea configuration
+ report and exits. The report is a copy of the
+ <filename>config.report</filename> file produced by
+ <userinput>./configure</userinput>: it is embedded in the
+ executable binary.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+
</chapter>
projects / thirdparty / kea.git / commitdiff
