Clixon

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

Table of contents

• Table of contents
• Installation
• Documentation
• Dependencies
• Licenses
• History
• Datastore
• Yang
• Netconf
• Restconf

Installation

A typical installation is as follows:

     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)

One example applications is provided, a IETF IP YANG datamodel with generated CLI and configuration interface.

Documentation

• Frequently asked questions
• Reference manual (Better: cd doc; make doc)
• Routing example
• Test

Dependencies

Clixon is dependend on the following packages

• CLIgen is required for building CLIXON. If you need to build and install CLIgen:

    git clone https://github.com/olofhagsand/cligen.git
    cd cligen; configure; make; make install

• Yacc/bison
• Lex/Flex
• Fcgi (if restconf is enabled)
• Qdbm key-value store (if keyvalue datastore is enabled)

Licenses

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.

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.

Clixon origins from work at KTH

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);

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:

• 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/*