In Elektra different forms of application integrations are possible:
- A lightweight integration where configuration files are integrated in a global key database. This will not be discussed here, if you are interested please continue reading about mounting
- Integration techniques without modifying the applications. This will also not be discussed here, if you are interested please read:
- Integration where applications directly use Elektra to read and store settings.
In this tutorial we will discuss (3), i.e., how to extend an application to directly access Elektra’s key database.
When the application is fully integrated in Elektra’s ecosystem following benefits arise:
- Benefits that shared libraries have, e.g.
- All applications profit from fixes, optimization and new features
- Less memory consumption, because the libraries executable instructions are only loaded once
- Faster development time, because many non-trivial problems (e.g. OS-dependent resolving of configuration file names with atomic updates) are already solved and tested properly
- The administrator can choose:
- the configuration file syntax (e.g. XML or JSON)
- notification and logging on configuration changes
- defaults on absence of values using specifications
- and all other features that plugins provide
- The parsing result is guaranteed to be the same because the same parser will be used.
- Other applications can use your configuration as override or as fallback (see below)
We call the process of making applications aware of other's configuration "to elektrify". This tutorial is suited both for new and existing applications.
As first step, locate places where configuration is parsed or generated. Afterwards, use Elektra’s data structures instead at these locations. Before we are going to describe how to do this, we will describe some possibilities to keep all advantages your previous configuration system had.
You can keep code you want within Elektra as plugins. This allows your application, and other applications participating in Elektra’s ecosystem to access your configuration. Doing this, the syntax of the configuration file stays the same as before. You can keep the same validation as you had before. The application profits from Elektra’s infrastructure solving basic issues like getting configuration from other parts of the system, update and conflict detection, and resolving of the file name. In particular we gain a lot because every other program can also access the configuration of your software.
If you do not have the code or want to get rid of it, you can use a variety of already implemented plugins to extend the functionality of the configuration system. There are plenty of plugins that parse and generate configuration files in different formats, do syntactic checks, do notifications (e.g. via dbus), and write out events in their log files.
New applications do not have the burden to stay compatible with the configuration system they had to before. So they will prefer to use more standard plugins and contribute to make them flawless. But they can also use self-written plugins for adding needed behavior or cross-cutting concerns.
To sum up, if a developer wants to elektrify software, he or she can do that without any need for changes to the outside world regarding the format and semantics of the configuration. In the interconnected world it is a matter of time until other software also wants to access the configuration, and with elektrified software it is possible for every application to do so.
As first step in a C-application you need to create an in-memory
Key. Such a
Key is Elektra’s atomic unit and consists of:
- a unique name
- a value
Keys are either associated with entries in configuration files or used
as arguments in the API to transport some information.
Thus a key is in-memory and does not need any of the other Elektra objects. We always can create one (the tutorial will use the C-API, but it describes general concepts useful for other languages in the same way):
Key *parentKey = keyNew("/sw/org/myapp/#0/current", KEY_END);
- The first argument of
keyNewis the name of the key. It consists of different parts,
/is the hierarchy-separator:
swis for software
orgis a URL/organization name to avoid name clashes with other application names. Use only one part of the URL/organization, so e.g.
myappis the name of the most specific component that has its own configuration
#0is the major version number of the configuration (increment if you need to introduce incompatible changes).
currentis the profile to use. Administrators need it if they want to start up applications with different configurations.
KEY_ENDas C needs a proper termination of variable length arguments.
The key name is standardized to make it easier to locate configuration.
Now we have the
Key we will use to pass as argument.
First we open our key database (KDB):
KDB *repo = kdbOpen(parentKey);
Key is seldom alone, but they are often found in groups, as typical in
configuration files. To represent many keys (a set of keys) Elektra
has the data structure
KeySet. Because the
Key's name is unique we
can lookup keys in a
KeySet without ambiguity. Furthermore, we
can iterate over all
Keys in a
KeySet without a hassle.
To create an empty
KeySet we use:
KeySet *conf = ksNew(200, KS_END);
- 200 is an approximation for how many
Keys we think we will have in the
conf, intended for optimization purposes.
- After the first argument we can list build-in keys that should be available in any case.
- The last argument needs to be
Now we have everything ready to fetch the latest configuration:
kdbGet(repo, conf, parentKey);
Note it is important for applications that the parentKey starts with a slash
This ensures pulling in all keys of the so-called namespace.
Such a name cannot physically exist in configuration files, but they are
the most important key names to actually work with configuration within
applications as we will see when introducing
To lookup a key, we use:
Key *k = ksLookupByName(conf, "/sw/org/myapp/#0/current/section/subsection/key", 0);
We see in this example that only Elektra paths are hard coded in the application, no configuration file or similar.
As already mentioned keys starting with slash
/ do not exist
in configuration files, but are "representatives", "proxies" or
"logical placeholders" for keys from any other namespace.
So that every tool has a consistent view to the key database
it is vital that every application does a
ksLookup for every
key it uses. So even if your application iterates over keys,
always remember to do a cascading lookup for every single key!
Thus we are interested in the value we use:
char *val = keyString(k);
We need to convert the configuration value to the data type we need.
To do this manually has severe drawbacks:
- hard coded names might have typos or might be inconsistent
- tedious handling if key or value might be absent
- always calling
ksLookupwhich gets tiresome for arrays
- converting to needed data type is error prone
So (larger) applications should not directly use
instead use code generation to provide a type-safe frontend.
For more information about that, continue reading here.
Now, we have a fully working configuration system without any hard coded information (such as configuration files). We already gained something. But, we did not discuss how we can actually achieve application integration, the goal of Elektra.
Elektra 0.8.11 introduces the so called specification for the
application's configuration, located below its own namespace
spec (next to user and system).
spec allow us to specify which keys the application reads,
which fallback they might have and which is the default value using
metadata. The implementation of these features happened in
When using cascading keys (those starting with
/), the following features
are now available (in the metadata of respective
override/#: use these keys in favor of the key itself (note that
#is the syntax for arrays, e.g.
#0for the first element,
#_10for the 11th and so on)
namespace/#: instead of using all namespaces in the predefined order, one can specify namespaces to search in a given order
fallback/#: when no key was found in any of the (specified) namespaces the
fallback-keys will be searched
default: the value to use if nothing else was found
You can use those features like following:
kdb set /overrides/test "example override" sudo kdb setmeta spec/test override/#0 /overrides/test
This technique provides complete transparency how a program will fetch a configuration value. In practice that means that:
kdb get "/sw/org/myapp/#0/current/section/subsection/key"
, will give you the exact same value as the application gets when it uses the above lookup C code.
What we do not see in the program above are the default values and
fallbacks. They are present in the so-called specification (namespace
The specification consists of (meta) key-value pairs, too. So we do not have
to learn something new.
So lets say, that another application
otherapp has the
value we actually want. We want to improve the integration. In the case that we
do not have a value for
we want to use
So we specify:
kdb setmeta spec/sw/org/myapp/#0/current/section/subsection/key \ "fallback/#0" /sw/otherorg/otherapp/#0/current/section/subsection/key
Voila, we have done a system integration between
Note that the fallback, override and cascading works on key level, and not like most other systems have implemented, on configuration file level.
To make this work within your application make sure to always call
ksLookup before using a value from Elektra.
Elektra does not hard code any configuration data in your application.
default specification, we even can startup applications without
any configuration file at all and still do not have anything hard coded
in the applications binary.
Furthermore, by using cascading keys for
Elektra gives you the possibility to specify how to retrieve configuration data.
In this specification you can define to consider or prefer configuration data
from other applications or shared places. Doing so, we can achieve configuration