mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-01 14:35:29 +00:00
Code Issues Releases Wiki Activity

[5-netconf-doc-config] Updated netconf doc

Browse Source
This commit is contained in:
Francis Dupont
2018-10-16 22:16:52 +02:00
parent 1036f44ff8
commit 1113d7fea4
2 changed files with 94 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
doc/examples/netconf/simple.json
View File

@@ -3,14 +3,24 @@
{ {
"Netconf": "Netconf":
{ {
// This map specifies how each server is managed: // Control flags can be defined in the global scope or
// the YANG model to use and the control channel. // 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: // Currently three control channel types are supported:
// "stdout" which output the configuration on the standard output, // "stdout" which output the configuration on the standard output,
// "unix" which uses the local control channel supported by // "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 // 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": "managed-servers":
{ {
// This is how Netconf can communicate with the DHCPv4 server. // This is how Netconf can communicate with the DHCPv4 server.
@@ -21,7 +31,7 @@
"control-socket": "control-socket":
{ {
"socket-type": "unix", "socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-v4" "socket-name": "/tmp/kea4-ctrl-socket"
} }
}, },
@@ -32,7 +42,7 @@
"control-socket": "control-socket":
{ {
"socket-type": "unix", "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. // 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": [ "hooks-libraries": [
// Hook libraries list may contain more than one library. // Hook libraries list may contain more than one library.
{ {
@@ -69,8 +80,8 @@
"library": "/opt/local/netconf-commands.so", "library": "/opt/local/netconf-commands.so",
// Some libraries may support parameters. Make sure you // Some libraries may support parameters. Make sure you
// type this section carefully, as the CA does not validate // type this section carefully, as the kea-netconf does not
// it (because the format is library specific). // validate it (because the format is library specific).
"parameters": { "parameters": {
"param1": "foo" "param1": "foo"
} }
@@ -88,12 +99,14 @@
"output_options": [ "output_options": [
{ {
"output": "/var/log/kea-netconf.log", "output": "/var/log/kea-netconf.log",
// Several additional parameters are possible in addition // Several additional parameters are possible in
// to the typical output. Flush determines whether logger // addition to the typical output.
// flushes output to a file. Maxsize determines maximum // Flush determines whether logger flushes output
// filesize before the file is being rotated. maxver // to a file.
// specifies the maximum number of rotated files being // Maxsize determines maximum filesize before
// kept. // the file is being rotated.
// Maxver specifies the maximum number of
// rotated files being kept.
"flush": true, "flush": true,
"maxsize": 204800, "maxsize": 204800,
"maxver": 4 "maxver": 4

112
doc/guide/netconf.xml
View File

@@ -197,11 +197,14 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
<title>Supported YANG models</title> <title>Supported YANG models</title>
<para> <para>
The currently the only supported model is <command>kea-dhcp4-server</command>. The currently the only supported models are
There is partial support for <command>kea-dhcp6-server</command>, but the <command>kea-dhcp4-server</command> and
primary focus of testing was on DHCPv4. Several other models <command>kea-dhcp6-server</command>.
(<command>ietf-dhcpv6-server</command>, <command>kea-dhcp-ddns</command> There is partial support for <command>ietf-dhcpv6-server</command>,
and <command>kea-ctrl-agent</command>) are currently not supported. It is but the primary focus of testing was on Kea DHCP servers.
Several other models
(<command>kea-dhcp-ddns</command> and
<command>kea-ctrl-agent</command>) are currently not supported. It is
envisaged the situation to change in the future. envisaged the situation to change in the future.
</para> </para>
@@ -230,8 +233,8 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
<listitem> <listitem>
<simpara> <simpara>
For each managed server get the YANG configuration from the For each managed server get the YANG configuration from the
startup datastore, translate it to JSON and load it onto the server startup datastore, translate it to JSON and load it onto
being configured. the server being configured.
</simpara> </simpara>
</listitem> </listitem>
@@ -251,7 +254,7 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
</section> </section>
<section xml:id="netconf-configuration"> <section xml:id="netconf-configuration">
<title>Configuration</title> <title>Configuration</title>
@@ -260,14 +263,15 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
The behavior described in <xref linkend="using-netconf"/> is The behavior described in <xref linkend="using-netconf"/> is
controlled by a few configuration flags which can be set in controlled by a few configuration flags which can be set in
the global scope or in a specific managed server scope. 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: These flags are:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<simpara> <simpara>
The <command>boot-update</command> controls the initial The <command>boot-update</command> controls the initial
configuration phase: when true (the default) 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 configuration file is loaded first, then the startup YANG
model is loaded. This setting lets you define a control socket in model is loaded. This setting lets you define a control socket in
your local JSON file and then download the configuration from YANG. 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) module change subscription: when true (the default)
a module change callback is subscribed, when false a module change callback is subscribed, when false
the phase is skipped and running configuration updates 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. used to subscribe for changes.
</simpara> </simpara>
</listitem> </listitem>
@@ -290,11 +294,16 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
<simpara> <simpara>
The <command>validate-changes</command> controls the subscription The <command>validate-changes</command> controls the subscription
option: when true (the default) a module change callback 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 is subscribed for both validation and application. This means
that the kea-netconf will call config-test first and then, that the kea-netconf will call config-test first and then,
if it is successful, will call config-set to actually apply if it is successful, will call config-set to actually apply
the configuration. This approach is safer, but slower. the configuration. This approach is safer, but slower.
When false it is subscribed only for application. When false it is subscribed only for application.
-->
</simpara> </simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@@ -320,8 +329,11 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
</screen> </screen>
Note the alternative to boot with full configurations does not Note the alternative to boot with full configurations does not
allow an easy track of changes, so it not really compatible with 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. solution attempts to provide maximum flexibility.
-->
</para> </para>
<para> <para>
@@ -333,14 +345,15 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
</para> </para>
<para> <para>
When a module change are tracked (using When module changes are tracked (using
<command>subscribe-changes</command> set to true) and the running <command>subscribe-changes</command> set to true) and the
configuration has changed (e.g. using <command>sysrepocfg</command> or any running configuration has changed
NETCONF client) the callback is called to validate the modified (e.g. using <command>sysrepocfg</command> or any NETCONF client)
configuration (if <command>validate-changes</command> was not set to the callback is called to validate the modified configuration
false) and a second time to apply it. If the validation failed the (if <command>validate-changes</command> was not set to false)
callback is still called again but with an ABORT (vs APPLY) event with and a second time to apply it. If the validation failed the
rollback changes. callback is still called again but with an ABORT (vs APPLY)
event with rollback changes.
</para> </para>
<para> <para>
@@ -349,8 +362,8 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
</para> </para>
<para> <para>
There are four ways in which a modified YANG configuration could possibly There are four ways in which a modified YANG configuration could
be incorrect: possibly be incorrect:
<orderedlist> <orderedlist>
<listitem> <listitem>
<simpara> <simpara>
@@ -363,14 +376,16 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
<listitem> <listitem>
<simpara> <simpara>
It can fail to be translated from YANG to JSON, e.g. 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. -->
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
It can fail Kea server sanity checks, e.g. out of subnet It can fail Kea server sanity checks, e.g. out of subnet
pool range. pool range or unsupported database type.
</simpara> </simpara>
</listitem> </listitem>
@@ -412,8 +427,11 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
<listitem> <listitem>
<simpara> <simpara>
<command>model</command> specifies the YANG model. Unless explicitly <command>model</command> specifies the YANG model / module name.
specified, each Kea daemon has its own YANG model. <--! Two bad proposals
(default the corresponding service Kea one).
Unless explicitly specified, each Kea daemon has its own YANG model. -->
</simpara> </simpara>
</listitem> </listitem>
@@ -457,25 +475,23 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
</simpara> </simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
The <command>stdout</command> socket type displays modified
configurations on the standard output.
</para> </para>
<para> <para>
User contexts can store arbitrary data as long as it is valid JSON 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 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. managed service entry and control socket scopes.
</para> </para>
<para> <para>
Hooks libraries can be loaded by the Netconf agent just like other servers Hooks libraries can be loaded by the Netconf agent just like
or agents. It currently supports no hook point, however. This is expected other servers or agents. It currently supports no hook point,
to change in the upcoming Kea releases. The however. This is expected to change in the upcoming Kea
<command>hooks-libraries</command> list contains the list of hooks releases. The <command>hooks-libraries</command> list
libraries that should be loaded by netconf, along with their configuration contains the list of hooks libraries that should be loaded by Netconf,
information specified with <command>parameters</command>. along with their configuration information specified with
<command>parameters</command>.
</para> </para>
<para> <para>
@@ -488,8 +504,8 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
<section xml:id="netconf-example"> <section xml:id="netconf-example">
<title>Kea-netconf Configuration Example</title> <title>Kea-netconf Configuration Example</title>
<para> <para>
The following example demonstrates the basic Netconf configuration. More The following example demonstrates the basic Netconf configuration.
examples are available in <command>doc/examples/netconf</command> More examples are available in <command>doc/examples/netconf</command>
directory in Kea sources. directory in Kea sources.
</para> </para>
<para> <para>
@@ -515,7 +531,8 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
// "unix" which uses the local control channel supported by // "unix" which uses the local control channel supported by
// "dhcp4" and "dhcp6" servers ("d2" support is not yet available), // "dhcp4" and "dhcp6" servers ("d2" support is not yet available),
// and "http" which uses the Control agent "ca" to manage itself or // 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": "managed-servers":
{ {
// This is how Netconf can communicate with the DHCPv4 server. // 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. // 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": [ "hooks-libraries": [
// Hook libraries list may contain more than one library. // Hook libraries list may contain more than one library.
{ {
@@ -593,12 +611,14 @@ ietf-dhcpv6-types | 2018-01-30 | Imported | |
"output_options": [ "output_options": [
{ {
"output": "/var/log/kea-netconf.log", "output": "/var/log/kea-netconf.log",
// Several additional parameters are possible in addition // Several additional parameters are possible in
// to the typical output. Flush determines whether logger // addition to the typical output.
// flushes output to a file. Maxsize determines maximum // Flush determines whether logger flushes output
// filesize before the file is being rotated. maxver // to a file.
// specifies the maximum number of rotated files being // Maxsize determines maximum filesize before
// kept. // the file is being rotated.
// Maxver specifies the maximum number of
// rotated files being kept.
"flush": true, "flush": true,
"maxsize": 204800, "maxsize": 204800,
"maxver": 4 "maxver": 4