12 Python API

This section documents the Clixon Python API. The Python API is a stand-alone client which uses the internal Netconf protocol to the Clixon backend. The primary application is the clixon-server and its network services.

12.1 Overview

The Clixon Python API consist of two parts:

  • The server (clixon_server.py).

  • Service modules.

The server listens for events from the Clixon backend and run the modules when needed. All service logic are implemented in the modules and are described in detail below.

12.2 Overview

The Python API connect to Clixons internal socket and communicate over NETCONF. When started it registers for notifications of service commits and controller transactions.

Whenever a commit occurs, the Clixon Controller issues a notification the Python API listens to.

When the Python API receives a service commit it runs all the service modules which manipulates the configuration tree. When finished, the configuration is sent back to the Clixon backend.

In summary:

  1. The user configures a service from the CLI.

  2. The user commits the service.

  3. Pyapi receives a <services-commit> notification.

  4. Pyapi executes all service modules that may modify the configuration (device) tree.

  5. For each modification, an <edit-config> message is sent to the backend.

  6. When completed, pyapi sends <transaction-actions-done> to the backend.

  7. If pyapi encounters an error, it aborts by sending <transaction-error> to the backend instead.

  8. The new configuration is pushed to the devices by the backend.

12.3 Installation

12.3.1 Prerequisites

Installation of Cligen and Clixon is not covered in this section. The Clixon controller must be up and running before the Python API can be used.

It is expected that Python, Pip etc are installed on the system.

12.3.2 Installation

Python API is available on GitHub:

$ git clone https://github.com/clicon/clixon-pyapi.git

Once cloned, the requirementes are installed:

$ cd clixon-pyapi
$ pip3 install -r requirements.txt

And then the Clixon pyapi library is installed:

$ sudo python3 setup.py install

The server is installed manually, for example:

$ sudo cp clixon_server.py /usr/local/bin/

The install script install.sh performs the two steps above.

12.4 Usage

12.4.1 Command line options

The Python API server has the following command line options:

$ python3 clixon_server.py -h

 clixon_server.py -f<module1,module2> -s<path> -d -p<pidfile>
     -f       Clixon controller configuration file
     -m       Modules path
     -e       Comma separate list of modules to exclude
     -d       Enable verbose debug logging
     -s       Clixon socket path
     -p       Pidfile for Python server
     -F       Run in foreground
     -P       Prettyprint XML
     -l       <s|o> Log on (s)yslog, std(o)ut
     -h       This!

12.4.2 Logging and debugging

The server can be run in the foreground with debug flags:

clixon_server.py -F -d -P -f /usr/local/etc/controller.xml

Just make sure to stop the API server from controller CLI before doing so, we don’t support two servers running in parallell:

> processes services stop

When running the server in foreground it is possible to set breakpoints etc and print log messages using the log object which is passed as an argument to setup().

It is also possible to use the Python REPL to interact with the API:

$ python3
>>> from clixon.clixon import Clixon
>>> cx = Clixon(source="running")
>>> root = cx.get_root()
>>> root.<TAB>

Above we retrieved the running configuration and can tab-complete the object tree.

12.4.3 Startup

Pyapi needs to know where the python code for the service model is located. This can be modified with the ‘-m’ flag:

python3 ./clixon_server.py -f /usr/local/etc/controller.xml

which makes the server run in the background with minimal logging.

12.5 NACM

The Python API server can be run with NACM enabled in the backend and will use either the CLI user or the RESTCONF user for authentication.

Whenever a commit happens the Python API server will fetch the transaction details for the commit and get the username of the user that made the commit. The API server will then use that username when doing a get-config, edit-config etc.

In sequence

  1. User configures a service from the CLI.

  2. User commits the service.

  3. Pyapi receives a <services-commit> notification.

  4. Pyapi fetches the transaction details from the backend.

  5. Pyapi gets the username of the user that made the commit.

  6. Pyapi uses the username to do a get-config as the user.

  7. Pyapi sends the modified configuration back to the backend (edit-config) as the user.

  8. If pyapi encounters an error, it aborts by sending <transaction-error> to the backend instead.

  9. The new configuration is eventually pushed to the devices by the backend.