Configuration Framework

These files are the main template files that will be used to generate the final configuration file for the running service. They contain all the configuration options needed for a running Sipwise C5 system. The configuration framework will combine these files with the values provided by config.yml, constants.yml and network.yml to generate the appropriate configuration file.

Example: Let’s say we are changing the IP used by kamailio load balancer on interface eth0 to IP 1.2.3.4. This will change kamailio’s listen IP address, when the configuration file is generated. A quick look to the template file under /etc/ngcp-config/templates/etc/kamailio/lb/kamailio.cfg.tt2 will show a line like this:

After applying the changes with the ngcpcfg apply 'my commit message' command, a new configuration file will be created under /etc/kamailio/lb/kamailio.cfg with the proper values taken from the main configuration files (in this case network.yml):

All the low-level configuration is provided by these .tt2 template files and the corresponding config.yml file. Anyway, advanced users might require a more particular configuration.

Instead of editing .tt2 files, the configuration framework recognises .customtt.tt2 files. These files are the same as .tt2, but they have higher priority when the configuration framework creates the final configuration files. If you need to introduce changes in a template, you must always copy the required .tt2 file to .customtt.tt2, make changes in the latter file one and leave the .tt2 file untouched. This way, the system will use the new custom configuration allowing you to switch back to the original one quickly.

Example: We’ll create /etc/ngcp-config/templates/etc/lb/kamailio.cfg.customtt.tt2 and use it for our customized configuration. In this example, we’ll append a comment at the end of the template.

The ngcpcfg command will generate /etc/kamailio/lb/kamailio.cfg from our custom template instead of the general one:

The huge drawback of .customtt.tt2 files are necessity to keep them up-to-date manually. Keeping them outdated will cause the system misbehaviour as different components will use different code version (as new .tt2 version will be overwritten by old .customtt.tt2).

The .patchtt.tt2 concept should help users here. It will minimise the manual efforts by using linux "patch" utility. The ngcpcfg tool is searching for .patchtt.tt2 files every time 'ngcpcfg build' has been called. If .patchtt.tt2 is detected, the ngcpcfg tool will try to apply .patchtt.tt2 on .tt2 and store result in .customtt.tt2 if no conflicts noticed during patching. Further building process happens in a common way. Example:

To convert some/all the current .customtt.tt2 users can use command ngcpcfg patch --from-customtt [<customtt_file>]:

Here is the example of newly created .patchtt.tt2 file:

See more details about .patchtt.tt2 files below in patchtt section.

Keeping custom modifications directly in the .customtt.tt2 templates is NOT recommended as templates become outdated with every software upgrade.

A better way is to handle custom modifications using .patchtt.tt2 files (e.g. /etc/ngcp-config/templates/etc/cron.d/cleanup-tools.patchtt.tt2). In this case, on every "ngcpcfg patch", a .patchtt.tt2 file will be applied on top of the .tt2 file and the result will be saved into the customtt file and used commonly as described in the previous section. "ngcpcfg patch" is the first step on "ngcpcfg build" that guarantees the latest upstream templates with the availability of the necessary local changes on every configuration apply.

After creating the configuration files, the configuration framework can execute some commands before and after placing that file in its target directory. These commands usually are used for changing the file’s owner, groups, or any other attributes. There are some rules these commands need to match:

Example: We need www-data as owner of the configuration file /etc/ngcp-ossbss/provisioning.conf. The configuration framework will by default create the configuration files with root:root as owner:group and with the same permissions (rwx) as the original template. For this particular example, we will change the owner of the generated file using the .postbuild mechanism.

.services files are pretty similar and might contain commands that will be executed after the build process. There are two types of .services files:

When the services step is triggered all .services files associated to a changed configuration file will be executed. In case of the general file, any change to any of the configuration files in the directory will trigger the execution of the commands.

These commands are usually service reload/restarts to ensure the new configuration has been loaded by running services.

Example:

In this example we created two .services files. Now, each time we trigger a change to /etc/mysql.my.cnf or to /etc/asterisk/* we’ll see that MySQL or Asterisk services will be restarted by the ngcpcfg system.

The apply option is a short-cut for the options "check && build && services && commit" and also executes etckeeper to record any modified files inside /etc. It is the recommended option to use the ngcpcfg framework unless you want to execute any specific commands as documented below.

The build option generates (and therefore also updates) configuration files based on their configuration (config.yml) and template files (.tt2). Before the configuration file is generated a present .prebuild will be executed, after generation of the configuration file the according .postbuild script (if present) will be executed. If a file or directory is specified as argument the build will generate only the specified configuration file/directory instead of running through all present templates.

Example: to generate only the file /etc/nginx/sites-available/ngcp-panel you can execute:

Example: to generate all the files located inside the directory /etc/nginx/ you can execute:

The commit option records any changes done to the configuration tree inside /etc/ngcp-config. The commit option should be executed when you’ve modified anything inside the configuration tree.

Decrypt /etc/ngcp-config-crypted.tgz.gpg and restore configuration files, doing the reverse operation of the encrypt option. Note: This feature is only available if the ngcp-ngcpcfg-locker package is installed.

Show uncommitted changes between ngcpcfg’s Git repository and the working tree inside /etc/ngcp-config. Iff the tool doesn’t report anything it means that there are no uncommitted changes. If the --addremove option is specified then new and removed files (iff present) that are not yet (un)registered to the repository will be reported, no further diff actions will be executed then. Note: This option is available since ngcp-ngcpcfg version 0.11.0.

Encrypt /etc/ngcp-config and all resulting configuration files with a user defined password and save the result as /etc/ngcp-config-crypted.tgz.gpg. Note: This feature is only available if the ngcp-ngcpcfg-locker package is installed.

The help options displays ngcpcfg’s help screen and then exits without any further actions.

The initialise option sets up the ngcpcfg framework. This option is automatically executed by the installer for you, so you shouldn’t have to use this option in normal operations mode.

The services option executes the service handlers for any modified configuration file(s)/directory.

The status option provides a human readable interface to check the state of the configuration tree. If you are unsure what should be done as next step or if want to check the current state of the configuration tree, invoke ngcpcfg status.

If everything is OK and nothing needs to be done the output should look like:

If the output doesn’t say "OK", follow the instructions provided by the output of 'ngcpcfg status'.

Further details regarding the ngcpcfg tool are available through 'man ngcpcfg' on the Sipwise Next Generation Platform.