experiments/clixon
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs

Browse source
This commit is contained in:
Olof hagsand 2017-05-07 18:11:20 +02:00
parent a18f66b6d0
commit b99ce2c499
9 changed files with 224 additions and 403 deletions
Download patch file Download diff file Expand all files Collapse all files

233
README.md
View file

@ -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,16 +14,13 @@ Table of contents
* [Dependencies](#dependencies)
* [Licenses](#licenses)
* [History](#history)
* [Datastore](#datastore)
* [Yang](#yang)
* [Netconf](#netconf)
* [Restconf](#restconf)
Installation
============
A typical installation is as follows:
```
configure # Configure clixon to platform
configure # Configure clixon to platform
make # Compile
sudo make install # Install libs, binaries, and config-files
sudo make install-include # Install include files (for compiling)
@ -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
=======
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.
Background
==========
Clixon origins from work at [KTH](http://www.csc.kth.se/~olofh/10G_OSR)
Datastore
=========
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
datastore.
The datastore is primarily designed to be used by Clixon but can be used
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);
```
We implemented Clixon since we needed a generic configuration tool in
several projects, including
[KTH](http://www.csc.kth.se/~olofh/10G_OSR). Most of these projects
were for embedded network and measuring-probe devices. We started with
something called Clicon which was based on a key-value specification
and data-store. But as time passed new standards evaolved and we
started adapting it to XML, Yang and netconf. Finally we made Clixon
where the legacy key specification has been replaced completely by
YANG and using XML as configuration data. This means that legacy
Clicon applications do not run on Clixon.
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/*
```

15
apps/netconf/README.md
View file

@ -1,17 +1,16 @@
# Clixon Netconf
Clixon netconf implements the following standards:
- RFC 4741 (NETCONF Configuration Protocol),
- RFC 4742 (Using the NETCONF Configuration Protocol over Secure SHell (SSH)) and
- RFC 5277 (NETCONF Event Notifications).
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. 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

12
apps/restconf/README.md
View file

@ -1,11 +1,5 @@
# Clixon Restconf
Contents:
1. Features
2. Installation using NGINX
3. Debugging
## 1. FEATURES
### 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:
```

73
datastore/README.md
View file

@ -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
datastore plugin for other applications
separately.
## 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
datastore. In principle, you cannot 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.
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);
```
The plugin is the complete path-name of a file.
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:
```
xmldb_connect(h);
xmldb_setopt(h, "dbdir", dbdir);
xmldb_setopt(h, "yangspec", yspec);
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);
```

2
doc/Doxyfile
View file

@ -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

2
doc/Doxyfile.graphs
View file

@ -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

260
doc/FAQ.md
View file

@ -1,112 +1,66 @@
Frequently Asked Questions - CliXon
===================================
# Clixon FAQ
Q: What is CliXon?
------------------
CliXon is a configuration management tool including CLI generation,
Yang parser, netconf interface and an embedded databases.
## What is Clixon?
Q: Why should you use CliXon?
-----------------------------
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.
Clixon is a configuration management tool including a generated CLI ,
Yang parser, netconf and restconf interface and an embedded databases.
Q: What license is available?
-----------------------------
The basic license is open-source, GPLv3. Contact authors for commercial license.
## Why should I use Clixon?
Q: Is CliXon extendible?
------------------------
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.
If you want an easy-to-use configuration frontend based on yang with an
open-source license. Typically for embedded devices requiring a
config interface such as routers and switches.
Q: Which language is CliXon implemented in?
-------------------------------------------
CliXon is written in C. The plugins are written in C. The CLI
## What license is available?
CLIXON is dual license. Either Apache License, Version 2.0 or GNU
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?
-----------------------------------
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.
## How to best understand Clixon?
Run the ietf yang routing example, in the example directory.
The commit transaction mechanism has been simplified too. But CliXon
is not backward compliant with key-based Clixon applications, such as
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:
## 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?
--------------------------------------
CliXon uses Doxygen for reference documentation.
## What about 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?
-------------------------------------------
Yes, the example works as docker containers as well. backend and cli needs a
common file-system so they need to run as a composed pair.
cd example/docker
make docker # Prepares /data as shared file-system mount
run.sh # Starts an example backend and a cli
## How is configuration data stored?
Configuration data is stored in an XML datastore. The default is a
text-based addatastore, but there also exists a key-value datastore
using qdbm. In the example the datastore are regular files found in
/usr/local/var/routing/.
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 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?
-------------------------------
## 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?
--------------------------------------
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
## What is a Clixon configuration file?
Clixon options are stored in a configuration file you must specify
when you start a backend or client using -f. The example configuration
file is /usr/local/etc/routing.conf.
This file is generated from the base source clixon.conf.cpp.cpp and
is merged with local configuration files, such as routing.conf.local.
This is slightly confusing and could be improved.
Q: How do you 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.
## Can I run Clixon as docker containers?
Yes, the example works as docker containers as well. backend and cli needs a
common file-system so they need to run as a composed pair.
```
cd example/docker
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
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?
--------------------------------
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?
--------------------------
## How do I 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.

28
example/README.md
View file

@ -1,16 +1,21 @@
# Clixon yang routing example
## Compile and run
```
cd example
make && sudo make install
# Start backend
clixon_backend -f /usr/local/etc/routing.conf -I
# Edit cli
clixon_cli -f /usr/local/etc/routing.conf
# Send netconf command
clixon_netconf -f /usr/local/etc/routing.conf
cd example
make && sudo make install
```
Start backend:
```
clixon_backend -f /usr/local/etc/routing.conf -I
```
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>]]>]]>
```

2
test/README.md
View file

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