netways_macbook_pro_workstationMy preferred platform to develop Icinga 2 was still Fedora including Vagrant boxes and Docker containers. Apart from that we, the developers at NETWAYS, do have our own Windows VM to develop and test Icinga 2 on Windows as well (check this blog post I wrote a while ago).
Though I’m getting older and more lazy. I want a stack to work with, not hacking wrong kernel modules or other broken stuff while trying to get my stuff fixed. At last years Icinga Camp in SFO it was pretty obvious – everyone uses Macbooks these days to get their stuff done.
Hey, there’s even MS Office which won’t screw up your Powerpoint presentations (Libreoffice does…) you share with other Icinga team members. Long story short – my new notebook at NETWAYS is now a Macbook Pro. Shiny little thing with plenty of stuff already pre-installed.

Development Tools

There’s Xcode but nothing I would need to compile Icinga 2 or run a web application. While I still could go for Docker or Vagrant, I just want to natively run my development stack on OSX even. Can’t be that hard, no?
For gods sake there’s homebrew and additional repositories allowing you to add your own development stack getting to work on your terminal.
The following instructions are only meant for development and testing environments, not for production! Although it will lead us somewhere with Packages and Appstore apps? Maybe, let’s see about that in 2016 😉
This has been tested on OSX Yosemite 10.10.5.


Get iterm2. Much better than the integrated terminal. Open a new iterm2 terminal.
Install homebrew and fix the Github API rate limiting by generating an application token.

ruby -e "$(curl -fsSL"
$ vim $HOME/.bash_profile
source $HOME/.bashrc
$ vim $HOME/.bashrc
$ source $HOME/.bashrc

Now install Git and wget.

$ brew install git wget

Add a new user and group called “icinga” from “settings” – “user and groups”. Make sure that the user is also a member of the group.
Afterwards modify the user’s shell.

$ dscl
list Local/Default/Users
read Local/Default/Users/icinga
change Local/Default/Users/icinga UserShell /bin/bash /usr/bin/false


Icinga 2

Install all requirements for compiling Icinga 2 via brew.

$ brew install ccache boost cmake bison flex yajl openssl mysql-connector-c++ postgresql

Configure ccache for usage with clang (note: Apple does not natively support gcc anymore). Though clang is way better with compiler errors than gcc ever will be, especially with boost.

vim $HOME/.bashrc
export CC='ccache clang'
export CXX='ccache clang++'
export CCACHE_CPP2=yes

Clone the Icinga 2 source tree.

$ cd $HOME
$ mkdir -p coding/icinga && cd coding/icinga

As user:

$ git clone git://
$ cd icinga2

As developer with ssh access:

$ git clone
$ cd icinga2

Since Icinga 2 uses cmake, we’ll build the debug version inside its dedicated “debug” directory. That way the source git tree remains clean.
Note: Icinga 2 will be installed in /usr/local/icinga2. Unity builds are off, meaning no release builds but debug builds (that way we’ll have more fun with debugging in lldb later on).

mkdir debug
cd debug
cd ..
sudo make -j4 install -C debug

Since this is a source build, we’ll need to fix some permissions (that’s why we enforce users to use packages). One for the path, second for bash completion and third for the command pipe permissions for Icinga Web 2 later on.

chown -R icinga:icinga /usr/local/icinga2
vim $HOME/.profile
export PATH=/usr/local/icinga2/sbin/:$PATH
source /usr/local/icinga2/etc/bash_completion.d/icinga2
source $HOME/.profile
# ensure that the web server can read the command pipe
icinga2 feature enable command
icinga2 daemon
chown -R icinga:_www /usr/local/icinga2/var/run/icinga2/cmd

Monitoring Plugins

$ brew install nagios-plugins
$ sudo vim /usr/local/icinga2/etc/icinga2/constants.conf
const PluginDir = "/usr/local/sbin"


Get the package from and install it.
Start it and ensure that you’ll set a root password:

sudo /usr/local/mysql/support-files/mysql.server start

You can ensure that MySQL is started on boot time in the settings tab.
Create the “icinga” database for the DB IDO feature, create users and import the schema.

