The Sipwise C5 provides a configuration framework for consistent and easy to use low level settings management. A basic usage of the configuration framework only needs two actions already used in previous chapters:
Low level management of the configuration framework might be required by advanced users though. This chapter explains the architecture and usage of Sipwise C5 configuration framework. If the basic usage explained above fits your needs, feel free to skip this chapter and return to it when your requirements change.
A more detailed workflow of the configuration framework for creating a configuration file consists of 7 steps:
The Sipwise C5 provides configuration file templates for most of the services it runs. These templates are stored in the directory /etc/ngcp-config/templates.
Example: Template files for /etc/ngcp-sems/sems.conf are stored in /etc/ngcp-config/templates/etc/ngcp-sems/.
There are different types of files in this template framework, which are described below.
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:
listen=udp:[% ip %]:[% kamailio.lb.port %]
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):
listen=udp:1.2.3.4:5060
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. An advanced user should create a .customtt.tt2 file from a copy of the corresponding .tt2 template and leave the .tt2 template untouched. This way, the user will have his personalized configuration and the system will continue providing a working, updated configuration template in .tt2 format.
Example: We’ll create /etc/ngcp-config/templates/etc/lb/kamailio.cfg.customtt.tt2 and use it for our personalized configuration. In this example, we’ll just append a comment at the end of the template.
cd /etc/ngcp-config/templates/etc/kamailio/lb cp kamailio.cfg.tt2 kamailio.cfg.customtt.tt2 echo '# This is my last line comment' >> kamailio.cfg.customtt.tt2 ngcpcfg apply 'my commit message'
The ngcpcfg command will generate /etc/kamailio/kamailio.cfg from our custom template instead of the general one.
tail -1 /etc/kamailio/kamailio.cfg # This is my last line comment
| tip | |
The tt2 files use the Template Toolkit language. Therefore you can use all the feature this excellent toolkit provides within ngcpcfg’s template files (all the ones with the .tt2 suffix). |
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.
echo 'chgrp www-data ${output_file}' \
> /etc/ngcp-config/templates/etc/ngcp-ossbss/provisioning.conf.postbuild.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.
| tip | |
If the service script has the execute flags set (chmod +x $file) it will be invoked directly. If it doesn’t have execute flags set it will be invoked under bash. Make sure the script is bash compatible if you do not set execute permissions on the service file. |
These commands are usually service reload/restarts to ensure the new configuration has been loaded by running services.
| info | |
The configuration files mentioned in the following example usually already exist on the platform. Please make sure you don’t overwrite any existing files if following this example. |
Example:
echo 'ngcp-service mariadb restart' \ > /etc/ngcpcfg-config/templates/etc/mysql/my.cnf.services echo 'ngcp-service asterisk restart' \ > /etc/ngcpcfg-config/templates/etc/asterisk/ngcpcfg.services
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 /etc/ngcp-config/config.yml file contains all the user-configurable options, using the YAML (YAML Ain’t Markup Language) syntax.
The /etc/ngcp-config/constants.yml file provides configuration options for the platform that aren’t supposed to be edited by the user. Do not manually edit this file unless you really know what you’re doing.
The /etc/ngcp-config/network.yml file provides configuration options for all interfaces and IP addresses on those interfaces. You can use the ngcp-network tool for conveniently change settings without having to manually edit this file.
The /etc/ngcp-config/ngcpcfg.cfg file is the main configuration file for ngcpcfg itself. Do not manually edit this file unless you really know what you’re doing.
The ngcpcfg utility supports the following command line options:
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:
ngcpcfg build /etc/nginx/sites-available/ngcp-panel
Example: to generate all the files located inside the directory /etc/nginx/ you can execute:
ngcpcfg build /etc/nginx/
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 uncommited 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 uncommited 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.
Retrieve modifications from shared storage. Note: This option is available in the High Availability setup only.
Push modifications to shared storage and remote systems. After changes have been pushed to the nodes the build option will be executed on each remote system to rebuild the configuration files (unless the --nobuild has been specified, then the build step will be skipped). If hostname(s) or IP address(es) is given as argument then the changes will be pushed to the shared storage and to the given hosts only. If no host has been specified then the hosts specified in /etc/ngcp-config/systems.cfg are used. Note: This option is available in the High Availability setup only.
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 just invoke ngcpcfg status.
If everything is OK and nothing needs to be done the output should look like:
# ngcpcfg status Checking state of ngcpcfg: OK: has been initialised already (without shared storage) Checking state of configuration files: OK: nothing to commit. Checking state of /etc files OK: nothing to commit.
If the output doesn’t say "OK" just 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.