Friday, June 14, 2024
HomeHow toHow to Install Icinga 2 Monitoring Software on Debian 12

How to Install Icinga 2 Monitoring Software on Debian 12

Icinga 2 is an open-source monitoring system that checks the availability of network resources, notifies users of outages, and generates performance data for reporting. You can monitor network services (SMTP, POP3, HTTP, NNTP, ping), host resources (CPU usage, Disk usage), and network components (switches, routers, temperature, and humidity sensors) using Icinga2. It can be integrated with Nagios plugins.

In the following tutorial, you will learn how to install Icinga2 on a Debian 12 server and connect it to a client node. Instead of the default Apache server, we will use Nginx to run Icinga2 Web.

Prerequisites

  • Two machines running Debian 12. One of them will act as a Master server and another one will act as the client for monitoring.

  • A non-root user with sudo privileges on both servers.

  • A fully qualified domain name (FQDN) for the master server, icinga.example.com and the client node, client.example.com.

  • Make sure everything is updated.

    $ sudo apt update && sudo apt upgrade
    
  • Few packages that your system needs.

    $ sudo apt install wget curl nano software-properties-common dirmngr apt-transport-https gnupg2 ca-certificates lsb-release debian-archive-keyring ufw unzip -y
    

    Some of these packages may already be installed on your system.

Step 1 – Configure Firewall on the Master server

The first step is to configure the firewall. Debian comes with ufw (Uncomplicated Firewall) by default.

Check if the firewall is running.

$ sudo ufw status

You should get the following output.

Status: inactive

Allow SSH port so the firewall doesn’t break the current connection on enabling it.

$ sudo ufw allow OpenSSH

Allow port 5665 which is required by the Icinga2 client to connect to the server.

$ sudo ufw allow 5665

Allow HTTP and HTTPS ports as well.

$ sudo ufw allow http
$ sudo ufw allow https

Enable the Firewall

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Check the status of the firewall again.

$ sudo ufw status

You should see a similar output.

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80/tcp                     ALLOW       Anywhere
443                        ALLOW       Anywhere
5665                       ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80/tcp (v6)                ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)
5665 (v6)                  ALLOW       Anywhere (v6)

Step 2 – Install MariaDB Server

Debian 12 ships with the latest version of MariaDB. You can install it with a single command.

$ sudo apt install mariadb-server

Check the version of MySQL.

$ mysql --version
mysql  Ver 15.1 Distrib 10.11.4-MariaDB, for debian-linux-gnu (x86_64) using  EditLine wrapper

Run the MariaDB secure install script.

$ sudo mariadb-secure-installation

You will be asked for the root password. Press Enter because we haven’t set any password for it.

NOTE: RUNNING ALL PARTS OF THIS SCRIPT IS RECOMMENDED FOR ALL MariaDB
      SERVERS IN PRODUCTION USE!  PLEASE READ EACH STEP CAREFULLY!

In order to log into MariaDB to secure it, we'll need the current
password for the root user. If you've just installed MariaDB, and
haven't set the root password yet, you should just press enter here.

Enter current password for root (enter for none):

Next, you will be asked if you want to switch to the Unix socket authentication method. The unix_socket plugin allows you to use your operating system credentials to connect to the MariaDB server. Since you already have a protected root account, enter n to proceed.

OK, successfully used password, moving on...

Setting the root password or using the unix_socket ensures that nobody
can log into the MariaDB root user without the proper authorisation.

You already have your root account protected, so you can safely answer 'n'.

Switch to unix_socket authentication [Y/n] n

Next, you will be asked if you want to change your root password. On Debian 12, the root password is tied closely to automated system maintenance, so it should be left alone. Type n to proceed further.

 ... skipping.

You already have your root account protected, so you can safely answer 'n'.

Change the root password? [Y/n] n

Next, you will be asked certain questions to improve MariaDB security. Type Y to remove anonymous users, disallow remote root logins, remove the test database, and reload the privilege tables.

 ... skipping.

By default, a MariaDB installation has an anonymous user, allowing anyone
to log into MariaDB without having to have a user account created for
them.  This is intended only for testing, and to make the installation
go a bit smoother.  You should remove them before moving into a
production environment.

Remove anonymous users? [Y/n] y
 ... Success!

Normally, root should only be allowed to connect from 'localhost'.  This
ensures that someone cannot guess at the root password from the network.

Disallow root login remotely? [Y/n] y
 ... Success!

By default, MariaDB comes with a database named 'test' that anyone can
access.  This is also intended only for testing, and should be removed
before moving into a production environment.

Remove test database and access to it? [Y/n] y
 - Dropping test database...
 ... Success!
 - Removing privileges on test database...
 ... Success!

Reloading the privilege tables will ensure that all changes made so far
will take effect immediately.

Reload privilege tables now? [Y/n] y
 ... Success!

Cleaning up...

All done!  If you've completed all of the above steps, your MariaDB
installation should now be secure.

Thanks for using MariaDB!

You can enter the MariaDB shell by typing sudo mysql or sudo mariadb on the command line.

Step 3 – Configure MariaDB

Log in to the MariaDB shell. Enter your root password when prompted.

$ sudo mysql

Create the Icinga database.

MariaDB [(none)]> CREATE DATABASE icinga2;

Create the SQL user account for Icinga2. Don’t change the database and the username because they are already set by default. If you want to change them, you will need to perform some extra steps while installing the MySQL driver in Step 5. Enter the password and you will get an error and then be asked to reconfigure where you can specify your custom database name and users.

MariaDB [(none)]> CREATE USER 'icinga2'@'localhost' IDENTIFIED BY 'Your_password2';

Grant all privileges on the database to the user.

MariaDB [(none)]> GRANT ALL PRIVILEGES ON icinga2.* TO 'icinga2'@'localhost';

Since we are not modifying the root user, you should create another SQL user for performing administrative tasks that employ password authentication. Choose a strong password for this one.

MariaDB> GRANT ALL ON *.* TO 'navjot'@'localhost' IDENTIFIED BY 'Yourpassword32!' WITH GRANT OPTION;

Flush user privileges.

MariaDB [(none)]> FLUSH PRIVILEGES;

Exit the shell.

MariaDB [(none)]> exit

Step 4 – Install Icinga2 and Monitoring plugins on the Master Server

We will use the Icinga2 official repository for installation. Download and import the Icinga2 GPG key.

$ wget -O - https://packages.icinga.com/icinga.key | sudo gpg --dearmor -o /usr/share/keyrings/icinga-archive-keyring.gpg

Run the following commands to create and add the Icinga2 repository information to the APT sources list.

$ echo "deb [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/debian icinga-`lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/$(lsb_release -cs)-icinga.list
$ echo "deb-src [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] http://packages.icinga.com/debian icinga-`lsb_release -cs` main" | sudo tee -a /etc/apt/sources.list.d/$(lsb_release -cs)-icinga.list

Update the system repositories list.

$ sudo apt update

Install Icinga2, Icingacli, and the monitoring plugins.

$ sudo apt install icinga2 monitoring-plugins -y

Step 5 – Install IDO MySQL driver on the Master Server

For Icinga2 to work, it needs a database. For that, we need to install the IDO MySQL driver and set up the database connection. Run the following command to install the MySQL driver.

$ sudo apt install -y icinga2-ido-mysql

Next, you will be asked to enable the ido-mysql feature. Select Yes to continue.

Next, You will be prompted to set up the driver and create a database using the dbconfig-common utility. Select Yes to continue.

 

Next, you will be asked for the MySQL password for the icinga2 database. Enter the password configured in step 3 to continue.

You will be asked to confirm the password again.

You can check the database details in the /etc/icinga2/features-available/ido-mysql.conf file.

$ sudo cat /etc/icinga2/features-available/ido-mysql.conf
/**
 * The db_ido_mysql library implements IDO functionality
 * for MySQL.
 */

library "db_ido_mysql"

object IdoMysqlConnection "ido-mysql" {
  user = "icinga2",
  password = "Your_password2",
  host = "localhost",
  database = "icinga2"
}

Enable the ido-mysql feature.

$ sudo icinga2 feature enable ido-mysql
Enabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect.

Restart the Icinga2 service.

$ sudo systemctl restart icinga2

Verify the service status.

$ sudo systemctl status icinga2
? icinga2.service - Icinga host/service/network monitoring system
     Loaded: loaded (/lib/systemd/system/icinga2.service; enabled; preset: enabled)
    Drop-In: /etc/systemd/system/icinga2.service.d
             ??limits.conf
     Active: active (running) since Mon 2024-01-08 07:35:29 UTC; 4s ago
    Process: 15404 ExecStartPre=/usr/lib/icinga2/prepare-dirs /etc/default/icinga2 (code=exited, status=0/SUCCESS)
   Main PID: 15411 (icinga2)
     Status: "Startup finished."
      Tasks: 14
     Memory: 13.6M
        CPU: 858ms
     CGroup: /system.slice/icinga2.service
             ??15411 /usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2 --no-stack-rlimit daemon --close-stdio -e /var/log/icinga2/error.log
             ??15433 /usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2 --no-stack-rlimit daemon --close-stdio -e /var/log/icinga2/error.log
             ??15438 /usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2 --no-stack-rlimit daemon --close-stdio -e /var/log/icinga2/error.log

Step 6 – Configure Icinga2 API

To manage and configure the Icinga2 monitoring through HTTP, you need to configure the Icinga2 API. Run the following command to enable the Icinga2 API, generate TLS certificates for Icinga2, and update Icinga2 configurations.

$ sudo icinga2 api setup

You will get a similar output.

information/cli: Generating new CA.
information/base: Writing private key to '/var/lib/icinga2/ca//ca.key'.
information/base: Writing X509 certificate to '/var/lib/icinga2/ca//ca.crt'.
information/cli: Generating new CSR in '/var/lib/icinga2/certs//icinga.example.com.csr'.
information/base: Writing private key to '/var/lib/icinga2/certs//icinga.example.com.key'.
information/base: Writing certificate signing request to '/var/lib/icinga2/certs//icinga.example.com.csr'.
information/cli: Signing CSR with CA and writing certificate to '/var/lib/icinga2/certs//icinga.example.com.crt'.
information/pki: Writing certificate to file '/var/lib/icinga2/certs//icinga.example.com.crt'.
information/cli: Copying CA certificate to '/var/lib/icinga2/certs//ca.crt'.
information/cli: Adding new ApiUser 'root' in '/etc/icinga2/conf.d/api-users.conf'.
information/cli: Reading '/etc/icinga2/icinga2.conf'.
information/cli: Enabling the 'api' feature.
Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.
information/cli: Updating 'NodeName' constant in '/etc/icinga2/constants.conf'.
information/cli: Created backup file '/etc/icinga2/constants.conf.orig'.
information/cli: Updating 'ZoneName' constant in '/etc/icinga2/constants.conf'.
information/cli: Backup file '/etc/icinga2/constants.conf.orig' already exists. Skipping backup.
Done.

Now restart your Icinga 2 daemon to finish the installation!

The above command creates a /etc/icinga2/conf.d/api-users.conf file with the default user root having all the permissions over the Icinga2 API. We need a new user with minimal permissions required by Icinga Web.

Open the api-users.conf file for editing.

$ sudo nano /etc/icinga2/conf.d/api-users.conf

Add the following code at the end of the file. Choose a strong password for the API.

/** api for icingaweb2 */
object ApiUser "icingaweb2" {
  password = "PassWordApiIcingaWeb2"
  permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
}

Make a note of the credentials which will be needed later on to access the website. The Icinga2 API server listens on port 5665 by default. Restart the service for the changes to take effect.

$ sudo systemctl restart icinga2

The next step is to install the Icinga Web interface. It comes pre-configured for Apache but we will be using the Nginx server. Therefore, first, we need to install Nginx and the SSL certificates.

Step 7 – Install Nginx

Debian 12 ships with an older version of Nginx. To install the latest version, you need to download the official Nginx repository.

Import Nginx’s signing key.

$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

Add the repository for Nginx’s mainline version.

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/mainline/debian `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list

Update the system repositories.

$ sudo apt update

Install Nginx.

$ sudo apt install nginx

Verify the installation. On Debian systems, the following command will only work with sudo.

$ sudo nginx -v
nginx version: nginx/1.25.3

Start the Nginx server.

$ sudo systemctl start nginx

Check the service status.

$ sudo systemctl status nginx
? nginx.service - nginx - high performance web server
     Loaded: loaded (/lib/systemd/system/nginx.service; enabled; preset: enabled)
     Active: active (running) since Mon 2024-01-08 07:43:24 UTC; 4s ago
       Docs: https://nginx.org/en/docs/
    Process: 16330 ExecStart=/usr/sbin/nginx -c /etc/nginx/nginx.conf (code=exited, status=0/SUCCESS)
   Main PID: 16331 (nginx)
      Tasks: 3 (limit: 2299)
     Memory: 2.9M
        CPU: 16ms
     CGroup: /system.slice/nginx.service
             ??16331 "nginx: master process /usr/sbin/nginx -c /etc/nginx/nginx.conf"
             ??16332 "nginx: worker process"
             ??16333 "nginx: worker process"

Jan 08 07:43:24 icinga systemd[1]: Starting nginx.service - nginx - high performance web server...
Jan 08 07:43:24 icinga systemd[1]: Started nginx.service - nginx - high performance web server.

Step 8 – Install SSL

We need to install Certbot to generate the SSL certificate. You can install Certbot using Debian’s repository or grab the latest version using the Snapd tool. We will be using the Snapd version.

Debian 12 comes doesn’t come with Snapd installed. Install Snapd package.

$ sudo apt install snapd

Run the following commands to ensure that your version of Snapd is up to date.

$ sudo snap install core && sudo snap refresh core

Install Certbot.

$ sudo snap install --classic certbot

Use the following command to ensure that the Certbot command can be run by creating a symbolic link to the /usr/bin directory.

$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Verify if Certbot is functioning correctly.

$ certbot --version
certbot 2.8.0

Run the following command to generate an SSL Certificate.

$ sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d icinga.example.com

The above command will download a certificate to the /etc/letsencrypt/live/icinga.example.com directory on your server.

Generate a Diffie-Hellman group certificate.

$ sudo openssl dhparam -dsaparam -out /etc/ssl/certs/dhparam.pem 4096

Check the Certbot renewal scheduler service.

$ sudo systemctl list-timers

You will find snap.certbot.renew.service as one of the services scheduled to run.

NEXT                        LEFT          LAST                        PASSED  UNIT                         ACTIVATES
-----------------------------------------------------------------------------------------------------------------------------------------
Mon 2024-01-08 09:47:46 UTC 1h 56min left Sun 2024-01-07 09:47:46 UTC 22h ago systemd-tmpfiles-clean.timer systemd-tmpfiles-clean.service
Mon 2024-01-08 13:35:00 UTC 5h 43min left -                           -       snap.certbot.renew.timer     snap.certbot.renew.service
Tue 2024-01-09 00:00:00 UTC 16h left      Mon 2024-01-08 00:00:01 UTC 7h ago  dpkg-db-backup.timer         dpkg-db-backup.service

Do a dry run of the process to check whether the SSL renewal is working fine.

$ sudo certbot renew --dry-run

If you see no errors, you are all set. Your certificate will renew automatically.

Step 9 – Configure Nginx and PHP

Since Icinga is configured for Apache, the PHP-FPM package is not installed by default. You will also need the PHP Imagick module if you want to export the graphs to PDF. Run the following command to install PHP-FPM and the PHP Imagick library.

$ sudo apt install php-fpm php-imagick

Configure PHP-FPM

Open the file /etc/php/8.2/fpm/pool.d/www.conf.

$ sudo nano /etc/php/8.2/fpm/pool.d/www.conf

We need to set the Unix user/group of PHP processes to nginx. Find the user=www-data and group=www-data lines in the file and change them to nginx.

...
; Unix user/group of processes
; Note: The user is mandatory. If the group is not set, the default user's group
;       will be used.
user = nginx
group = nginx
...

Find the listen.owner = www-data and listen.group = www-data lines in the file and change them to nginx.

; Set permissions for unix socket, if one is used. In Linux, read/write
; permissions must be set in order to allow connections from a web server. Many
; BSD-derived systems allow connections regardless of permissions. The owner
; and group can be specified either by name or by their numeric IDs.
; Default Values: user and group are set as the running user
;                 mode is set to 0660
listen.owner = nginx
listen.group = nginx

Save the file by pressing Ctrl + X and entering Y when prompted.

Restart the PHP-FPM service.

$ sudo systemctl restart php8.2-fpm

Configure Nginx

Create and open the file /etc/nginx/conf.d/icinga.conf for editing.

$ sudo nano /etc/nginx/conf.d/icinga.conf

Paste the following code in it.

server {
    listen       443 ssl http2;
    listen       [::]:443 ssl http2;
    server_name  icinga.example.com;

    access_log  /var/log/nginx/icinga.access.log;
    error_log   /var/log/nginx/icinga.error.log;

    # SSL
    ssl_certificate      /etc/letsencrypt/live/icinga.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/icinga.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/icinga.example.com/chain.pem;
    ssl_session_timeout  5m;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    resolver 8.8.8.8;

    location ~ ^/index\.php(.*)$ {
        # fastcgi_pass 127.0.0.1:9000;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock; # Depends On The PHP Version
        fastcgi_index index.php;
        # try_files $uri =404;
        # fastcgi_split_path_info ^(.+\.php)(/.+)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME /usr/share/icingaweb2/public/index.php;
        fastcgi_param ICINGAWEB_CONFIGDIR /etc/icingaweb2;
        fastcgi_param REMOTE_USER $remote_user;
    }

    location ~ ^/(.*)? {
        alias /usr/share/icingaweb2/public;
        index index.php;
        rewrite ^/$ /dashboard;
        try_files $1 $uri $uri/ /index.php$is_args$args;
    }

    location ~ \.php$ {
        return 404;
    }
}

# enforce HTTPS
server {
    listen       80;
    listen       [::]:80;
    server_name  icinga.example.com;
    return 301   https://$host$request_uri;
}

Notice the root directory to be used in the Nginx configuration is /usr/share/icingaweb2/public.

Save the file by pressing Ctrl + X and entering Y when prompted once finished.

Open the file /etc/nginx/nginx.conf for editing.

$ sudo nano /etc/nginx/nginx.conf

Add the following line before the line include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size 64;

Save the file by pressing Ctrl + X and entering Y when prompted.

Verify the Nginx configuration file syntax.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Restart the Nginx service.

$ sudo systemctl restart nginx

Step 10 – Prepare Web Setup

Before accessing Icinga Web, we need to install it along with the command line tool.

$ sudo apt install icingaweb2 icingacli

Add the Nginx user to the icingaweb2 group.

$ sudo usermod -aG icingaweb2 nginx

Set the permissions of the Icingaweb directory to the icingaweb2 group.

$ sudo icingacli setup config directory --group icingaweb2
Successfully created configuration directory /etc/icingaweb2

When using Icinga Web, you are required to authenticate using a token. Generate the token using the following command.

$ sudo icingacli setup token create
The newly generated setup token is: 56951f01f9f77a68

Note down the token because you will need it later. You can always retrieve it later using the following command.

$ sudo icingacli setup token show
The current setup token is: 56951f01f9f77a68

The next step is to create a database and a database user. Log in to the MariaDB shell.

$ sudo mysql

Create the Icinga Web database.

MariaDB [(none)]> CREATE DATABASE icingaweb2;

Create the SQL user account for Icinga Web.

MariaDB [(none)]> CREATE USER 'icingaweb2'@'localhost' IDENTIFIED BY 'Your_password3';

Grant all privileges on the database to the user.

MariaDB [(none)]> GRANT ALL PRIVILEGES ON icingaweb2.* TO 'icingaweb2'@'localhost';

Flush user privileges.

MariaDB [(none)]> FLUSH PRIVILEGES;

Exit the shell.

MariaDB [(none)]> exit

Restart Nginx and PHP-FPM to apply the permission changes.

$ sudo systemctl restart nginx php8.2-fpm

Step 11 – Set up IcingaWeb

Open the URL https://icinga.example.com/setup in your browser and you will get the following screen.

Enter the token generated in the previous step and press the Next button to proceed.

On the next screen, choose the modules you want to install and click Next to proceed. The Monitoring module is selected for you by default. On the next page, you will be shown the requirements and whether they have been fulfilled. Make sure all the requirements are marked green.

Click Next to proceed to the next page to select the authentication type.

The authentication type is set to Database by default. Click Next to proceed. You will be asked to fill in the database credentials on the next page.

Fill in the database credentials created in step 10. Click the Validate Configuration button to verify the credentials. Once verified, click Next to proceed. Next, you will be asked to name the authentication backend.

Leave the default value and click Next to proceed. On the next page, you will be asked to create an administrator account.

Enter the credentials for your new administrator account and click Next to proceed. Next, you will be shown the Application Configuration page.

The Enable strict content security policy is unchecked. Check it and leave all the other default values untouched. Click Next to proceed. You will be asked to review the configuration on the last page.

You can go back to change any of the settings. If you are satisfied, click Next to proceed.

Click Next to proceed with the configuration of the monitoring module. Next, you will be asked for Icinga database credentials.

Fill in the database credentials in step 3 and click Validate Configuration to verify the connection. Once verified, click Next to proceed. Next, you will be asked to fill in the API details.

Fill in the API credentials created in step 6, 127.0.0.1 as the Host, and click Validate Configuration to verify the connection. Click Next to proceed. Next, you will be asked to choose protected custom variables for monitoring security.

Leave the default values and click Next to proceed. Next, you will be asked to review the Monitoring configuration. You can go back and change it if you want.

If you are satisfied, click Finish to complete the installation.

Once finished successfully, click the Login to Icinga Web 2 button to open the login page (https://icinga.example.com).

Enter your administrator account details and click the Login button to open the Icinga Web dashboard.

Visit the Overview >> Services page to check the status of the master server similar to the following.

Step 12 – Initialize Master Server

The next step is to initialize the master server as the master node. The master node acts as the main controller for the monitoring stack. Run the following command to start the initialization process.

$ sudo icinga2 node wizard

You will be prompted if it is an agent setup. Enter n to set up the master node.

Welcome to the Icinga 2 Setup Wizard!

We will guide you through all required configuration details.

Please specify if this is an agent/satellite setup ('n' installs a master setup) [Y/n]: n

Next, you will be asked for the common name or the domain name. Press Enter to select the default value that is displayed if it’s the correct one. Otherwise, enter the domain and press Enter.

Please specify the common name (CN) [icinga.example.com]:
Reconfiguring Icinga...
Checking for existing certificates for common name 'icinga.example.com'...
Certificate '/var/lib/icinga2/certs//icinga.example.com.crt' for CN 'icinga.example.com' already existing. Skipping certificate generation.
Generating master configuration for Icinga 2.
'api' feature already enabled.

Next, enter the master zone name and press Enter to proceed. In our case, it is the same as the server domain name.

Master zone name [master]: icinga.example.com

Next, you will be asked if you want to add any additional global zones. Press n to skip adding and press Enter to proceed.

Default global zones: global-templates director-global
Do you want to specify additional global zones? [y/N]: n

In the next step, leave the API bind host and port as default and press Enter to proceed.

Please specify the API bind host/port (optional):
Bind Host []:
Bind Port []:

Next, press Y to disable the configuration inside the /etc/icinga2/conf.d/ directory since we will use the Icinga2 Zones configuration later.

Do you want to disable the inclusion of the conf.d directory [Y/n]: Y
Disabling the inclusion of the conf.d directory...
Checking if the api-users.conf file exists...

Done.

Now restart your Icinga 2 daemon to finish the installation!

Restart the service to apply the changes.

$ sudo systemctl restart icinga2

And last but not least, run the following command to create a ticket for the client server. Use the client’s domain name as the argument.

$ sudo icinga2 pki ticket --cn 'client.example.com'
c81f2a3b86534f34160ed8b776906e5452d8d09c

Note down the ticket for use later.

Step 13 – Initialize Icinga2 Agent on Client Server

Log in to the client server and install Icinga2 and the monitoring plugins. Run the following commands to do that.

$ wget -O - https://packages.icinga.com/icinga.key | sudo gpg --dearmor -o /usr/share/keyrings/icinga-archive-keyring.gpg
$ echo "deb [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/debian icinga-`lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/$(lsb_release -cs)-icinga.list
$ echo "deb-src [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] http://packages.icinga.com/debian icinga-`lsb_release -cs` main" | sudo tee -a /etc/apt/sources.list.d/$(lsb_release -cs)-icinga.list
$ sudo apt update
$ sudo apt install icinga2 monitoring-plugins -y

