From b99ce2c499d8949b649fecbdec690b908fbc8f67 Mon Sep 17 00:00:00 2001 From: Olof hagsand Date: Sun, 7 May 2017 18:11:20 +0200 Subject: [PATCH] docs --- README.md | 233 +++++------------------------------ apps/netconf/README.md | 15 ++- apps/restconf/README.md | 12 +- datastore/README.md | 73 +++++++---- doc/Doxyfile | 2 +- doc/Doxyfile.graphs | 2 +- doc/FAQ.md | 260 +++++++++++++++++++--------------------- example/README.md | 28 ++--- test/README.md | 2 +- 9 files changed, 224 insertions(+), 403 deletions(-) diff --git a/README.md b/README.md index afc3f14d..b199f554 100644 --- a/README.md +++ b/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,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/* -``` diff --git a/apps/netconf/README.md b/apps/netconf/README.md index 3878aa56..4cd5f454 100644 --- a/apps/netconf/README.md +++ b/apps/netconf/README.md @@ -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 - - - diff --git a/apps/restconf/README.md b/apps/restconf/README.md index 36916db1..cedf819f 100644 --- a/apps/restconf/README.md +++ b/apps/restconf/README.md @@ -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: ``` diff --git a/datastore/README.md b/datastore/README.md index f9baa58b..774e3a92 100644 --- a/datastore/README.md +++ b/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 -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); ``` diff --git a/doc/Doxyfile b/doc/Doxyfile index f18d01f3..98375856 100644 --- a/doc/Doxyfile +++ b/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 diff --git a/doc/Doxyfile.graphs b/doc/Doxyfile.graphs index 7a115a20..03ca9505 100644 --- a/doc/Doxyfile.graphs +++ b/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 diff --git a/doc/FAQ.md b/doc/FAQ.md index 79c38315..f11b497d 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -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("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 +``` + +## 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 ROUTING]]>]]> ]]>]]> Routing notification]]>]]> Routing 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 example("This is a comment") ("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. + diff --git a/example/README.md b/example/README.md index b03e4cf5..8c325b60 100644 --- a/example/README.md +++ b/example/README.md @@ -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 ``` ]]>]]> - ]]>]]> - ]]>]]> - ]]>]]> - ]]>]]> - ]]>]]> ``` diff --git a/test/README.md b/test/README.md index 4c13fdd1..2267552d 100644 --- a/test/README.md +++ b/test/README.md @@ -1,4 +1,4 @@ -# CLixon tests +# Clixon tests This directory contains testing code for clixon and the example routing application: