Upgrade repair test and docs

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
+## Repair
-backend or copy the repaired configuration to candidate and then commit.
 
-Note that if the broken configuration contains syntactic errors
+If the system is in the failsafe mode (or fails to start), a user can
-(eg `STARTUP_ERR`) you cannot access the startup via Restconf or
+repair a broken configuration and then restart the backend. This can
-Netconf operations since the XML may be broken.
+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
+In some circumstances, it is also possible to repair the startup
-and then copy/commit it via CLI, Netconf or Restconf.
+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:
+```
+  <rpc>
+    <copy-config>
+      <source><startup/></source>
+      <target><candidate/></target>
+    </copy-config>
+  </rpc>
+```
+
+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:
+```
+  <rpc>
+    <edit-config>
+      <target><candidate/></target>
+      <config>
+        <x xmlns="example" operation='delete'/>
+      </config>
+    </edit-config>
+  </rpc>
+```
+
+Instead, assuming `y` is a valid syntax, this is allowed (`x` is not explicitly accessed):
+```
+  <rpc>
+    <edit-config>
+      <target><candidate/></target>
+      <config operation='replace'>
+        <y xmlns="example"/>
+      </config>
+    </edit-config>
+  </rpc>
+```
+
+Finally, the candidate is validate and committed:
+```
+  <rpc>
+    <commit/>
+  </rpc>
+```
+
+This example is also used as a [test script](../test/test_upgrade_repair.sh).
 
 ## Flowcharts
 

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='<a0 xmlns="urn:example:a">old version</a0>'
+SAMEXML='<a1 xmlns="urn:example:a">always work</a1>'
+NEWXML='<a2 xmlns="urn:example:a">new version</a2>'
+
 # 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 <<EOF > $dir/failsafe_db
 <config>
-   <a1 xmlns="urn:example:a">always work</a1>
+   $SAMEXML
 </config>
 EOF
 
@@ -86,8 +90,8 @@ cat <<EOF > $dir/non-compat-invalid.xml
          <namespace>urn:example:a</namespace>
       </module>
    </modules-state>
-   <a0 xmlns="urn:example:a">old version</a0>
+   $OLDXML
-   <a1 xmlns="urn:example:a">always work</a1>
+   $SAMEXML
 </config>
 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 '<rpc><get-config><source><running/></source></get-config></rpc>]]>]]>' '^<rpc-reply><data><a1 xmlns="urn:example:a">always work</a1></data></rpc-reply>]]>]]>$'
+expecteof "$clixon_netconf -qf $cfg" 0 '<rpc><get-config><source><running/></source></get-config></rpc>]]>]]>' "^<rpc-reply><data>$SAMEXML</data></rpc-reply>]]>]]>$"
 
-#repair    
+new "copy startup->candidate"
+expecteof "$clixon_netconf -qf $cfg" 0 "<rpc><copy-config><target><candidate/></target><source><startup/></source></copy-config></rpc>]]>]]>" "^<rpc-reply><ok/></rpc-reply>]]>]]>$"
 
-#exit
+new "Check candidate db content is startup"
+expecteof "$clixon_netconf -qf $cfg" 0 '<rpc><get-config><source><candidate/></source></get-config></rpc>]]>]]>' "^<rpc-reply><data>$OLDXML$SAMEXML</data></rpc-reply>]]>]]>$"
+
+# Note you cannot edit invalid XML since a0 lacks namespace
+new "Put new version into candidate"
+expecteof "$clixon_netconf -qf $cfg" 0 "<rpc><edit-config><target><candidate/></target><config operation='replace'>$NEWXML$SAMEXML</config></edit-config></rpc>]]>]]>" "^<rpc-reply><ok/></rpc-reply>]]>]]>$"
+
+new "Check candidate db content is updated"
+expecteof "$clixon_netconf -qf $cfg" 0 '<rpc><get-config><source><candidate/></source></get-config></rpc>]]>]]>' "^<rpc-reply><data>$SAMEXML$NEWXML</data></rpc-reply>]]>]]>$"
+
+new "commit to running"
+expecteof "$clixon_netconf -qf $cfg" 0 "<rpc><commit/></rpc>]]>]]>" "^<rpc-reply><ok/></rpc-reply>]]>]]>$"
+
+new "Check running db content is updated"
+expecteof "$clixon_netconf -qf $cfg" 0 '<rpc><get-config><source><running/></source></get-config></rpc>]]>]]>' "^<rpc-reply><data>$SAMEXML$NEWXML</data></rpc-reply>]]>]]>$"
 
 new "Kill restconf daemon"
 stop_restconf