docs
This commit is contained in:
Olof hagsand
parent
a18f66b6d0
commit
b99ce2c499
9 changed files with 224 additions and 403 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
260
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<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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue