Page History

Introduction

Configuration

Activation du module

Le module Voici le fichier CFG de configuration présent dans : /etc/shinken/modules/broker-module-livedata.cfg 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"

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

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

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

#===============================================================================
# broker module livedata
#===============================================================================
# Daemons that can load this module:
# - broker
# This module is an api getting information from the broker
#===============================================================================

define# broker module {

    #livedata
#================================= Module identity =========
    # Module name. Must be unique
    module_name               broker-module-livedata

    # Module type (to load module code). Do not edit.
    module_type               broker_module_livedata

    #=====================================
# Daemons that can load this module:
# - broker
# This module is an api getting information from the broker
#======================================================= Listening address =========
    # host: IP address to listen to.
    #       note: 0.0.0.0 = all interfaces.
    host                      0.0.0.0
    # port to listen
    port              ===============

define module {

    #======== Module identity =========
    # Module name. Must be unique
    module_name               broker-module-livedata

    # Module type (to load module code). Do not edit.
    module_type               broker_module_livedata

    #======== Listening address =========
    # host: IP address to listen to.
    #       note: 0.0.0.0 = all interfaces.
    host                      0.0.0.0
    # port to listen
    port                      51000

    # 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                   0
    ssl_cert                  /etc/shinken/certs/server.cert
    ssl_key                   /etc/shinken/certs/server.key
    token                     ak5zv6t5s25r6g4
}

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:

define module {
    [...]
    host        51000

    # HTTPs part, enable if you want to set  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:

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:

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_sslthe 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                   0
    ssl_cert                  /etc/shinken/certs/server.cert
    ssl_key                   /etc/shinken/certs/server.key
    token     1
    ssl_cert              ak5zv6t5s25r6g4
}

Mise en marche du module

Pour mettre en marche votre module il vous faut l'ajouter à la listes des modules actifs sur le broker souhaité.

    /etc/shinken/

[...]
define broker {
[...]certs/server.cert
    modulesssl_key                   Simple-log, WebUI, Graphite-Perfdata, sla, Livestatus, broker-module-livedata
[...]
}

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

service shinken-arbiter restart

Fonctionnement

L'accès à cette API est restreinte aux détenteurs d'un token généré dans la configuration (modifiable par l'utilisateur) du module.

Appeler l'API

Authentification

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

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:

http://192.168.1.59

Pour utiliser l'API il vous faut utiliser une adresse telle que : http://{ip_broker}:{port_module}/api/v1/host/408cd29ad37611e8810e0800277b7e16?token={token}

ou https://IP_DU_BROKER:PORT_DU_MODULE/api/v1/TYPE/UUID?token=TOKEN_DU_MODULE

Exemple pour un hôte avec le module sur le port 51000 du broker en localhost et "adt" comme token : 

:51000/api/v1/host/408cd29ad37611e8810e0800277b7e16?token=

L'API vous renverra alors du json sous un format standardisé.

mon_token

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

Réponse

Codes de

OK

Permission refusée (Mauvais token)

Hôte introuvable

L'élément n'est pas un hôte

Retour du code 500

retour

Retour du code 404

Retour du code 401

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

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

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

Paramètres

Réponse

Codes de retour

Retours du code 500

Retour du code 404

Réponse

Codes de retour

Retour du code 401

Retour du code 200

• check_uuid : text
• check_name : text
• check_display_name : textstatus : 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

GET /api/V1/cluster/{uuid}

Cet appel permet de recevoir des informations sur un cluster.

Paramètres

Réponse

Codes de retour

Retours du code 500

GET /api/V1/cluster/{uuid}

Cet appel permet de recevoir des informations sur un cluster.

Paramètres

Réponse

Codes de retour

Retour du code 404

Retour du code 401

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

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

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

Paramètres

Réponse

Codes de retour

Retours du code 500

Codes de retour

Retour du code 404

Retour du code 401

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

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 tel que :

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é, suivit d'un tiret. Ou plus simplement dans l'UI de Visualisation.

Macros Shinken

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