Verify if the Icinga service is enabled and running.

$ sudo systemctl status icinga2
? icinga2.service - Icinga host/service/network monitoring system
     Loaded: loaded (/lib/systemd/system/icinga2.service; enabled; preset: enabled)
    Drop-In: /etc/systemd/system/icinga2.service.d
             ??limits.conf
     Active: active (running) since Mon 2024-01-08 12:52:53 UTC; 35s ago
   Main PID: 19530 (icinga2)
     Status: "Startup finished."
      Tasks: 12
     Memory: 13.4M
        CPU: 216ms
     CGroup: /system.slice/icinga2.service
             ??19530 /usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2 --no-stack-rlimit daemon --close-stdio -e /var/log/icinga2/error.log
             ??19573 /usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2 --no-stack-rlimit daemon --close-stdio -e /var/log/icinga2/error.log
             ??19578 /usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2 --no-stack-rlimit daemon --close-stdio -e /var/log/icinga2/error.log

Start the Icinga Node Wizard to initialize the agent on the client server.

$ sudo icinga2 node wizard

You will be prompted if it is an agent setup. Enter Y to set up the agent.

Welcome to the Icinga 2 Setup Wizard!

We will guide you through all required configuration details.

Please specify if this is an agent/satellite setup ('n' installs a master setup) [Y/n]: Y

Next, you will be asked to specify the common name. Leave the default value and press Enter to proceed.

Starting the Agent/Satellite setup routine...

Please specify the common name (CN) [client.example.com]:

Next, specify the parent endpoint as icinga.example.com and enter Y to establish a connection to the parent node from the client.

Please specify the parent endpoint(s) (master or satellite) where this node should connect to:
Master/Satellite Common Name (CN from your master/satellite node): icinga.example.com

Do you want to establish a connection to the parent node from this node? [Y/n]: Y

Next, enter the IP address of the master server and leave the port value unchanged as default.

Please specify the master/satellite connection information:
Master/Satellite endpoint host (IP address or FQDN): 199.247.31.184
Master/Satellite endpoint port [5665]:

Enter N to reject adding more master endpoints.

Add more master/satellite endpoints? [y/N]: N

Next, you will be shown the certificate information for the master server. Press Y to confirm the information and proceed.

Parent certificate information:

 Version:             3
 Subject:             CN = icinga.example.com
 Issuer:              CN = Icinga CA
 Valid From:          Jan  8 07:36:55 2024 GMT
 Valid Until:         Feb  8 07:36:55 2025 GMT
 Serial:              3a:e5:5e:e6:d5:5e:cc:1d:89:be:18:0b:10:cb:7d:54:8f:82:b1:5e

 Signature Algorithm: sha256WithRSAEncryption
 Subject Alt Names:   icinga.example.com
 Fingerprint:         DB 62 0D 2D AF 73 02 F2 86 92 5E A8 50 CD 0F 4F F2 D6 9E 86 AE F6 F9 E4 D7 F2 F2 60 78 1B 92 E5

Is this information correct? [y/N]: Y

Next, enter the request ticket generated in the previous step.

Please specify the request ticket generated on your Icinga 2 master (optional).
 (Hint: # icinga2 pki ticket --cn 'client.example.com'): c81f2a3b86534f34160ed8b776906e5452d8d09c

Leave the API bind host and port as default and press Enter to continue.

Please specify the API bind host/port (optional):
Bind Host []:
Bind Port []:

Next, enter Y twice to accept configuration and commands from the master node.

Accept config from parent node? [y/N]: Y
Accept commands from parent node? [y/N]: Y

Press Enter to accept the default local zone name which is the client domain name. Enter the master domain name as the parent zone name to proceed.

Reconfiguring Icinga...
Disabling feature notification. Make sure to restart Icinga 2 for these changes to take effect.
Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.

Local zone name [client.example.com]:
Parent zone name [master]: icinga.example.com

Press N to skip adding additional global zones.

Default global zones: global-templates director-global
Do you want to specify additional global zones? [y/N]: N

Press Y to skip disable the configurations from the /etc/icinga2/conf.d/ directory.

Do you want to disable the inclusion of the conf.d directory [Y/n]: Y
Disabling the inclusion of the conf.d directory...

Done.

Now restart your Icinga 2 daemon to finish the installation!

Restart the Icinga service to apply the configuration changes.

$ sudo systemctl restart icinga2

Step 14 – Create Zones Configuration on the Master Server

Log back into the server and create a new directory as the default zone.

$ sudo mkdir -p /etc/icinga2/zones.d/icinga.example.com/

Next, create a configuration file in the newly created directory and open it for editing.

$ sudo nano /etc/icinga2/zones.d/icinga.example.com/client.example.com.conf

Paste the following code in it. The IP address in the code should match the public IP address of the client.

// Endpoints
object Endpoint "client.example.com" {
}
// Zones
object Zone "client.example.com" {
    endpoints = [ "client.example.com" ]
    parent = "icinga.example.com"
}
// Host Objects
object Host "client.example.com" {
    check_command = "hostalive"
    address = "95.179.138.148"
    vars.client_endpoint = name
}

Save the file by pressing Ctrl + X and entering Y when prompted once finished.

Create and open the services file for editing.

$ sudo nano /etc/icinga2/zones.d/icinga.example.com/services.conf

Paste the following code in it.

// Ping
 apply Service "Ping" {
 check_command = "ping4"
 assign where host.address // check executed on master
 }
 // System Load
 apply Service "System Load" {
 check_command = "load"
 command_endpoint = host.vars.client_endpoint // Check executed on client01
 assign where host.vars.client_endpoint
 }
 // SSH Service
 apply Service "SSH Service" {
 check_command = "ssh"
 command_endpoint = host.vars.client_endpoint
 assign where host.vars.client_endpoint
 }
 // Icinga 2 Service
 apply Service "Icinga2 Service" {
 check_command = "icinga"
 command_endpoint = host.vars.client_endpoint
 assign where host.vars.client_endpoint
 }

Run the following command to verify the configuration.

$ sudo icinga2 daemon -C

You will get a similar output.

[2024-01-08 13:01:26 +0000] information/cli: Icinga application loader (version: r2.14.1-1)
[2024-01-08 13:01:26 +0000] information/cli: Loading configuration file(s).
[2024-01-08 13:01:26 +0000] information/ConfigItem: Committing config item(s).
[2024-01-08 13:01:26 +0000] information/ApiListener: My API identity: icinga.example.com
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 1 IcingaApplication.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 1 Host.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 1 FileLogger.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 1 IdoMysqlConnection.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 4 Zones.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 1 CheckerComponent.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 2 Endpoints.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 2 ApiUsers.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 1 ApiListener.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 1 NotificationComponent.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 246 CheckCommands.
[2024-01-08 13:01:26 +0000] information/ConfigItem: Instantiated 4 Services.
[2024-01-08 13:01:26 +0000] information/ScriptGlobal: Dumping variables to file '/var/cache/icinga2/icinga2.vars'
[2024-01-08 13:01:27 +0000] information/cli: Finished validating the configuration file(s).

Restart the Icinga service to apply the configuration changes.

$ sudo systemctl restart icinga2

Step 15 – Verify on the Icinga Dashboard

Open the Icinga2 Web Dashboard to verify the client machine information. Select Overview >> Hosts from the left menu, and you will see the following screen.

It might take some time for the client status to show as UP. Click the Client to see more details about it. Select Overview >> Services and you will see the following statuses about the client.

This confirms that the client is sending stats correctly to the Icinga master server.

Conclusion

This concludes our tutorial on installing Icinga Monitoring Software on a Debian 12 server and configuring it to monitor a client machine running the same Operating system. If you have any questions, post them in the comments below.

<!–

 

 

–>

RELATED ARTICLES

LEAVE A REPLY

Please enter your comment!
Please enter your name here


Most Popular