Versions Compared

Old Version 57

changes.mady.by.user Mathieu Carrié

Saved on

compared with

New Version 58

changes.mady.by.user Mathieu Carrié

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

Le module broker-module-livedata permet de mettre à disposition sur le Broker une API HTTP permettant d'accéder aux informations d'un hôte, d'un cluster ou d'un check.


Cette API peut être utilisée pour accéder rapidement aux informations d'éléments supervisés pour ensuite les intégrer dans des outils externes (outil de ticketing, récolte de données, etc...).


Panel
titleSommaire

Table of Contents
maxLevel3
stylenone


Activation du module

Le module broker-module-livedata est un module qui peut être activé seulement sur un démon Broker.

L'activation du module s'effectue en ajoutant le module dans le fichier de configuration du Broker concerné.

Pour ce faire, dans le fichier de configuration de votre Broker à l'emplacement /etc/shinken/brokers/nom_de_votre_broker.cfg à la ligne suivante, et ajouter "broker-module-livedata"

Code Block
languagebash
define broker {
    [...]
    modules                   Simple-log, WebUI, Graphite-Perfdata, sla, broker-module-livedata
    [...]
}


Pour prendre en compte le changement de configuration, redémarrer l'Arbiter:

Code Block
service shinken-arbiter restart


Configuration


La configuration du module se trouve par défaut dans le fichier suivant: /etc/shinken/modules/broker-module-livedata.cfg

Configuration de l'interface et du port d'écoute

Par défaut, le port de l'API rendue disponible par le module "broker-module-livedata" est 51000. Ce port peut être changé via le paramètre "port" dans le fichier de configuration du module: /etc/shinken/modules/broker-module-livedata.cfg.


En plus du port, il est également possible de configurer l'interface réseau sur laquelle est mise à disposition l'API. Si par exemple l'API ne doit être accessible seulement via un réseau local, il est possible de n'écouter les requêtes que sur cette interface réseau.

Cette modification de configuration se fait via le paramètre "host" du fichier de configuration du module: /etc/shinken/modules/broker-module-livedata.cfg. Dans l'exemple suivant, l'API ne sera disponible que sur l'interface avec l'adresse 192.168.1.27:

Code Block
languagebash
title/etc/shinken/modules/broker-module-livedata.cfg
define module {
    [...]
    host                      192.168.1.27
    [...]
}


L'API du module est par défaut mise à disposition sur toutes les interfaces: le paramètre "host" est à 0.0.0.0


Pour prendre en compte le changement de configuration, il faut ensuite rédémarrer l'Arbiter:

Code Block
service shinken-arbiter restart


Activation du SSL

L'API du module est accessible via HTTP. Si pour des raisons de sécurité, cette API doit être accessible via HTTPS, il faut passer le paramètre "use_ssl" à 1 dans le fichier de configuration du module:

Code Block
languagebash
title/etc/shinken/modules/broker-module-livedata.cfg
define module {
    [...]
    # HTTPs part, enable if you want to set the visualisation interface listen in HTTPs mode
    # disabled by default. Set your own certificates. Set your own token, it is usefull to get access to the API
    use_ssl                   1
    ssl_cert                  /etc/shinken/certs/server.cert
    ssl_key                   /etc/shinken/certs/server.key


    [...]
}

Les paramètres "ssl_cert" et "ssl_key" permettent de spécifier la clé et le certificat SSL à utiliser pour la connexion.


Pour prendre en compte le changement de configuration, il faut ensuite rédémarrer l'Arbiter:

Code Block
service shinken-arbiter restart


Authentification

L'API du module broker-module-livedata est accessible à l'adresse suivante:

Code Block
http://<ip-broker>:<port-module>/


Les appels effectués à l'API demandent l'utilisation d'un token d'identification. Ce token est spécifié dans le fichier de configuration du module (/etc/shinken/modules/broker-module-livedata.cfg).

Ce token doit être ajouté en paramètre à chaque requête sous peine de recevoir une erreur 401 de la part de l'API.


Par exemple:

Code Block
http://192.168.1.59:51000/api/v1/host/408cd29ad37611e8810e0800277b7e16?token=mon_tokenak5zv6t5s25r6g4


Chaque appel à l'API renvoie une réponse au format JSON.

Utilisation

Les routes suivantes sont mise à disposition par l'API. Chaque appel doit contenir dans ses paramètres le token d'identification décrit dans la section précédente.

GET /api/V1/host/{uuid}

Cet appel permet de recevoir des informations sur un hôte.

Paramètres


ParamètreDescription
uuidUUID de l'hôte


Réponse

Codes de retour


Codes de retourExplications
200

OK

401

Permission refusée (Mauvais token)

404

Hôte introuvable


Retour du code 200
  • host_uuid : text
  • host_name : text
  • host_display_name : text
  • status : text
    • OK
    • WARNING
    • CRITICAL
    • UNKNOWN
    • MISSING-DATA
    • SHINKEN-INACTIVE
  • status_since : epoch (en secondes)
  • context : text
    • NOTHING
    • ACKNOWLEDGED
    • PARTIAL-ACKNOWLEDGED
    • INHERITED-ACKNOWLEDGED
    • DOWNTIME
    • PARTIAL-DOWNTIME
    • INHERITED-DOWNTIME
    • FLAPPING
    • PARTIAL-FLAPPING
    • DISABLED

  • business_impact : 0, 1, 2, 3, 4, 5

  • output : text

  • long_output : text

Exemple


Code Block
titlehttp://localhost:51000/api/v1/host/408cd29ad37611e8810e0800277b7e16?token=ak5zv6t5s25r6g4
{
 "status": "OK",
 "host_display_name": "localhost",
 "long_output": "",
 "host_name": "localhost",
 "context": "NOTHING",
 "status_since": 1540457802,
 "business_impact": 2,
 "output": "PING OK - Packet loss = 0%, RTA = 0.02 ms",
 "host_uuid": "408cd29ad37611e8810e0800277b7e16"
}


GET /api/V1/check-on-host/{uuid}

Cet appel permet de recevoir des informations sur un check attaché à un hôte.

Paramètres


ParamètreDescription
uuidUUID du check, sachant qu'il correspond à {uuid_de_l'hôte}-{uuid_du_check}


Réponse

Codes de retour


Codes de retourExplications
200

OK

401

Permission refusée (Mauvais token)

404

Check introuvable


Retour du code 200
  • check_uuid : text
  • check_name : text
  • check_display_name : text
  • status : text
    • OK
    • WARNING
    • CRITICAL
    • UNKNOWN
    • MISSING-DATA
    • SHINKEN-INACTIVE
  • status_since : epoch (en secondes)
  • context : text
    • NOTHING
    • ACKNOWLEDGED
    • PARTIAL-ACKNOWLEDGED
    • INHERITED-ACKNOWLEDGED
    • DOWNTIME
    • PARTIAL-DOWNTIME
    • INHERITED-DOWNTIME
    • FLAPPING
    • PARTIAL-FLAPPING
    • DISABLED
  • output : text
  • business_impact : 0, 1, 2, 3, 4, 5
  • long_output : text
  • host_uuid : text
  • host_name : text
  • host_display_name : text

Exemple


Code Block
titlehttp://localhost:51000/api/v1/check-on-host/408cd29ad37611e8810e0800277b7e16-022a505c849f840e110f2aba5e27597f?token=ak5zv6t5s25r6g4
{
 "status": "OK",
 "host_display_name": "localhost",
 "check_name": "Broker Daemon Livedata - broker-master",
 "host_uuid": "408cd29ad37611e8810e0800277b7e16",
 "long_output": "",
 "host_name": "localhost",
 "context": "NOTHING",
 "output": "<span style=\"color:#2A9A3D;font-weight:bold;\">[OK]</span> The example works fine.<br/>",
 "business_impact": 2,
 "status_since": 1540457781.797493,
 "check_uuid": "022a505c849f840e110f2aba5e27597f",
 "check_display_name": "Broker Daemon Livedata - broker-master"
}


GET /api/V1/cluster/{uuid}

Cet appel permet de recevoir des informations sur un cluster.

Paramètres


ParamètreDescription
uuidUUID du cluster


Réponse

Codes de retour


Codes de retourExplications
200

OK

401

Permission refusée (Mauvais token)

404

Cluster introuvable


