From 6ec85a26b76f13a9ad5ea42bcc702db10af9ca79 Mon Sep 17 00:00:00 2001
From: cg-tw <83637804+cg-tw@users.noreply.github.com>
Date: Thu, 30 Jan 2025 10:23:37 +0100
Subject: [PATCH 1/2] EVent handler for Cloud

---
 cloud/monitoring/event-handler.md             | 187 +++++++++++++++++
 cloud/sidebarsCloud.js                        |   4 +
 .../current/monitoring/event-handler.md       | 195 ++++++++++++++++++
 3 files changed, 386 insertions(+)
 create mode 100644 cloud/monitoring/event-handler.md
 create mode 100644 i18n/fr/docusaurus-plugin-content-docs-cloud/current/monitoring/event-handler.md

diff --git a/cloud/monitoring/event-handler.md b/cloud/monitoring/event-handler.md
new file mode 100644
index 000000000000..b7d92d6d5ecf
--- /dev/null
+++ b/cloud/monitoring/event-handler.md
@@ -0,0 +1,187 @@
+---
+id: event-handler
+title: Event handler (auto remediation)
+---
+
+## Introduction
+
+Event handlers are optional system commands (scripts or executables) that are run whenever a host
+or service state change occurs.
+
+An obvious use for event handlers is the ability for Centreon to proactively fix problems before anyone is notified.
+
+### When Are Event Handlers Executed?
+
+Event handlers are executed when a service or host:
+
+* Is in a SOFT problem state
+* Initially goes into a HARD problem state
+* Initially recovers from a SOFT or HARD problem state.
+
+[SOFT and HARD states are described here](../alerts-notifications/concepts.md#status-types).
+
+### Event Handler Types
+
+There are different types of optional event handlers that you can define to handle host and state changes:
+
+* Global host event handler
+* Global service event handler
+* Host-specific event handlers
+* Service-specific event handlers
+
+Global host and service event handlers are run for every host or service state change that occurs, immediately prior to
+any host- or service-specific event handler that may be run.
+
+### Enabling Event Handlers
+
+Event handlers can be enabled or disabled on a poller.
+
+Host- and service-specific event handlers can be enabled or disabled in your host and service definitions. Host- and
+service-specific event handlers will not be executed if the global option is disabled on your poller.
+
+### Event Handler Execution Order
+
+As already mentioned, global host and service event handlers are executed immediately before host- or service-specific
+event handlers.
+
+Event handlers are executed for HARD problem and recovery states immediately after notifications are sent out.
+
+## Configuration
+
+### Step 1: Create a command
+
+Event handler commands will likely be shell or perl scripts, but they can be any type of executable that can run from a
+command prompt. As a minimum, the scripts should take the following macros as arguments:
+
+* For Services: $SERVICESTATE$, $SERVICESTATETYPE$, $SERVICEATTEMPT$
+* For Hosts: $HOSTSTATE$, $HOSTSTATETYPE$, $HOSTATTEMPT$
+
+The scripts should examine the values of the arguments passed to it and take any necessary action based upon those values.
+
+Event handler commands will normally be executed with the same permissions as the user under which Centreon Engine
+(the **centreon-engine** user) is running on your machine. This can present a problem if you want to write an event handler that
+restarts system services, as **root** privileges are generally required to perform tasks of that kind.
+
+Ideally you should evaluate the types of event handlers you will be implementing and grant just enough permissions to
+the Centreon Engine user to execute the necessary system commands. You might want to try using sudo to accomplish this.
+
+1. To create a command, go to **Configuration > Commands > Miscellaneous**.
+2. [Create your command as described here](./basic-objects/commands.md#creating-a-custom-check-command).
+3. Make sure to [add your new command to the command whitelist of the poller](./basic-objects/commands.md#command-whitelist) that will monitor the resources you want.
+
+### Step 2: Enable event handlers on your platform
+
+1. Go to **Configuration > Pollers > Engine configuration** and edit the Centreon Engine configurations for all the servers that will monitor resources with event handlers.
+
+2. In the **Check Options** tab, in the **Misc Options** section, make sure **Event Handler Option** is enabled.
+
+### Step 3: Configure event handlers for resources
+
+#### For all resources monitored by a specific poller
+
+To define an event handler command for all hosts and/or services monitored by a specific poller:
+
+1. Go to **Configuration > Pollers > Engine configuration** and edit the Centreon Engine configuration for this poller.
+
+2. In the **Check Options** tab, in the **Event Handler** section, select one of the commands you created at step 1 (in the **Global host event handler** or **Global service event handler** fields).
+
+3. Click **Save**.
+
+#### For selected resources
+
+1. Go to **Configuration > Hosts > Hosts** or to **Configuration > Services > Services by host** and edit your hosts or services.
+
+2. On the **Data Processing** tab, in the **Event handler** field, select one of the commands you created at step 1.
+
+3. Click **Save**.
+
+> You can also configure this command on [host templates](basic-objects/hosts-templates.md) or [service templates](basic-objects/services-templates.md).
+
+### Example
+
+The example below assumes that you are monitoring the HTTP server on the local machine. We will assume that the **Max
+Check Attempts** option for the service has a value of 4 or greater (i.e., the service is checked 4 times before it is
+considered to have a real problem).
+
+1. Store the following event handler script in **/usr/lib/centreon/plugins/eventhandlers/restart-httpd**.
+
+```Shell
+#!/bin/sh
+#
+# Event handler script for restarting the web server on the local machine
+#
+# Note: This script will only restart the web server if the service is
+#       retried 3 times (in a "soft" state) or if the web service somehow
+#       manages to fall into a "hard" error state.
+#
+
+# What state is the HTTP service in?
+case "$1" in
+OK)
+	# The service just came back up, so don't do anything...
+	;;
+WARNING)
+	# We don't really care about warning states, since the service is probably still running...
+	;;
+UNKNOWN)
+	# We don't know what might be causing an unknown error, so don't do anything...
+	;;
+CRITICAL)
+	# Aha!  The HTTP service appears to have a problem - perhaps we should restart the server...
+	# Is this a "soft" or a "hard" state?
+	case "$2" in
+
+	# We're in a "soft" state, meaning that Centreon is in the middle of retrying the
+	# check before it turns into a "hard" state and contacts get notified...
+	SOFT)
+
+		# What check attempt are we on?  We don't want to restart the web server on the first
+		# check, because it may just be a fluke!
+		case "$3" in
+
+		# Wait until the check has been tried 3 times before restarting the web server.
+		# If the check fails on the 4th time (after we restart the web server), the state
+		# type will turn to "hard" and contacts will be notified of the problem.
+		# Hopefully this will restart the web server successfully, so the 4th check will
+		# result in a "soft" recovery.  If that happens no one gets notified because we
+		# fixed the problem!
+		3)
+			echo -n "Restarting HTTP service (3rd soft critical state)..."
+			# Call the init script to restart the HTTPD server
+			/etc/rc.d/init.d/httpd restart
+			;;
+			esac
+		;;
+
+	# The HTTP service somehow managed to turn into a hard error without getting fixed.
+	# It should have been restarted by the code above, but for some reason it didn't.
+	# Let's give it one last try, shall we?  
+	# Note: Contacts have already been notified of a problem with the service at this
+	# point (unless you disabled notifications for this service)
+	HARD)
+		echo -n "Restarting HTTP service..."
+		# Call the init script to restart the HTTPD server
+		/etc/rc.d/init.d/httpd restart
+		;;
+	esac
+	;;
+esac
+exit 0
+```
+
+The sample script provided above will attempt to restart the web server on the local machine in two different cases:
+
+* After the service has been rechecked for the 3rd time and is in a SOFT CRITICAL state
+* After the service first goes into a HARD CRITICAL state
+
+The script should theoretically restart the web server and fix the problem before the service goes into a HARD problem
+state, but we include a fallback case in the event that it doesn't work the first time. Note that the event
+handler will only be executed the first time the service falls into a HARD problem state. This prevents Centreon
+from continuously executing the script to restart the web server if the service remains in a HARD problem state.
+
+2. Go to **Configuration > Commands > Miscellaneous** and create a command with the following characteristics:
+
+* Command Name: **restart-httpd**
+* Command Line: `$CENTREONPLUGINS$/eventhandlers/restart-httpd  $SERVICESTATE$ $SERVICESTATETYPE$ $SERVICEATTEMPT$`
+
+3. Edit the service you want, then select the **restart-httpd** command in the **Event handler** field.
diff --git a/cloud/sidebarsCloud.js b/cloud/sidebarsCloud.js
index ee087d455e94..80332078307d 100644
--- a/cloud/sidebarsCloud.js
+++ b/cloud/sidebarsCloud.js
@@ -351,6 +351,10 @@ module.exports = {
             }
           ]
         },
+        {
+          "type": "doc",
+          "id": "monitoring/event-handler"
+        }
       ]
     },
     {
diff --git a/i18n/fr/docusaurus-plugin-content-docs-cloud/current/monitoring/event-handler.md b/i18n/fr/docusaurus-plugin-content-docs-cloud/current/monitoring/event-handler.md
new file mode 100644
index 000000000000..85bc4a0db9c8
--- /dev/null
+++ b/i18n/fr/docusaurus-plugin-content-docs-cloud/current/monitoring/event-handler.md
@@ -0,0 +1,195 @@
+---
+id: event-handler
+title: Gestionnaire d'évènements (auto-remédiation)
+---
+
+## Introduction
+
+Les gestionnaires d'évènements sont des commandes système facultatives (scripts ou
+exécutables) qui sont exécutées chaque fois qu'un changement d'état d'un hôte ou d'un service se produit.
+
+Une utilisation évidente du gestionnaire d'évènements est la possibilité pour Centreon de résoudre proactivement les
+problèmes avant que quiconque ne soit averti.
+
+### Quand le gestionnaire d'évènements est-il exécuté ?
+
+Le gestionnaire d'évènements est exécuté lorsqu'un service ou un hôte :
+
+* Est dans un état problématique SOFT
+* Entre initialement dans un état problématique HARD
+* Récupère initialement d'un état problématique SOFT ou HARD.
+
+[Les états SOFT et HARD sont décrits ici](../alerts-notifications/concepts.md#types-de-statuts).
+
+### Types de gestionnaires d'évènements
+
+Il existe différents types de gestionnaires d'évènements que vous pouvez définir pour gérer les changements d'état :
+
+* Gestionnaire d'évènements global pour les hôtes
+* Gestionnaire d'évènements global pour les services
+* Gestionnaire d'évènements spécifiques à un hôte
+* Gestionnaire d'évènements spécifiques à un service
+
+Les gestionnaires d'évènements globaux d'hôtes et de services sont exécutés pour chaque changement d'état d'hôte ou de
+service qui se produit, immédiatement avant tout gestionnaire d'évènement spécifique à l'hôte ou au service.
+
+### Activation des gestionnaires d'évènements
+
+Les gestionnaires d'évènements peuvent être activés ou désactivés sur un collecteur.
+
+Les gestionnaires d'évènements spécifiques à l'hôte et au service peuvent être activés ou désactivés dans vos définitions
+d'hôte et de service. Les gestionnaires d'évènements spécifiques ne seront pas exécutés si l'option globale est désactivée
+sur votre collecteur.
+
+### Ordre d'exécution du gestionnaire d'évènements
+
+Comme déjà mentionné, les gestionnaires d'évènements globaux d'hôte et de service sont exécutés immédiatement avant les
+gestionnaires d'évènements spécifiques à l'hôte ou au service.
+
+Les gestionnaires d'évènements sont exécutés pour les problèmes HARD et les états de récupération immédiatement après
+l'envoi des notifications.
+
+## Configuration
+
+### Étape 1 : Créer une commande
+
+Les commandes du gestionnaire d'évènements seront en général des scripts shell ou perl, mais il peut s'agir de
+n'importe quel type d'exécutable pouvant être exécuté à partir d'un invite de commandes. Au minimum, les scripts doivent
+prendre les macros suivantes comme arguments :
+
+* Pour les services : $SERVICESTATE$, $SERVICESTATETYPE$, $SERVICEATTEMPT$
+* Pour les hôtes : $HOSTSTATE$, $HOSTSTATETYPE$, $HOSTATTEMPT$
+
+Les scripts doivent examiner les valeurs des arguments qui leur sont transmis et prendre toutes les mesures nécessaires
+en fonction de ces valeurs.
+
+Les commandes du gestionnaire d'évènements s'exécuteront normalement avec les mêmes autorisations que l'utilisateur sous
+lequel Centreon Engine (utilisateur **centreon-engine**) s'exécute sur votre machine. Cela peut poser un problème si vous
+souhaitez écrire un gestionnaire d'évènements qui redémarre les services système, car les privilèges **root** sont
+généralement requis pour effectuer ce type de tâches.
+
+Idéalement, vous devez évaluer les types de gestionnaires d'évènements que vous allez implémenter et accorder juste
+assez de permissions à l'utilisateur Centreon Engine pour exécuter les commandes système nécessaires. Vous voudrez
+peut-être essayer d'utiliser sudo pour ce faire.
+
+1. Pour créer une commande, allez à la page **Configuration > Commandes > Divers**.
+2. [Créez votre command comme décrit ici](./basic-objects/commands.md#créer-une-commande-personnalisée).
+3. [Ajoutez votre nouvelle commande à la liste blanche des commandes du collecteur](./basic-objects/commands.md#command-whitelist) qui supervisera les ressources désirées.
+
+### Étape 2 : Activer les gestionnaires d'évènements sur votre plateforme
+
+1. Allez à la page **Configuration > Collecteurs > Configuration du moteur de collecte** et éditez les configurations Centreon Engine pour tous les serveurs qui superviseront des ressources avec gestionnaires d'évènements.
+
+2. Dans l'onglet **Options de contrôle**, dans la section **Autres options**, assurez-vous que l'option **Gestionnaire d'évènements** est activée.
+
+### Étape 3 : Configurer les gestionnaires d'évènements
+
+#### Sur toutes les ressources supervisées par un collecteur
+
+Pour définir une commande de gestionnaire d'évènements pour tous les hôtes et/ou services supervisés par un collecteur spécifique :
+
+1. Allez à la page **Configuration > Collecteurs > Configuration du moteur de collecte** et éditez la configuration Centreon Engine pour ce collecteur.
+
+2. Dans l'onglet **Options de contrôle**, dans la section **Gestionnaire d'évènements**, sélectionnez l'une des commandes créées à l'étape 1 (dans les champs **Gestionnaire global d’évènements d'hôte** or **Gestionnaire global d’évènements de service**).
+
+3. Cliquez sur **Sauvegarder**.
+
+#### Sur des ressources sélectionnées
+
+1. Allez à la page **Configuration > Hôtes > Hôtes** ou à la page **Configuration > Services > Services par hôte** et éditez vos hôtes ou vos services.
+
+2. Dans l'onglet **Traitement des données**, dans le champ **Gestionnaire d'évènements**, sélectionnez l'une des commandes créées à l'étape 1.
+
+3. Cliquez sur **Sauvegarder**.
+
+> Vous pouvez également configurer cette commande sur les [modèles d'hôtes](basic-objects/hosts-templates.md) ou les [modèles de services](basic-objects/services-templates.md).
+
+### Exemple
+
+L'exemple ci-dessous suppose que vous supervisez un serveur HTTP sur la machine locale. Nous supposerons que l'option
+**Max Check Attempts** pour le service a une valeur de 4 ou plus (c'est-à-dire que le service est vérifié 4 fois avant
+qu'il ne soit considéré comme ayant un réel problème).
+
+1. On stocke le script du gestionnaire d'évènements dans **/usr/lib/centreon/plugins/eventhandlers/restart-httpd**.
+
+```Shell
+#!/bin/sh
+#
+# Event handler script for restarting the web server on the local machine
+#
+# Note: This script will only restart the web server if the service is
+#       retried 3 times (in a "soft" state) or if the web service somehow
+#       manages to fall into a "hard" error state.
+#
+
+# What state is the HTTP service in?
+case "$1" in
+OK)
+	# The service just came back up, so don't do anything...
+	;;
+WARNING)
+	# We don't really care about warning states, since the service is probably still running...
+	;;
+UNKNOWN)
+	# We don't know what might be causing an unknown error, so don't do anything...
+	;;
+CRITICAL)
+	# Aha!  The HTTP service appears to have a problem - perhaps we should restart the server...
+	# Is this a "soft" or a "hard" state?
+	case "$2" in
+
+	# We're in a "soft" state, meaning that Centreon is in the middle of retrying the
+	# check before it turns into a "hard" state and contacts get notified...
+	SOFT)
+
+		# What check attempt are we on?  We don't want to restart the web server on the first
+		# check, because it may just be a fluke!
+		case "$3" in
+
+		# Wait until the check has been tried 3 times before restarting the web server.
+		# If the check fails on the 4th time (after we restart the web server), the state
+		# type will turn to "hard" and contacts will be notified of the problem.
+		# Hopefully this will restart the web server successfully, so the 4th check will
+		# result in a "soft" recovery.  If that happens no one gets notified because we
+		# fixed the problem!
+		3)
+			echo -n "Restarting HTTP service (3rd soft critical state)..."
+			# Call the init script to restart the HTTPD server
+			/etc/rc.d/init.d/httpd restart
+			;;
+			esac
+		;;
+
+	# The HTTP service somehow managed to turn into a hard error without getting fixed.
+	# It should have been restarted by the code above, but for some reason it didn't.
+	# Let's give it one last try, shall we?  
+	# Note: Contacts have already been notified of a problem with the service at this
+	# point (unless you disabled notifications for this service)
+	HARD)
+		echo -n "Restarting HTTP service..."
+		# Call the init script to restart the HTTPD server
+		/etc/rc.d/init.d/httpd restart
+		;;
+	esac
+	;;
+esac
+exit 0
+```
+
+L'exemple de script fourni ci-dessus tentera de redémarrer le serveur web sur la machine locale :
+
+* Une fois que le service a été revérifié pour la troisième fois et est dans un état SOFT CRITICAL
+* Une fois que le service passe pour la première fois dans un état HARD CRITICAL.
+
+Le script devrait théoriquement redémarrer le serveur web et résoudre le problème avant que le service ne passe dans
+un état de problème HARD, mais nous incluons un cas de secours dans le cas où cela ne fonctionne pas la première fois.
+Il convient de noter que le gestionnaire d'évènements ne sera exécuté que la première fois que le service tombe dans un
+état de problème HARD. Cela empêche Centreon d'exécuter en continu le script pour redémarrer le serveur web si le
+service reste dans un état de problème HARD.
+
+2. À la page **Configuration > Commandes > Divers**, on crée une commande avec les caractéristiques suivantes :
+
+* Nom : **restart-httpd**
+* Ligne de commande : `$CENTREONPLUGINS$/eventhandlers/restart-httpd  $SERVICESTATE$ $SERVICESTATETYPE$ $SERVICEATTEMPT$`
+
+3. On édite le service désiré, puis on sélectionne la commande **restart-httpd** dans le champ **Gestionnaire d'évènements**.

From 980355729e0220303112a1aaefbc8f74e90c5329 Mon Sep 17 00:00:00 2001
From: cg-tw <83637804+cg-tw@users.noreply.github.com>
Date: Thu, 30 Jan 2025 10:29:39 +0100
Subject: [PATCH 2/2] Improve wording

---
 cloud/monitoring/event-handler.md                               | 2 +-
 .../current/monitoring/event-handler.md                         | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/cloud/monitoring/event-handler.md b/cloud/monitoring/event-handler.md
index b7d92d6d5ecf..48c3e17c2707 100644
--- a/cloud/monitoring/event-handler.md
+++ b/cloud/monitoring/event-handler.md
@@ -175,7 +175,7 @@ The sample script provided above will attempt to restart the web server on the l
 * After the service first goes into a HARD CRITICAL state
 
 The script should theoretically restart the web server and fix the problem before the service goes into a HARD problem
-state, but we include a fallback case in the event that it doesn't work the first time. Note that the event
+state, but we include a fallback case in the event that it doesn't work the first time. In that case the event
 handler will only be executed the first time the service falls into a HARD problem state. This prevents Centreon
 from continuously executing the script to restart the web server if the service remains in a HARD problem state.
 
diff --git a/i18n/fr/docusaurus-plugin-content-docs-cloud/current/monitoring/event-handler.md b/i18n/fr/docusaurus-plugin-content-docs-cloud/current/monitoring/event-handler.md
index 85bc4a0db9c8..3ef440a492b1 100644
--- a/i18n/fr/docusaurus-plugin-content-docs-cloud/current/monitoring/event-handler.md
+++ b/i18n/fr/docusaurus-plugin-content-docs-cloud/current/monitoring/event-handler.md
@@ -183,7 +183,7 @@ L'exemple de script fourni ci-dessus tentera de redémarrer le serveur web sur l
 
 Le script devrait théoriquement redémarrer le serveur web et résoudre le problème avant que le service ne passe dans
 un état de problème HARD, mais nous incluons un cas de secours dans le cas où cela ne fonctionne pas la première fois.
-Il convient de noter que le gestionnaire d'évènements ne sera exécuté que la première fois que le service tombe dans un
+Dans ce cas, le gestionnaire d'évènements ne sera exécuté que la première fois que le service tombe dans un
 état de problème HARD. Cela empêche Centreon d'exécuter en continu le script pour redémarrer le serveur web si le
 service reste dans un état de problème HARD.