From: Francis Dupont Date: Sun, 14 Oct 2018 11:09:45 +0000 (+0200) Subject: [5-netconf-doc-config] Filled netconf agent doc X-Git-Tag: 148-lib-process-servers-without-arguments_base~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a9641535c5d1356ab78357b5db9cf7ad93a14123;p=thirdparty%2Fkea.git [5-netconf-doc-config] Filled netconf agent doc --- diff --git a/doc/examples/netconf/simple.json b/doc/examples/netconf/simple.json index a9902e1738..38f8a92940 100644 --- a/doc/examples/netconf/simple.json +++ b/doc/examples/netconf/simple.json @@ -10,7 +10,7 @@ // "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". + // to forward commands to "dhcp4" or "dhcp6" (same comment about "d2"). "managed-servers": { // This is how Netconf can communicate with the DHCPv4 server. diff --git a/doc/guide/netconf.xml b/doc/guide/netconf.xml index 5c003e7b3c..bb4b52e0b0 100644 --- a/doc/guide/netconf.xml +++ b/doc/guide/netconf.xml @@ -12,7 +12,8 @@
Overview Kea 1.5.0 introduced an optional support for YANG/NETCONF - interface. + 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 @@ -191,4 +192,443 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
+ +
+ Using the Netconf agent + + + The Netconf agent follows this algorithm: + + + + Open a connection with the sysrepo enviroment and establish + two sessions with the startup and running datastores. + + + + + + For each managed server get the initial configuration from + the server through the control scoket. + + + + + + For each managed server get the YANG configuration from the + startup datastore, translate it to JSON and load it in the server. + + + + + + For each managed server subscribe a module change callback + using its model name. + + + + + + When a running configuration is changed, the callback tries + to validate or load the updated configuration to the managed + server. + + + + +
+ +
+ Configuration + + + The behavior described in 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: + + + + The boot-update 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. + + + + + + The subscribe-changes 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. + + + + + + The validate-changes 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. + + + + 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. + + + + The idea behind the initial configuration phase is to boot + Kea servers with a minimal configuration which includes only + a control socket making them manageable. + For instance for the DHCPv4 server: + +{ + "Dhcp4": { + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea4-sock" + } + } +} + + 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. + + + + With module change subscriptions the sysrepocfg + 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. + + + + A modified YANG configuration has four ways to be incorrect: + + + + It can be not schema compliant, e.g. unknown entry, + missing mandatory entry, value with a bad type or + not matching a constraint. + + + + + + It can fail to be translated from YANG to JSON, e.g. + invalid user context. + + + + + + It can fail Kea server sanity checks, e.g. out of subnet + pool range. + + + + + + Syntax is correct and pass server sanity checks but + the configuration fails to be run. + + + + 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 validate-changes to true). The last + case makes the application phase to fail without a sensible report + to sysrepo. + + + + The managed Kea servers or agents are described in the + managed-servers section. Each sub-section + begins by the service name: dhcp4, + dhcp6, d2 + (the DHCP-DDNS server which not yet suppors the control channel + feature), and ca (the control agent). + + + + Each managed server entry contains optionally: + + + + boot-update, + subscribe-changes and + validate-changes control flags. + + + + + + model specifies the model / module name + (default the corresponding service Kea one). + + + + + + 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 (the default, not really a socket), + unix (standard direct server control channel), + and http (using a control agent). + + + + + + 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/). + + + + + The stdout socket type displays modified + configurations on the standard output. + + + + 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. + + + + Hooks libraries can be loaded by the Netconf agent just like to + other servers or agents. It currently supports no hook point. + The hooks-libraries list contains the list of hooks + libraries that should be loaded by netconf, along with their + configuration information specified with parameters. + + + + Please consult for the details how to + configure logging. The Netconf's root logger's name is + kea-netconf as given in the example above. + +
+ +
+ Example + + The following example demonstrates the basic Netconf configuration. + + + +// 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 + } + ] + } +} + + +
+ +
+ Starting and Stopping the Netconf Agent + + + 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 + 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. + + + + + + -v - prints out the Kea version and exits. + + + + + + -V - prints out the Kea extended version + with additional parameters and exits. The listing includes + the versions of the libraries dynamically linked to Kea. + + + + + + -W - prints out 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. + + + +
+