From: Francis Dupont Date: Tue, 16 Oct 2018 20:16:52 +0000 (+0200) Subject: [5-netconf-doc-config] Updated netconf doc X-Git-Tag: 148-lib-process-servers-without-arguments_base~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1113d7fea4cd6a7adae9bc8c18e90eb613315e35;p=thirdparty%2Fkea.git [5-netconf-doc-config] Updated netconf doc --- diff --git a/doc/examples/netconf/simple.json b/doc/examples/netconf/simple.json index 38f8a92940..a64008caee 100644 --- a/doc/examples/netconf/simple.json +++ b/doc/examples/netconf/simple.json @@ -3,14 +3,24 @@ { "Netconf": { - // This map specifies how each server is managed: - // the YANG model to use and the control channel. + // 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. 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 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), + // "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" (same comment about "d2"). + // to forward commands to "dhcp4" or "dhcp6" (in the future also + // to d2). "managed-servers": { // This is how Netconf can communicate with the DHCPv4 server. @@ -21,7 +31,7 @@ "control-socket": { "socket-type": "unix", - "socket-name": "/path/to/the/unix/socket-v4" + "socket-name": "/tmp/kea4-ctrl-socket" } }, @@ -32,7 +42,7 @@ "control-socket": { "socket-type": "unix", - "socket-name": "/path/to/the/unix/socket-v6" + "socket-name": "/tmp/kea6-ctrl-socket" } }, @@ -61,7 +71,8 @@ }, // Netconf is able to load hook libraries that augment its operation. - // The primary functionality is the ability to add new commands. + // Currently there are no hook points defined in kea-netconf + // processing. "hooks-libraries": [ // Hook libraries list may contain more than one library. { @@ -69,8 +80,8 @@ "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). + // type this section carefully, as the kea-netconf does not + // validate it (because the format is library specific). "parameters": { "param1": "foo" } @@ -88,12 +99,14 @@ "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. + // 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 diff --git a/doc/guide/netconf.xml b/doc/guide/netconf.xml index a9f3ceba40..89afcb0156 100644 --- a/doc/guide/netconf.xml +++ b/doc/guide/netconf.xml @@ -197,11 +197,14 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | Supported YANG models - The currently the only supported model is kea-dhcp4-server. - There is partial support for kea-dhcp6-server, but the - primary focus of testing was on DHCPv4. Several other models - (ietf-dhcpv6-server, kea-dhcp-ddns - and kea-ctrl-agent) are currently not supported. It is + The currently the only supported models are + kea-dhcp4-server and + kea-dhcp6-server. + There is partial support for ietf-dhcpv6-server, + but the primary focus of testing was on Kea DHCP servers. + Several other models + (kea-dhcp-ddns and + kea-ctrl-agent) are currently not supported. It is envisaged the situation to change in the future. @@ -230,8 +233,8 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | For each managed server get the YANG configuration from the - startup datastore, translate it to JSON and load it onto the server - being configured. + startup datastore, translate it to JSON and load it onto + the server being configured. @@ -251,7 +254,7 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | - +
Configuration @@ -260,14 +263,15 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | 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 defined in managed server scope takes precedence. + In the second case the value defined in managed server scope + takes precedence. These flags are: The boot-update controls the initial configuration phase: when true (the default) the initial - configuration is retrieved from the classic Kea server JSON + configuration retrieved from the classic Kea server JSON configuration file is loaded first, then the startup YANG model is loaded. This setting lets you define a control socket in your local JSON file and then download the configuration from YANG. @@ -281,7 +285,7 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | 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. When set to true, running datastore is + are disabled. When set to true, the running datastore is used to subscribe for changes. @@ -290,11 +294,16 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | 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 subscribed only for application. + +<--! Incorrect change: is subscribed for both validation and application. This means that the kea-netconf will call config-test first and then, if it is successful, will call config-set to actually apply the configuration. This approach is safer, but slower. When false it is subscribed only for application. +--> @@ -320,8 +329,11 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | 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. However, the + the YANG / Netconf configuration management paradigm. +<--! spurious statement + However, the solution attempts to provide maximum flexibility. +--> @@ -333,14 +345,15 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | - When a module change are tracked (using - subscribe-changes set to true) and the running - configuration has changed (e.g. using sysrepocfg or any - NETCONF client) the callback is called to validate the modified - configuration (if validate-changes was not set to - false) and a second time to apply it. If the validation failed the - callback is still called again but with an ABORT (vs APPLY) event with - rollback changes. + 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 is called to validate the modified configuration + (if validate-changes was not set to false) + and a second time to apply it. If the validation failed the + callback is still called again but with an ABORT (vs APPLY) + event with rollback changes. @@ -349,8 +362,8 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | - There are four ways in which a modified YANG configuration could possibly - be incorrect: + There are four ways in which a modified YANG configuration could + possibly be incorrect: @@ -363,14 +376,16 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | It can fail to be translated from YANG to JSON, e.g. - invalid user context or unsupported database type. + invalid user context. +<--! need another example but this one falls in the next case + or unsupported database type. --> It can fail Kea server sanity checks, e.g. out of subnet - pool range. + pool range or unsupported database type. @@ -412,8 +427,11 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | - model specifies the YANG model. Unless explicitly - specified, each Kea daemon has its own YANG model. + model specifies the YANG model / module name. +<--! Two bad proposals +(default the corresponding service Kea one). + +Unless explicitly specified, each Kea daemon has its own YANG model. --> @@ -457,25 +475,23 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | - - 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 as YANG model entry, + enclosed in curly brackets). They are accepted at the Netconf entry, managed service entry and control socket scopes. - Hooks libraries can be loaded by the Netconf agent just like other servers - or agents. It currently supports no hook point, however. This is expected - to change in the upcoming Kea releases. The - hooks-libraries list contains the list of hooks - libraries that should be loaded by netconf, along with their configuration - information specified with parameters. + Hooks libraries can be loaded by the Netconf agent just like + other servers or agents. It currently supports no hook point, + however. This is expected to change in the upcoming Kea + releases. The hooks-libraries list + contains the list of hooks libraries that should be loaded by Netconf, + along with their configuration information specified with + parameters. @@ -488,8 +504,8 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
Kea-netconf Configuration Example - The following example demonstrates the basic Netconf configuration. More - examples are available in doc/examples/netconf + The following example demonstrates the basic Netconf configuration. + More examples are available in doc/examples/netconf directory in Kea sources. @@ -515,7 +531,8 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | // "unix" which uses the local control channel supported by // "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" (in the future also to d2). + // to forward commands to "dhcp4" or "dhcp6" (in the future also + // to d2). "managed-servers": { // This is how Netconf can communicate with the DHCPv4 server. @@ -566,7 +583,8 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | }, // Netconf is able to load hook libraries that augment its operation. - // Currently there are no hook points defined in kea-netconf processing. + // Currently there are no hook points defined in kea-netconf + // processing. "hooks-libraries": [ // Hook libraries list may contain more than one library. { @@ -593,12 +611,14 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | | "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. + // 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