From: Francis Dupont Date: Thu, 22 Nov 2018 08:50:08 +0000 (+0100) Subject: [195-document-sample-netconf-operation] Added operation examples X-Git-Tag: 284-need-dhcp6-example-for-netconf_base~5 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=eb4ca638fd80995e998efd870bc8524b2a03220d;p=thirdparty%2Fkea.git [195-document-sample-netconf-operation] Added operation examples --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 33d68dfd4c..0656ad7f12 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 diff --git a/doc/examples/netconf/BAD-config.xml b/doc/examples/netconf/BAD-config.xml new file mode 100644 index 0000000000..acf9342d97 --- /dev/null +++ b/doc/examples/netconf/BAD-config.xml @@ -0,0 +1,18 @@ + + + 1 + + 2001:db8:1::0 + 2001:db8:1::ffff + 2001:db8:1::0/112 + + 2001:db8::/64 + + + eth1 + + + /tmp/kea6-sock + unix + + diff --git a/doc/examples/netconf/BAD-schema.xml b/doc/examples/netconf/BAD-schema.xml new file mode 100644 index 0000000000..80b5c13203 --- /dev/null +++ b/doc/examples/netconf/BAD-schema.xml @@ -0,0 +1,18 @@ + + + 1 + + 2001:db8::1:0 + 2001:db8::1:ffff + 2001:db8::1:0/112 + + 2001:db8::/64 + + + eth1 + + + /tmp/kea6-sock + unix + + diff --git a/doc/examples/netconf/BAD-translator.xml b/doc/examples/netconf/BAD-translator.xml new file mode 100644 index 0000000000..a0924cff8d --- /dev/null +++ b/doc/examples/netconf/BAD-translator.xml @@ -0,0 +1,19 @@ + + + 1 + + 2001:db8::1:0 + 2001:db8::1:ffff + 2001:db8::1:0/112 + + 2001:db8::/64 + + + eth1 + + + /tmp/kea6-sock + unix + + bad + diff --git a/doc/examples/netconf/logging.xml b/doc/examples/netconf/logging.xml new file mode 100644 index 0000000000..16024c62e7 --- /dev/null +++ b/doc/examples/netconf/logging.xml @@ -0,0 +1,26 @@ + + + eth1 + + + 1 + + 2001:db8::1:0 + 2001:db8::1:ffff + 2001:db8::1:0/112 + + 2001:db8::/64 + + + /tmp/kea6-sock + unix + + + kea-dhcp6 + + stderr + + 99 + DEBUG + + diff --git a/doc/examples/netconf/startup.xml b/doc/examples/netconf/startup.xml new file mode 100644 index 0000000000..c59934ba1f --- /dev/null +++ b/doc/examples/netconf/startup.xml @@ -0,0 +1,18 @@ + + + 1 + + 2001:db8::1:0 + 2001:db8::1:ffff + 2001:db8::1:0/112 + + 2001:db8::/64 + + + eth1 + + + /tmp/kea6-sock + unix + + diff --git a/doc/examples/netconf/twopools.xml b/doc/examples/netconf/twopools.xml new file mode 100644 index 0000000000..719dbc79ed --- /dev/null +++ b/doc/examples/netconf/twopools.xml @@ -0,0 +1,23 @@ + + + 1 + + 2001:db8::1:0 + 2001:db8::1:ffff + 2001:db8::1:0/112 + + + 2001:db8::2:0 + 2001:db8::2:ffff + 2001:db8::2:0/112 + + 2001:db8::/64 + + + eth1 + + + /tmp/kea6-sock + unix + + diff --git a/doc/examples/netconf/twosubnets.xml b/doc/examples/netconf/twosubnets.xml new file mode 100644 index 0000000000..2e7ad70d13 --- /dev/null +++ b/doc/examples/netconf/twosubnets.xml @@ -0,0 +1,27 @@ + + + 1 + + 2001:db8:1:: + 2001:db8:1::ffff + 2001:db8:1::/112 + + 2001:db8:1::/64 + + + 1 + + 2001:db8:2:: + 2001:db8:2::ffff + 2001:db8:2::/112 + + 2001:db8:2::/64 + + + eth1 + + + /tmp/kea6-sock + unix + + diff --git a/doc/guide/netconf.xml b/doc/guide/netconf.xml index 589d517c30..43d0364153 100644 --- a/doc/guide/netconf.xml +++ b/doc/guide/netconf.xml @@ -711,4 +711,418 @@ done in dependency order and reverse dependency order accordingly. +
+ Step by Step Netconf Operation Example + +
+ Setup of Netconf Operation Example + + 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: + + # ip link set down dev ens38 + # ip link set name eth1 dev ens38 + # ip link set up dev eth1 + + The interface must have an address in the test prefix: + + # ip -6 addr add 2001:db8::1/64 dev eth1 + + + + + The Kea DHCPv6 server must be launched with a configuration + specifying a control socket so kea-netconf + can push configuration to it: + +{ + "Dhcp6": { + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea6-sock" + } + } +} + + Launched when the configuration is in the + boot.json file by: + + # kea-dhcp6 -d -c boot.json + + The current configuration can be dumped by: + + # echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea6-sock '-,ignoreeof' + + + + + A more complete startup configuration must be installed in the + sysrepo datastore. The configuration in + startup.xml is: + +<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> + + and can be installed by: + + # sysrepocfg -d startup -f xml -i startup.xml kea-dhcp6-server + + A copy of these configurations are in the netconf example directory. + + + + kea-netconf 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. + + + + 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. + + + + kea-netconf configuration to manage the + Kea DHCPv6 server in the netconf.json is: + +{ + "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 + } + ] + } +} + + Note in production you should not need to log at the DEBUG level. + The Kea Netconf agent is lanched by: + + # kea-netconf -d -c netconf.json + + +
+ +
+ Error handling in Netconf Operation Example + + There are 4 ways for a configuration to be bad: + + + + The configuration does not comply with the YANG schema. + + + + The configuration can not be translated from YANG to + the Kea JSON. + + + + The configuration is rejected by the Kea server. + + + + + The configuration was validated by the Kea server but + can not be applied. + + + + + + + In the first case the configuration in + the BAD-schema.xml file: + +<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> + + is directly rejected by sysrepocfg: + + # sysrepocfg -d running -f xml -i BAD-schema.xml kea-dhcp6-server + + + + + In the second case the configuration is rejected by + kea-netconf, for instance for the + BAD-translator.xml file: + +<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> + + + + + In the third case the configuration is presented to the + Kea DHCPv6 server and fails to validate as in the + BAD-config.xml file: + +<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> + + + + + 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. + +
+ +
+ Netconf Operation Example with Two Pools + + This example adds a second pool to the initial (i.e. startup) + configuration in the twopools.xml file: + +<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> + + This configuration is installed by: + + # sysrepocfg -d running -f xml -i twopools.xml kea-dhcp6-server + + +
+ +
+ Netconf Operation Example with Two Subnets + + This example specifies two subnets in the + twosubnets.xml file: + +<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> + + This configuration is installed by: + + # sysrepocfg -d running -f xml -i twosubnets.xml kea-dhcp6-server + + +
+ +
+ Netconf Operation Example with Logging + + This example adds a Logging section to the initial (i.e. startup) + configuration in the logging.xml file: + +<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> + + 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. + + + + The corresponding Kea configuration in JSON is: + +{ + "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 + } + ] + } +} + + +
+
+