2 Installation

2.1 Packages

Some packages are required. The following are example of debian-based packages:

sudo apt install flex bison git make gcc libnghttp2-dev libssl-dev

2.2 Source

Check out the following GIT repos:

• https://github.com/clicon/cligen.git/

• https://github.com/clicon/clixon.git/

• https://github.com/clicon/clixon-controller.git/

• https://github.com/clicon/clixon-pyapi.git/

2.3 Building

The source is built as follows.

2.3.1 Add the clicon user and group

sudo useradd clicon -N
sudo groupadd clicon
sudo usermod -a -G clicon `whoami`

2.3.2 Cligen

cd cligen
./configure
make
sudo make install

2.3.3 Clixon

cd clixon
./configure
make
sudo make install

2.3.4 Python API

Either use PIP or Debian packages.

PIP:

cd clixon-pyapi
sudo -u clicon pip3 install -r requirements.txt
sudo python3 setup.py install

Debian:

cd clixon-pyapi
sudo ./requirements-apt.sh
sudo python3 setup.py install

2.3.5 Controller

cd clixon-controller
./configure
make
sudo make install

To make the controller the default clixon application:

(cd /usr/local/etc/clixon; ln -s /usr/local/etc/clixon/controller.xml clixon.xml)

It is recommended to NOT run the controller as root.

2.3.6 SystemD

In the clixon-controller source folder there is a file named clixon-controller.service which can be used to run the Controller backend using SystemD.

To install the SystemD service either copy the file manually:

cp clixon-controller.service /usr/lib/systemd/system/

Or use the Makefile and run “sudo make systemd” to copy the file to /usr/lib/systemd/system/.

$ sudo make systemd
/usr/bin/install -c clixon-controller.service /usr/lib/systemd/system/
Systemd service installed, run systemctl enable clixon-controller.service to enable it

After copying the file, run the following commands to enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable clixon-controller.service
sudo systemctl start clixon-controller.service
sudo systemctl status clixon-controller.service

2.4 Configure options

The Controller configure script (generated by autoconf) includes several options apart from the standard ones.

These include (standard options are omitted)

--enable-debug

Build with debug symbols, default: no

--with-cligen=dir

Use CLIGEN here

--with-clixon=dir

Use Clixon here

--with-clicon-user=user

Run as this user in example and test

--with-clicon-group=group

Run as this group in example and test

2.5 Python install

Install the python code by copy:

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

Add a new clicon user and install the needed Python packages, the backend will start the Python server and drop the privileges to this user:

sudo useradd -g clicon -m clicon

2.6 Devices

The controller needs to be able to connect to devices via a NETCONF SSH sub-system.

Note

Devices must be reachable from the controller via a NETCONF SSH subsystem

Setting up he SSH subsystem is different for different device vendors.

When done, you can verify reachability as follows. Example: You login and start the controller as user ctrl, the device user is admin and the IP address is 172.17.0.3.

Verify the SSH subsystem works as follows:

ctrl> ssh admin@172.17.0.3 -s netconf
<?xml version="1.0" encoding="UTF-8"?>
<hello>....</hello>]]>]]>

2.7 Install script

# Do a fresh installation of Clixon controller on a Debian based system.

# Install the required packages
sudo apt update
sudo apt install -y flex bison git make gcc libnghttp2-dev libssl-dev

# Clone the repositories
git clone https://github.com/clicon/cligen.git
git clone https://github.com/clicon/clixon.git
git clone https://github.com/clicon/clixon-controller.git
git clone https://github.com/clicon/clixon-pyapi.git

# Add the clicon user
sudo useradd clicon -N
sudo groupadd clicon
sudo usermod -a -G clicon `whoami`

# Build and install cligen
(cd cligen && ./configure && make && sudo make install; ldconfig)

# Build and install clixon
(cd clixon && ./configure && make && sudo make install; ldconfig)

# Build and install clixon-controller
(cd clixon-controller && ./configure && make && sudo make install; ldconfig)

2.8 Building Debian packages

For each of the components (Cligen, Clixon, Clixon-controller and Clixon-pyapi) you can build Debian packages with the script build_deb.sh in the scripts/ directory.

The script will create a Debian package in the source directory and should be invoked from the source directory:

$ cd clixon-controller
$ ./scripts/build_deb.sh
...
$ ls *.deb
clixon-controller_1.2.0-1_amd64.deb

The package can be installed with dpkg -i <package> and removed with dpkg -r <package>.

2.9 Directory structure

In a typical installation, the main configuration file is in $SYSCONFIG/clixon/controller.xml (typically: usr/local/share/clixon/controller.xml). All other directories are declared in this configure file.

Extra config files loaded after the main in alphabetical order are placed in the $SYSCONFIG/clixon/controller/ directory. This is useful for adding and overriding the default config.

The directory structure is as follows:

${SYSCONFIG} (/usr/local/etc)
└── clixon
    ├── controller.xml
    └── clixon

${DATADIR}  (/usr/local/share)
├── clixon
└── controller
    ├── common
    │   ├── control
    │   │   └── clixon-controller-config.yang
    │   └── extensions
    ├── main
    │   ├── clixon-controller.yang
    │   └── ssh-users.yang
    ├── modules
    │   ├── __pycache__
    │   └── ssh_users.py
    └── mounts
        ├── default
        └── openconfig

${BINDIR} (/usr/local/bin)
├── clixon_cli
├── clixon_netconf
└── clixon_server.py

${SBINDIR} (/usr/local/sbin)
├── clixon_backend
└── clixon_restconf

${LIBDIR} (/usr/local/lib)
└── controller
    ├── backend
    │   └── controller_backend.so
    ├── cli
    │   └── controller_cli.so
    └── clispec
        ├── controller_configure.cli
        ├── controller_operation.cli
        └── controller_pipe.cli

${LOCALSTATEDIR} (/usr/local/var)
└── controller
    ├── candidate.d
    ├── running.d
    └── startup.dp

${RUNSTATEDIR} (/usr/local/var/run)
└── controller
    ├── controller.pid
    └── controller.sock

2.10 Running without root privileges

The controller can be run without root privileges. This is recommended for security reasons. There are two different scenarios other than the default:

• Install the controller as root and run it as a non-root user.

• Install the controller as a non-root user and run it as that user.

In both scenarios the users SSH keys must be installed in the devices to be managed by the controller.

2.10.1 Install the controller as root and run it as a non-root user

Scenario: You install the controller as root but start the backend as the user ‘user1’, ‘user2’ will then start a CLI which connects to the backend.

1. Install the controller as root (see above).

2. Create a user and group for the controller to run as. This is done in the example above.

3. Add the user who should run the CLI to the same group as the user who runs the backend.

4. Generate SSH keys for the user who runs the backend and copy them to the devices to be managed.

5. Modify the controller configuration file (controller.xml):

• Set CLICON_BACKEND_USER to the user who runs the backend.

• Set CLICON_SOCK to a path which is writable by the user who runs the backend.

• Set CLICON_SOCK_GROUP to the group of the user who runs the backend.

• Set CLICON_XMLDB_DIR a directory which is writable by the user who runs the backend.

• Set CONTROLLER_ACTION_COMMAND and the “-f” flag to the configuration file used here.

6. Start the backend as the user who runs the backend.

2.10.2 Install the controller as a non-root user and run it as that user

Scenario: You install the controller as a non-root user and run it as that user.

This requires the user to build Clixon controller with the –prefix flag set to a directory which is writable by the user. In this example we use a directory in the home directory of the user.

1. Create a directory in the home directory of the user who will run the controller (or in another directory which is writable by the user). Example: /home/user1/clixon.

2. For each of cligen, clixon and clixon-controller do the following:

   ./configure --prefix=/home/user1/clixon --install-scripts=/home/user1/clixon/bin/
   make
   make install
   

3. For the Python API (clixon-pyapi) do python3 setup.py install --prefix=/home/user1/clixon. This will install the Python API in /home/user1/clixon/lib/python3.x/site-packages.

4. You should be able to run the controller as the user who installed it. The controller will use the directories in /home/user1/clixon:

   $ /home/user1/clixon/sbin/clixon_backend -f /home/user1/clixon/etc/clixon/controller.xml