From e8983a4be53a967adc5f8a4c9baa69c615f1bda1 Mon Sep 17 00:00:00 2001 From: Olof hagsand Date: Tue, 19 Mar 2019 10:04:16 +0100 Subject: [PATCH] Upgrade repair test and docs --- doc/startup.md | 65 +++++++++++++++++++++++++++++++++---- test/test_upgrade_repair.sh | 33 +++++++++++++++---- 2 files changed, 84 insertions(+), 14 deletions(-) diff --git a/doc/startup.md b/doc/startup.md index 10ef3b85..c8b755f8 100644 --- a/doc/startup.md +++ b/doc/startup.md @@ -8,6 +8,7 @@ * [Extra XML](#extra-xml) * [Startup status](#startup-status) * [Failsafe mode](#failsafe-mode) + * [Repair](#repair) * [Flowcharts](#flowcharts) * [Thanks](#thanks) * [References](#references) @@ -193,15 +194,65 @@ contain syntax errors or invalidated XML. If the startup mode was `running`, the the `tmp` database will contain syntax errors or invalidated XML. -A user can repair a broken configuration and either restart the -backend or copy the repaired configuration to candidate and then commit. +## Repair -Note that if the broken configuration contains syntactic errors -(eg `STARTUP_ERR`) you cannot access the startup via Restconf or -Netconf operations since the XML may be broken. +If the system is in the failsafe mode (or fails to start), a user can +repair a broken configuration and then restart the backend. This can +be done out-of-band by editing the startup db and then restarting +clixon. -If the startup is not valid (no syntax errors), you can edit the XML -and then copy/commit it via CLI, Netconf or Restconf. +In some circumstances, it is also possible to repair the startup +configuration on-line without restarting the backend. This section +shows how to repair a startup datastore on-line. + +However, on-line repair _cannot_ be made in the following circumstances: +* The broken configuration contains syntactic errors - the system cannot parse the XML. +* The startup mode is `running`. In this case, the broken config is in the `tmp` datastore that is not a recognized Netconf datastore, it has to be accessed out-of-band. +* Netconf must be used. Restconf cannot separately access the different datastores. + +First, copy the (broken) startup config to candidate. This is necessary since you cannot make `edit-config` calls to the startup db: +``` + + + + + + +``` + +You can now edit the XML in candidate. However, there are some restrictions on the edit commands. For example, you cannot access invalid XML (eg that does not have a corresponding module) via the edit-config operation. +For example, assume `x` is obsolete syntax, then this is _not_ accepted: +``` + + + + + + + + +``` + +Instead, assuming `y` is a valid syntax, this is allowed (`x` is not explicitly accessed): +``` + + + + + + + + +``` + +Finally, the candidate is validate and committed: +``` + + + +``` + +This example is also used as a [test script](../test/test_upgrade_repair.sh). ## Flowcharts diff --git a/test/test_upgrade_repair.sh b/test/test_upgrade_repair.sh index e063f19e..7b416596 100755 --- a/test/test_upgrade_repair.sh +++ b/test/test_upgrade_repair.sh @@ -12,6 +12,10 @@ cfg=$dir/conf_yang.xml fyangA0=$dir/A@0814-01-28.yang fyangA1=$dir/A@2019-01-01.yang +OLDXML='old version' +SAMEXML='always work' +NEWXML='new version' + # Yang module A revision "0814-01-28" # Note that this Yang model will exist in the DIR but will not be loaded # by the system. Just here for reference @@ -70,7 +74,7 @@ EOF # Create failsafe db cat < $dir/failsafe_db - always work + $SAMEXML EOF @@ -86,8 +90,8 @@ cat < $dir/non-compat-invalid.xml urn:example:a - old version - always work + $OLDXML + $SAMEXML EOF @@ -96,7 +100,7 @@ EOF mode=startup -new "test params: -f $cfg" +new "test params: -s $mode -f $cfg" # Bring your own backend if [ $BE -ne 0 ]; then # kill old backend (if any) @@ -121,11 +125,26 @@ new "waiting" sleep $RCWAIT new "Check running db content is failsafe" -expecteof "$clixon_netconf -qf $cfg" 0 ']]>]]>' '^always work]]>]]>$' +expecteof "$clixon_netconf -qf $cfg" 0 ']]>]]>' "^$SAMEXML]]>]]>$" -#repair +new "copy startup->candidate" +expecteof "$clixon_netconf -qf $cfg" 0 "]]>]]>" "^]]>]]>$" -#exit +new "Check candidate db content is startup" +expecteof "$clixon_netconf -qf $cfg" 0 ']]>]]>' "^$OLDXML$SAMEXML]]>]]>$" + +# Note you cannot edit invalid XML since a0 lacks namespace +new "Put new version into candidate" +expecteof "$clixon_netconf -qf $cfg" 0 "$NEWXML$SAMEXML]]>]]>" "^]]>]]>$" + +new "Check candidate db content is updated" +expecteof "$clixon_netconf -qf $cfg" 0 ']]>]]>' "^$SAMEXML$NEWXML]]>]]>$" + +new "commit to running" +expecteof "$clixon_netconf -qf $cfg" 0 "]]>]]>" "^]]>]]>$" + +new "Check running db content is updated" +expecteof "$clixon_netconf -qf $cfg" 0 ']]>]]>' "^$SAMEXML$NEWXML]]>]]>$" new "Kill restconf daemon" stop_restconf