Canopsis Events
Le stream connector Canopsis Events vous permet d'envoyer des données d'évènements depuis Centreon vers Canopsis via leur API REST HTTP.
Avant de commencer
- Dans la plupart des cas, vous enverrez les données depuis le serveur central. Il est également possible de les envoyer depuis un serveur distant ou un collecteur (par exemple si vous voulez éviter que le serveur central ne représente un point de défaillance unique, ou bien si vous êtes un MSP et vous installez le stream connector sur un collecteur ou un serveur distant dans l'infratructure de votre client).
- Par défaut, le stream connector Canopsis Events envoie des évènements Broker host_status, service_status, acknowledgement et downtime. Ces formats d'événement sont décrits ici.
- Ces évènements sont envoyés à chaque contrôle sur l'hôte ou le service. Des paramètres dédiés vous permettent de ne pas envoyer certains évènements.
Compatibilité
Ce stream connector est conçu pour être compatible avec l'API v.4 de Canopsis, ce qui inclut les versions suivantes de Canopsis : 22.10, 23.04, 23.10 et 24.04.
Installation
Faites l'installation sur le serveur qui enverra les données à Canopsis (serveur central, serveur distant, collecteur).
- Connectez-vous en tant que
rootsur le serveur Centreon central en utilisant votre client SSH préféré. - Exécutez la commande adaptée à votre système :
- Alma / RHEL / Oracle Linux 8
- Alma / RHEL / Oracle Linux 9
- Debian_11
dnf install centreon-stream-connector-canopsis
dnf install centreon-stream-connector-canopsis
apt install centreon-stream-connector-canopsis
Configuration de Canopsis
Vous devrez paramétrer votre interface Canopsis pour qu'elle puisse recevoir des données de la part de Centreon. Reportez-vous au guide d'utilisation Canopsis , notamment vérifiez que les droits de création, lecture et suppression sont activés (voir la documentation d' administration des droits et celle d' administration de la planification dans le cas des plages de maintenance). Pour l'utilisateur associé à la clé d'authentification, il faut modifier la matrice de droits à la page Administration > Droits. Vous devez avoir au minimum coché les cases indiquées dans le tableau suivant :
| Section | Sous-section | Case minimales à cocher |
|---|---|---|
| Général | Événement | Cocher la seule case disponible |
| Comportements périodiques | Comportements périodiques | Cocher les cases create, read, update et delete |
| Comportements périodiques | Comportements périodiques : Dates d'exceptions | Cocher les cases create et read |
| Comportements périodiques | Comportements périodiques : Raisons | Cocher les cases create et read |
| Comportements périodiques | Comportements périodiques : Types | Cocher la case read |
Assurez-vous que Canopsis puisse recevoir les données envoyées par Centreon : les flux ne doivent pas être bloqués par la configuration de Canopsis ou par un équipement de sécurité.
Configurer le stream connector dans Centreon
- Sur votre serveur central, allez à la page Configuration > Collecteurs > Configuration de Centreon Broker.
- Cliquez sur central-broker-master (ou sur la configuration du Broker correspondant si les évènements seront envoyés par un serveur distant ou un collecteur).
- Dans l'onglet Output, sélectionnez Generic - Stream connector dans la liste, puis cliquez sur Add. Un nouvel output apparaît dans la liste.
- Remplissez les champs de la manière suivante :
| Champ | Valeur |
|---|---|
| Name | Canopsis events |
| Path | /usr/share/centreon-broker/lua/canopsis2x-events-apiv2.lua |
| Filter category | Neb |
- Pour permettre à Centreon de se connecter à votre équipement Canopsis, remplissez les paramètres obligatoires suivants. La première entrée existe déjà. Cliquez sur le lien +Add a new entry en-dessous du tableau Filter category pour en ajouter un autre.
| Type | Nom | Description | Exemple de valeur |
|---|---|---|---|
| string | canopsis_authkey | Clé d'authentification à l'API Canopsis | an_authkey |
| string | canopsis_host | Adresse de l'hôte Canopsis | a host |
- Renseignez les paramètres optionnels désirés (en utilisant le lien +Add a new entry) :
| Type | Nom | Description | Valeur par défaut |
|---|---|---|---|
| string | logfile | Fichier dans lequel les logs sont écrits | /var/log/centreon-broker/canopsis-events-apiv2.log |
| number | log_level | Niveau de verbosité des logs : de 1 (erreurs) à 3 (debug) | 1 |
-
Utilisez les paramètres optionnels du stream connector pour filtrer ou adapter les données que vous voulez que Centreon envoie à Canopsis.
-
Redémarrez centengine sur tous les collecteurs :
systemctl restart centengineCanopsis reçoit maintenant les données de Centreon.
Filtrer ou adapter les données que vous voulez envoyer à Canopsis
Tous les stream connectors ont un jeu de paramètres optionnels qui vous permettent de filtrer les données que vous enverrez à Canopsis, de reformater les données, de définir un proxy...
Chaque paramètre optionnel a une valeur par défaut, qui est indiquée dans la documentation correspondante.
-
Pour remplacer la valeur par défaut d'un paramètre, cliquez sur le lien +Add a new entry en-dessous du tableau Filter category, afin d'ajouter un paramètre personnalisé. Par exemple, si vous ne voulez envoyer à Canopsis que les évènements liés à un hostgroup nommé "Europe", entrez :
type = string
name = accepted_hostgroup
value = Europe -
Pour le stream connector Canopsis Events, les données suivantes remplacent toujours les valeurs par défaut. Il n'est donc pas nécessaire de les redéfinir dans l'interface sauf si vous voulez en changer les valeurs (par exemple retirer les plages de maintenance à la variable accepted_elements).
| Type | Nom | Description | Valeur par défaut pour le stream connector Canopsis | Valeur(s) possibles |
|---|---|---|---|---|
| string | accepted_categories | Chaque événement est lié à une catégorie de broker qui peut être utilisée pour filtrer les événements | neb | neb ou bam |
| string | accepted_elements | Élément Centreon géré par ce connecteur (pour en ajouter, vous devez regarder la section des format d'événement personnalisé, voir ci-dessous), la iste de éléments à séparer par des virgules sans espaces | host_status,service_status,acknowledgement,downtime | host_status ou service_status ou acknowledgement ou downtime |
| string | canopsis_downtime_comment_route | Route Canopsis pour envoyer les commentaires sur les plages de maintenance | /api/v4/pbehavior-comments | /api/v4/pbehavior-comments |
| string | canopsis_downtime_reason_name | Nom de la raison Canopsis pour les plages de maintenance | Centreon_downtime | - |
| string | canopsis_downtime_reason_route | Route Canopsis pour requêter le champs "raison" | /api/v4/pbehavior-reasons | /api/v4/pbehavior-reasons |
| string | canopsis_downtime_route | Route Canopsis pour envoyer les plages de maintenance | /api/v4/pbehaviors | /api/v4/pbehaviors |
| number | canopsis_downtime_send_pbh | Désactiver (0) / Activer (1) l'envoi des plages de maintenance si toutes les règles pour le faire sont validées (le champs raison et le type existent) | 1 | 0 ou 1 |
| string | canopsis_downtime_type_name | Nom de la catégorie de type des plages de maintenance de Canopsis | Default maintenance | - |
| string | canopsis_downtime_type_route | Route Canopsis pour requêter le champs "type" | /api/v4/pbehavior-types | /api/v4/pbehavior-types |
| string | canopsis_event_route | Route Canopsis pour envoyer les événements (hors plages de maintenance) | /api/v4/event | /api/v4/event |
| number | canopsis_port | Port Canopsis | 443 | - |
| number | canopsis_sort_list_hostgroups | Désactiver (0) / Activer (1) le tri des listes de groupes d'hôtes | 0 | 0 ou 1 |
| number | canopsis_sort_list_servicegroups | Désactiver (0) /Activer (1) le tri des listes de groupes de services | 0 | 0 ou 1 |
| string | connector | Le type de connecteur s'affichant dans l'interface Canopsis dans Alarmes > Type de connecteur | centreon-stream | - |
| string | connector_name | Nom du connector | centreon-stream-central | - |
| string | connector_name_type | Type de connector | poller | - |
| string | sending_method | Méthode d'envoi (seule l'API est disponible pour le moment) | api | api |
| string | sending_protocol | Protocole d'envoi (peut être https ou http) | https | http ou https |
| number | use_severity_as_state | Désactiver (0) /Activer (1) convertit la sévérité en état | 0 | 0 ou 1 |
Event bulking
Ce stream connector n'est pas compatible avec l'event bulking pour le moment. Cela signifie qu'il n'est pas capable d'envoyer plus d'un évènement lors de chaque appel à l'API REST Canopsis.
Format des évènements
Ce stream connector envoie des évènements au format suivant :
Exemple de sortie pour un événement service_status
[
{
"action_url": "",
"component": "Host-name",
"connector": "centreon-stream",
"connector_name": "Central",
"event_type": "check",
"host_id": "15",
"hostgroups": [
"Group 1",
"Group 2"
],
"long_output": "Plugin's long output",
"notes_url": "",
"output": "Plugin's output",
"resource": "Service-name",
"service_id": "47",
"servicegroups": [],
"source_type": "resource",
"state": 1,
"timestamp": 1708693347
}
]
Exemple de sortie pour un événement host_status
[
{
"action_url": "",
"component": "Host-1",
"connector": "centreon-stream",
"connector_name": "Central",
"event_type": "check",
"host_id": "15",
"hostgroups": [
"Group 1",
"Group 2"
],
"long_output": "OK: Host is OK",
"notes_url": "",
"output": "OK: Host is OK",
"source_type": "component",
"state": 0,
"timestamp": 1708953238
}
]
Exemple de sortie pour un événement acquittement
[
{
"author": "admin",
"component": "Host-1",
"connector": "centreon-stream",
"connector_name": "Central",
"event_type": "ack",
"long_output": "Acknowledged by admin",
"output": "Acknowledged by admin",
"resource": "passif",
"source_type": "resource",
"state": 1,
"timestamp": 1709052753
}
]
Exemple de sortie pour un événement plage de maintenance
[
{
"_id": "centreon-downtime-8-1715607730",
"author": "admin",
"enabled": true,
"entity_pattern": [
[
{
"field": "name",
"cond": {
"type": "eq",
"value": "Test-Service-Demo-Canopsis/Test-Demo-Canopsis"
}
}
]
],
"name": "centreon-downtime-8-1715607730",
"reason": "XXXX",
"rrule": "",
"tstart": 1715607718,
"tstop": 1715607958,
"type": "XXXX"
}
]
- Remarque : Dans la version 22.10 de Canopsis, il y a en plus un champ "color" supplémentaire.
Format d'évènement personnalisé
Ce stream connector vous permet de changer le format des événements pour correspondre à vos besoins. Cela vous permet de gérer des types d'événements qui ne le sont pas par défaut, comme les évènements ba_status.
Pour utiliser cette fonctionnalité vous devez configurer un fichier json de formatage et ajouter un nouveau paramètre à la configuration du stream connector.
| Type | Nom | Valeur |
|---|---|---|
| string | format_file | /etc/centreon-broker/canopsis-events-format.json |
Le fichier de configuration de format des évènements doit être lisible par l'utilisateur centreon-broker.
Pour en savoir plus sur les fichiers modèle et comment formatter les évènements vous pouvez consulter la documentation dédiée.
Commandes Curl : tester le stream connector
Voici la liste des commandes curl qui sont utilisées par le stream connector Canopsis.
Configuration du stream connector
Si vous voulez tester que les commandes de configuration sont envoyées correctement à Canopsis, utilisez les commandes curl suivantes.
Requête de la route pbehavior-reasons
Cette commande vérifie que la route pbehavior-reasons est accessible et renvoie notamment les valeurs du champ Raison des plages de maintenance. Cela permet par la suite de vérifier que le nom du champ Raison pour les plages de maintenance Centreon existe (par défaut ce nom est Centreon_downtime).
- Connectez-vous au serveur que vous avez configuré pour envoyer les évènements à Canopsis (le serveur central, un serveur distant ou un collecteur)
- Exécutez la commande suivante :
curl -X GET -H 'accept: application/json' -H 'x-canopsis-authkey: <canopsis-auth-token>' '<https_canopsis_host_url>:<canopsis_port><canopsis_pbehavior_reasons>'
Remplacez les
<xxxx>dans la commande ci-dessus par les valeurs correctes d'authentification à l'hôte Canopsis. Les valeurs par défaut définies dans le stream connector sont : pour canopsis_port : 443 et pour canopsis_pbehavior_reasons : /api/v4/pbehavior-reasons.
- Vérifiez que la commande renvoie bien une structure de données de la forme suivante :
"data":[
{
"_id":"XXXX",
"description":"DESCRIPTION",
"name":"NAME"
}
]
Requête de la route pbehavior-types
Cette commande vérifie que la route pbehavior-types est accessible et renvoie notamment l'ID des Types des plages de maintenance possibles. Cela permet par la suite de vérifier que le nom du Type des plages de maintenance Centreon existe (par défaut ce nom est Default maintenance).
- Connectez-vous au serveur que vous avez configuré pour envoyer les évènements à Canopsis (le serveur central, un serveur distant ou un collecteur)
- Exécutez la commande suivante :
curl -X GET -H 'accept: application/json' -H 'x-canopsis-authkey: <canopsis-auth-token>' '<https_canopsis_host_url>:<canopsis_port><canopsis_pbehavior_types>'
Remplacez les
<xxxx>dans la commande ci-dessus par les valeurs correctes d'authentification à l'hôte Canopsis. Les valeurs par défaut définies dans le stream connector sont : pour canopsis_port : 443, et pour canopsis_pbehavior_types : /api/v4/pbehavior-types.
- Vérifiez que la commande renvoie bien une structure de données de la forme suivante :
"data":[
{
"_id":"ec35c069-1651-4ee1-8944-3e5574e7b516",
"name":"Default active",
"description":"Default active",
"type":"active",
"priority":2,
"icon_name":"",
"color":"#2FAB63"
},
{
"_id":"470c469c-77bc-402c-910f-30a8b2584343",
"name":"Default inactive",
"description":"Default inactive",
"type":"inactive",
"priority":1,
"icon_name":"brightness_3",
"color":"#979797"
},
{
"_id":"5ea9d2d8-0f16-4e19-bcca-64b1e96e00fa",
"name":"Default maintenance",
"description":"Default maintenance",
"type":"maintenance",
"priority":3,
"icon_name":"build",
"color":"#BF360C"
},
{
"_id":"1fb65097-ddaa-4e99-9239-8263095c156c",
"name":"Default pause",
"description":"Default pause",
"type":"pause",
"priority":4,
"icon_name":"pause",
"color":"#5A6D80"
}
]
En laissant les valeurs par défaut du stream connector Canopsis, les plages de maintenance sont classées dans le type Default maintenance.
Requête de la route app-info
Cette commande vérifie que la route app-info est accessible et retourne des informations concernant l'hôte Canopsis.
- Connectez-vous au serveur que vous avez configuré pour envoyer les évènements à Canopsis (le serveur central, un serveur distant ou un collecteur)
- Exécutez la commande suivante :
curl -X GET -H 'accept: application/json' -H 'x-canopsis-authkey: <canopsis-auth-token>' '<https_canopsis_host_url>:<canopsis_port>/api/v4/app-info'
Remplacez tous les
<xxxx>dans la commande ci-dessus par les valeurs correctes d'authentification à l'hôte Canopsis. Pour le port, la valeur par défaut définie dans le stream connector est 443.
Cette commande permet entre autres d'accéder à la version de Canopsis.
Envoyer des évènements
Si vous voulez tester que les évènements sont envoyés correctement à Canopsis :
- Connectez-vous au serveur que vous avez configuré pour envoyer les évènements à Canopsis (le serveur central, un serveur distant ou un collecteur)
- Exécutez la commande suivante :
curl -X POST -H 'content-length: 400' -H 'content-type: application/json' -H 'x-canopsis-authkey: <canopsis-auth-token>' '<https_canopsis_host_url>:<canopsis_port><canopsis_event_route>' -d '[{"hostgroups":[],"component":"Test-Canopsis","host_id":"8","event_type":"check","resource":"passif","output":"Test_passif_output","servicegroups":[],"connector":"centreon-stream","source_type":"resource","action_url":"","long_output":"Test-curl-command Passif long output","notes_url":"","connector_name":"Central","timestamp":1710843117,"service_id":"10","state":1}]'
Remplacez tous les
<xxxx>dans la commande ci-dessus par les valeurs correctes d'authentification à l'hôte Canopsis. Les valeurs par défaut définies dans le stream connector sont : pour canopsis_port : 443 et canopsis_event_route : /api/v4/event.
- Vérifiez que l'évènement a bien été reçu par Canopsis : les statuts doivent apparaître à la page Alarmes > En Cours de Canopsis.
