7.9 KiB
Frequently Asked Questions - CliXon
Q: 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?
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?
The basic license is open-source, GPLv3. Contact authors for commercial license.
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.
Q: Which language is CliXon implemented in?
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.
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: ./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. 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?
- 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
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?
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' configuration.
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
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.
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?
As an alternative to cli configuration, you can use netconf. Easiest is to just pipe netconf commands to the clixon_netconf application. Example: echo "]]>]]>" | clixon_netconf -f /usr/local/etc/routing.conf
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
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 ROUTING]]>]]> ]]>]]> Routing notification]]>]]> Routing notification]]>]]> ...