Commit eb4ca638 authored by Francis Dupont's avatar Francis Dupont

[195-document-sample-netconf-operation] Added operation examples

parent 1a757f3a
......@@ -62,9 +62,16 @@ nobase_dist_doc_DATA += examples/kea6/simple.json
nobase_dist_doc_DATA += examples/kea6/softwire46.json
nobase_dist_doc_DATA += examples/kea6/stateless.json
nobase_dist_doc_DATA += examples/kea6/with-ddns.json
nobase_dist_doc_DATA += examples/netconf/BAD-config.xml
nobase_dist_doc_DATA += examples/netconf/BAD-schema.xml
nobase_dist_doc_DATA += examples/netconf/BAD-translator.xml
nobase_dist_doc_DATA += examples/netconf/comments.json
nobase_dist_doc_DATA += examples/netconf/simple.json
nobase_dist_doc_DATA += examples/netconf/logging.xml
nobase_dist_doc_DATA += examples/netconf/simple-dhcp4.json
nobase_dist_doc_DATA += examples/netconf/simple.json
nobase_dist_doc_DATA += examples/netconf/startup.xml
nobase_dist_doc_DATA += examples/netconf/twopools.xml
nobase_dist_doc_DATA += examples/netconf/twosubnets.xml
# These are files that document our APIs. They're not really needed as the
# content is included in the api.xml, but may be useful for people who
......
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6>
<id>1</id>
<pool>
<start-address>2001:db8:1::0</start-address>
<end-address>2001:db8:1::ffff</end-address>
<prefix>2001:db8:1::0/112</prefix>
</pool>
<subnet>2001:db8::/64</subnet>
</subnet6>
<interfaces-config>
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
<socket-name>/tmp/kea6-sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
</config>
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet4>
<id>1</id>
<pool>
<start-address>2001:db8::1:0</start-address>
<end-address>2001:db8::1:ffff</end-address>
<prefix>2001:db8::1:0/112</prefix>
</pool>
<subnet>2001:db8::/64</subnet>
</subnet6>
<interfaces-config>
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
<socket-name>/tmp/kea6-sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
</config>
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6>
<id>1</id>
<pool>
<start-address>2001:db8::1:0</start-address>
<end-address>2001:db8::1:ffff</end-address>
<prefix>2001:db8::1:0/112</prefix>
</pool>
<subnet>2001:db8::/64</subnet>
</subnet6>
<interfaces-config>
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
<socket-name>/tmp/kea6-sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
<user-context>bad</user-context>
</config>
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<interfaces-config>
<interfaces>eth1</interfaces>
</interfaces-config>
<subnet6>
<id>1</id>
<pool>
<start-address>2001:db8::1:0</start-address>
<end-address>2001:db8::1:ffff</end-address>
<prefix>2001:db8::1:0/112</prefix>
</pool>
<subnet>2001:db8::/64</subnet>
</subnet6>
<control-socket>
<socket-name>/tmp/kea6-sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
<logger>
<name>kea-dhcp6</name>
<output-option>
<output>stderr</output>
</output-option>
<debuglevel>99</debuglevel>
<severity>DEBUG</severity>
</logger>
</config>
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6>
<id>1</id>
<pool>
<start-address>2001:db8::1:0</start-address>
<end-address>2001:db8::1:ffff</end-address>
<prefix>2001:db8::1:0/112</prefix>
</pool>
<subnet>2001:db8::/64</subnet>
</subnet6>
<interfaces-config>
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
<socket-name>/tmp/kea6-sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
</config>
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6>
<id>1</id>
<pool>
<start-address>2001:db8::1:0</start-address>
<end-address>2001:db8::1:ffff</end-address>
<prefix>2001:db8::1:0/112</prefix>
</pool>
<pool>
<start-address>2001:db8::2:0</start-address>
<end-address>2001:db8::2:ffff</end-address>
<prefix>2001:db8::2:0/112</prefix>
</pool>
<subnet>2001:db8::/64</subnet>
</subnet6>
<interfaces-config>
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
<socket-name>/tmp/kea6-sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
</config>
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6>
<id>1</id>
<pool>
<start-address>2001:db8:1::</start-address>
<end-address>2001:db8:1::ffff</end-address>
<prefix>2001:db8:1::/112</prefix>
</pool>
<subnet>2001:db8:1::/64</subnet>
</subnet6>
<subnet6>
<id>1</id>
<pool>
<start-address>2001:db8:2::</start-address>
<end-address>2001:db8:2::ffff</end-address>
<prefix>2001:db8:2::/112</prefix>
</pool>
<subnet>2001:db8:2::/64</subnet>
</subnet6>
<interfaces-config>
<interfaces>eth1</interfaces>
</interfaces-config>
<control-socket>
<socket-name>/tmp/kea6-sock</socket-name>
<socket-type>unix</socket-type>
</control-socket>
</config>
......@@ -711,4 +711,418 @@ done in dependency order and reverse dependency order accordingly.
</itemizedlist>
</section>
<section xml:id="operation-example">
<title>Step by Step Netconf Operation Example</title>
<section xml:id="operation-example-setup">
<title>Setup of Netconf Operation Example</title>
<para>
The test box has an Ethernet interface named eth1.
On some systems it is possible to rename interfaces,
for instance on a Linux with an ens38 interface:
<screen>
# ip link set down dev <userinput>ens38</userinput>
# ip link set name eth1 dev <userinput>ens38</userinput>
# ip link set up dev eth1
</screen>
The interface must have an address in the test prefix:
<screen>
# ip -6 addr add 2001:db8::1/64 dev eth1
</screen>
</para>
<para>
The Kea DHCPv6 server must be launched with a configuration
specifying a control socket so <command>kea-netconf</command>
can push configuration to it:
<screen>
{
"Dhcp6": {
"control-socket": {
"socket-type": "unix",
"socket-name": "/tmp/kea6-sock"
}
}
}
</screen>
Launched when the configuration is in the
<filename>boot.json</filename> file by:
<screen>
# kea-dhcp6 -d -c <userinput>boot.json</userinput>
</screen>
The current configuration can be dumped by:
<screen>
# echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea6-sock '-,ignoreeof'
</screen>
</para>
<para>
A more complete startup configuration must be installed in the
sysrepo datastore. The configuration in
<filename>startup.xml</filename> is:
<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>
{
"Netconf":
{
"managed-servers":
{
"dhcp6":
{
"control-socket":
{
"socket-type": "unix",
"socket-name": "/tmp/kea6-sock"
}
}
}
},
"Logging":
{
"loggers":
[
{
"name": "kea-netconf",
"output_options":
[
{
"output": "stderr"
}
],
"severity": "DEBUG",
"debuglevel": 99
}
]
}
}
</screen>
Note in production you should not need to log at the DEBUG level.
The Kea Netconf agent is lanched by:
<screen>
# kea-netconf -d -c <userinput>netconf.json</userinput>
</screen>
</para>
</section>
<section xml:id="operation-example-errors">
<title>Error handling in Netconf Operation Example</title>
<para>
There are 4 ways for a configuration to be bad:
<orderedlist>
<listitem>
<simpara>
The configuration does not comply with the YANG schema.
</simpara>
</listitem>
<simpara>
The configuration can not be translated from YANG to
the Kea JSON.
</simpara>
<listitem>
<simpara>
The configuration is rejected by the Kea server.
</simpara>
</listitem>
<listitem>
<simpara>
The configuration was validated by the Kea server but
can not be applied.
</simpara>
</listitem>
</orderedlist>
</para>
<para>
In the first case the configuration in
the <filename>BAD-schema.xml</filename> file:
<screen>
&lt;config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"&gt;
&lt;subnet4&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>
is directly rejected by <command>sysrepocfg</command>:
<screen>
# sysrepocfg -d running -f xml -i <userinput>BAD-schema.xml</userinput> kea-dhcp6-server
</screen>
</para>
<para>
In the second case the configuration is rejected by
<command>kea-netconf</command>, for instance for the
<filename>BAD-translator.xml</filename> file:
<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;user-context&gt;bad&lt;/user-context&gt;
&lt;/config&gt;
</screen>
</para>
<para>
In the third case the configuration is presented to the
Kea DHCPv6 server and fails to validate as in the
<filename>BAD-config.xml</filename> file:
<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>
</para>
<para>
In the last case the problem is detected too late and
the change must be reverted, for instance using the startup
datastore as a backup.
</para>
</section>
<section xml:id="operation-example-2pools">
<title>Netconf Operation Example with Two Pools</title>
<para>
This example adds a second pool to the initial (i.e. startup)
configuration in the <filename>twopools.xml</filename> file:
<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;pool&gt;
&lt;start-address&gt;2001:db8::2:0&lt;/start-address&gt;
&lt;end-address&gt;2001:db8::2:ffff&lt;/end-address&gt;
&lt;prefix&gt;2001:db8::2: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>
This configuration is installed by:
<screen>
# sysrepocfg -d running -f xml -i <userinput>twopools.xml</userinput> kea-dhcp6-server
</screen>
</para>
</section>
<section xml:id="operation-example-2subnets">
<title>Netconf Operation Example with Two Subnets</title>
<para>
This example specifies two subnets in the
<filename>twosubnets.xml</filename> file:
<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::&lt;/start-address&gt;
&lt;end-address&gt;2001:db8:1::ffff&lt;/end-address&gt;
&lt;prefix&gt;2001:db8:1::/112&lt;/prefix&gt;
&lt;/pool&gt;
&lt;subnet&gt;2001:db8:1::/64&lt;/subnet&gt;
&lt;/subnet6&gt;
&lt;subnet6&gt;
&lt;id&gt;1&lt;/id&gt;
&lt;pool&gt;
&lt;start-address&gt;2001:db8:2::&lt;/start-address&gt;
&lt;end-address&gt;2001:db8:2::ffff&lt;/end-address&gt;
&lt;prefix&gt;2001:db8:2::/112&lt;/prefix&gt;
&lt;/pool&gt;
&lt;subnet&gt;2001:db8:2::/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>
This configuration is installed by:
<screen>
# sysrepocfg -d running -f xml -i <userinput>twosubnets.xml</userinput> kea-dhcp6-server
</screen>
</para>
</section>
<section xml:id="operation-example-logging">
<title>Netconf Operation Example with Logging</title>
<para>
This example adds a Logging section to the initial (i.e. startup)
configuration in the <filename>logging.xml</filename> file:
<screen>
&lt;config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"&gt;
&lt;interfaces-config&gt;
&lt;interfaces&gt;eth1&lt;/interfaces&gt;
&lt;/interfaces-config&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;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;logger&gt;
&lt;name&gt;kea-dhcp6&lt;/name&gt;
&lt;output-option&gt;
&lt;output&gt;stderr&lt;/output&gt;
&lt;/output-option&gt;
&lt;debuglevel&gt;99&lt;/debuglevel&gt;
&lt;severity&gt;DEBUG&lt;/severity&gt;
&lt;/logger&gt;
&lt;/config&gt;
</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>
The corresponding Kea configuration in JSON is:
<screen>
{
"Dhcp6": {
"control-socket": {
"socket-name": "/tmp/kea6-sock",
"socket-type": "unix"
},
"interfaces-config": {
"interfaces": [ "eth1" ]
},
"subnet6": [
{
"id": 1,
"pools": [
{
"pool": "2001:db8::1:0/112"
}
],
"subnet": "2001:db8::/64"
}
]
},
"Logging": {
"loggers": [
{
"name": "kea-dhcp6",
"output_options": [
{
"output": "stderr"
}
],
"severity": "DEBUG",
"debuglevel": 99
}
]
}
}
</screen>
</para>
</section>
</section>
</chapter>
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment