The Icinga Config Compiler: An Overview

The Icinga configuration format was designed to be easy to use for novice users while at the same time providing more advanced features to expert users. At first glance it might look like a simple key-value configuration format:

object Host "" {
	import "generic-host"
	address = ""
	address6 = "2001:db8::17"

However, it features quite a bit of functionality that elevates it to the level of scripting languages: variables, functions, control flow (if, for, while) and a whole lot more.

Icinga’s scripting language is used in several places:

  • configuration files
  • API filter expressions
  • auto-generated files used for keeping track of modified attributes

In this post I’d like to show how some of the config machinery works internally.

The vast majority of the config compiler is contained in the lib/config directory. It weighs in at about 4.5% of the entire code base (3059 out of 68851 lines of code as of July 2018). The compiler is made up of three major parts:


The lexer (lib/config/config_lexer.ll, based on flex) takes the configuration source code in text form and breaks it up into tokens. In doing so the lexer recognizes all the basic building blocks that make up the language:

  • keywords (e.g. “object”, “for”, “break”) and operators (e.g. >, ==, in)
  • identifiers
  • literals (numbers, strings, booleans)
  • comments

However, it has no understanding of how these tokens fit together syntactically. For that it forwards them to the parser. All in all the lexer is actually quite boring.


The parser (lib/config/config_parser.yy, based on GNU Bison) takes the tokens from the lexer and tries to figure out whether they represent a valid program. In order to do so it has production rules which define the language’s syntax. As an example here’s one of those rules for “for” loops:

| T_FOR '(' identifier T_FOLLOWS identifier T_IN rterm ')'
        BeginFlowControlBlock(context, FlowControlContinue | FlowControlBreak, true);
        $$ = new ForExpression(*$3, *$5, std::unique_ptr($7), std::unique_ptr($10), @$);
        delete $3;
        delete $5;

Here’s a list of some of the terms used in the production rule example:

Symbol Description
T_FOR Literal text “for”.
identifier A valid identifier
T_FOLLOWS Literal text “=>”.
T_IN Literal text “in”.
BeginFlowControlBlock, EndFlowControlBlock These functions enable the use of certain flow control statements which would otherwise not be allowed in code blocks. In this case the “continue” and “break” keywords can be used in the loop’s body.
rterm_scope_require_side_effect A code block for which Icinga can’t prove that the last statement doesn’t modify the program state.
An example for a side-effect-free code block would be { 3 } because Icinga can prove that executing its last statement has no effect.

After matching the lexer tokens against its production rules the parser continues by constructing an abstract syntax tree (AST). The AST is an executable representation of the script’s code. Each node in the tree corresponds to an operation which Icinga can perform (e.g. “multiply two numbers”, “create an object”, “retrieve a variable’s value”). Here’s an example of an AST for the expression “2 + 3 * 5”:

Note how the parser supports operator precedence by placing the AddExpression AST node on top of the MultiplyExpression node.

Icinga’s AST supports a total of 52 different AST node types. Here are some of the more interesting ones:

Node Type Description
ArrayExpression An array definition, e.g. [ varName, "3", true ]. Its interior values are also AST nodes.
BreakpointExpression Spawns the script debugger console if Icinga is started with the -X command-line option.
ImportExpression Corresponds to the import keyword which can be used to import another object or template.
LogicalOrExpression Implements the || operator. This is one of the AST node types which don’t necessarily evaluate all of its interior AST nodes, e.g. for true || func() the function call never happens.
SetExpression This is essentially the = operator in its various forms, e.g. host_name = "localhost"

On their own the AST nodes just describe the semantical structure of the script. They don’t actually do anything in terms of performing any real actions.


Icinga contains a virtual machine (in the language sense) for executing AST expressions (mostly lib/config/expression.cpp and lib/config/vmops.hpp). Given a reference to an AST node – such as root node from the example in the previous section – it attempts to evaluate that node. What that means exactly depends on the kind of AST node:

The LiteralExpression class represents bare values (e.g. strings, numbers and boolean literals). Evaluating a LiteralExpression AST node merely yields the value that is stored inside of that node, i.e. no calculation of any kind takes place. On the other hand, the AddExpression and MultiplyExpression AST nodes each have references to two other AST nodes. These are the operands which are used when asking an AddExpression or MultiplyExpression AST node for “their” value.

Some AST nodes require additional context in order to run. For example a script function needs a way to access its arguments. The VM provides these – and a way to store local variables for the duration of the script’s execution – through an instance of the StackFrame (lib/base/scriptframe.hpp) class.

Future Considerations

All in all the Icinga scripting language is actually fairly simple – at least when compared to other more sophisticated scripting engines like V8. In particular Icinga does not implement any kind of optimization.
A first step would be to get rid of the AST and implement a bytecode interpreter. This would most likely result in a significant performance boost – because it allows us to use the CPU cache much more effectively than with thousands, if not hundreds of thousands AST nodes scattered around the address space. It would also decrease memory usage both directly and indirectly by avoiding memory fragmentation.
However, for now the config compiler seems to be doing its job just fine and is probably one of the most solid parts of the Icinga codebase.

Flapping in Icinga 2.8.0

The author viewing the code for the first time

Flapping detection is a feature many monitoring suites offer. It is mainly used to detect unfortunately chosen thresholds, but can also help in detecting network issues or similar. In most cases two thresholds are used, high and low. If the flapping value, which is the percentage of state changes over a set time, gets higher than the high threshold, it is considered flapping. It will then stay flapping until the value drops below the low threshold.
Naturally Icinga 2 had such a feature, just that it implemented a different approach and didn’t work. For 2.8.0 we decided it was time to finally fix flapping, so I went to investigate. As I said the flapping was working differently from Icinga 1, Shinken, etc. Instead of two thresholds there was just one, instead of one flapping value there were two and they change based on the time since the last check. Broken down it looks like this:

positive; //value for state changes
negate; //value for stable changes
FLAPPING_INTERVAL; //Compile time constant to smoothen the values
OnCheckResult() {
  if (positive + negative > FLAPPING_INTERVAL) {
    pct = (positive + negative - FLAPPING_INTERVAL) / FLAPPING_INTERVAL;
    positive -= pct * positive;
    negative -= pct * negative;
  weight = now - timeOfLastCheck;
  if (stateChange)
    positive += weight;
    negative += weight;
IsFlapping() {
  return 100 * positive / (negative + positive);

The idea was to have the two flapping values (positive & negative) increase one or the other with every checkresult. Positive for state changes and negative for results which were not state changes, by the time since the last check result. The first problem which arises here, while in most cases the check interval is relatively stable, after a prolonged Icinga outage one of the values could be extremely inflated. Another problem is the degradation of the result, in my tests it took 17 consecutive stable results for a flapping value to calm down.
After some tweaking here and there, I decided it would be wisest to go with the old and proven style Icinga 1 was using. Save the last 20 checkresults, count the state changes and divide them by 20. I took inspiration in the way Shinken handles flapping and added weight to the sate changes, with the most recent one having a value of 1.2 and the 20th (oldest) one of 0.8. The issue of possibly wasting memory on saving the state changes could be resolved by using one integer as a bit array. This way we are actually using slightly less memory now \o/

The above example would then have a value of 39.1%, flapping in the case of default thresholds. More details on the usage and calculation of flapping in Icinga 2 can be found in the documentation once version 2.8.0 is released.

Alt, aber bewährt

Immer wieder geht es in der IT um Vergleiche,  z.B. bei der Web-Entwicklung (NodeJS vs. PHP), der Datenhaltung (MongoDB vs. SQL-Datenbanken) oder auch scheinbaren Kleinigkeiten wie das Einlesen einer Datei in den Arbeitsspeicher.
Letztgenannter Vorgang würde bspw. in der Programmiersprache C unter Linux und anderen POSIX-Systemen wie folgt aussehen (Prüfungen auf Fehler habe ich der Übersichtlichkeit halber weggelassen):

void* read_file(char const *path, size_t *length) {
    int fd;
    struct stat stats;
    void *buf, *pos;
    ssize_t current_read;
    size_t remain;
    fd = open(path, O_RDONLY);
    fstat(fd, &stats);
    buf = malloc(stats.st_size);
    pos = buf;
    remain = stats.st_size;
    for (;;) {
        current_read = read(fd, pos, remain);        
        if (current_read == 0) {
        *(char**)&pos += current_read;
        remain -= (size_t)current_read;
    *length = stats.st_size;
    return buf;

Die Alternative dazu wäre die Verwendung von mmap():

void* read_file_via_mmap(char const *path, size_t *length) {
    int fd;
    struct stat stats;
    void *addr, *buf;
    fd = open(path, O_RDONLY);
    fstat(fd, &stats);
    addr = mmap(NULL, stats.st_size, PROT_READ, MAP_SHARED, fd, 0);
    buf = malloc(stats.st_size);
    memcpy(buf, addr, stats.st_size);
    munmap(addr, stats.st_size);
    *length = stats.st_size;
    return buf;

Deren Verfechter werben damit, dass die Anzahl der Systemaufrufe pro Datei konstant ist. Dem kann ich nicht widersprechen – die Datei wird mit open() geöffnet und mit mmap() in den Adressbereich integriert. Damit kann auf den Inhalt zugegriffen werden als befände er sich im Arbeitsspeicher. Das ermöglicht das anschließende Kopieren mit Hilfe von memcpy().
Aber das hilft einem nur weiter, wenn das auch tatsächlich messbar Zeit spart – dies ist definitiv nicht der Fall:

aklimov@ws-aklimov:~$ time ./read garbage
real    0m8.108s
user    0m0.000s
sys     0m3.664s
aklimov@ws-aklimov:~$ time ./mmap garbage
real    0m8.099s
user    0m0.652s
sys     0m3.000s

Das Lesen einer Datei (3 GB) hat im konkreten Fall nicht viel weniger Zeit in Anspruch genommen. Die Verwendung von mmap() hat lediglich ca. 660 Millisekunden von der linken in die rechte Tasche transferiert. Um genau zu sein – die Systemaufrufe der konventionellen Methode (strace):

open("garbage", O_RDONLY)               = 3                                                                                                                                                  
read(3, "\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0"..., 3221225472) = 2147479552                                                      
read(3, "\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0\377\0"..., 1073745920) = 1073745920                                                      
read(3, "", 0)                          = 0
close(3)                                = 0

… vs. mmap():

open("garbage", O_RDONLY)               = 3
mmap(NULL, 3221225472, PROT_READ, MAP_SHARED, 3, 0) = 0x7ff5423c6000
munmap(0x7ff5423c6000, 3221225472)      = 0
close(3)                                = 0

Zwar benötigt die konventionelle Methode im konkreten Fall einen Systemaufruf mehr, aber angesichts der Dateigröße ist das meiner Meinung nach trotzdem vergleichsweise effizient.


Nicht alles was glänzt ist auch Gold. Und mit Kaffeesatzlesen ist niemandem geholfen.

Alexander Klimov
Alexander Klimov
Senior Developer

Alexander hat 2017 seine Ausbildung zum Developer bei NETWAYS erfolgreich abgeschlossen. Als leidenschaftlicher Programmierer und begeisterter Anhänger der Idee freier Software, hat er sich dabei innerhalb kürzester Zeit in die Herzen seiner Kollegen im Development geschlichen. Wäre nicht ausgerechnet Gandhi sein Vorbild, würde er von dort aus daran arbeiten, seinen geheimen Plan, erst die Abteilung und dann die Weltherrschaft an sich zu reißen, zu realisieren - tut er aber nicht. Stattdessen beschreitet er mit der...

Schwarze Magie für GNU/Linux-Nerds

“Linux ist der beste Virenschutz”, heißt es in “Fachkreisen”. “Installiere Linux und Du wirst fortan ruhiger schlafen können!” Ähm… falsch.
Ja, Linux ist ein guter Anfang was die Herstellung der Sicherheit auf dem eigenen Rechner betrifft. Aber es hilft einem nichts ohne brain.exe. Vor allem wenn man es mit einem Magier zu tun bekommt…

Mögen die Spiele beginnen!

ps -fu nagios

Wer auf das Monitoring-System Zugriff hat, hat viel Macht.

Wo Bernd recht hat, hat er recht – nicht umsonst nimmt z. B. Gunnars Jabber-Notification-Skript Nutzername und Passwort via Umgebungsvariablen entgegen. Check- und Notification-Skripte, die diesem Beispiel nicht folgen, reißen eine Sicherheitslücke auf, die jeder Systemnutzer ganz einfach ausnutzen kann:

aklimov@icinga2:~$ ps -fu nagios
nagios    8128     1  0 11:10 ?        00:00:00 /usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2 --no-stack-rlimit daemon -e /var/log/icinga2/error.log
nagios    8148  8128  0 11:10 ?        00:00:00 /usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2 --no-stack-rlimit daemon -e /var/log/icinga2/error.log
nagios    8433  8148  0 11:17 ?        00:00:00 /usr/lib/nagios/plugins/check_ping -6 -H ::1 -c 200,15% -w 100,5%
nagios    8434  8433  0 11:17 ?        00:00:00 /bin/ping6 -n -U -w 10 -c 5 ::1
nagios    8435  8148  0 11:17 ?        00:00:00 /usr/lib/nagios/plugins/check_ping -4 -H -c 200,15% -w 100,5%
nagios    8436  8148  0 11:17 ?        00:00:00 /usr/lib/nagios/plugins/check_ping -H -c 5000,100% -w 3000,80%
nagios    8437  8435  0 11:17 ?        00:00:00 /bin/ping -n -U -w 10 -c 5
nagios    8438  8436  0 11:17 ?        00:00:00 /bin/ping -n -U -w 30 -c 5

Schwarze Magie ist hier noch nicht im Spiel. (Aber dieses Beispiel ist auch nur zum Aufwärmen.)

strace -p

Was tut ein Programm so alles wenn ich gerade mal nicht hinschaue? Um diese Frage zu beantworten, wird nicht zwangsläufig der Quellcode benötigt. In vielen Fällen reicht bereits strace:
aklimov@WS-AKlimov:~$ echo $$  # Prozess-ID der Shell
aklimov@WS-AKlimov:~$ strace -p20901
strace: Process 20901 attached

Der Ausgabe können wir entnehmen, dass die Shell gerade darauf wartet, dass ein beliebiger Kindprozess (z. B. strace) sich beendet.
Diese Art der Hexenkunst hat sich bereits rumgesprochen und die Kernel-Entwickler haben ihre Wirkung eingedämmt. Daher konnte ich ohne weiteres nur den Elternprozess von strace als Beispiel nehmen.

gdb -p

Ich erinnere mich noch genau an diese eine AWP-Unterrichtsstunde in der Berufsschule:
Es ging darum, dass ein C/C++-Programm auf mehrere Module aufgeteilt werden kann. Mit dem static-Schlüsselwort sei es möglich, “modulglobale” Variablen zu erstellen – d. h. Variablen, die zwar global, aber nur für das eigene Modul sichtbar sind. Ein Argument des Lehrers für solche Variablen war allen Ernstes die Sicherheit. Und die Übung zu diesem Thema bestand darin, in einem Modul ein Passwort vor den anderen Modulen zu verbergen.
Wenn der wüsste…
Zunächst starte ich in einem neuen Terminal cat:
aklimov@WS-AKlimov:~$ cat
Damit haben wir auch schon unseren “Opfer”-Prozess, der im konkreten Fall auf eingehende Daten wartet.
Darauf hin öffne ich ein zweites Terminal (mit den gleichen Benutzerrechten!) und starte gdb:
aklimov@WS-AKlimov:~$ ps -ef |grep cat
aklimov  10217 10149  0 12:25 pts/11   00:00:00 cat
aklimov  11088 10298  0 12:26 pts/12   00:00:00 grep cat
aklimov@WS-AKlimov:~$ gdb -p 10217
GNU gdb (Debian 7.11.1-2+b1) 7.11.1
Copyright (C) 2016 Free Software Foundation, Inc.
Attaching to process 10217

Die schwarze Magie daran…

… besteht darin, dass ich nun innerhalb dieses Prozesses schalten und walten kann wie ich will. (Und sämtlichen Speicher aller Module auslesen.)
Beispielsweise kann ich den Standard-Eingabe-Datenstrom (Stdin) des Prozesses on-the-fly durch /dev/null ersetzen (ohne ihn zu verlieren):

Aktion (Beschreibung) Aktion (GDB) Datei-Deskriptoren
/dev/null öffnen (gdb) p open("/dev/null", 0)
$1 = 3
0 /dev/pts/1
3 /dev/null
Stdin sichern (gdb) p dup(0)
$2 = 4
0, 4 /dev/pts/1
3 /dev/null
Datenstrom umleiten (gdb) p dup2(3, 0)
$3 = 0
4 /dev/pts/1
0, 3 /dev/null
Redundanten Deskriptor schließen (gdb) p close(3)
$4 = 0
4 /dev/pts/1
0 /dev/null
Programm-Ausführung fortsetzen (gdb) c
[Inferior 1 (process 10217) exited normally]


Linux nimmt einem keinerlei Sicherheitsfragen vollständig ab. Es gibt einem lediglich die Möglichkeit, sich selbst um diese zu kümmern (und sie nicht der NSA zu überlassen).
Gehet hin und sichert euch!

Alexander Klimov
Alexander Klimov
Senior Developer

Alexander hat 2017 seine Ausbildung zum Developer bei NETWAYS erfolgreich abgeschlossen. Als leidenschaftlicher Programmierer und begeisterter Anhänger der Idee freier Software, hat er sich dabei innerhalb kürzester Zeit in die Herzen seiner Kollegen im Development geschlichen. Wäre nicht ausgerechnet Gandhi sein Vorbild, würde er von dort aus daran arbeiten, seinen geheimen Plan, erst die Abteilung und dann die Weltherrschaft an sich zu reißen, zu realisieren - tut er aber nicht. Stattdessen beschreitet er mit der...

Builds beschleunigen mit ccache

Builds beschleunigen mit ccache
Wer häufig größere C-/C++-Projekte neukompilieren muss, kennt das Problem: Nach “make clean” oder “configure” mit geänderten Flags kann man sich eigentlich erstmal eine Tasse Kaffee holen, da “make” teilweise Minuten lang braucht.
Abhilfe schafft hier ccache, indem nur noch tatsächlich geänderte Dateien neukompiliert werden. Am einfachsten lässt es sich mit dem jeweiligen Paketmanager installieren, z.b. per “apt-get install ccache” unter Debian oder Ubuntu.
Danach muss die ~/.bashrc-Datei bearbeitet werden und folgende Zeilen am Ende eingefügt werden:

export CC="ccache gcc"
export CXX="ccache g++"

Damit die Änderungen Wirkung tragen, muss man sich neu-anmelden oder alternativ einmalig folgenden Befehl verwenden:

source ~/.bashrc

Danach sollten die beiden Environment-Variablen gesetzt sein:

$ export | egrep CC\|CXX
declare -x CC="ccache gcc"
declare -x CXX="ccache g++"

Bei Projekten, die autoconf verwenden, muss nun “configure” erneut aufgeführt werden, damit beim nächsten “make” auch tatsächlich ccache verwendet wird.
Je nachdem, wie stark sich das eigene Projekt zwischen Rebuilds ändert, umso mehr Zeit sollte ccache einem ersparen. In meinem Fall bei Icinga 2 haben sich die Buildzeiten im Durchschnitt jeweils um 3-4 Minuten verkürzt.