Cleaned up after regression tests. New upgrade running docs.
This commit is contained in:
Olof hagsand
parent
29535d5997
commit
b3cd48468d
5 changed files with 113 additions and 88 deletions
106
doc/startup.md
106
doc/startup.md
|
|
@ -21,33 +21,41 @@ This document describes the configuration startup mechanism of the Clixon backen
|
|||
* An upgrade callback when in-compatible XML is encountered
|
||||
* A "failsafe" mode allowing a user to repair the startup on errors or failed validation.
|
||||
|
||||
Notes on this document:
|
||||
* "database" and "datastore" are used interchangeably for the same XML or JSON file storing a configuration.
|
||||
* For some scenarios, such a the "running" startup mode, a "temporary" datastore is used (called tmp_db). This file may have to be accessed out-of-band in failure scenarios.
|
||||
|
||||
## Modes
|
||||
|
||||
When the Clixon backend starts, it can start in one of four modes:
|
||||
* `startup`: The configuration is loaded from a persistent `startup` database. This database is loaded, validated and committed into the running database.
|
||||
* `running`: Similar to `startup`, but instead the `running` database is used as persistent database.
|
||||
* `none`: No databases are touched - the system starts and loads existing running database without validation or commits.
|
||||
* `startup`: The configuration is loaded from a persistent `startup` datastore. The XML is loaded, parsed, validated and committed into the running database.
|
||||
* `running`: Similar to `startup`, but instead the `running` datastore is used as a persistent database. The system copies the original running-db to a temporary store(tmp_db), and commits that temporary datastore into the (new) running datastore.
|
||||
* `none`: No data stores are touched - the system starts and loads existing running datastore without validation or commits.
|
||||
* `init`: Similar to `none`, but the running database is cleared before loading
|
||||
|
||||
`Startup` targets usecases where running db may be in memory and a
|
||||
separate persistent storage (such as flash) is available. `Running` is
|
||||
for usecases when the running db is located in persistent The `none`
|
||||
for usecases when the running db is located in persistent. The `none`
|
||||
and `init` modes are mostly for debugging, or restart at crashes or updates.
|
||||
|
||||
## Startup configuration
|
||||
|
||||
When the backend daemon is started in `startup` mode, the system loads
|
||||
the `startup` database. The `running` mode is very similar, the only
|
||||
difference is that the running database is copied (overwrites) the
|
||||
startup database before this phase.
|
||||
the `startup` database.
|
||||
|
||||
When loading the startup configuration, it is checked for parse
|
||||
errors, the yang model-state is detected and the XML is validated
|
||||
against the backend Yang models.
|
||||
The `running` mode is similar, the only difference is that the running
|
||||
database is copied into a temporary database which then acts as the
|
||||
startup store.
|
||||
|
||||
When loading the startup/tmp configuration, the following actions are performed by the system:
|
||||
|
||||
* It is checked for parse errors,
|
||||
* the yang model-state is detected (if present)
|
||||
* the XML is validated against the Yang models loaded in the backend (NB: may be different from the model-state).
|
||||
|
||||
If yang-models do not match, an `upgrade` callback is made.
|
||||
|
||||
If any errors are detected, the backend tries to enter a `failsafe` mode.
|
||||
If any errors are detected, the backend enters a `failsafe` mode.
|
||||
|
||||
## Model-state
|
||||
|
||||
|
|
@ -123,24 +131,25 @@ Example upgrade callback:
|
|||
};
|
||||
```
|
||||
|
||||
Note that this is simply a template for upgrade. Actual upgrading may
|
||||
be implememted by a user.
|
||||
Note that the example shown is only a template for an upgrade
|
||||
function. Actual upgrading code may be implemented by a user.
|
||||
|
||||
If no action is made, and the XML is not upgraded, the next step of
|
||||
the startup is made, which is XML/Yang validation.
|
||||
If no action is made by the upgrade calback, and thus the XML is not
|
||||
upgraded, the next step is XML/Yang validation.
|
||||
|
||||
An out-dated XML
|
||||
may still pass validation and the system will go up in normal state.
|
||||
An out-dated XML may still pass validation and the system will go up
|
||||
in normal state.
|
||||
|
||||
However, if the validation fails, the backend will try to enter the
|
||||
failsafe mode so that the user may perform manual upgarding of the
|
||||
configuration.
|
||||
|
||||
|
||||
## Extra XML
|
||||
|
||||
If validation succeeds and the startup configuration has been committed to the running database, a user may add "extra" XML.
|
||||
If the Yang validation succeeds and the startup configuration has been committed to the running database, a user may add "extra" XML.
|
||||
|
||||
There are two ways to add extra XML to running database after start. Note that this XML is not "committed" into running.
|
||||
There are two ways to add extra XML to running database after start. Note that this XML is "merged" into running, not "committed".
|
||||
|
||||
The first way is via a file. Assume you want to add this xml:
|
||||
```
|
||||
|
|
@ -154,9 +163,11 @@ clixon_backend ... -c extra.xml
|
|||
```
|
||||
|
||||
The second way is by programming the plugin_reset() in the backend
|
||||
plugin. The example code contains an example on how to do this (see plugin_reset() in example_backend.c).
|
||||
plugin. The example code contains an example on how to do this (see
|
||||
plugin_reset() in example_backend.c).
|
||||
|
||||
The extra-xml feature is not available if startup mode is `none`. It will also not occur in failsafe mode.
|
||||
The extra-xml feature is not available if startup mode is `none`. It
|
||||
will also not occur in failsafe mode.
|
||||
|
||||
## Startup status
|
||||
|
||||
|
|
@ -174,13 +185,18 @@ in `CLICON_XMLDB_DIR/failsafe_db`. If such a config is not found, the
|
|||
backend terminates.
|
||||
|
||||
If the failsafe is found, the failsafe config is loaded and
|
||||
committed into the running db. The `startup` database will contain syntax
|
||||
errors or invalidated XML.
|
||||
committed into the running db.
|
||||
|
||||
A user can repair the `startup` configuration and either restart the
|
||||
backend or copy the startup configuration to candidate and the commit.
|
||||
If the startup mode was `startup`, the `startup` database will
|
||||
contain syntax errors or invalidated XML.
|
||||
|
||||
Note that the if the startup configuration contains syntactic errors
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -192,22 +208,25 @@ and then copy/commit it via CLI, Netconf or Restconf.
|
|||
This section contains "pseudo" flowcharts showing the dynamics of
|
||||
the configuration databases in the startup phase.
|
||||
|
||||
The flowchart starts in one of the the modes (non, init, startup, running):
|
||||
The flowchart starts in one of the modes (none, init, startup, running):
|
||||
|
||||
### init mode
|
||||
|
||||
Starting in init mode:
|
||||
```
|
||||
reset
|
||||
running |--------+------------> GOTO EXTRA XML
|
||||
```
|
||||
|
||||
Start in running mode:
|
||||
```
|
||||
running ----+
|
||||
\ copy
|
||||
startup +------------> GOTO STARTUP
|
||||
### running mode
|
||||
|
||||
```
|
||||
Starting in startup mode:
|
||||
running ----+ |----------+--------> GOTO EXTRA XML
|
||||
\ copy parse validate OK / commit
|
||||
tmp ------+-------+------+-----------+
|
||||
|
||||
```
|
||||
|
||||
### startup mode
|
||||
```
|
||||
reset
|
||||
running |--------+------------> GOTO EXTRA XML
|
||||
|
|
@ -215,29 +234,36 @@ running |--------+------------> GOTO EXTRA XML
|
|||
startup -------+--+-------+------------+
|
||||
```
|
||||
|
||||
If validation of startup fails:
|
||||
### Failure
|
||||
```
|
||||
failsafe ----------------------+
|
||||
reset \ commit
|
||||
running |-------+---------------> GOTO EXTRA XML
|
||||
running |-------+---------------> GOTO SYSTEM UP
|
||||
parse validate fail
|
||||
startup ---+-------------------------------------> INVALID XML
|
||||
tmp/startup --+-----+---------------------------------> INVALID XML
|
||||
```
|
||||
|
||||
Load EXTRA XML:
|
||||
### Extra XML
|
||||
```
|
||||
running -----------------+----+------> GOTO SYSTEM UP
|
||||
reset loadfile / merge
|
||||
tmp |-------+-----+-----+
|
||||
```
|
||||
|
||||
SYSTEM UP:
|
||||
### System UP
|
||||
```
|
||||
running ----+-----------------------> RUNNING
|
||||
\ copy
|
||||
candidate +---------------------> CANDIDATE
|
||||
|
||||
```
|
||||
|
||||
|
||||
### Invalid XML
|
||||
repair restart
|
||||
tmp/startup --------+---------+----------------------->
|
||||
|
||||
|
||||
|
||||
## Thanks
|
||||
Thanks matt smith and dave cornejo for input
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue