---
categories: monitoring
title: Howto Icinga
---

## Introduction

Icinga2 est un logiciel de monitoring réseau qui vise à surveiller des services en place sur des serveurs.

Icinga2 se veut un remplacement pour Icinga, un fork bien établit de Nagios. Contrairement à Icinga, qui reprenait une partie du code de Nagios et qui avait un système de configuration compatible, Icinga2 a été complètement réécrit et n'est pas compatible avec Nagios.

## Structure de l'infrastructure de monitoring

Il existe plusieurs manières de déployer Icinga2 pour surveiller un ensemble de machines. Icinga est assez flexible et permet de contruire des architectures distribuées ou centralisées en fonction des besoins. Pour mieux s'y retrouver, on peut donner des noms aux machines (aka noeuds) qui hébergent une instance de icinga2 en fonction de leur utilité :

* Noeud master : Il est en haut de la hierarchie. C'est la machine centrale du cluster.
* Noeud satellite : C'est un fils d'un master ou d'un autre satellite.
* Noeud client : Il est en bas de la hierarchie, connecté a un satellite ou un master. Il agit comme un agent.

![Illustration des noms des rôles dans icinga2](howtoicinga_distributed_roles.png)

A noter que cette hiérarchie s'applique en premier lieux à des `zones`, les noeuds étant membres d'une seule zone. Habituellement une zone contient un seul noeud et porte le même nom que celui-ci par convention. Mais pour un master ou des satellites, on peut être amené à placer plusieurs noeuds dans une même zone pour les faire travailler ensemble en mode haute disponibilité et répartition de charge. La notion de `zones` est très importante en mode cluster, car c'est elles qui sont directement configués, les machines récupérant la configuration de la `zone` qui leur a été attribuée

Pour configurer le cluster il existe 3 méthodes différentes, toutes les trois s'appuyant sur la présence de l'agent icinga2 sur les machines du cluster.

A noter qu'il est aussi possible de surveiller des services sans la présence de l'agent icinga2. Pour cela on pourra s'appuyer sur d'autres protocoles SNMP, SSH, NRPE pour exécuter de manière distante un check.

### Configuration locale (bottom up config sync)

**Attention, cette méthode est dépréciée depuis la sortie de la versions 2.6**

Dans ce mode de configuration, les machines locales sont configurées pour se surveiller elles-mêmes et remonter les résultats des checks. La configuration réside sur les machines locales et est synchronisée vers le serveur central.

L'avantage de cette méthode est que les clients locaux peuvent écrire leurs configurations directement sans à avoir à passer par une gestion centralisée des tests et des configurations.

Plus [d'infos dans la documentation officielle (en anglais)](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/distributed-monitoring#distributed-monitoring-bottom-up).

### Configuration centrale (top down config sync)

Le principe de la configuration en cluster est semblable à celui de la configuration locale. La seule différence est que la configuration des machines locales est faite sur le serveur central. Lorsque l'on redémarre le daemon, le serveur central s'assure que les machines locales ont la bonne configuration. Plutôt d'aller « du bas vers le haut » on va donc « du haut vers le bas ».

Cette méthode est idéale si l'on souhaite centraliser l'ensemble de notre configuration.

Plus [d'infos dans la documentation officielle (en anglais)](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/distributed-monitoring#distributed-monitoring-top-down-config-sync).

### Pont d'exécution de commandes (top down command endpoint)

Avec la méthode du pont d'exécution de commandes, l'ensemble des configurations sont sur le serveur central et y restent. Il n'y a pas de synchronisation de configuration avec les machines locales. Quand le serveur central souhaite effectuer un test sur une machine locale, il la lance directement sur cette dernière au travers de l'agent local icinga2. Le seul pré-requis est que les objets de type `CheckCommand` définissant les commandes à exécuter doivent être présent localement (i.e. là où la commande est exécutée). Le principe est similaire à NRPE.

Cela implique cependant que les machines locales doivent accepter des commandes directement du serveur central.

Plus [d'infos dans la documentation officielle (en anglais)](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/distributed-monitoring#distributed-monitoring-top-down-command-endpoint).


## Installation

Dans la suite, on va détailler une installation classique avec un cluster en configuration centrale (top down configuration). On a donc un "master" (icinga2-master, 192.0.2.1) qui héberge `icinga2` avec toute la configuration du cluster et aussi l'interface web `icingaweb2` et un "client" (icinga2-client1, 192.0.2.10) qui va recevoir la configuration du master.

### Installation du master

#### Icinga2

L'installation d'`icinga2` sur le master est relativement simple. Cependant, la documentation disponible en ligne conseille d'utiliser les paquetages officiels disponible sur les dépôts proposés par les développeurs.

~~~
# wget -O - http://packages.icinga.com/icinga.key | apt-key add -
# echo 'deb http://packages.icinga.com/debian icinga-jessie main' >/etc/apt/sources.list.d/icinga.list
# apt update
# apt install icinga2
~~~

Pour finaliser l'installation d'icinga2 en master, il faut se servir de son assistant de configuration. Il se chargera de créer une CA pour l'authentification avec les autres instances `icinga2` du cluster et activer l'API. La commande qui suit lance un assistant d'installation. Mis à part la première option où il faut répondre `n`, les autres peuvent être laissées vides pour conserver les valeurs par défaut:

~~~
# icinga2 node wizard
~~~

Après l'exécution de l'assistant, notre master est configuré dans une zone ayant le même nom que lui. On termine par un redémarrage complet du daemon pour activer les changements de la configuration.

~~~
# service icinga2 restart
~~~

### WebUI

Pour fonctionner, la WebUI a besoin d'un serveur web avec PHP et d'un serveur de bases de données (MySQL ou PostgreSQL). Dans la suite de l'exemple, nous utiliseront [/HowtoApache]() et [/HowtoLAMP/MySQL]().

Ici, MySQL va servir à 2 choses :

* Sauvegarder les utilisateurs & groupes de l'interface Web
* Contenir les informations de configuration d'icinga2, le status des hôtes et des services... qui sont mis à jour par le module `ido-mysql` d'icinga2

~~~
# apt update
# apt install icingaweb2 icinga2-ido-mysql
~~~

*Note* : Le paquetage `icinga2-ido-mysql` fournit un assistant d'installation pour configurer une base de données et un utilisateur MySQL automatiquement. Si on le souhaite, il est également possible de le faire manuellement. Il faut alors se charger de créer une base de données, un utilisateur ayant les accès à celle-ci et importer le schéma des tables. Les paramètres sont alors à écrire dans `/etc/icinga2/features-available/ido-mysql.conf` et le schéma des tables à importer est dans `/usr/share/icinga2-ido-mysql/schema/mysql.sql`

Une fois l'installation terminée, il est nécessaire d'activer le module `ido-mysql` d'icinga2 :

~~~
# icinga2 feature enable ido-mysql
# service icinga2 restart
~~~

Il est possible de lancer des commandes (planifier un check, downtimer une machine...) à partir du WebUI directement. Pour cela, il faut ajouter à l'utilisateur du serveur web au groupe `nagios`.

~~~
# addgroup --system www-data nagios
# icinga2 feature enable command
# service icinga2 restart
~~~

*Note* : Il est aussi possible de contrôler icinga2 directement via son API. Cela est pratique notament dans le cas où l'interface web n'est pas sur la même machine. Il faut à ce moment là créer un utilisateur API avec un couple login/pass et les renseigner dans la configuration de l'interface web.

Pour continuer l'installation du WebUI, il faut aller la page suivante <http://example.org/icingaweb2/setup>. L'installeur va nous demander un token. On peut créer ce token avec la commande suivante :

~~~
# icingacli setup token create
~~~

La prochaine étape de l'assistant vous demande quelles fonctions activer. Il faut au moins activer `Monitoring` (sinon, l'interface web perd tout son intérêt!).

L'assistant lance ensuite une série de tests. Il est important de s'assurer que tous les tests sont OK. Il est normal que les tests PostgreSQL s'affichent en jaune, car on utilise MySQL.

`Icingaweb2` offre plusieurs backends d'authentification. Pour une grande organisation, il est préférable d'utiliser le backend LDAP. Mais pour quelques comptes, il est cependant plus simple d'utiliser le backend basé sur une base de données.

Si l'on choisit un backend base de données, il suffit de renter les informations d'authentification que l'on souhaite avoir. La WebUI va ensuite nous informer que la base de données n'existe pas encore et nous demander le mot de passe administrateur pour en créer une pour nous. Encore une fois, il est possible de faire cela directement en ligne de commande avec MySQL.

Après avoir finalisé les informations pour l'authentification, il vous faudra donner au WebUI l'accès à la base de données créée précédemment pour `icinga2`. Si vous avez utilisé l'assistant de configuration du paquetage `icinga2-ido-mysql`, vous pourrez retrouver directement les informations d'authentification à MySQL utilisé par icinga2 dans `/etc/icinga2/features-available/ido-mysql.conf`.

Et voilà! Votre WebUI devrait être en place et vous devriez pouvoir vous connecter au <http://example.org/icingaweb2/>

## Installation d'un client

### Configuration du lien master-client

Par défaut, quand on installe icinga2 sur une machine, le daemon est lancé et icinga2 se met à surveiller l'hôte local. Pour cette documentation, nous allons monter une architecture de surveillance de type [configuration en cluster](#Configurationencluster). Cela va nous permettre de pouvoir centraliser la configuration à un seul endroit et de la gérer à travers git.

**Attention!** La seule commande `icinga2 node <paramètre>` que l'on devrait exécuter avec ce type de configuration est `icinga2 node wizard` au tout début du processus d'installation.

Malgré les apparences, les commandes `icinga2 node update-config` ou encore `icinga2 node add` s'appliquent à une configuration de type locale. De plus, ces commandes sont dépréciées.

On commence donc par installer `icinga2` :

~~~
# wget -O - http://packages.icinga.com/icinga.key | apt-key add -
# echo 'deb http://packages.icinga.com/debian icinga-jessie main' >/etc/apt/sources.list.d/icinga.list
# apt update
# apt install icinga2
~~~

Une fois que cela est fait, on lance l'assistant de configuration :

~~~
# icinga2 node wizard
~~~

L'assistant nous pose plusieurs questions. On y répond de la manière suivante :

~~~
Please specify if this is a satellite setup ('n' installs a master setup) [Y/n]: y
Starting the Node setup routine...
Please specifiy the common name (CN) [icinga2-client1]:
Please specify the master endpoint(s) this node should connect to:
Master Common Name (CN from your master setup): icinga2-master
Do you want to establish a connection to the master from this node? [Y/n]: y
Please fill out the master connection information:
Master endpoint host (Your master's IP address or FQDN): 192.0.2.1
Master endpoint port [5665]:
Add more master endpoints? [y/N]: n
Please specify the master connection for CSR auto-signing (defaults to master endpoint host):
Host [192.0.2.1]:
Port [5665]:
information/base: Writing private key to '/etc/icinga2/pki/icinga2-client1.key'.
information/base: Writing X509 certificate to '/etc/icinga2/pki/icinga2-client1.crt'.
information/cli: Fetching public certificate from master (192.0.2.1, 5665):

Certificate information:

 Subject:     CN = icinga2-master
 Issuer:      CN = Icinga CA
 Valid From:  Aug 15 21:03:54 2016 GMT
 Valid Until: Aug 12 21:03:54 2031 GMT
 Fingerprint: 13 37 FF 42 00 A6 D6 DE DB EE F6 73 16 45 2A 14 F5 24 05 11

Is this information correct? [y/N]: y
information/cli: Received trusted master certificate.

Please specify the request ticket generated on your Icinga 2 master.
 (Hint: # icinga2 pki ticket --cn 'icinga2-sclient1'): ed347c9f5c4c1a08f811bf2032944d01c48979a
information/cli: Requesting certificate with ticket 'ed347c9f5c4c1a08f811bf2032944d01c48979a'.

information/cli: Writing signed certificate to file '/etc/icinga2/pki/icinga2-client1.crt'.
information/cli: Writing CA certificate to file '/etc/icinga2/pki/ca.crt'.
Please specify the API bind host/port (optional):
Bind Host []:
Bind Port []:
Accept config from master? [y/N]: y
Accept commands from master? [y/N]: n
~~~

À noter qu'à l'étape où l'assistant demande le ticket généré sur le master, il faut exécuter la commande suivante sur le master et copier l'output dans l'assistant :

~~~
icinga2 pki ticket --cn '<nom du client>'
~~~
Après l'exécution de l'assistant, l'instance icinga2 est réglée comme appartenant à sa propre `zone` (ayant le même nom que lui). Cette `zone` est fille du master renseigner lors de l'assistant.
Si client reconnaît maintenant le master, il est nécessaire de configurer le master pour qu'il reconnaisse le client. On va donc modifier le fichier `zones.conf` sur le master y ajouter la `zone` et le `endpoint` du nouveau client :

~~~
[...]

object Endpoint "icinga2-client1" {
  host = "192.0.2.10"
}

object Zone "icinga2-client1" {
  endpoints = [ "icinga2-client1" ]
  parent = "master"
}
~~~

Et voilà ! En théorie, le master et le client peuvent se parler ! Comme nous n'avons pas encore configuré de test sur le nouveau client, il est normal qu'il n'apparaisse pas dans la WebUI.

### Ajout de tests sur le client depuis le master

Avec le type de configuration que l'on a choisi, les fichiers de configuration sont modifiés sur le master, qui les synchronise sur le(s) client(s).
Nous allons donc ajouter nos tests sur le master dans `zones.d`, le dossier prévu à cet effet. On commence par y créer un nouveau dossier correspondant à la zone (donc le client appartenant à celle-ci) que l'on souhaite configurer :

~~~
# mkdir /etc/icinga2/zones.d/icinga2-client1
~~~

Dans ce dossier, on crée un fichier nommé `hosts.conf` qui va nous servir à définir un nouvel objet de type `Host`. Cet objet va nous permettre par la suite de lier d'autres types d'objets à notre nouveau client :

~~~
object Host "icinga2-client1" {
  check_command = "hostalive"

  address = "192.0.2.10"
}
~~~

On peut maintenant ajouter de nouveaux tests dans `services.conf`, des objets de type `Service` :

~~~
object Service "disk" {
  import "generic-service"

  host_name = "icinga2-sclient1"
  check_command = "disk"
}

object Service "ssh" {
  import "generic-service"

  host_name = "icinga2-sclient1"
  check_command = "ssh"
}
~~~

Pour que la synchronisation se fasse entre le master et le client, on redémarre `icinga2` sur le master :

~~~
# service icinga2 reload
~~~

*Note* : Si, pour une raison ou une autre, la configuration venait à être invalide lors du reload, celui-ci va être avorté. Mais icinga2 va continuer de fonctionner avec l'ancienne configuration valide chargée avant. En effet, il contrôle la configuration avant de demander au daemon de s'arréter.

*Note* : Pour controler la syntaxe de la configuration, on peut utiliser la commande `service icinga2 checkconfig` ou `icinga2 daemon --validate`

Si tout s'est passé correctement, vous devriez voir apparaître une nouvelle machine dans le WebUI, accompagné de trois nouveaux services, `ping4`, `disk` et `ssh`.

A noter que cette méthode de configuration est assez fastidieuse étant donné que l'on doit déclarer chaques services pour chaques machines. Ainsi, on tendra a préviligier l'utilisation de gabarits que l'on va ensuite appliquer sur les machines en fonctions de règles. Ces règles peuvent être basées sur :

* Des conventions de nommage des machines (i.e. foo-mail -> correspond à \*-mail -> Application de services propres à un serveur mail (SMTP, IMAP, mailq...))
* L'appartenance à des groupes
* La présence d'attributs personalisés sur l'hôte

Ainsi, à place de définir 1000 services ssh pour 1000 machine linux, on va définir une fois le service ssh et l'appliquer aux 1000 machines. Dans l'exemple suivant, on va ainsi appliquer le service ssh aux machines dont on connait l'addresse et dont l'attribut personalisé de `os` a pour valeur "linux".

~~~
apply Service "ssh" {
  import "generic-service"

  check_command = "ssh"
  assign where host.address && host.vars.os == "Linux"
}
~~~


## Plomberie

### Dossiers par défaut d'icinga2

* `/etc/icinga2` Dossier des fichiers de configuration
* `/usr/share/icinga2/include` Dossier des templates & commandes par défaut
* `/var/lib/icinga2` Dossier de "travail" d'`icinga2`, contient la CA, les logs cluster, la configuration chargée et/ou reçue, un fichier dump de l'état du cluster

### Fichiers de configuration

Les fichiers de configuration se trouvent dans `/etc/icinga2`. Tous les fichiers de configuration utilisent la même syntaxe. Il existe d'ailleurs un plugin vim pour cette dernière :

~~~
# apt -t jessie-backports install vim-icinga2
~~~

La configuration d'icinga2 se base principalement sur des objets de types différents. Par exemple, l'objet `Host` définit une machine (indépendament de la présence de l'agent icinga2) alors que l'objet `Service` sert à définir un service et il est rataché à une machine. On peut retrouver une description détaillée de tous les objets [ici (en anglais)](http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/object-types).

En général, l'emplacement des objets n'est pas réellement important. Dans l'exemple plus haut, on aurait ainsi pu ajouter l'objet `Host` dans le fichier `/etc/icinga2/zones.d/icinga2-client1/foo_bar.conf` au lieu de `/etc/icinga2/zones.d/icinga2-client1/hosts.conf`. C'est cependant un bonne pratique de séparer clairement ses différents objets en fichiers nommés de manière claire.


#### init.conf

Le premier fichier à être lu au démarrage du daemon. Il sert à définir sous quel groupe et quel user le daemon est lancé.

*Note* : Sous Debian 8, icinga2 fonctionne sous l'utilisateur et le groupe `nagios`

#### icinga2.conf

Le fichier de configuration principal. Il sert surtout à définir les fichiers de configuration qui seront lus, comme `/features-enabled/*` par exemple. Ce fichier est le second à être lu au démarrage du daemon.

*Note* : En configuration en cluster, une bonne pratique est de commenter l'inclusion du dossier `conf.d` et de placer la totalité de la configuration dans les zones qui seront déployées.

#### constants.conf

Ce fichier regroupe les constantes globales d'Icinga2. On y trouve entre autres le Salt pour la génération de tokens et le nom de domaine du master (`NodeName`).

#### zones.conf

Ce fichier sert à définir les relations entre le master et les clients, comme démontré dans l'exemple de configuration plus haut.

#### features-available

Les fichiers dans ce dossier sont des plugins qui peuvent être activés avec les commandes suivantes :

~~~
# icinga2 feature enable <nom du plugin>
# service icinga2 reload
~~~

Une fois activés, ils sont symlinkés dans `/features-enabled`, un peu comme pour Apache.

#### pki/

Ce dossier regroupe les fichiers du Public Key Infrastructure (PKI), qui servent de base d'authentification entre les clients et le master.
Dans le cas du master, la clé privée de la CA se trouve dans `/var/lib/icinga2/ca/`

#### scripts/

Ce dossier regroupe les différents scripts qui sont lancés lors d'événements. Par exemple, c'est ici que l'on ajouterais de nouveaux scripts à être lancé pour des objets de type `EventCommand`.

#### conf.d/

Ce dossier regroupe de base la configuration standard de l'instance icinga2. Quand on travaille en mode cluster, il est préférable de ne pas prendre appui dessus (en commentant la ligne d'inclusion dans le fichier `icinga2.conf`). A place on va mettre la totalité de la configuration dans les zones à fin qu'elle contrôlable et déployée depuis le master.

*Note* : On peut néanmoins copier son contenu dans le dossier de la zone du master et s'en servir comme base pour construire sa configuration.

#### repository.d/

`repository.d` regroupe les configurations des clients lors d'une synchronisation de type locale.

#### zones.d/

Dans une configuration en mode cluster, ce dossier héberge sur le master la totalitée des configurations déployées dans des sous dossier. Chaque sous dossiers contient la configuration de la zone ayant le même nom.

### Utilisation de NRPE

Lors d'une migration de `nagios` vers `icinga2`, il peut être intéréssant de supporter tout les checks fait par NRPE pour fluidifier la transition vers la nouvelle plateforme.

Pour cela, il faut d'abord récupérer le client `NRPE` :

~~~
# apt install nagios-nrpe-plugin
~~~

En suite, il suffit juste de créer les services dans la configuration du master pour paramettrer les checks voulu. L'exemple suivant crée un service `swap` pour la machine `remote-nrpe-host` qui exécutera la commande `check_swap` par NRPE.

~~~
object Service "nrpe-swap" {
  import "generic-service"

  host_name = "remote-nrpe-host"

  check_command = "nrpe"
  vars.nrpe_command = "check_swap"
}
~~~

### Utilisation de SSH

Dans certaines situations, l'utilisation de NRPE, ou icinga2 n'est pas possible (restrictions firewall, NAT...). Dans ces cas là, on peut aussi exécuter des commandes via une connexion SSH.

Quelques pré-requis avant :

* L'utilisateur du daemon icinga2 doit avoir une clé ssh pour s'authentifier. Celle-ci doit être autorisée par l'hôte distant.
* Le daemon doit avoir l'empreinte du serveur ssh dans son known_hosts. (Sinon, il refusera de se connecter)
* Les scripts/plugins/commandes à exécuter doivent être présents sur la machine et exécutables par l'utilisateur utilisé par icinga2

Avec ces pré-requis, il suffit alors de définir une commande de check important l'objet `by_ssh` fournit avec icinga2. Ensuite, il suffit d'utiliser cette commande lors de la définition des services

~~~
object CheckCommand "by_ssh_swap" {
  import "by_ssh"

  vars.by_ssh_command = "/usr/lib/nagios/plugins/check_swap -w $by_ssh_swap_warn$ -c $by_ssh_swap_crit$"
  vars.by_ssh_swap_warn = "75%"
  vars.by_ssh_swap_crit = "50%"
}

object Service "swap" {
  import "generic-service"

  host_name = "remote-ssh-host"
  check_command = "by_ssh_swap"
  vars.by_ssh_logname = "icinga"
}
~~~

*Cool fact* : on peut donc faire du NRPE par SSH (dans le cas d'une machine en NAT). Exemple :

~~~
object CheckCommand "nrpe_via_ssh" {
  import "by_ssh"

  vars.by_ssh_command = "/usr/lib/nagios/plugins/check_nrpe -H $host.vars.internalIP$ $service.vars.nrpe_command$"
  vars.by_ssh_logname = "monitoring"

}

apply Service "ssh-nrpe-load" {
  import "generic-service"

  check_command = "nrpe_via_ssh"
  vars.nrpe_command = "-c check_load"
  vars.notification_period = "worktime"

  assign where host.vars.service_base && host.check_command == "nrpe_via_ssh"
}
~~~