Aller au contenu principal
Version: 23.04

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

  1. Connectez-vous en tant que root sur le serveur Centreon central en utilisant votre client SSH préféré.
  2. Exécutez la commande adaptée à votre système :
dnf 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 :

SectionSous-sectionCase minimales à cocher
GénéralÉvénementCocher la seule case disponible
Comportements périodiquesComportements périodiquesCocher les cases create, read, update et delete
Comportements périodiquesComportements périodiques : Dates d'exceptionsCocher les cases create et read
Comportements périodiquesComportements périodiques : RaisonsCocher les cases create et read
Comportements périodiquesComportements périodiques : TypesCocher 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

  1. Sur votre serveur central, allez à la page Configuration > Collecteurs > Configuration de Centreon Broker.
  2. 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).
  3. Dans l'onglet Output, sélectionnez Generic - Stream connector dans la liste, puis cliquez sur Add. Un nouvel output apparaît dans la liste.
  4. Remplissez les champs de la manière suivante :
ChampValeur
NameCanopsis events
Path/usr/share/centreon-broker/lua/canopsis2x-events-apiv2.lua
Filter categoryNeb
  1. 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.
TypeNomDescriptionExemple de valeur
stringcanopsis_authkeyClé d'authentification à l'API Canopsisan_authkey
stringcanopsis_hostAdresse de l'hôte Canopsisa host
  1. Renseignez les paramètres optionnels désirés (en utilisant le lien +Add a new entry) :
TypeNomDescriptionValeur par défaut
stringlogfileFichier dans lequel les logs sont écrits/var/log/centreon-broker/canopsis-events-apiv2.log
numberlog_levelNiveau de verbosité des logs : de 1 (erreurs) à 3 (debug)1
  1. Utilisez les paramètres optionnels du stream connector pour filtrer ou adapter les données que vous voulez que Centreon envoie à Canopsis.

  2. Déployez la configuration.

  3. Redémarrez centengine sur tous les collecteurs :

    systemctl restart centengine

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

TypeNomDescriptionValeur par défaut pour le stream connector CanopsisValeur(s) possibles
stringaccepted_categoriesChaque événement est lié à une catégorie de broker qui peut être utilisée pour filtrer les événementsnebneb ou bam
stringaccepted_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 espaceshost_status,service_status,acknowledgement,downtimehost_status ou service_status ou acknowledgement ou downtime
stringcanopsis_downtime_comment_routeRoute Canopsis pour envoyer les commentaires sur les plages de maintenance/api/v4/pbehavior-comments/api/v4/pbehavior-comments
stringcanopsis_downtime_reason_nameNom de la raison Canopsis pour les plages de maintenanceCentreon_downtime-
stringcanopsis_downtime_reason_routeRoute Canopsis pour requêter le champs "raison"/api/v4/pbehavior-reasons/api/v4/pbehavior-reasons
stringcanopsis_downtime_routeRoute Canopsis pour envoyer les plages de maintenance/api/v4/pbehaviors/api/v4/pbehaviors
numbercanopsis_downtime_send_pbhDé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)10 ou 1
stringcanopsis_downtime_type_nameNom de la catégorie de type des plages de maintenance de CanopsisDefault maintenance-
stringcanopsis_downtime_type_routeRoute Canopsis pour requêter le champs "type"/api/v4/pbehavior-types/api/v4/pbehavior-types
stringcanopsis_event_routeRoute Canopsis pour envoyer les événements (hors plages de maintenance)/api/v4/event/api/v4/event
numbercanopsis_portPort Canopsis443-
numbercanopsis_sort_list_hostgroupsDésactiver (0) / Activer (1) le tri des listes de groupes d'hôtes00 ou 1
numbercanopsis_sort_list_servicegroupsDésactiver (0) /Activer (1) le tri des listes de groupes de services00 ou 1
stringconnectorLe type de connecteur s'affichant dans l'interface Canopsis dans Alarmes > Type de connecteurcentreon-stream-
stringconnector_nameNom du connectorcentreon-stream-central-
stringconnector_name_typeType de connectorpoller-
stringsending_methodMéthode d'envoi (seule l'API est disponible pour le moment)apiapi
stringsending_protocolProtocole d'envoi (peut être https ou http)httpshttp ou https
numberuse_severity_as_stateDésactiver (0) /Activer (1) convertit la sévérité en état00 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.

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

  1. Connectez-vous au serveur que vous avez configuré pour envoyer les évènements à Canopsis (le serveur central, un serveur distant ou un collecteur)
  2. 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.

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

  1. Connectez-vous au serveur que vous avez configuré pour envoyer les évènements à Canopsis (le serveur central, un serveur distant ou un collecteur)
  2. 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.

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

  1. Connectez-vous au serveur que vous avez configuré pour envoyer les évènements à Canopsis (le serveur central, un serveur distant ou un collecteur)
  2. 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 :

  1. Connectez-vous au serveur que vous avez configuré pour envoyer les évènements à Canopsis (le serveur central, un serveur distant ou un collecteur)
  2. 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.

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

image