</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>
+<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>
+</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>
+<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>
+</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>
+<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>
+</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>
+<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>
+</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>
+<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>
+</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>
+<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>
+</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>
+<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>
+</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>
projects / thirdparty / kea.git / commitdiff
