XiVO confgend developer’s guide

xivo-confgend uses drivers to implement the logic required to generate configuration files. It uses stevedore to do the driver instantiation and discovery.

Plugins in xivo-confgend use setuptools’ entry points. That means that installing a new plugin to xivo-confgend requires an entry point in the plugin’s setup.py.

Drivers

Driver plugin are classes that are used to generate the content of a configuration file.

The implementation of a plugin should have the following properties.

  1. It’s __init__ method should take one argument

  2. It should have a generate method which will return the content of the file

  3. A setup.py adding an entry point

The __init__ method argument is the content of the configuration of xivo-confgend. This allows the driver implementor to add values to the configuration in /etc/xivo-confgend/conf.d/*.yml and these values will be available in the driver.

The generate method has no argument, the configuration provided to the __init__ should be sufficient for most cases. generate is called within a scoped_session of xivo-dao, allowing the usage of xivo-dao without prior setup in the driver.

The namespaces used for entry points in xivo-confgend have the following form:

xivo_confgend.<resource>.<filename>

as an example, a generator for sip.conf would have the following namespace:

xivo_confgend.asterisk.sip.conf

Example

Here is a typical setup.py:

 1#!/usr/bin/env python
 2# -*- coding: utf-8 -*-
 3# Copyright 2016 by Avencall
 4# SPDX-License-Identifier: GPL-3.0+
 5
 6from setuptools import setup
 7from setuptools import find_packages
 8
 9
10setup(
11    name='XiVO confgend driversample',
12    version='0.0.1',
13
14    description='An example driver',
15
16    packages=find_packages(),
17
18    entry_points={
19        'xivo_confgend.asterisk.sip.conf': [
20            'my_driver = src.driver:MyDriver',
21        ],
22    }
23)

With the following package structure:

.
├── setup.py
└── src
    └── driver.py

driver.py:

 1# -*- coding: utf-8 -*-
 2# Copyright 2016 by Avencall
 3# SPDX-License-Identifier: GPL-3.0+
 4
 5
 6class MyDriver(object):
 7
 8    def __init__(self, config):
 9        self._config = config
10
11    def generate(self):
12        return 'Hello World!'

To enable this plugin, you need to:

  1. Install the plugin with:

    python setup.py install

  2. Create a config file in /etc/xivo-confgend/conf.d:

    plugins:
  asterisk.sip.conf: my_driver

  3. Restart xivo-confgend:

    systemctl restart xivo-confgend