.. _controller_install: .. sectnum:: :start: 2 :depth: 3 ************ Installation ************ 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 Source ====== Check out the following GIT repos: - ``_ - ``_ - ``_ - ``_ Building ======== The source is built as follows. Add the clicon user and group ----------------------------- :: sudo useradd clicon -N sudo groupadd clicon sudo usermod -a -G clicon `whoami` Cligen ------ :: cd cligen ./configure make sudo make install Clixon ------ :: cd clixon ./configure make sudo make install 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 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. 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 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 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 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 ....]]>]]> 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) 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 ` and removed with `dpkg -r `. 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 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. 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. 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