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

* Documentation : <https://docs.icinga.com/>

[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 2 qui a été complètement ré-écrite.

Après avoir utilisé Nagios pendant plus de 10 ans, nous utilisons désormais Icinga.

_Cette documentation concerne Icinga version 2._

## Installation

Sur Debian 9, tous les paquets (*icinga2* et *icingaweb2*) sont disponibles dans les dépôts officiels.

> *Note* Pour Debian 8, il faut utiliser les paquets du dépot packages.icinga.com car l'interface web n'est pas présente.
>
>~~~
># echo 'deb http://packages.icinga.com/debian icinga-jessie main' >/etc/apt/sources.list.d/icinga.list
># wget http://packages.icinga.com/icinga.key -O /etc/apt/trusted.gpg.d/icinga.asc
>
># cat /etc/apt/preferences.d/icinga2 
>Package: *
>Pin: release a=icinga-jessie
>Pin-Priority: 50
>
>Package: icinga2 icinga2-bin icinga2-common icinga2-ido-mysql libicinga2
>Pin: release a=jessie-backports
>Pin-Priority: 950
>
>Package: icingaweb2 icingaweb2-common icingaweb2-module-monitoring php-icinga icingacli
>Pin: release a=icinga-jessie
>Pin-Priority: 950
>~~~

~~~
# apt install icinga2

# icinga2 --version
icinga2 - The Icinga 2 network monitoring daemon (version: r2.6.3-1)

Copyright (c) 2012-2017 Icinga Development Team (https://www.icinga.com/)
License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl2.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Application information:
  Installation root: /usr
  Sysconf directory: /etc
  Run directory: /run
  Local state directory: /var
  Package data directory: /usr/share/icinga2
  State path: /var/lib/icinga2/icinga2.state
  Modified attributes path: /var/lib/icinga2/modified-attributes.conf
  Objects path: /var/cache/icinga2/icinga2.debug
  Vars path: /var/cache/icinga2/icinga2.vars
  PID path: /run/icinga2/icinga2.pid

System information:
  Platform: Debian GNU/Linux
  Platform version: 8 (jessie)
  Kernel: Linux
  Kernel version: 3.16.0-4-amd64
  Architecture: x86_64

Build information:
  Compiler: GNU 4.9.2
  Build host: smithers
~~~

## Architecture

Icinga peut avoir différents rôles :

* nœud **master** : serveur central
* nœud **satellite** : serveur dans une zone différente rattaché au nœud master
* nœud **client** : serveur chargé de lancer des commandes locales (semblable à un serveur *nrpe*)

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.


## Configuration

~~~
/etc/icinga2
├── conf.d
│   └── *.conf
├── constants.conf
├── features-available
│   └── *.conf
├── features-enabled
│   └── *.conf
├── icinga2.conf
├── init.conf
├── pki
├── repository.d
│   └── README
├── scripts
│   ├── mail-host-notification.sh
│   └── mail-service-notification.sh
├── zones.conf
└── zones.d
    └── README
~~~

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_).


## Configuration nœud 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.

~~~
# icinga2 node wizard
Welcome to the Icinga 2 Setup Wizard!
We'll guide you through all required configuration details.


Please specify if this is a satellite setup ('n' installs a master setup) [Y/n]: n
Starting the Master setup routine...
Please specify the common name (CN) [icinga2-master]:  
Checking for existing certificates for common name 'icinga2-master'...
Certificates not yet generated. Running 'api setup' now.
information/cli: Generating new CA.
[...]
Done.

Now restart your Icinga 2 daemon to finish the installation!

# systemctl restart icinga2
~~~

## Configuration interface web

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

La base de données sert :

* au module IDO : pour dumper l'état d'Icinga (informations de configuration, statut des hôtes et services, etc.)
* à l'interface web pour gérer les utilisateurs et groupes (facultatif)

~~~
# 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 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`

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

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

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

~~~
# 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 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`.

L'interface web est désormais accessible via <http://monitoring.example.org/icingaweb2/>


## Configuration client

Pour surveiller un équipement, il faut installer Icinga (nœud client) ou s'appuyer sur d'autres protocoles (NRPE, SSH, SNMP).

### Surveiller un équipement avec Icinga (nœud client)

Quand on installe Icinga sur un équipement, le daemon est lancé et se met à surveiller l'hôte local.
On va configurer de manière minimale pour juste le rattacher au nœud master et c'est le master qui va décider comment utiliser la machine.

On utilise l'assistant de configuration (_note_: les autres commandes `icinga2 node <paramètre>` sont dépréciées) :

~~~
# icinga2 node wizard
Welcome to the Icinga 2 Setup Wizard!
We'll guide you through all required configuration details.

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 13 00 DE DB EE F0 00 16 45 2A 14 F5 00 CA FE

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]: y
~~~

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

~~~
# icinga2 pki ticket --cn '<nom du client>'
~~~

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 :

~~~
[...]

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 ! On peut maintenant configurer les checks via le master.

> *Note* : nous n'avons pas encore configuré de test sur le client, il est normal qu'il n'apparaisse pas sur l'interface web.


#### mode top down command endpoint (exécution de commande)

<https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/distributed-monitoring#distributed-monitoring-top-down-command-endpoint>

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

#### mode bottom up config sync (checks envoyés vers le master)

<https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/distributed-monitoring#distributed-monitoring-bottom-up>

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

<https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/distributed-monitoring#distributed-monitoring-top-down-config-sync>

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.



#### Cas A - Client avec configuration centrale sur le master

Dans ce premier cas, les fichiers de configuration sont présents et 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" {
  import "generic-host"

  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 Icinga sur le master :

~~~
# systemctl reload icinga2
~~~

> *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…))
* L'appartenance à des groupes
* La présence d'attributs personnalisé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'adresse et dont l'attribut vars.os a pour valeur "linux".

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

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

#### Cas B - Configuration en pont d'éxécution de commandes

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.

Ainsi, on peut définir dans un fichier `icinga2-client2.conf` :

~~~
object Host "icinga2-client2" {
  import "generic-host"

  check_command = "hostalive"
  address = "192.0.2.20"
}

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

  command_endpoint = "icinga2-client2"
  host_name = "icinga2-sclient2"
  check_command = "disk"
}

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

  command_endpoint = "icinga2-client2"
  host_name = "icinga2-sclient2"
  check_command = "ssh"
}
~~~

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.


### Surveiller un équipement sans Icinga (NRPE, SSH, etc.)

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.

~~~
object Host "no-icinga2-host" {
  import "generic-host"

  check_command = "hostalive"
  address = "192.0.2.10"
}
~~~

#### Utilisation de NRPE

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.

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

~~~
object Host "no-icinga2-host" {
  import "generic-host"

  check_command = "hostalive"
  address = "192.0.2.30"
}

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

  host_name = "no-icinga2-host"

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

#### Utilisation de SSH

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.

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 = "no-icinga2-host"
  check_command = "by_ssh_swap"
  vars.by_ssh_logname = "icinga"
}
~~~

> *Cool fact* : on peut même faire du NRPE par SSH (dans le cas d'une machine en NAT ou avec un firewall assez restrictif). 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"
}
~~~


## Configuration avancée

### Zone globale

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 :

~~~
object Zone "global-templates" {
  global = true
}
~~~

### Envoi de notifications

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

~~~
apply Notification "mail" to Service {
  import "mail-service-notification"

  users = ["foo"]
  states = [ Critical, Unknown ]
  period = "9to5"

  assign where true
}
~~~

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.

~~~
object User "foo" {
  import "generic-user"

  display_name = "Foo"
  email = "foo@example.net"
}
~~~

### Timeperiods

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.

~~~
object TimePeriod "HO" {
  import "legacy-timeperiod"

  display_name = "Heures Ouvrées"
  ranges = {
    "monday"    = "09:00-12:00,14:00-18:00"
    "tuesday"   = "09:00-12:00,14:00-18:00"
    "wednesday" = "09:00-12:00,14:00-18:00"
    "thursday"  = "09:00-12:00,14:00-18:00"
    "friday"    = "09:00-12:00,14:00-18:00"
  }
}
~~~

### Contrôle de santé du cluster

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.

Exemple avec *cluster-zone* :

~~~
# cat /etc/icinga2/zone.d/icinga2-master/cluster.conf

apply Service "cluster-health" {
  check_command = "cluster-zone"

  display_name = "cluster-health-" + host.name
  vars.cluster_zone = host.name

  assign where host.vars.client_endpoint
}
~~~

### Haute disponibilité

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.

Modules avec des fonctions de haute disponibilité :

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


### Gestion de la PKI - Génération manuelle des certificats

Dans certains cas, on peut être amené à générer manuellement le certificat TLS pour l'authentification d'un nouveau nœud.

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

~~~
# icinga2 pki new-cert --cn icinga2-client2 \
  --key icinga2-client2.key \
  --csr icinga2-client2.csr
~~~

En suite, depuis le master, on génère le certificat avec la CSR.

~~~
# icinga2 pki sign-csr --csr icinga2-client2.csr --cert icinga2-client2
~~~

Il ne reste plus qu'a rapatrier les fichiers `/etc/icinga2/pki/icinga2-client2.*` sur la machine désignée.

## API

### Scripts Perl

Sur une debian Jessie :

~~~
# apt install libconfig-inifiles-perl
# cpan install REST::Client
~~~

[Exemples en Perl](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api#icinga2-api-clients-programmatic-examples-perl)

## FAQ

### Que veut-dire « Icinga » ?

C'est un mot zulu signifiant « il recherche » ou « il examine ».

### plugin Vim pour la syntaxe de la configuration d'Icinga

Tous les fichiers de configuration utilisent la même syntaxe. Il existe un plugin vim pour cette dernière :

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

### Existe-t-il un log des évènements ?

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 : 

~~~
# mkdir -p /usr/local/share/icingaweb2/modules/
# cd /usr/local/share/icingaweb2/modules/
# git clone https://github.com/Icinga/icingaweb2-module-generictts.git generictts

# ln -s /usr/local/share/icingaweb2/modules/generictts /etc/icingaweb2/enabledModules/generictts
~~~

Vous n'avez plus qu'a vous rendre dans l'interface pour voir que le plugin est bien activé.


### Erreur `mux_client_request_session` Session open refused by peer

Sur l'interface web, on peut voir l'erreur suivante :

~~~
Remote command execution failed: mux_client_request_session: session request failed: Session open refused by peer
~~~

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. 

## Liens

[https://www.icinga.com/category/technical/api/](https://www.icinga.com/category/technical/api/)

[https://docs.icinga.com/icinga2/latest/doc/module/icinga2/toc](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/toc)

### API

[https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api#icinga2-api-clients-cli-console](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api#icinga2-api-clients-cli-console)