Vous êtes ici:

Menu


Stacks Image 8983
L'API Rest est une fonctionnalité récente de Centreon. Elle est un peu méconnue mais elle mérite que l'on s'y intéresse. Et effectivement, pour mon prochain projet pour l'Open Summit de 2017, j'ai besoin d'un requêteur simple et léger pour interroger l'état de mon serveur Centreon. Tout au long de cet article, nous allons voir comment utiliser l'API Rest en ligne de commande pour obtenir l'état de santé de notre infrastructure informatique.
Nous utiliserons mon OS préféré DEBIAN pour utiliser l'API Rest.

1 Prérequis

Pour utiliser l'API Rest en ligne de commande, nous aurons besoin des utilitaires suivants : curl et jq. curl est un utilitaire destiné à récupérer des informations d'une ressource accessible grâce à une URL. Il peut être utilisé comme client REST, ce qui nous intéresse dans notre cas. jq est un utilitaire, à l'instar de sed, manipulant et transformant les données JSON.
Il est temps d'installer ces utilitaires :
apt-get install curl jq

2 Première utilisation

2.1 Authentification

2.1a Authentification admin

Maintenant, pour effectuer des requêtes avec l'API Rest, nous devons disposer des autorisations nécessaires. Cette autorisation sera paramètre au niveau des contacts Centreon. Dans un premier temps, nous devrons définir un mot de passe puis activer l'option Reach API. Pour mes tests, j'ai utilisé le contact admin mais je vous conseille d'utiliser un autre contact dans un environnement de production.
Stacks Image 294335

2.1b Authentification user

Dans un environnement de production, nous utiliserons un user spécifique conditionné par une ACL. Tout d'abord, créez votre utilisateur.
Stacks Image 294377
C'est le minimum vital pour créer un utilisateur, définissez un mot de passe. Dans l'onglet Centreon Authentication, activez les API pour le temps réel et/ou la configuration.
Stacks Image 294384
Nous continuons par créer une ACL pour cet utilisateur. On lui ajoutera le minimum vital, à savoir, toutes les ressources et les actions simples.
Stacks Image 294390
Sélectionnez l'onglet Authorizations Information et ajouter All ressources et Simple User.
Stacks Image 294387
Sauvegardez et votre user est prêt pour les REST Api Centreon.

2.2 Test d'authentification

Pour utiliser les requêtes de l'API Rest, nous allons nous authentifier pour récupérer un jeton (Token). Celui-ci nous servira pour effectuer toutes les opérations de requêtes qui suivront. Ce Token a une durée de validité de l'orde d'une dizaine de minutes. Voici la commande pour obtenir ce jeton.
curl -s -d "username=admin&password=password" -H "Content-Type: application/x-www-form-urlencoded" -X POST http://192.168.0.250/centreon/api/index.php?action=authenticate
Description des paramètres
-s : mode silence; on n'affiche pas la progression des données
-d : on envoie des données avec la commande POST, dans notre cas l'identifiant du contact et son mot de passe
-H : on ajoute un Header à l'envoie des données
-X : méthode de la requête POST dans notre cas

Notre serveur de supervision a pour adresse IP 192.168.0.250.
Vous obtiendrez ce jeton comme ci-dessous :
{"authToken":"NWEwODhmODA1ZjllMDUuODA4MjAxNTY="}
Pour effectuer une requête, il faut récupérer le résultat situé à droite en enlevant les doubles-quotes.
Stacks Image 294368
Protéger votre token
Attention, le token peut comporter des suites de caractères spéciaux comme ceux-ci : {"authToken":"rSRl\/\/gAniKn5HDebToYgf19Q03RMZmVGl3J2z\/dx10="}. SI vous ne protégez pas votre token avec des simples quotes, vous aurez droit à un message d'erreur.
curl -s 'http://192.168.1.99/centreon/api/index.php?object=centreon_realtime_services&action=list&status=critical' -H 'Content-Type: application/json' -H 'centreon-auth-token: rSRl\/\/gAniKn5HDebToYgf19Q03RMZmVGl3J2z\/dx10='
"Forbidden"

En encadrant votre token de simple quote, vous éviterez ce problème.
curl -s 'http://192.168.1.99/centreon/api/index.php?object=centreon_realtime_services&action=list&status=critical' -H 'Content-Type: application/json' -H 'centreon-auth-token: 'rSRl\/\/gAniKn5HDebToYgf19Q03RMZmVGl3J2z\/dx10=''
[{"host_id":"91","name":"srv-mysql-01","description":"disk-\/usr","service_id":"590","state":"2","state_type":"1","output":"Disk \/usr - used : 152.87 Go - size : 158.00 Go - percent : 96 %\n","perfdata":"used=164145131639o;135720966554;152686087373;0;169651208192 size=169651208192o","max_check_attempts":"3","check_attempt":"3","last_check":"1563179799","last_state_change":"1563177879","last_hard_state_change":"1563177999","acknowledged":"0","criticality":null},{"host_id":"34","name":"mbi1904","description":"DWH-db-content","service_id":"310","state":"2","state_type":"1","output":"[Table mod_bi_hgmonthavailability: EMPTY] [Table mod_bi_hgservicemonthavailability: EMPTY] [Table mod_bi_metricmonthcapacity: EMPTY] [Table mod_bi_metriccentiledailyvalue: EMPTY]\n","perfdata":"","max_check_attempts":"3","check_attempt":"3","last_check":"1563172116","last_state_change":"1563084698","last_hard_state_change":"1563084698","acknowledged":"1","criticality":null}]

