You can support us by downloading this article as PDF from the Link below. Download the guide as PDF

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 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

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

PostgreSQL

psql -q -c "CREATE DATABASE director WITH ENCODING 'UTF8';"
psql director -q -c "CREATE USER director WITH PASSWORD 'director';
GRANT ALL PRIVILEGES ON DATABASE director TO director;
CREATE EXTENSION pgcrypto;"

3. Install ipl

MODULE_NAME=ipl
MODULE_VERSION=v0.4.0
REPO="https://github.com/Icinga/icingaweb2-module-${MODULE_NAME}"
MODULES_PATH="/usr/share/icingaweb2/modules"
git clone ${REPO} "${MODULES_PATH}/${MODULE_NAME}" --branch "${MODULE_VERSION}"
icingacli module enable "${MODULE_NAME}"

4. Install incubator

MODULE_NAME=incubator
MODULE_VERSION=v0.5.0
REPO="https://github.com/Icinga/icingaweb2-module-${MODULE_NAME}"
MODULES_PATH="/usr/share/icingaweb2/modules"
git clone ${REPO} "${MODULES_PATH}/${MODULE_NAME}" --branch "${MODULE_VERSION}"
icingacli module enable "${MODULE_NAME}"

5. Install reactbundle

MODULE_NAME=reactbundle
MODULE_VERSION=v0.7.0
REPO="https://github.com/Icinga/icingaweb2-module-${MODULE_NAME}"
MODULES_PATH="/usr/share/icingaweb2/modules"
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:

ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
REPO_URL="https://github.com/icinga/icingaweb2-module-director"
TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"
MODULE_VERSION="1.7.2"
URL="${REPO_URL}/archive/v${MODULE_VERSION}.tar.gz"
install -d -m 0755 "${TARGET_DIR}"
wget -q -O - "$URL" | tar xfz - -C "${TARGET_DIR}" --strip-components 1

Installation from GIT repository

ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
REPO_URL="https://github.com/icinga/icingaweb2-module-director"
TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"
MODULE_VERSION="1.7.2"
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 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:

[db]
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.

[config]
endpoint = icinga-master
; host = 127.0.0.1
; 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.

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

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.

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

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 the service, choose the name of the service from the imports drop-down then click Add.

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

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

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

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

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

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 172.16.10.4.

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

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.

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.

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 https://packages.icinga.com/icinga.key | apt-key add -

Add the Icinga2 repository to the server:

cat <<EOF >> /etc/apt/sources.list.d/icinga2.list
deb http://packages.icinga.com/ubuntu icinga-bionic main
deb-src http://packages.icinga.com/ubuntu icinga-bionic main
EOF

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.

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

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
e.g:
echo "172.16.10.2 master-icinga" >> /etc/hosts

In the example above, 172.16.10.2 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.

vi deployment-script.sh

Make the script executable:

chmod a+x deployment-script.sh

Run the script:

./deployment-script.sh

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

systemctl restart 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:

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.

Conclusion

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.

You can support us by downloading this article as PDF from the Link below. Download the guide as PDF