In the previous article we discussed How To Install Icinga2 on CentOS 8 / RHEL 8. In this article we will cover how to automate Icinga2 configurations with a tool called Icinga Director. Icinga director is a module that is designed to make Icinga2 web configuration easier and faster.

Icinga Director helps less advanced users add, monitor and delete hosts and services through a web interface which involves a simple point and click.

Icinga director centos8

Icinga Director can also be a perfect tool to use when one doesn’t have root access to the master server. With Icinga Director, you have the advantage of importing and syncing objects to director.

The imported objects can be edited after sync id done. Some of the import sources supported by Icinga Director include CSV, XML, JSON, PuppetDB, AWS and YAML.

Install Icinga Director on CentOS 8 | RHEL 8

The steps below will guide you how to install Icinga Director on CentOS 8 / RHEL 8. We assume you have a running instance of Icinga web2. If you haven’t, follow the links below:

Install and Configure Icinga 2 and Icinga Web 2 on CentOS 8 / RHEL 8

How To Install Icinga Web 2 on CentOS 8 / RHEL 8

The following Icinga modules must be installed and enabled:

  • Reactbundle
  • ipl
  • incubator
  • PHP modules
  1. Install git and PHP modules
sudo yum install git -y
sudo yum install rh-php71-php-curl rh-php71-php-pcntl rh-php71-php-posix rh-php71-php-sockets rh-php71-php-xml rh-php71-php-zip -y

2. Create an empty database for Icinga Director


mysql -e "CREATE DATABASE director CHARACTER SET 'utf8';
   CREATE USER [email protected] IDENTIFIED BY 'director';
   GRANT ALL ON director.* TO [email protected];"


psql -q -c "CREATE DATABASE director WITH ENCODING 'UTF8';"
psql director -q -c "CREATE USER director WITH PASSWORD 'director';

3. Install ipl

git clone ${REPO} "${MODULES_PATH}/${MODULE_NAME}" --branch "${MODULE_VERSION}"
icingacli module enable "${MODULE_NAME}"

4. Install incubator

git clone ${REPO} "${MODULES_PATH}/${MODULE_NAME}" --branch "${MODULE_VERSION}"
icingacli module enable "${MODULE_NAME}"

5. Install reactbundle

git clone ${REPO} "${MODULES_PATH}/${MODULE_NAME}" --branch "${MODULE_VERSION}"
icingacli module enable "${MODULE_NAME}"

6. Install the Director module

Director module can be installed using two methods:

  1. Installation from tarball file
  2. Installation from git repository

Installation from release tarball

Use the following script to install Icinga Director module from tarball:

install -d -m 0755 "${TARGET_DIR}"
wget -q -O - "$URL" | tar xfz - -C "${TARGET_DIR}" --strip-components 1

Installation from GIT repository

git clone "${REPO_URL}" "${TARGET_DIR}" --branch v${MODULE_VERSION}
cd "${TARGET_DIR}" && git checkout "v${MODULE_VERSION}"

Once the installation has been done successfully, the next step is to enable it. This can be done by either using icingacli in the shell or using the web interface.

On command line:

icingacli module enable director

On web interface, choose Configuration / Modules, select the director module and choose State: enable

Icinga director enable module

Icinga Director configuration management

Create a global object in the /etc/icinga2/zones.conf file.

object Zone "director-global" {
  global = true

Icinga Director uses a relational database, (MySQL, MariaDB or PostgreSQL). We need to create a database resource for the Director instance.

Edit the file /etc/icingaweb2/resources.ini and add the following information:

Remember to use the password you used during creation of the database user and also the type of database you are using.

Also use the "utf8" for charset

[Director DB]
type = "db"
db = "mysql"
host = "localhost"
dbname = "director"
username = "director"
password = "director"
charset = "utf8"

Configure the Director to use the database resource that we created above.

Add the following information in the /etc/icingaweb2/modules/director/config.ini file:

resource = "Director DB"

Configure ApiUser file at /etc/icinga2/conf.d/api-users.conf

object ApiUser "director" {
        password = "director"
        permissions = [ "*" ]

Configure the kickstart.ini file in /etc/icingaweb2/modules/director/kickstart.ini.

This file contains the endpoint (master-hostname), username and password of the APIUser configured at /etc/icinga2/conf.d/api-users.conf, resolvable host and port.

endpoint = icinga-master
; host =
; port = 5665
username = director
password = director

Schema creation and Database kickstart

Run the following to create a schema and kickstart an empty database:

icingacli director kickstart run
icingacli director migration run --verbose
icingacli director migration pending --verbose

We have successfully configured Icinga Director and can now be used to automate tasks and monitoring.

How to Add Hosts to Icinga2 using the Icinga Director

The following steps will guide us on how to add a host to Icinga2 using the Icinga Director that we just configured above.

  1. Create a service Template

We need to configure a service template that will be used to monitor systems and services.

In the template, we shall define the service and part of the system that will be monitored.

In this post, we shall create a template that monitors system load and Disk usage.

To configure this, login to your Icinga web dashboard, navigate to ‘Icinga Director‘ on the left panel. Select Services then choose the Service Template option. To create a new service template, click the ‘Add‘ button.

Create service template icinga director

Add a template as shown in the image below:

Name: give it a descriptive name

Check command: the command that will be used to check monitoring e.g ssh, ping

Allow Run on Agent

add service template icinga

Click Add to add the service template.

Repeat the same for the for Disk usage.

2. Create ServiceSet and add Service Template

We’ll create a ServiceSet from the templates we created above:

Click ServiceSet then Add on the Services menu.

Add service set icinga2

Give the service set a unique descriptive name and a description:

add new icinga serviceSet1

Next, add the service templates to the serviceSet we created. In our case, we’ll be adding to standard-linux-server serviceSet.

Click on the service set name on the left pane then choose the Services option on the top right tab

Click the add service tab to add a service

add service to service set 1

Add the service, choose the name of the service from the imports drop-down then click Add.

add new service serviceset

Repeat the same for all the services we created.

3. Create a Host Template and Add the ServiceSet

The next step is to create a host and attach the ServiceSet we created above. This is what will be used to ass new hosts to the Master node.

On the Icinga Director menu, click Hosts then ‘Host Templates

add host template icinga director

Now click ‘Add‘ to create a new host template.

Make sure you fill the following fields:

  • Name: descriptive name for the template
  • check command: hostalive
  • Icinga2 Agent: yes
  • Establish connection: yes
  • Accepts Config: yes
add host icinga director 2

The next step is to add a serviceSet to the template. Click on the template we created, then click ‘Services‘ on the top menu.

add serviceset to host icinga2

Click on ‘Add Service set‘ tab to add the serviceSet.

Choose the service set we created. In our case, standard-linux-server.

add service set icinga2 1

At this point, a host template has been created and a serviceSet added to it. This means that the setup is now ready for hosts to be added to Icinga2.

4. Add a host to Icinga2 using Icinga Director

The next step is to try to add a host to our Icinga2 using the Icinga director we have configured.

We will add a client whose hostname is client02.icinga.computingforgeeks and has IP

In the Icinga Director menu, click Hosts then select Hosts in the menu that displays.

add host to icinga using icinga director

Click ‘Add‘ on the right then choose the host template we created. In our case, standard-linux-server.

Give it a hostname, display name and the host IP.

The hostname should bethe hostname of the client server.

add icinga client icinga director

It is time to deploy the changes we’ve made so far. On the Icinga Director Menu, Click on Deployments, you will see a number of changes that haven’t been deployed yet. Click on the tab ‘Deploy xx pending changes‘ where ‘xx’ is the number of pending deployments.

How to deploy changes icinga director

THis will add client02.icinga.computingforgeeks to Icinga using the host template.

5. Initialize Icinga2 client

We need to install the necessary Icinga2 packages on client02 for monitoring.

Connect to the client host then download the packages:

Add Icinga2 key:

curl | apt-key add -

Add the Icinga2 repository to the server:

cat <<EOF >> /etc/apt/sources.list.d/icinga2.list
deb icinga-bionic main
deb-src icinga-bionic main

Install Icinga2

sudo apt update
sudo apt install icinga2 monitoring-plugins

After successfully installing icinga2 on the client, the next step is downloading the deployment script from the Icinga director dashboard.

On the Icinga director menu, select ‘Hosts‘ then choose the ‘Hosts‘ option in the ‘Manage your Icinga Hosts’ menu.

Download icinga client script

Select your host, in our case, client02.icinga.computingforgeeks then choose ‘Agent‘ on the top right panel.

download icinga client script icinga director

Download the agent deployment script for for your system, in our case it is Linux. Use the download button just below the Linux comandline title.

This is the script we’ll use to run on the client server for the deployment to take effect.

We need to set the hostname of the master Icinga host to the client’s /etc/hosts file:

echo "IP-OF-MASTER master-hostname" >> /etc/hosts
echo " master-icinga" >> /etc/hosts

In the example above, is the IP of the master and ‘master-icinga’ is the master’s hostname.

Create and executable script on the client and paste the content of the downloaded file to it.

cp icinga2-agent-kickstart.bash

Make the script executable:

chmod a+x

Run the script:


Upon sucessful execution, the script will exit and you have to restart Icinga2 service in the client:

systemctl restart icinga2
deployment script icinga2

Testing Icinga2 Director

The service is now initialized and the host should be up seen on the Icinga2 web dashboard.

On the dashboard, click on Overview then Hosts you should be able to see the newly added host among the hosts listed:

icinga2 active hosts

When you click on the hostname, you will see more detailed information about the client. You can also check the service stats for the services that we added.

Icinga director client stats


We have sucessfully added a client to our Icinga2 using Icinga Director. We can now add as many clients as we wish to Icinga using the Icinga Director.

This is a tool that will help reduce the manual work of having to configure every client host that you wish to monitor using Icinga2.

Fell free to comment or reach out in case you run into issues deploying this module of Icinga 2.

Your support is our everlasting motivation,
that cup of coffee is what keeps us going!

As we continue to grow, we would wish to reach and impact more people who visit and take advantage of the guides we have on our blog. This is a big task for us and we are so far extremely grateful for the kind people who have shown amazing support for our work over the time we have been online.

Thank You for your support as we work to give you the best of guides and articles. Click below to buy us a coffee.


    • Hi,
      Just before the deployment script, there is a step to download another script from the icinga Director server. The name of the script is icinga2-agent-kickstart.bash. The content of icinga2-agent-kickstart.bash are copied to the on the client server.


Please enter your comment!
Please enter your name here