$ sudo mysql -p
$ sudo mysql icinga < $HOME/coding/icinga/icinga2/lib/db_ido_mysql/schema/mysql.sql


OSX already provides a web server but with limited PHP capabilities. Just start it and enable the rewrite module.

sudo su -
apachectl start
cd /etc/apache2
cp httpd.conf httpd.conf.bak
vim httpd.conf
LoadModule rewrite_module libexec/apache2/
apachectl restart


Unfortunately the PHP module provided by OSX misses important modules such as gettext required by Icinga Web 2. Therefore we’ll use an external PHP package which includes itself optionally into /etc/apache2/other. We’ll also set the timezone here – modify that for your needs.

$ curl -s | bash -s 5.6
$ vim $HOME/.profile
export PATH=/usr/local/php5/bin:$PATH
$ vim /usr/local/php5/php.d/99-liip-developer.ini

Now fix the MySQL socket for php-mysql:

# mkdir /var/mysql
# cd /var/mysql
# ln -s /tmp/mysql.sock mysql.sock

Icinga Web 2

This setup is pretty common to the existing documentation, the only real difference is that the default configuration directory is not ‘/etc/icingaweb2’ but ‘/usr/local/icingaweb2/etc’. Do these steps as root (e.g. ‘sudo -i’).
Note: We’ll use the git master here to allow pulling the latest fixes and also providing feedback for developers. We’ll also generate the web setup token in this step.

# cd /usr/local/share/
# git clone git://
# cd icingaweb2
# ./bin/icingacli setup config webserver apache --document-root /usr/local/share/icingaweb2/public --config /usr/local/icingaweb2/etc > /etc/apache2/other/icingaweb2.conf
# apachectl restart
# mkdir /usr/local/icingaweb2
#allow apache to manage the directory, group permissions are tricky
# chown -R _www:_www /usr/local/icingaweb2/etc/
# /usr/local/share/icingaweb2/bin/icingacli setup config directory --group icingaweb2 --config /usr/local/icingaweb2/etc
Successfully created configuration directory /usr/local/icingaweb2/etc
# /usr/local/share/icingaweb2/bin/icingacli setup token create --config /usr/local/icingaweb2/etc
The newly generated setup token is: c89435f0d16c8faf

Navigate to http://localhost/icingaweb2/setup and follow the installation instructions. Keep the following infos in mind:

  • Keep the internal database as is
  • Provide the previously set root password for MySQL when asked
  • Monitoring module uses DB IDO with “icinga” everywhere (db, user, pass, etc)
  • External command pipe is located in /usr/local/icinga2/var/run/icinga2/cmd/icinga2.cmd

Icinga Web 2 will log errors directly to syslog by default.

$ sudo less /private/var/log/system.log

Run it

Apache and MySQL should be running already. Since there is no Init-Script for Icinga 2 at this stage, we’ll just run the daemon in foreground (that’s something we developers do all the time, either directly or attached to a debugger).

$ sudo -i
# icinga2 daemon -C
# icinga2 daemon

Look how shiny 🙂

Test the Cluster? Sure.

It’s not that hard to let Icinga 2 run with multiple instances in their own jail, listening on different cluster ports.
The main idea is to have each instance put into their own tree with etc, var, usr and so on. I guess that’s a topic for a blog post in the future. For now, have a read inside the docs.

Development IDE

If you’ve got yourself a CLion license, install it as well. Jetbrains generously granted the Icinga project a free license for open source projects 🙂
Clion integrates CMake which we use for Icinga 2 – easily compile and debug Icinga 2.


Enjoying OSX whilst developing Icinga 2 natively is a perfect combination. And we still have Linux in Docker/Vagrant and Windows in Parallels. Since it’s hard to get an OSX VM, the perfect fit for us developers.
I’d say a native app only makes sense once the 2.4 API is released. That could also involve one that works as client, not server daemon, receiving alerts directly from the event stream api.
If you prefer working on Icinga 2 on OSX and getting the app stuff going, don’t hesitate to do so. We love our community members always coming up with new stuff! 🙂
Guess who will be using a local demo for the Icinga 2 API talk at Icinga Camp Portland 🙂