Retour du code 200
  • cluster_uuid : text
  • cluster_name : text
  • cluster_display_name : text
  • status : text
    • OK
    • WARNING
    • CRITICAL
    • UNKNOWN
    • MISSING-DATA
    • SHINKEN-INACTIVE
  • status_since : epoch (en secondes)
  • context : text
    • NOTHING
    • ACKNOWLEDGED
    • PARTIAL-ACKNOWLEDGED
    • INHERITED-ACKNOWLEDGED
    • DOWNTIME
    • PARTIAL-DOWNTIME
    • INHERITED-DOWNTIME
    • FLAPPING
    • PARTIAL-FLAPPING
    • DISABLED
  • business_impact : 0, 1, 2, 3, 4, 5
  • output : text
  • long_output : text

Exemple


Code Block
titlehttp://localhost:51000/api/v1/cluster/408gfhfr7611e8810e0800277b7e16?token=ak5zv6t5s25r6g4
{
 "status": "OK",
 "cluster_display_name": "localhost",
 "long_output": "",
 "cluster_name": "localhost",
 "context": "NOTHING",
 "status_since": 1540457802,
 "business_impact": 2,
 "output": "PING OK - Packet loss = 0%, RTA = 0.02 ms",
 "cluster_uuid": "408gfhfr7611e8810e0800277b7e16"
}


GET /api/V1/check-on-cluster/UUID

Cet appel permet de recevoir des informations sur un check attaché à un cluster.

Paramètres


ParamètreDescription
uuidUUID du check, sachant qu'il correspond à {uuid_du_cluster}-{uuid_du_check}


Réponse

Codes de retour


Codes de retourExplications
200

OK

401

Permission refusée (Mauvais token)

404

Check introuvable


Retour du code 200


  • check_uuid : text
  • check_name : text
  • check_display_name : text
  • status : text
    • OK
    • WARNING
    • CRITICAL
    • UNKNOWN
    • MISSING-DATA
    • SHINKEN-INACTIVE
  • status_since : epoch (en secondes)
  • context : text
    • NOTHING
    • ACKNOWLEDGED
    • PARTIAL-ACKNOWLEDGED
    • INHERITED-ACKNOWLEDGED
    • DOWNTIME
    • PARTIAL-DOWNTIME
    • INHERITED-DOWNTIME
    • FLAPPING
    • PARTIAL-FLAPPING
    • DISABLED
  • output : text
  • business_impact : 0, 1, 2, 3, 4, 5
  • long_output : text
  • cluster_uuid : text
  • cluster_name : text
  • cluster_display_name : text

Exemple


Code Block
titlehttp://localhost:51000/api/v1/check-on-cluster/408gfhfr7611e8810e0800277b7e16-044a505c849f840e110f2aba5e27597f?token=ak5zv6t5s25r6g4
{
 "status": "OK",
 "cluster_display_name": "localhost",
 "check_name": "Broker Daemon Livedata - broker-master",
 "cluster_uuid": "408gfhfr7611e8810e0800277b7e16",
 "long_output": "",
 "cluster_name": "localhost",
 "context": "NOTHING",
 "output": "<span style=\"color:#2A9A3D;font-weight:bold;\">[OK]</span> The example works fine.<br/>",
 "business_impact": 2,
 "status_since": 1540457781.797493,
 "check_uuid": "044a505c849f840e110f2aba5e27597f",
 "check_display_name": "Example cluster check"
}


Obtenir un UUID

Hôtes et Clusters

Pour récupérer l'UUID d'un hôte ou d'un cluster il suffit de se rendre dans sa page de configuration sur l'UI de Configuration, ou de le sélectionner dans l'UI de Visualisation. Il se trouve alors dans l'URL de la page comme sur les screens suivants:


Panel



Panel


Checks attachés

Pour récupérer l'UUID d'un check attaché à un hôte ou à un cluster, il suffit de se rendre dans sa page de configuration sur l'UI de Configuration en y rajoutant l'UUID de l'hôte ou du cluster sur lequel il est attaché, suivi d'un tiret. Dans l'interface de Visualisation, il peut être trouvé directement dans l'URL en ouvrant le détail du check:


Panel


Macros Shinken

Des macros sont également disponibles sur Shinken pour utiliser l'UUID d'un hôte/cluster/check.

MacroDescription
$HOSTUUID$Renvoie l'UUID de l'hôte ou du cluster
$SERVICEUUID$Renvoie l'UUID du check


...