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

[#195,!131] Applied changes to the NETCONF step by step.

Browse Source 
As a result of review.
This commit is contained in:
Marcin Siodelski
2018-11-28 19:45:28 +01:00
committed by Francis Dupont
parent d6fd4c0e85
commit e847b7cc55
1 changed files with 85 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
doc/guide/netconf.xml
View File

@@ -714,6 +714,10 @@ done in dependency order and reverse dependency order accordingly.
<section xml:id="operation-example"> <section xml:id="operation-example">
<title>Step by Step Netconf Operation Example</title> <title>Step by Step Netconf Operation Example</title>
<note><para>Copies of example configurations presented within this section
can be found in the Kea source code, under <filename>doc/examples/kea6</filename>
and <filename>doc/examples/netconf</filename>.</para></note>
<section xml:id="operation-example-setup"> <section xml:id="operation-example-setup">
<title>Setup of Netconf Operation Example</title> <title>Setup of Netconf Operation Example</title>
@@ -733,9 +737,13 @@ done in dependency order and reverse dependency order accordingly.
</para> </para>
<para> <para>
The Kea DHCPv6 server must be launched with a configuration The Kea DHCPv6 server must be launched with the configuration
specifying a control socket so <command>kea-netconf</command> specifying a control socket used to receive control commands.
can push configuration to it: The <command>kea-netconf</command> 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 the example control socket specification for the
Kea DHCPv6 server:
<screen> <screen>
{ {
"Dhcp6": { "Dhcp6": {
@@ -746,66 +754,22 @@ done in dependency order and reverse dependency order accordingly.
} }
} }
</screen> </screen>
Launched when the configuration is in the In order to launch the Kea DHCPv6 server using configuration
<filename>boot.json</filename> file by: contained within <filename>boot.json</filename> file, run:
<screen> <screen>
# kea-dhcp6 -d -c <userinput>boot.json</userinput> # kea-dhcp6 -d -c <userinput>boot.json</userinput>
</screen> </screen>
The current configuration can be dumped by: The current configuration of the server can be fetched via
control socket by running:
<screen> <screen>
# echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea6-sock '-,ignoreeof' # echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea6-sock '-,ignoreeof'
</screen> </screen>
</para> </para>
<para> <para>
A more complete startup configuration must be installed in the The following is the example <filename>netconf.json</filename>
sysrepo datastore. The configuration in configuration for <command>kea-netconf</command>, to manage the Kea
<filename>startup.xml</filename> is: DHCPv6 server:
<screen>
&lt;config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"&gt;
&lt;subnet6&gt;
&lt;id&gt;1&lt;/id&gt;
&lt;pool&gt;
&lt;start-address&gt;2001:db8::1:0&lt;/start-address&gt;
&lt;end-address&gt;2001:db8::1:ffff&lt;/end-address&gt;
&lt;prefix&gt;2001:db8::1:0/112&lt;/prefix&gt;
&lt;/pool&gt;
&lt;subnet&gt;2001:db8::/64&lt;/subnet&gt;
&lt;/subnet6&gt;
&lt;interfaces-config&gt;
&lt;interfaces&gt;eth1&lt;/interfaces&gt;
&lt;/interfaces-config&gt;
&lt;control-socket&gt;
&lt;socket-name&gt;/tmp/kea6-sock&lt;/socket-name&gt;
&lt;socket-type&gt;unix&lt;/socket-type&gt;
&lt;/control-socket&gt;
&lt;/config&gt;
</screen>
and can be installed by:
<screen>
# sysrepocfg -d startup -f xml -i <userinput>startup.xml</userinput> kea-dhcp6-server
</screen>
A copy of these configurations are in the netconf example directory.
</para>
<para>
<command>kea-netconf</command> will push 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.
</para>
<para>
Changes to the running datastore are applied after validation
to Kea servers. Note they are not by default copied back to the
startup datastore, i.e. changes are not permanent.
</para>
<para>
<command>kea-netconf</command> configuration to manage the
Kea DHCPv6 server in the <filename>netconf.json</filename> is:
<screen> <screen>
{ {
"Netconf": "Netconf":
@@ -841,28 +805,81 @@ done in dependency order and reverse dependency order accordingly.
} }
} }
</screen> </screen>
Note in production you should not need to log at the DEBUG level. Note that in production you should not need to log at the DEBUG level.
</para>
<para>
The Kea Netconf agent is lanched by: The Kea Netconf agent is lanched by:
<screen> <screen>
# kea-netconf -d -c <userinput>netconf.json</userinput> # kea-netconf -d -c <userinput>netconf.json</userinput>
</screen> </screen>
</para> </para>
<para>
Now that both <filename>kea-netconf</filename> and
<filename>kea-dhcp6</filename> are running, it is possible to populate
updated to configuration to the DHCPv6 server. The following is
the configuration extracted from the <filename>startup.xml</filename>:
<screen>
&lt;config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"&gt;
&lt;subnet6&gt;
&lt;id&gt;1&lt;/id&gt;
&lt;pool&gt;
&lt;start-address&gt;2001:db8::1:0&lt;/start-address&gt;
&lt;end-address&gt;2001:db8::1:ffff&lt;/end-address&gt;
&lt;prefix&gt;2001:db8::1:0/112&lt;/prefix&gt;
&lt;/pool&gt;
&lt;subnet&gt;2001:db8::/64&lt;/subnet&gt;
&lt;/subnet6&gt;
&lt;interfaces-config&gt;
&lt;interfaces&gt;eth1&lt;/interfaces&gt;
&lt;/interfaces-config&gt;
&lt;control-socket&gt;
&lt;socket-name&gt;/tmp/kea6-sock&lt;/socket-name&gt;
&lt;socket-type&gt;unix&lt;/socket-type&gt;
&lt;/control-socket&gt;
&lt;/config&gt;
</screen>
In order to populate this new configuration:
<screen>
# sysrepocfg -d startup -f xml -i <userinput>startup.xml</userinput> kea-dhcp6-server
</screen>
</para>
<para>
<command>kea-netconf</command> will push 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.
</para>
<para>
Changes to the running datastore are applied after validation
to the Kea servers. Note they are not by default copied back to the
startup datastore, i.e. changes are not permanent.
</para>
</section> </section>
<section xml:id="operation-example-errors"> <section xml:id="operation-example-errors">
<title>Error handling in Netconf Operation Example</title> <title>Error handling in Netconf Operation Example</title>
<para> <para>
There are 4 ways for a configuration to be bad: There are four classes of isssues with the configurations applied via
netconf:
<orderedlist> <orderedlist>
<listitem> <listitem>
<simpara> <simpara>
The configuration does not comply with the YANG schema. The configuration does not comply with the YANG schema.
</simpara> </simpara>
</listitem> </listitem>
<listitem>
<simpara> <simpara>
The configuration cannot be translated from YANG to The configuration cannot be translated from YANG to
the Kea JSON. the Kea JSON.
</simpara> </simpara>
</listitem>
<listitem> <listitem>
<simpara> <simpara>
The configuration is rejected by the Kea server. The configuration is rejected by the Kea server.
@@ -878,8 +895,8 @@ done in dependency order and reverse dependency order accordingly.
</para> </para>
<para> <para>
In the first case the configuration in In the first case, the following <filename>BAD-schema.xml</filename>
the <filename>BAD-schema.xml</filename> file: configuration file:
<screen> <screen>
&lt;config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"&gt; &lt;config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"&gt;
&lt;subnet4&gt; &lt;subnet4&gt;
@@ -907,8 +924,8 @@ done in dependency order and reverse dependency order accordingly.
</para> </para>
<para> <para>
In the second case the configuration is rejected by In the second case, the configuration is rejected by
<command>kea-netconf</command>, for instance for the <command>kea-netconf</command>. For example, the
<filename>BAD-translator.xml</filename> file: <filename>BAD-translator.xml</filename> file:
<screen> <screen>
&lt;config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"&gt; &lt;config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"&gt;
@@ -934,7 +951,7 @@ done in dependency order and reverse dependency order accordingly.
</para> </para>
<para> <para>
In the third case the configuration is presented to the In the third case, the configuration is presented to the
Kea DHCPv6 server and fails to validate as in the Kea DHCPv6 server and fails to validate as in the
<filename>BAD-config.xml</filename> file: <filename>BAD-config.xml</filename> file:
<screen> <screen>
@@ -960,9 +977,9 @@ done in dependency order and reverse dependency order accordingly.
</para> </para>
<para> <para>
In the last case the problem is detected too late and In the last case, the misconfiguration is detected too late and
the change must be reverted, for instance using the startup the change must be reverted in sysrepo, e.g. using the startup
datastore as a backup, or with other words use the datastore as a backup. For this reason, please use the
<command>sysrepocfg</command> <option>--permanent</option> / <command>sysrepocfg</command> <option>--permanent</option> /
<option>-p</option> option (or simlar feature of NETCONF clients) <option>-p</option> option (or simlar feature of NETCONF clients)
with care. with care.
@@ -1080,9 +1097,6 @@ done in dependency order and reverse dependency order accordingly.
&lt;/logger&gt; &lt;/logger&gt;
&lt;/config&gt; &lt;/config&gt;
</screen> </screen>
Note in Kea models the "loggers" list was moved in global
parameters and the "Logging" global object removed as it is
planned in a future release for Kea JSON configurations.
</para> </para>
<para> <para>
@@ -1128,8 +1142,8 @@ done in dependency order and reverse dependency order accordingly.
</para> </para>
<para> <para>
To finish one of the previous examples can be replayed using Finally, any of the previous examples can be replayed using
<command>sysrepocfg</command> in edit mode by: <command>sysrepocfg</command> in edit mode as follows:
<screen> <screen>
# sysrepocfg -d running -f xml -e <userinput>vi</userinput> kea-dhcp6-server # sysrepocfg -d running -f xml -e <userinput>vi</userinput> kea-dhcp6-server
</screen> </screen>