[Icinga](https://www.icinga.com/) est un logiciel libre de surveillance système et réseau d'équipements. Au départ (en 2009), c'est un fork de [Nagios](https://www.nagios.com/) avec pour objectifs davantage d'évolutivité et une interface web plus moderne. La version 1 d'Icinga a une configuration compatible avec Nagios, ce qui n'est pas le cas de la version 2qui a été complètement ré-écrite.
On peut donc découper la configuration Icinga en différentes zones : la zone principale avec le(s) nœud(s) master et des zones secondaires pour les nœuds satellite. Cette notion de zone permet par exemple d'avoir des nœuds satellite répartis dans plusieurs pays. Si l'on utilise un nœud client, il aura généralement sa propre zone.
La configuration d'Icinga se base sur des objets de types différents : l'objet **Host** définit une machine surveillée alors que l'objet **Service** définit un service rattaché à une machine. Voir [description détaillée de tous les objets](http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/object-types).
Le nom des fichiers contenant les objets n'est pas important, mais une bonne pratique est de séparer ses objets dans des fichiers du type `/etc/icinga2/zones.d/<ZONE>/hosts.conf` et `/etc/icinga2/zones.d/<ZONE>/services.conf` (s’il n'y a qu'une zone, on peut l'appeler _master_).
On utilise l'assistant de configuration : il se chargera d'activer l'API et de créer une autorité de certification pour l'authentification avec les éventuels autres nœuds.
L'interface web a besoin d'un serveur web avec PHP : nous utilisons [Apache](HowtoApache) ; d'un accès à l'API Icinga et du module IDO qui va stocker les informations dans une base de données : nous utilisons [MySQL](HowtoMySQL).
> *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 le faire manuellement, les paramètres sont stockés dans le fichier `/etc/icinga2/features-available/ido-mysql.conf` et le schéma des tables est dans `/usr/share/icinga2-ido-mysql/schema/mysql.sql`
Il est possible de lancer des commandes (planifier un check, downtimer une machine…) à partir de l'interface web directement. Pour cela, il faut ajouter à l'utilisateur du serveur web au groupe **nagios**.
> *Note* : Il est aussi possible de contrôler icinga2 directement via son API. Cela est pratique notamment 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 de l'interface web, il faut aller sur <http://monitoring.example.com/icingaweb2/setup>, un token sera demandé qui peut être créé avec la commande `icingacli setup token create`.
La prochaine étape de l'assistant demande quelles fonctions activer : il faut au moins activer le module **Monitoring** sinon l'interface web perd 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).
Pour le paramétrage de l'authentification à l'interface web, on peut utiliser la base de données utilisé par le module IDO ou avoir d'autre backend (LDAP, etc.).
L'assistant va ensuite avoir besoin des paramètres d'accès à la base de données, on pourra réutiliser les paramètres utilisés pour IDO via le fichier `/etc/icinga2/features-available/ido-mysql.conf`.
> *Note* : Pour contrôler l'empreinte du certificat de la machine à laquelle on se connecte, on peut utiliser la commande `openssl x509 -noout -in /etc/icinga2/pki/icinga2-master.crt -fingerprint -sha1`
À 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 :
Après l'exécution de l'assistant, l'instance Icinga est réglée comme appartenant à sa propre *zone*. 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 :
C'est la méthode la plus simple, similaire à NRPE : le nœud master souhaitant effectuer un check, il lance une commande au travers de l'agent local icinga2 installé. Le seul pré-requis est que les objets de type **CheckCommand** définissant les commandes à exécuter doivent être présent sur le master **et** localement (i.e. là où la commande est exécutée).
_Attention, cette méthode est dépréciée depuis la sortie de la version 2.6 et devrait être [retirée dans une future version](https://github.com/Icinga/icinga2/issues/4799)_
Avec cette méthode, les équipements sont configurés pour se surveiller eux-mêmes et remonter les résultats des checks. La configuration réside sur les machines locales et est synchronisée vers le nœud master.
#### mode top down config sync (checks envoyés vers le master)
Le principe est semblable à la méthode précédente, la 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 permet de centraliser l'ensemble de notre configuration.
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 :
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 :
> *Note* : Si, pour une raison ou une autre, la configuration venait à être invalide lors du reload, celui-ci va être avorté. Mais Icinga 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. Pour contrôler la syntaxe de la configuration, on peut d'ailleurs utiliser la commande `icinga2 daemon --validate`
Si tout s'est passé correctement, vous devriez voir apparaître une nouvelle machine dans l'interface web, accompagné de deux nouveaux services : *disk* et *ssh*.
À noter que cette méthode de configuration est assez fastidieuse étant donné que l'on doit déclarer chaque services pour chaque machines. Ainsi, on tendra à privilégier 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…))
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'adresse et dont l'attribut vars.os a pour valeur "linux".
Dans ce cas, toute la configuration va rester sur le nœud master (et donc dans le dossier `/etc/icinga2/zone.d/master/`). C'est le master qui va planifier l'exécution des checks.
La définition de l'hôte et des services est quasi identique au cas précédent. Cependant, il faut ajouter l'attribut **command_endpoint** aux objets de type *Service* pour definir l'*Endpoint* qui doit être commandé pour exécuter la commande.
Comme annoncé plus haut, il est aussi possible de surveiller une machine qui n'aurait pas Icinga par d'autres moyens comme NRPE ou SSH. La commande de l'exécution des checks devra alors être prise en charge par un nœud du cluster Icinga. Idéalement, un *master* ou un *satellite*. Ainsi, la configuration proposée doit être entreposée dans le dossier de la zone qui aura la charge de la surveillance de la machine.
Lors d'une migration de *Nagios* vers *Icinga*, il peut être intéressant de supporter tous les checks fait par NRPE pour fluidifier la transition vers la nouvelle plateforme.
En suite, il suffit juste de créer les services dans la configuration du master pour paramétrer les checks voulu. L'exemple suivant crée un service *swap* pour la machine *no-icinga2-host* décrite plus haut qui exécutera la commande *check_swap* par NRPE.
Dans certaines situations, l'utilisation de NRPE ou Icinga n'est pas possible (restrictions firewall, NAT…). Dans ces cas-là, on peut aussi exécuter des commandes via une connexion SSH.
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
Une bonne pratique est de créer une zone globale. Elle va ainsi permettre de pousser des fichiers de configuration sur tous les nœuds icinga2 du cluster. C'est pratique pour déployer des éléments de configuration générique et/ou globaux. Ainsi, si on appelle notre zone globale *global-templates*, il suffit de créer un dossier `/etc/icinga2/zone.d/global-templates` et d'ajouter le bloc suivant au fichier `/etc/icinga2/zone.conf` pour **chaque** installations d'icinga2 :
Contrôler le bon fonctionnement de services, c'est bien. Alerter en cas de défaillance c'est mieux !
On peut définir un objet notification qui sera appliqué a nos services pour envoyer des mails. Il utilisera le script d'envoi d'emails fournit avec icinga2
L'objet **Notification** 'mail' est définit pour envoyer une notification par courriel à l'utilisateur 'foo' lorsqu'un service est en état *Critical* ou *Unknown* sur la période *9to5* fournit dans la configuration par défaut.
On peut facilement décrire de nouveaux objets **Timeperiod** pour décrire par exemple les heures ouvrées et envoyer des notifications uniquement durant cette période. Ici, c'est défini du lundi au vendredi, de 9h à 12h et de 14h à 18h.
Une autre bonne pratique est de rajouter des checks pour s'assurer du bon fonctionnement de notre cluster. Il existe deux commandes utilisables qui sont complémentaires :
* cluster : Elle s'assure que tout les *endpoints* de la zone soient actifs et que les zones directement connectés fonctionnent correctement
* cluster-zone : Elle s'assure que la zone donnée en paramètres est bien connecté au cluster
Idéalement, il faut donc utiliser **cluster** pour des zones de plus d'une machine, et **cluster-zone** pour s'assurer que chaque zone filles fonctionnent bien. Dans notre cas on va utiliser des checks *cluster-health* depuis le master pour s'assurer que nos deux endpoints *icinga2-client1* et *icinga2-client2* soient bien connectés.
Dans certaines situations, on va vouloir mettre plusieurs instances Icinga dans une même zone à fin de les faire travailler ensemble et ainsi répartir la charge et avoir une tolérance de panne. Les modules d'Icinga sont capables de gérer la répartition entre chaque membre actifs d'une même zone.
* checker : Il va répartir l'exécution des checks entre chaque machine de la zone
* notification : De même, il peut répartir l'envoi des notifications entre chaque machine. C'est aussi désactivable avec le paramètre *enable_ha* - A ce moment-là chaque nœuds avec la fonctionnalité de notification active enverra une notification
* ido-{mysql,postgresql} : Là, les nœuds de la zone vont s'accorder pour qu'une seule instance écrive dans la base de données MySQL. Si l'instance en charge d'écrire est down, une autre prendra la relève. Désactivable avec le paramètre *enable_ha*
Pour ajouter un nouveau nœud une *zone* master, il suffit de l'installer normalement comme expliqué plus haut, puis d'ajuster le fichier `zone.conf` pour faire en sorte que les deux nœuds appartiennent bien à la même zone.
La commande suivante sert à générer une CSR, pour une machine "icinga2-client2". Elle peut être directement lancée sur la machine désignée ou depuis le master du cluster (si la machine monitorée n'a pas encore été provisionnée par exemple).
Par défaut, il n'y en a pas. Néanmoins, il existe un module *compatlog*, activable avec `icinga2 feature enable compatlog` qui permet de générer un log des évènements dans `/var/log/icinga2/compat/icinga.log`
### Comment ajouter des plugins sur l'interface web ?
L'interface icingaweb2 est elle aussi extensible via des plugins. Mais comme la grande partie d'entre eux n'est pas packagée, il faut les installer soi-même. Quelques modules bien connus sont référencés [sur le site d'icinga](https://www.icinga.com/products/icinga-web-2-modules/)
Ainsi, on veut installer le plugin [generictts](https://github.com/Icinga/icingaweb2-module-generictts), on va faire :
Il est possible que le `MaxSession` d'OpenSSH soit atteint. Voir la [page dédiée à OpenSSH](/HowtoOpenSSH#ssh-refuse-douvrir-une-session-ou-nombre-maximum-de-sessions-ssh-atteint) pour le changer.
### Comment ajouter un dashlet (onglet) dans icinga-web
Pour créer des nouvelles vues dans Icinga web à partir d'un filtre, appelé "dashlet" dans Inciga, vous pouvez suivre [cet article](https://icinga.com/blog/2021/01/27/creating-dashboards-based-on-custom-filters/) du blog d'Icinga.