2.3 Première requête

Nous allons utiliser ce jeton pour effectuer notre première requête sur les informations temps réel de notre supervision. Nous allons récupérer, par exemple, tous les services en état critique de notre infrastructure. Pour obtenir les services en état critique, il faut ajouter le paramètre status égal à critical dans l'URL.
curl -s 'http://192.168.0.250/centreon/api/index.php?object=centreon_realtime_services&action=list&status=critical' -H 'Content-Type: application/json' -H 'centreon-auth-token: 'NWEwODhmODA1ZjllMDUuODA4MjAxNTY=''
Nous aurons le résultat suivant :
[{"host_id":"21","name":"vmitop","description":"MySQL_qcache-hitrate","service_id":"93","state":"2","state_type":"1","output":"CRITICAL: query cache hitrate at 0.00%","perfdata":"'qcache_hitrate'=0.00%;40:;20:;0; 'qcache_hitrate_now'=100.00%;;;0;","max_check_attempts":"3","check_attempt":"3","last_check":"1510511092","last_state_change":"1510081625","last_hard_state_change":"1510081985","acknowledged":"1","criticality":"1"},{"host_id":"14","name":"Centreon-Server","description":"version_plugin_old","service_id":"380","state":"2","state_type":"1","output":"CRITICAL - Ver. Centreon 20160524  Ver. Git 20171013, The plugin must be updated","perfdata":"","max_check_attempts":"3","check_attempt":"3","last_check":"1510468293","last_state_change":"1510079517","last_hard_state_change":"1510079517","acknowledged":"1","criticality":""}]
C'est assez brut de fonderie et pas très lisible. Ce qui m'intéresse, c'est le nombre de service qui est en état critique. Nous utiliserons l'utilitaire jq pour cela.
curl -s 'http://192.168.0.250/centreon/api/index.php?object=centreon_realtime_services&action=list&status=critical' -H 'Content-Type: application/json' -H 'centreon-auth-token: 'NWEwODhmODA1ZjllMDUuODA4MjAxNTY='' | jq 'length'
Nous aurons le résultat suivant :
2
Si vous voulez les services critiques non-acquités, il faudra utiliser le paramètre viewType comme ceci :
curl -s 'http://192.168.0.250/centreon/api/index.php?object=centreon_realtime_services&action=list&status=critical&viewType=unhandled' -H 'Content-Type: application/json' -H 'centreon-auth-token: 'NWEwODkyNWEwM2Y4YjQuODA2MTQxNDQ='' | jq 'length'

3 Script etat_monitoring

3.1 Authentification

Passons à un exercice pratique. Nous allons créer un petit script utilisant l'API Rest en bash pour récupérer les états des hosts et des services. Commençons par la récupération du jeton (token).
#!/bin/bash
# etat_monitoring.sh
# version 1.00
# date 12/11/2017

CURL="/usr/bin/curl"
JQ="/usr/bin/jq"
SED="/bin/sed"

IP_CENTREON="192.168.0.250"
USER="admin"
PASSWORD="password"

TOKEN=`$CURL -s -d "username=$USER&password=$PASSWORD" -H "Content-Type: application/x-www-form-urlencoded" -X POST http://$IP_CENTREON/centreon/api/index.php?action=authenticate | $JQ '.["authToken"]'| $SED -e 's/^"//' -e 's/"$//'`

echo $TOKEN
Modifiez les droits du fichier pour le rendre exécutable.
chmod +x etat_monitoring.sh
Lancez la commande, vous devriez afficher un jeton comme ci-dessous :
root@debkvm:/home/vmdebian# ./etat_monitoring.sh
NWEwOGFiMjQyNjAxZjMuMDUxNjMwNzE=

3.2 les requêtes

Maintenant que nous avons notre jeton, nous allons construire nos requêtes pour les hosts puis pour les services. Ajoutons ces lignes à notre script et supprimons la ligne echo $TOKEN.
NB_HOST=`$CURL -s "http://$IP_CENTREON/centreon/api/index.php?object=centreon_realtime_hosts&action=list&viewType=unhandled&status=down" -H 'Content-Type: application/json' -H 'centreon-auth-token: '$TOKEN'' | $JQ 'length'`

NB_SERVICE=`$CURL -s "http://$IP_CENTREON/centreon/api/index.php?object=centreon_realtime_services&action=list&viewType=unhandled&status=critical" -H 'Content-Type: application/json' -H 'centreon-auth-token: '$TOKEN'' | $JQ 'length'`

echo "Critical hosts    : "$NB_HOST
echo "Critical services : "$NB_SERVICE
Pour obtenir les états non acquittés, nous utiliserons le paramètre viewType à unhandled. Attention par défaut, comme sur la vue temps réel, le nombre d'objets est limité à 30. Pour augmenter cette limite, il faudra utiliser le paramètre limit. Exemple de l'utilisation du script :
root@debkvm:/home/vmdebian# ./etat_monitoring.sh
Critical hosts : 1
Critical services : 1
Stacks Image 294364
Notre exemple en image
Nous avons vu un bref aperçu de l'API Rest, il existe encore bien d'autres possibilités comme l'utilisation de CLAPI dans l'API Rest.

4 Pour aller plus loin

comments powered by Disqus
comments powered by Disqus
 Vous êtes ici: