docs

README.md

@@ -4,7 +4,7 @@ Clixon is an automatic configuration manager where you from a YANG
 specification generate interactive CLI, NETCONF, RESTCONF and embedded
 databases with transaction support.
 
-Presentations and tutorial is found on the [CLICON project page](http://www.clicon.org)
+Presentations and tutorial is found on the [Clicon project page](http://www.clicon.org)
 
 Table of contents
 =================
@@ -14,10 +14,7 @@ Table of contents
   * [Dependencies](#dependencies)
   * [Licenses](#licenses)
   * [History](#history)
-  * [Datastore](#datastore)
   * [Yang](#yang)
-  * [Netconf](#netconf)
-  * [Restconf](#restconf)
 
 Installation
 ============
@@ -33,14 +30,17 @@ One example applications is provided, a IETF IP YANG datamodel with generated CL
 Documentation
 =============
 - [Frequently asked questions](doc/FAQ.md)
+- [XML datastore](datastore/README.md)
+- [Netconf support](apps/netconf/README.md)
+- [Restconf support](apps/restconf/README.md)
 - [Reference manual](http://www.clicon.org/doxygen/index.html) (Better: cd doc; make doc)
 - [Routing example](example/README.md)
-- [Test](test/README.md)
+- [Tests](test/README.md)
 
 Dependencies
 ============
 Clixon is dependend on the following packages
-- [CLIgen](http://www.cligen.se) is required for building CLIXON. If you need 
+- [CLIgen](http://www.cligen.se) is required for building Clixon. If you need 
 to build and install CLIgen: 
 ```
     git clone https://github.com/olofhagsand/cligen.git
@@ -53,217 +53,38 @@ to build and install CLIgen:
 
 Licenses
 ========
-CLIXON is dual license. Either Apache License, Version 2.0 or GNU
+Clixon is dual license. Either Apache License, Version 2.0 or GNU
 General Public License Version 2. You choose.
 
-See LICENSE.md for license, CHANGELOG for recent changes.
+See [LICENSE.md](LICENSE.md) for license, [CHANGELOG](CHANGELOG.md) for recent changes.
 
-History
+Background
-=======
+==========
-CLIXON is a fork of CLICON where legacy key specification has been
-replaced completely by YANG. This means that legacy CLICON
-applications such as CLICON/ROST does not run on CLIXON.
 
-Clixon origins from work at [KTH](http://www.csc.kth.se/~olofh/10G_OSR)
+We implemented Clixon since we needed a generic configuration tool in
-
+several projects, including
-Datastore
+[KTH](http://www.csc.kth.se/~olofh/10G_OSR). Most of these projects
-=========
+were for embedded network and measuring-probe devices. We started with
-The Clixon datastore is a stand-alone XML based datastore used by
+something called Clicon which was based on a key-value specification
-Clixon. The idea is to be able to use different datastores. There is
+and data-store. But as time passed new standards evaolved and we
-currently a key-value plugin based on qdbm and a plain text-file
+started adapting it to XML, Yang and netconf. Finally we made Clixon
-datastore.
+where the legacy key specification has been replaced completely by
-
+YANG and using XML as configuration data. This means that legacy
-The datastore is primarily designed to be used by Clixon but can be used
+Clicon applications do not run on Clixon.
-separately.  
-
-A datastore is a dynamic plugin that is loaded at runtime with a
-well-defined API. This means it is possible to create your own
-datastore and plug it in a Clixon backend at runtime. 
-
-### The functional API
-```
-int xmldb_plugin_load(clicon_handle h, char *filename);
-int xmldb_plugin_unload(clicon_handle h);
-int xmldb_connect(clicon_handle h);
-int xmldb_disconnect(clicon_handle h);
-int xmldb_getopt(clicon_handle h, char *optname, void **value);
-int xmldb_setopt(clicon_handle h, char *optname, void *value);
-int xmldb_get(clicon_handle h, char *db, char *xpath,
-	      cxobj **xtop, cxobj ***xvec, size_t *xlen);
-int xmldb_put(clicon_handle h, char *db, enum operation_type op, 
-	      char *api_path,  cxobj *xt);
-int xmldb_copy(clicon_handle h, char *from, char *to);
-int xmldb_lock(clicon_handle h, char *db, int pid);
-int xmldb_unlock(clicon_handle h, char *db);
-int xmldb_unlock_all(clicon_handle h, int pid);
-int xmldb_islocked(clicon_handle h, char *db);
-int xmldb_exists(clicon_handle h, char *db);
-int xmldb_delete(clicon_handle h, char *db);
-int xmldb_create(clicon_handle h, char *db);
-```
-
-### Using the API
-
-To use the API, a client needs the following:
-- A clicon handle. 
-- A datastore plugin, such as a text.so or keyvalue.so. These are normally built and installed at Clixon make.
-- A directory where to store databases
-- A yang specification. This needs to be parsed using the Clixon yang_parse() method.
-
-A client calling the API needs to (1)load a plugin and (2)connect to a
-datastore. You can connect to several datastores, even concurrently,
-but in practice in Clixon, you connect to a single store. 
-
-After connecting to a datastore, you can create and modify databases
-within the datastore, and set and get options of the datastore itself.
-
-When done, you disconnect from the datastore and unload the plugin.
-
-Within a datastore, the following four databases may exist:
-- running
-- candidate
-- startup
-- tmp
-
-Initially, a database does not exist but is created by
-xmldb_create(). It is deleted by xmldb_delete(). You may check for
-existence with xmldb_exists(). You need to create a database before
-you can perform any data access on it.
-
-You may lock a database for exclusive modification according to
-Netconf semantics. You may also unlock a single dabase, unlock all frm
-a specific session.
-
-You can read a database with xmldb_get() and modify a database with
-xmldb_put(), and xmldb_copy().
-
-A typical datastore session can be as follows, see the source code of
-datastore_client.c for a more elaborate example.
-
-```
-  h = clicon_handle_init();
-  xmldb_plugin_load(h, plugin);
-  xmldb_connect(h);
-  xmldb_setopt(h, "dbdir", dbdir);
-  xmldb_setopt(h, "yangspec", yspec);
-  /* From here databases in the datastore may be accessed */
-  xmldb_create(h, "candidate");
-  xmldb_copy(h, "running", "candidate");
-  xmldb_lock(h, "candidate", 7878);
-  xmldb_put(h, "candidate", OP_CREATE, "/interfaces/interface=eth0", xml);
-  xmldb_unlock(h, "candidate");
-  xmldb_get(h, "candidate", "/", &xml, &xvec, &xlen);
-  xmldb_disconnect(h)
-  xmdlb_plugin_unload(h);
-```
 
 YANG
 ====
-Clixon implements YANG RFC 6020. Clixon generates an interactive CLI
-for YANG specifications. It also provides Restconf and Netconf clients.
 
-Clixon YANG currently does not provide the following support:
+YANG is at the heart of Clixon. RFC 6020 is implemented with some
+exceptions as noted below. A Yang specification is used to generated
+an interactive CLI client. Clixon also provides a Netconf and Restconf
+client based on Yang.
+
+The following features are (not yet) implemented:
 - type object-references
 - if-feature
 - unique
 - rpc
 
-Netconf
-=======
-Clixon Netconf implements the following NETCONF standards:
-- RFC 4741 (NETCONF Configuration Protocol)
-- RFC 4742 (Using the NETCONF Configuration Protocol over Secure SHell (SSH))
-- RFC 5277 (NETCONF Event Notifications)
 
-It needs to be updated to RFC6241 and RFC 6242. 
 
-Clixon NETCONF currently does not support the following Netconf features:
-
-- :url capability
-- copy-config source config
-- edit-config testopts 
-- edit-config erropts
-- edit-config config-text
-
-Restconf
-========
-### Features
-
-Clixon restconf is a daemon based on FASTCGI. Instructions are available to
-run with NGINX. 
-The implementatation supports plain OPTIONS, HEAD, GET, POST, PUT, PATCH, DELETE.
-and is based on draft-ietf-netconf-restconf-13. 
-There is currently (2017) a RFC 8040, many of those features are _not_ implemented,
-including:
-- query parameters (section 4.9)
-- notifications (sec 6)
-- only rudimentary error reporting exists (sec 7)
-
-### Installation using Nginx
-
-Define nginx config file/etc/nginx/sites-available/default
-```
-server {
-  ...
-  location /restconf {
-    root /usr/share/nginx/html/restconf;
-    fastcgi_pass unix:/www-data/fastcgi_restconf.sock;
-    include fastcgi_params;
-  }
-}
-```
-Start nginx daemon
-```
-sudo /etc/init.d nginx start
-```
-
-Start clixon restconf daemon
-```
-olof@vandal> sudo su -c "/www-data/clixon_restconf -f /usr/local/etc/routing.conf " -s /bin/sh www-data
-```
-
-Make restconf calls with curl
-```
-olof@vandal> curl -G http://127.0.0.1/restconf/data/interfaces
-[
-  {
-    "interfaces": {
-      "interface":[
-        {
-          "name": "eth0",
-          "type": "eth",
-          "enabled": "true",
-          "name": "eth9",
-          "type": "eth",
-          "enabled": "true"
-         }
-      ]
-    }
-  }
-]
-olof@vandal> curl -G http://127.0.0.1/restconf/data/interfaces/interface/name=eth9/type
-[
-  {
-    "type": "eth" 
-  }
-]
-
-curl -sX POST -d '{"clicon":{"interfaces":{"interface":{"name":"eth1","type":"eth","enabled":"true"}}}}' http://localhost/restconf/data
-```
-
-### Debugging
-
-Start the restconf fastcgi program with debug flag:
-```
-sudo su -c "/www-data/clixon_restconf -Df /usr/local/etc/routing.conf" -s /bin/sh www-
-data
-```
-Look at syslog:
-```
-tail -f /var/log/syslog | grep clixon_restconf
-```
-
-Send command:
-```
-curl -G http://127.0.0.1/restconf/data/*
-```

apps/netconf/README.md

@@ -1,17 +1,16 @@
 # Clixon Netconf
 
-Clixon netconf implements the following standards:
+Clixon Netconf implements the following NETCONF standards:
-- RFC 4741 (NETCONF Configuration Protocol), 
+- RFC 4741 (NETCONF Configuration Protocol)
-- RFC 4742 (Using the NETCONF Configuration Protocol over Secure SHell (SSH)) and 
+- RFC 4742 (Using the NETCONF Configuration Protocol over Secure SHell (SSH))
-- RFC 5277 (NETCONF Event Notifications).
+- RFC 5277 (NETCONF Event Notifications)
 
-It needs to be updated to RFC6241 and RFC 6242. It also does not implement the following features:
+It needs to be updated to RFC6241 and RFC 6242. 
+
+Clixon NETCONF currently does not support the following features:
 
 - :url capability
 - copy-config source config
 - edit-config testopts 
 - edit-config erropts
 - edit-config config-text
-
-
-

apps/restconf/README.md

@@ -1,11 +1,5 @@
 # Clixon Restconf
-
+### Features
-Contents:
-1. Features
-2. Installation using NGINX
-3. Debugging
-
-## 1. FEATURES
 
 Clixon restconf is a daemon based on FASTCGI. Instructions are available to
 run with NGINX. 
@@ -17,7 +11,7 @@ including:
 - notifications (sec 6)
 - only rudimentary error reporting exists (sec 7)
 
-## 2. INSTALLATION using NGINX
+### Installation using Nginx
 
 Define nginx config file/etc/nginx/sites-available/default
 ```
@@ -69,7 +63,7 @@ olof@vandal> curl -G http://127.0.0.1/restconf/data/interfaces/interface/name=et
 curl -sX POST -d '{"clicon":{"interfaces":{"interface":{"name":"eth1","type":"eth","enabled":"true"}}}}' http://localhost/restconf/data
 ```
 
-## DEBUGGING
+### Debugging
 
 Start the restconf fastcgi program with debug flag:
 ```

datastore/README.md

@@ -2,14 +2,17 @@
 
 The Clixon datastore is a stand-alone XML based datastore used by
 Clixon. The idea is to be able to use different datastores. There is
-currently a Key-value plugin based on qdbm and a plain text-file
+currently a key-value plugin based on qdbm and a plain text-file
 datastore.
 
 The datastore is primarily designed to be used by Clixon but can be used
-separately.  See datastore_client.c for an example of how to use a
+separately.  
-datastore plugin for other applications
 
-## The functional API
+A datastore is a dynamic plugin that is loaded at runtime with a
+well-defined API. This means it is possible to create your own
+datastore and plug it in a Clixon backend at runtime. 
+
+### The functional API
 ```
 int xmldb_plugin_load(clicon_handle h, char *filename);
 int xmldb_plugin_unload(clicon_handle h);
@@ -28,40 +31,62 @@ int xmldb_unlock_all(clicon_handle h, int pid);
 int xmldb_islocked(clicon_handle h, char *db);
 int xmldb_exists(clicon_handle h, char *db);
 int xmldb_delete(clicon_handle h, char *db);
-int xmldb_init(clicon_handle h, char *db);
+int xmldb_create(clicon_handle h, char *db);
 ```
 
-## Using the API
+### Using the API
 
-This section described how the API is used. Please refer to datastore/datastore_client.c for an example of an actual implementation.
-
-### Prerequisities
 To use the API, a client needs the following:
 - A clicon handle. 
 - A datastore plugin, such as a text.so or keyvalue.so. These are normally built and installed at Clixon make.
-- A directory where to store the datastores
+- A directory where to store databases
 - A yang specification. This needs to be parsed using the Clixon yang_parse() method.
 
-### Dynamics
+A client calling the API needs to (1)load a plugin and (2)connect to a
+datastore. You can connect to several datastores, even concurrently,
+but in practice in Clixon, you connect to a single store. 
 
-A client calling the API needs to load a plugin and connect to a
+After connecting to a datastore, you can create and modify databases
-datastore. In principle, you cannot connect to several datastores,
+within the datastore, and set and get options of the datastore itself.
-even concurrently, but in practice in Clixon, you connect to a single
-store.
 
-Within a datastore, there may be 
+When done, you disconnect from the datastore and unload the plugin.
+
+Within a datastore, the following four databases may exist:
+- running
+- candidate
+- startup
+- tmp
+
+Initially, a database does not exist but is created by
+xmldb_create(). It is deleted by xmldb_delete(). You may check for
+existence with xmldb_exists(). You need to create a database before
+you can perform any data access on it.
+
+You may lock a database for exclusive modification according to
+Netconf semantics. You may also unlock a single dabase, unlock all frm
+a specific session.
+
+You can read a database with xmldb_get() and modify a database with
+xmldb_put(), and xmldb_copy().
+
+A typical datastore session can be as follows, see the source code of
+datastore_client.c for a more elaborate example.
 
 ```
   h = clicon_handle_init();
   xmldb_plugin_load(h, plugin);
-```
+  xmldb_connect(h);
-The plugin is the complete path-name of a file.
+  xmldb_setopt(h, "dbdir", dbdir);
-
+  xmldb_setopt(h, "yangspec", yspec);
-Thereafter, a connection is made to a specific plugin, such as a text plugin. It is possible to connect to several datastore at once, although this is not supported by CLixon:
+  /* From here databases in the datastore may be accessed */
-```
+  xmldb_create(h, "candidate");
-xmldb_connect(h);
+  xmldb_copy(h, "running", "candidate");
-xmldb_setopt(h, "dbdir", dbdir);
+  xmldb_lock(h, "candidate", 7878);
-xmldb_setopt(h, "yangspec", yspec);
+  xmldb_put(h, "candidate", OP_CREATE, "/interfaces/interface=eth0", xml);
+  xmldb_unlock(h, "candidate");
+  xmldb_get(h, "candidate", "/", &xml, &xvec, &xlen);
+  xmldb_disconnect(h)
+  xmdlb_plugin_unload(h);
 ```
 
 

doc/Doxyfile

@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "CliXoN"
+PROJECT_NAME           = "clixon"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version

doc/Doxyfile.graphs

@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "CLICON"
+PROJECT_NAME           = "clixon"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version

doc/FAQ.md

@@ -1,112 +1,66 @@
-Frequently Asked Questions - CliXon
+# Clixon FAQ
-===================================
 
-Q: What is CliXon?
+## What is Clixon?
-------------------
-CliXon is a configuration management tool including CLI generation,
-Yang parser, netconf interface and an embedded databases.
 
-Q: Why should you use CliXon?
+Clixon is a configuration management tool including a generated CLI ,
------------------------------
+Yang parser, netconf and restconf interface and an embedded databases.
-If you want an easy-to-use config frontend based on yang with an open-source license.
-Typically for embedded devices requiring a config interface such as routers and switches.
 
-Q: What license is available?
+## Why should I use Clixon?
------------------------------
-The basic license is open-source, GPLv3. Contact authors for commercial license.
 
-Q: Is CliXon extendible?
+If you want an easy-to-use configuration frontend based on yang with an
-------------------------
+open-source license.  Typically for embedded devices requiring a
-Yes. All application semantics is defined in plugins with well-defined APIs. There are currently three types of plugins: for CLI, for Netconf and for the backend. 
+config interface such as routers and switches. 
 
-Q: Which language is CliXon implemented in?
+## What license is available?
--------------------------------------------
+CLIXON is dual license. Either Apache License, Version 2.0 or GNU
-CliXon is written in C. The plugins are written in C. The CLI
+General Public License Version 2. 
+
+## Is Clixon extendible?
+Yes. All application semantics is defined in plugins with well-defined
+APIs. There are currently plugins for: CLI, Netconf,  Restconf, the datastore and the backend.
+
+## Which programming language is used?
+Clixon is written in C. The plugins are written in C. The CLI
 specification uses cligen (http://cligen.se)
 
 There is a project for writing plugins in Python. It is reasonable
 simple to spawn an external script from a backend.
 
-Q: Is CliXon different from Clicon?
+## How to best understand Clixon?
------------------------------------
+Run the ietf yang routing example, in the example directory.
-CliXon is a fork of Clicon focussing on Yang specification and XML
-database.  The yang support in clicon was grown out of a key-based
-scheme that became more and more complex since it had to translate
-between many different formats. CliXon uses only XML internally.
 
-The commit transaction mechanism has been simplified too. But CliXon
+## How do you build and install Clixon (and the example)?
-is not backward compliant with key-based Clixon applications, such as
+Clixon: 
-Rost.
+```
-
-Q: How to best understand CliXon?
----------------------------------
-Run the ietf yang routing example. It is used in many of the answers below.
-
-Q: How do you build and install CliXon (and the example)?
----------------------------------------------------------
-CliXon: 
 	./configure; 
 	make; 
 	sudo make install; 
 	sudo make install-include
-
+```
 The example: 
+```
 	 cd example; 
 	 make; 
 	 sudo make install
+```
 
-Q: What about reference documentation?
+## What about reference documentation?
---------------------------------------
+Clixon uses Doxygen for reference documentation.
-CliXon uses Doxygen for reference documentation.
 Build using 'make doc' and aim your browser at doc/html/index.html or
 use the web resource: http://clicon.org/ref/index.html
 
-Q: How do you run the example?
+## How do you run the example?
-------------------------------
 - Start a backend server: 'clixon_backend -Ff /usr/local/etc/routing.conf'
 - Start a cli session: clixon_cli -f /usr/local/etc/routing.conf
 - Start a netconf session: clixon_netconf -f /usr/local/etc/routing.conf
 
-Q: Can you run CliXon as docker containers?
+## How is configuration data stored?
--------------------------------------------
+Configuration data is stored in an XML datastore. The default is a
-Yes, the example works as docker containers as well. backend and cli needs a 
+text-based addatastore, but there also exists a key-value datastore
-common file-system so they need to run as a composed pair.
+using qdbm. In the example the datastore are regular files found in
-	cd example/docker
+/usr/local/var/routing/.
-	make docker # Prepares /data as shared file-system mount
-	run.sh      # Starts an example backend and a cli
 
-The containers are by default downloaded from dockerhib, but you may
+## What is validate and commit?
-build the containers locally: 
-	cd docker
-	make docker
-
-You may also push the containers with 'make push' but you may then consider changing the image name in the makefile.
-
-Q: How do you change the example?
----------------------------------
-- routing.conf.local - Override default settings
-- The yang specifications - This is the central part. It changes the XML, database and the config cli.
-- routing_cli.cli - Change the fixed part of the CLI commands 
-- routing_cli.c - Cli C-commands are placed here.
-- routing_backend.c - Commit and validate functions.
-- routing_netconf.c - Modify semantics of netconf commands.
-
-
-Q: How do you check what is in a database?
-------------------------------------------
-Use clixon_dbctrl. The name of the running or candidate databases are found in the
-configuration file.
-Example:
-	> clixon_dbctrl -d /usr/local/var/routing/candidate_db / -p
-	/interfaces/interface/eth0/ipv4 
-	/interfaces/interface/eth0/type bgp
-	/interfaces/interface/eth0 
-	/interfaces/interface/eth0/name eth0
-Each line corresponds to a database entry (node in an XML tree). 
-If the node is a leaf, the value appears as the second entry ('bgp' and 'eth0').
-
-Q: What is validate and commit?
--------------------------------
 Clixon follows netconf in its validate and commit semantics.
 In short, you edit a 'candidate' configuration, which is first
 'validated' for consistency and then 'committed' to the 'running' 
@@ -116,59 +70,31 @@ A clixon developer writes commit functions to incrementaly upgrade a
 system state based on configuration changes. Writing commit callbacks
 is the core functionality of a clixon system.
 
-Q: How do you write a commit function?
+## What is a Clixon configuration file?
---------------------------------------
+Clixon options are stored in a configuration file you must specify
-You write a commit function in routing_backend.c.
+when you start a backend or client using -f. The example configuration
-Every time a commit is made, transaction_commit() is called in the
+file is /usr/local/etc/routing.conf.
-backend.  It has a 'transaction_data td' argument which is used to fetch
+This file is generated from the base source clixon.conf.cpp.cpp and
-information on added, deleted and changed entries. You access this
+is merged with local configuration files, such as routing.conf.local.
-information using access functions as defined in clixon_backend_transaction.h
+This is slightly confusing and could be improved.
 
-Q: How do you check what has changed on commit?
+## Can I run Clixon as docker containers?
------------------------------------------------
+Yes, the example works as docker containers as well. backend and cli needs a 
-You use XPATHs on the XML trees in the transaction commit callback.
+common file-system so they need to run as a composed pair.
-Suppose you want to print all added interfaces:
+```
-	cxobj *target = transaction_target(td); # wanted XML tree
+	cd example/docker
-	vec = xpath_vec_flag(target, "//interface", &len, XML_FLAG_ADD); /* Get added i/fs */
+	make docker # Prepares /data as shared file-system mount
-	for (i=0; i<len; i++)             /* Loop over added i/fs */
+	run.sh      # Starts an example backend and a cli
-	  clicon_xml2file(stdout, vec[i], 0, 1); /* Print the added interface */
+```
-You can look for added, deleted and changed entries in this way.
+The containers are by default downloaded from dockerhib, but you may
+build the containers locally: 
+```
+	cd docker
+	make docker
+```
+You may also push the containers with 'make push' but you may then consider changing the image name in the makefile.
 
-Q: How do I access the XML tree?
+## How do I use netconf?
---------------------------------
-Using XPATH, find and iteration functions defined in the XML library. Example library functions:
-      xml_child_each(), 
-      xml_find(), 
-      xml_body(), 
-      clicon_xml2file(), 
-      xml_apply()
-More are found in the doxygen reference.
-
-Q: How do you write a CLI callback function?
---------------------------------------------
-(1) You add an entry in routing_cli.cli
-   example("This is a comment") <var:int32>("This is a variable"), mycallback("myarg");
-(2) Then define a function in routing_cli.c
-   mycallback(clicon_handle h, cvec *cvv, cg_var *arg)
-where 'cvv' contains the value of the variable and 'arg' contains the
-function parameter 'myarg'.
-
-Q: What are cg_var and cvec used in CLI callbacks?
---------------------------------------------------
-Those are 'CLIgen variables' and vector of CLIgen variables. 
-They are documented in CLIgen documentation. Some examples on usage is found in the
-routing_cli.c
-
-Q: How do you write a validation function?
-------------------------------------------
-Similar to a commit function, but instead write the transaction_validate() function.
-Check for inconsistencies in the XML trees and if they fail, make an clicon_err() call.
-    clicon_err(OE_PLUGIN, 0, "Route %s lacks ipv4 addr", name);
-    return -1;
-The validation or commit will then be aborted.
-
-Q: How do you use netconf?
---------------------------
 
 As an alternative to cli configuration, you can use netconf. Easiest is to just pipe netconf commands to the clixon_netconf application.
 Example:
@@ -176,25 +102,81 @@ Example:
 
 However, more useful is to run clixon_netconf as an SSH
 subsystem. Register the subsystem in /etc/sshd_config:
-
+```
 	Subsystem netconf /usr/local/bin/clixon_netconf
-
+```
 and then invoke it from a client using
+```
 	ssh -s netconf <host>
+```
+
+## How do I use notifications?
 
-Q: How do you use notifications?
---------------------------------
 The example has a prebuilt notification stream called "ROUTING" that triggers every 10s.
 You enable the notification either via the cli or via netconf:
 cli> notify 
 cli> Routing notification
 Routing notification
-...
+```
-
+clixon_netconf -qf /usr/local/etc/routing.conf 
-> clixon_netconf -qf /usr/local/etc/routing.conf 
 <rpc><create-subscription><stream>ROUTING</stream></create-subscription></rpc>]]>]]>
 <rpc-reply><ok/></rpc-reply>]]>]]>
 <notification><event>Routing notification</event></notification>]]>]]>
 <notification><event>Routing notification</event></notification>]]>]]>
 ...
 
+## I want to program. How do I extend the example?
+- routing.conf.local - Override default settings
+- The yang specifications - This is the central part. It changes the XML, database and the config cli.
+- routing_cli.cli - Change the fixed part of the CLI commands 
+- routing_cli.c - Cli C-commands are placed here.
+- routing_backend.c - Commit and validate functions.
+- routing_netconf.c - Modify semantics of netconf commands.
+
+## How do I write a commit function?
+You write a commit function in routing_backend.c.
+Every time a commit is made, transaction_commit() is called in the
+backend.  It has a 'transaction_data td' argument which is used to fetch
+information on added, deleted and changed entries. You access this
+information using access functions as defined in clixon_backend_transaction.h
+
+## How do i check what has changed on commit?
+You use XPATHs on the XML trees in the transaction commit callback.
+Suppose you want to print all added interfaces:
+```
+	cxobj *target = transaction_target(td); # wanted XML tree
+	vec = xpath_vec_flag(target, "//interface", &len, XML_FLAG_ADD); /* Get added i/fs */
+	for (i=0; i<len; i++)             /* Loop over added i/fs */
+	  clicon_xml2file(stdout, vec[i], 0, 1); /* Print the added interface */
+```
+You can look for added, deleted and changed entries in this way.
+
+## How do I access the XML tree?
+Using XPATH, find and iteration functions defined in the XML library. Example library functions:
+```
+      xml_child_each(), 
+      xml_find(), 
+      xml_body(), 
+      xml_print(), 
+      xml_apply()
+```
+More are found in the doxygen reference.
+
+## How do I write a CLI callback function?
+
+1. You add an entry in routing_cli.cli
+>   example("This is a comment") <var:int32>("This is a variable"), mycallback("myarg");
+2. Then define a function in routing_cli.c
+>   mycallback(clicon_handle h, cvec *cvv, cvec *arv)
+where 'cvv' contains the value of the variable 'var' and 'argv' contains the string "myarg".
+
+The 'cvv' datatype is a 'CLIgen variable vector'.
+They are documented in [CLIgen tutorial](https://github.com/olofhagsand/cligen/blob/master/cligen_tutorial.pdf)
+
+## How do I write a validation function?
+Similar to a commit function, but instead write the transaction_validate() function.
+Check for inconsistencies in the XML trees and if they fail, make an clicon_err() call.
+    clicon_err(OE_PLUGIN, 0, "Route %s lacks ipv4 addr", name);
+    return -1;
+The validation or commit will then be aborted.
+

example/README.md

@@ -1,16 +1,21 @@
 # Clixon yang routing example
 
-
 ## Compile and run
 ```
-cd example
+    cd example
-make && sudo make install
+    make && sudo make install
-# Start backend
+```
-clixon_backend -f /usr/local/etc/routing.conf -I
+Start backend:
-# Edit cli
+```
-clixon_cli -f /usr/local/etc/routing.conf
+    clixon_backend -f /usr/local/etc/routing.conf -I
-# Send netconf command
+```
-clixon_netconf -f /usr/local/etc/routing.conf
+Edit cli:
+```
+    clixon_cli -f /usr/local/etc/routing.conf
+```
+Send netconf command:
+```
+    clixon_netconf -f /usr/local/etc/routing.conf
 ```
 
 ## Setting data example using netconf
@@ -34,15 +39,10 @@ clixon_netconf -f /usr/local/etc/routing.conf
 ## Getting data using netconf
 ```
 <rpc><get-config><source><candidate/></source></get-config></rpc>]]>]]>
-
 <rpc><get-config><source><candidate/></source><filter/></get-config></rpc>]]>]]>
-
 <rpc><get-config><source><candidate/></source><filter type="xpath"/></get-config></rpc>]]>]]>
-
 <rpc><get-config><source><candidate/></source><filter type="subtree"><configuration><interfaces><interface><ipv4/></interface></interfaces></configuration></filter></get-config></rpc>]]>]]>
-
 <rpc><get-config><source><candidate/></source><filter type="xpath" select="/interfaces/interface/ipv4"/></get-config></rpc>]]>]]>
-
 <rpc><validate><source><candidate/></source></validate></rpc>]]>]]>
 ```
 

test/README.md

@@ -1,4 +1,4 @@
-# CLixon tests
+# Clixon tests
 
 This directory contains testing code for clixon and the example
 routing application: