How to Install Icinga 2 on Ubuntu (Complete Beginner Guide)

In this complete Icinga monitoring tutorial, I walk you through installing and configuring Icinga 2 on Ubuntu from scratch. This is a full getting-started guide designed for Linux administrators, homelab users, and anyone who wants to set up real infrastructure monitoring the right way.

Thanks to Icinga for sponsoring this tutorial! With Icinga (and this tutorial as your guide) you’ll be monitoring your servers like a pro in no time! Check out Icinga here.

Relevant Links

Commands Used During the Video

Adding Icinga’s Ubuntu Repository

Install prerequisite packages:

sudo apt install apt-transport-https wget

Download the keyring package for Icinga’s repository

wget -O icinga-archive-keyring.deb "https://packages.icinga.com/icinga-archive-keyring_latest+ubuntu$(
 . /etc/os-release; echo "$VERSION_ID"
).deb"

Install the keyring package via apt:

sudo apt install ./icinga-archive-keyring.deb

Create the sources list file for Icinga’s repositories:

sudo nano /etc/apt/sources.list.d/noble-icinga.list

Repository lines:

deb [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/ubuntu icinga-noble main

deb-src [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/ubuntu icinga-noble main

Update the package repository index:

sudo apt update

Install Icinga:

sudo apt install icinga2

Check the status of the icinga2 service:

systemctl status icinga2

If the service is not running and/or is not enabled, enable and start the service:

sudo systemctl enable --now icinga2

Run the Icinga Node Wizard

The Icinga Node Wizard asks you a number of questions to build initial configuration, set up background services, and optionally create a cluster:

sudo icinga2 node wizard

Set Up MariaDB

For this solution, we’ll need to create at least two databases. Run the following command to install MariaDB:

sudo apt install mariadb-server

Check the status of the mariadb service to ensure that it’s running:

systemctl status mariadb

To implement some basic security for MariaDB, run the following command to set defaults that are more secure:

sudo mysql_secure_installation

Install IcingaDB

IcingaDB is a very important component of Icinga, and is installed separately. Install the packages required for IcingaDB:

sudo apt install icingadb icingadb-redis

Redis is required by Icinga, so we should make sure that it’s running:

systemctl status icingadb-redis

If it’s not enable/start the service with the following command:

sudo icinga2 feature enable icingadb

We’ve made a number of changes to our configuration, so restart Icinga to ensure everything is in full effect so far:

sudo systemctl restart icinga2

Install Icinga Web

Icinga Web provides the dashboard/console for managing the solution through a web browser. To set this up, you’ll first install the following packages:

sudo apt install icingaweb2 icingadb-web icingacli php-imagick

Next, open Icinga in a web browser (replace the IP address with either the fully qualified domain name if you have one, or the actual IP address of your instance):

http://192.168.1.105/icingaweb2/setup

In order to proceed through the initial installation wizard, you’ll need to create a setup token. Back in the terminal, run this:

sudo icingacli setup token create

Note: If for some reason you forget the setup token after creating it, you can retrieve it with the following command:

sudo icingacli setup token show

We’ll need to create a database for Icinga Web. To do so, we’ll enter the MariaDB shell:

sudo mysql

Then, we’ll create the database for Icinga Web:

CREATE DATABASE icingaweb2;

We’ll also run the following command in order to create a “grant” that will allow Icinga to communicate with this database (be sure not to use the same password, it’s only provided as an example):

GRANT ALL ON icingaweb2.* TO icingaweb2@localhost IDENTIFIED BY 'CHANGEME';

Next, flush privileges:

FLUSH PRIVILEGES;

Back in the web browser, enter the database details for the icingaweb2 database. At some point later, you’ll be asked for database details for the IcingaDB database. Back in the terminal, enter the following in MariaDB to create the database:

CREATE DATABASE icingadb;

Also, create a grant as well:

GRANT ALL ON icingadb.* TO icingadb@localhost IDENTIFIED BY 'CHANGEME';

Finally, flush privileges again:

FLUSH PRIVILEGES;

We’re done with MariaDB (for now) so we’ll exit it:

exit

Back in a normal (non-mariadb) shell, enter the following command to import the required database schema for IcingaDB:

sudo mysql icingadb < /usr/share/icingadb/schema/mysql/schema.sql

Manual Monitoring

Note: Icinga supports adding hosts/services to monitor via config files or by using Icinga Director. (You should choose one method or the other). The video first shows the manual method, then later shows off Icinga Director.

On each node that’s being monitored (as well as on the server itself) install the monitoring-plugins package to ensure required checks are present:

sudo apt install monitoring-plugins

In order to edit config files, we’ll need to switch to root:

sudo su

Now we can navigate to the config directory:

cd /etc/icinga2/conf.d

To add a host, you can do so by editing the hosts.conf file:

nano hosts.conf

At the very end of the file, place the following to add a host (change the details to match the actual host you’d like to monitor):

object Host "LLTV Web Site" {
  address = "170.187.206.215"
  check_command = "hostalive"
}

Restart the icinga2 service so the changes will take effect:

sudo systemctl restart icinga2

At this point, if we refresh Icinga, the new host will show up as “pending”. Within a few minutes or so, it will reach out and check connectivity to that server, and then show us the result.

To monitor a service on a host (such as disk space) add the following:

apply Service "disk-root" {
  check_command = "disk"

  vars.disk_partitions = [ "/" ]
  vars.disk_warning = "20%"
  vars.disk_critical = "10%"

  assign where host.name == "LLTV Web Site"
}

To finalize the service we just added, let’s restart icinga2 again:

sudo systemctl restart icinga2

Similarly, to check load average you can add code similar to the following:

apply Service "load" {
  check_command = "load"

  vars.load_wload1 = 2.0
  vars.load_cload1 = 3.0

  vars.load_wload5 = 1.5
  vars.load_cload5 = 2.5

  vars.load_wload15 = 1.0
  vars.load_cload15 = 2.0

  assign where host.name == "LLTV Web Site"
}

Continuing, let’s add another check – this time for swap. We’ll add it to the same file as before:

apply Service "swap" {
  check_command = "swap"
  assign where host.name == "LLTV Web Site"
}

As usual, we’ll restart Icinga so the new update takes effect:

sudo systemctl restart icinga2

At this point, we’ve added several checks, and they should now show up within the Icinga Web dashboard.

Icinga Director

Icinga Director gives you the ability to manage configuration through Icinga Web. To set it up, we’ll go back to the terminal, and install another package:

sudo apt install icinga-director

Next, we’ll return to the MariaDB shell so we can create a database for Director to use:

sudo mysql

Now, we’ll create Director’s database:

CREATE DATABASE icinga_director CHARACTER SET 'utf8';

And we’ll also create a user grant as well:

GRANT ALL ON icinga_director.* TO icinga_director@localhost IDENTIFIED BY 'CHANGEME';

To wrap up database creation, we’ll flush privileges:

FLUSH PRIVILEGES;

Now we can exit the MariaDB shell:

exit

Now that we’ve created a database for director, we’ll return to our browser and create a new database resource. To do that, we’ll naviage to Configuration → Application → Resources menu. We’ll add the credentials to access our database there, and click through the remaining steps.

During the process, it will ask you for your API details. You can retrieve that info with the following command:

sudo cat /etc/icinga2/conf.d/api-users.conf

After that, enter any remaining details you may be asked for (use the video to see examples) and you should now have Icinga Director ready to go!

YOUR HOME FOR LINUX-RELATED FUN AND LEARNING