Page History

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 50100. 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 {
    [...]

Configuration

Voici le fichier CFG de configuration présent dans : /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 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                      0192.0168.01.027
    # port to listen
    port                      8000

    # HTTPs part, enable if you want to set the visualisation interface listen in HTTPs mode[...]
}

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 {
    [...]
    # disabledHTTPs by 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                   01
    ssl_cert                  /etc/shinken/certs/server.cert
    ssl_key                   /etc/shinken/certs/server.key


    token                     ak5zv6t5s25r6g4
}

Mise en marche du module

[...]
}

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

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

Il est fortement recommandé de changer ce token.

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:50100/api/v1/host/408cd29ad37611e8810e0800277b7e16?token=ak5zv6t5s25r6g4

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/all-monitored-elements

Cet appel permet de recevoir la liste des uuids de tous les hôtes et clusters ainsi que de leurs checks.

Réponse

Codes de retour

Retour du code 200

• hosts : 
  • host_uuid : text
  • checks :
    • check_uuid : text
• clusters :
  • cluster_uuid : text
  • checks :
    • check_uuid : text

Exemple

{
   "clusters":[
      {
         "cluster_uuid":"ac169cd1fb5744999eaadc5da595f88b",
         "checks":[
         ]
      },
      {
         "cluster_uuid":"0dcad2b1667642d28c933de70915331e",
         "checks":[
            "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
            "0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
            "0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
         ]
      }
   ],
   "hosts":[
      {
         "host_uuid":"ac169cd1fb5744999eaadc5da595f88b",

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

Pour se faire, rendez vous dans le fichier de configuration de votre broker à l'emplacement /etc/shinken/brokers/nom_de_votre_broker.cfg :

#===============================================================================
# BROKER
#===============================================================================
# Description: The broker is responsible for:
# - Exporting centralized logs of all Shinken daemon processes
# - Exporting status data
# - Exporting performance data
# - Exposing Shinken APIs:
#   - Status data
#   - Performance data
#   - Command interface
#===============================================================================

define broker {

# Shinken Enterprise. Lines added by import core. Do not remove it, it's used by Shinken Enterprise to update your objects if you re-import them.
    _SE_UUID            core-broker-060340145ade11e5b703080027f08538
    _SE_UUID_HASH       8e00136f9e61061e07ca0f4a63509b68
# End of Shinken Enterprise part

    #======== Daemon name and address =========
    # Daemon name. Must be unique
    broker_name               broker-master

"checks":[
     # IP/fqdn of this daemon]
 (note: you MUST change it by},
 the real ip/fqdn of this server){
    address     "host_uuid":"0dcad2b1667642d28c933de70915331e",
         "checks":[
      localhost

    # Port (HTTP/HTTPS) exposed by this daemon "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
    port        "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
              7772

"0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
    # 0 = use HTTP, 1 = use HTTPS"0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
    use_ssl     ]
                  0


    #======== Master or spare selection =========
    # 1 = is a spare, 0 = is not a spare
    spare  }
   ]
}

GET /api/v1/host

Cet appel permet de recevoir la liste des uuids de tous les hôtes ainsi que de leurs checks.

Réponse

Codes de retour

Retour du code 200

• hosts : 
  • host_uuid : text
  • checks :
    • check_uuid : text

Exemple

{
	"hosts":[
      {
         "host_uuid":"ac169cd1fb5744999eaadc5da595f88b",
          0

"checks":[
    #======== Daemon connection timeout and down state limit ========= ]
    # timeout: how},
 many seconds to consider a node don't answer
  {
   timeout         "host_uuid":"0dcad2b1667642d28c933de70915331e",
          3
"checks":[
    # data_timeout: how many second to consider a configuration transfert to be failed
 "0dcad2b1667642d28c933de70915331e-905374c0f6ed11e78cd83cf862f4613a",
        # because the network brandwith is too small.
 "0dcad2b1667642d28c933de70915331e-714f6a1b90b318bbcfffb1a71d6258af",
       data_timeout     "0dcad2b1667642d28c933de70915331e-8537fb11f6ed11e7bf9f3cf862f4613a",
         120

   "0dcad2b1667642d28c933de70915331e-8700ea097f3eb219b0e61d871936bfe4"
 # max_check_attempts: how many fail check to consider this daemon as DEAD
    max_check_attempts]
      }
   3]

    # Check this daemon every X seconds
    check_interval            10



    #======== Modules to enable for this daemon =========
    # Available:
    # - Simple-log            : save all logs into a common file
    # - WebUI                 : visualisation interface
    # - Graphite-Perfdata     : save all metrics into a graphite database
    # - sla                   : save sla into a database
    # - Livestatus            : TCP API to query element state, used by nagios external tools like NagVis or Thruk
    # - Broker-module-liveData: JSON API to query element data.
    modules                   Simple-log, WebUI, Graphite-Perfdata, sla, Livestatus, broker-module-livedata


    #======== Realm and architecture settings =========
    # Realm to set this daemon into
    realm                    All

    # 1 = take data from the daemon realm and its sub realms
    # 0 = take data only from the daemon realm
    manage_sub_realms        1


    # In NATted environments, you declare each satellite ip[:port] as seen by
    # *this* broker (if port not set, the port declared by satellite itself
    # is used)
    #satellitemap    scheduler-1=1.2.3.4:7768, poller-1=1.2.3.5:7771


    #======== Enable or not this daemon =========
    # 1 = is enabled, 0 = is disabled
    enabled                  1

}

Rendez vous alors à la ligne des modules et ajoutez-y broker-module-livedata : 

modules                   Simple-log, WebUI, Graphite-Perfdata, sla, Livestatus, broker-module-livedata

Redémarrez ensuite votre Arbiter pour que la configuration du Broker soit active, puis redémarrez votre Broker qui s'occupera de mettre en marche le module livedata.

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

URL = http://IP_DU_BROKER:PORT_DU_MODULE/api/V1/TYPE/UUID?token=TOKEN_DU_MODULE 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 8000 du broker en localhost et "adt" comme token : 

http://localhost:8000/api/V1/host/408cd29ad37611e8810e0800277b7e16?token=adt

Le fonctionnement de l'api est tel que : 

GET /api/v1/host/{uuid}

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

Paramètres

Réponse

Codes de retour

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

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

GET /api/v1/cluster

Cet appel permet de recevoir la liste des uuids de tous les clusters ainsi que de leurs checks.

Réponse

Codes de retour

Retour du code 200

clusters : 

• cluster_uuid : text
• checks :
  • check_uuid

• •  : text

Exemple

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

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 de la page comme sur les screens suivants:

Il est aussi possible de récupérer les uuid directement par le biais des requêtes apis : all-monitored-elements, host et cluster.

Checks attachés

Pour récupérer l'UUID d'un check attaché à un hôte ou à un cluster,

Obtenir un uuid

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:

Macros Shinken

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

Exemple d'utilisation

Ces macros peuvent être utilisées par exemple dans les URL externes. Par exemple:

L'URL externe de cet hôte amène directement sur le volet Graphiques de l'hôte en question.