Page History

Introduction

Shinken Enterprise s’appuie sur des programmes externes appelés "plugins de check ou sondes" pour pouvoir superviser une large variété d'éléments.

Le démon Poller exécute les sondes de supervision et le démon Reactionner exécute les scripts de notification. Ces deux démons devront donc accéder à ces sondes directement sur leur système/serveur.

Un certain nombre de sondes sont incluses lorsque vous installez de l'installation de Shinken Enterprise, mais vous pouvez également il est également possible d'en télécharger sur depuis l'Internet. 

Si vous avez Avec quelques compétences en scripting, vous pouvez également créer vos propres il est par ailleurs possible de créer des sondes assez simplement, il suffira d'utiliser les codes retours correspondants.

Qu'est ce qu'une sonde ou un plugin ?

Quelles sondes sont disponibles ?

Shinken Enterprise est livré en standard avec un pack de sondes. Ces sondes sont placées dans le répertoire répertoire /var/lib/shinken/libexec et ces sondes elles sont utilisées par des commandes Shinken déjà créées lorsque vous installez lors de l'installation de Shinken Enterprise.

Si vous regarder comment est créé la commande depuis l'UI de configuration, vous verrez que la ligne de commande fait référence à la variable de remplacement Dans les commandes, consultables dans l'Interface de Configuration, les lignes de commande font référence aux données de remplacement $NAGIOSPLUGINS$ , $PLUGINSDIR$ ou encore $USERPLUGINSDIR$.

Ces variables données sont globales , et déclarées depuis dans le fichier fichier /etc/shinken/resource.d/paths.cfg et elle représente . Elles représentent les chemins disques des répertoires des sondes :

Dans les répertoires $NAGIOSPLUGINS$ et $PLUGINSDIR$, il y a des sondes pour surveiller tout type d'éléments et services.

Ils Elles utilisent des protocoles classiques  WMIstandard comme : WMI, SNMP, SSH, TCP, UDP, ICMP, LDAP et plus encore.

Cela permet de surveiller à peu près tout :

• Unix/Linux, Windows

• Routeurs, Switches

• services réseau : "HTTP", "POP3", "IMAP", "FTP", "SSH", "DHCP"

• Charge CPU, utilisation disque, utilisation mémoire..mémoire…

• Applications, Bases de données, logs et plus.

Droits et accès 

Les sondes sont utilisées par les commandes Shinken. Commandes qui peuvent être rattachées directement à des hôtes et des checks ( via leurs commandes de vérification ), ou encore à des méthodes de notifications ( voir la page Créer une méthode de notification spécifique - bonnes pratiques ) ou commandes lancées par le gestionnaire d'événements ( voir la page Gestionnaire d'événements ).

Suivant le cas, elles seront donc exécutées par le Poller ( pour les hôtes et checks ) ou par le Reactionner ( pour les notifications et les gestionnaires d'évènements ).

Le démon correspondant exécutera alors la commande de son répertoire de sonde. Les processus Shinken des démons, lancés en tant qu'utilisateur Unix "shinken", utiliseront donc cet l'utilisateur "shinken" pour l'exécution des sondes.

Pour la bonne exécution des sondes, il est donc important de s'assurer que l'utilisateur shinken puisse correctement accéder en exécution aux scripts/sondes.

Pour cela, si besoin, rajoutez les droits UNIX correspondants :

chmodchmod 755 ma_sonde.py

ou

chmod +x ma_sonde.py

Aussi, les droits propriétaires des scripts peuvent rester root/root, il n'est pas nécessaire de donner changer le droit "propriétaire" ( ownership" ) du fichier à l'utilisateur "shinken" via la commande chown.

Comment utiliser une sonde ?

La plupart des sondes présentent des informations de type utilisation en les exécutant avec l'extension possèdent une option pour afficher l'aide dans la ligne de commande : "-h" ou "--help" dans la ligne de commande.

Comme vu précédemment, les scripts sont exécutés via l'utilisateur UNIX shinken, nous vous conseillons donc d'effectuer vos il faut donc effectuer les tests à partir de cet utilisateur :

su su - shinken

Par exemple, si vous voulez pour savoir comment fonctionne la sonde check_http ( sonde du répertoire $NAGIOSPLUGINS$ qui vérifie le statut du port HTTP d'un serveur ) ou pour savoir quelles options sont possibles, vous devez il est possible de lancer la commande suivante : 

/usr/lib64/nagios/plugins/check_http --help

Une fois que vous savez comment s'en servir, vous pouvez alors tenter d'exécuter la sonde avec les paramètres souhaités :

/usr/lib64/nagios/plugins/check_http -H www.google.fr

Vous obtenez alors la réponse de la sonde :

HTTP OK: HTTP/1.1 200 OK - 11837 bytes in 0.313 second response time |time=0.312690s;;;0.000000 size=11837B;;;0

Ici la ligne de retour contient deux parties séparées par le symbole pipe |.

Nous allons voir maintenant comment se compose le retour d'une sonde, de manière à ce que vous puissiez créer vos propres scripts de sonde.

Créer sa sonde (API)

Concept de sonde

Les scripts et les exécutables doivent faire au moins deux choses :

• sortir avec l'une des nombreuses valeurs possibles en retour ( "code retour" )

• retourner au moins une ligne de texte vers "STDOUT"

Le fonctionnement interne de la sonde importe peu à Shinken Enterprise, c'est l'interface entre eux deux qui compte.

Votre sonde peut vérifier le statut d'un port TCP, lancer une requête sur une base de données, ou faire tout ce qui est nécessaire pour vérifier un élément sur un réseau LAN ou WAN ou encore sur Internet. 

Les détails dépendront de ce qui doit être vérifié. 

Code retour

Format de sortie des données de sonde

Au minimum, la sonde doit retourner une ligne de texte vers STDOUT.

La sonde peut également retourner en option des données de performance pour la métrologie.  

Le format standard de sortie d'une sonde est donc le suivant :

TEXT OUTPUT | OPTIONAL_PERFDATA

Les données de performance sont optionnelles. Si une sonde retourne des données de performance, elles doivent être séparées du reste du texte par le symbole pipe | .

Exemples de retour de sonde

Voici un extrait de l'aide de la commande : 

Options:
 -h, --help
    Print detailed help screen
 -V, --version
    Print version information
 --extra-opts=[section][@file]
    Read options from an ini file. See
    https://www.nagios-plugins.org/doc/extra-opts.html
    for usage and examples.
 -H, --hostname=ADDRESS
    Host name argument for servers using host headers (virtual host)
    Append a port to include it in the header (eg: example.com:5000)

On peut lire que l'option "-H" permet de préciser le nom de l'hôte à tester, donc pour tester la réponse http de www.google.fr, on peut faire la commande suivante : 

/usr/lib64/nagios/plugins/check_http -H www.google.fr

Qui donne le retoure suivante : 

HTTP OK: HTTP/1.1 200 OK - 11837 bytes in 0.313 second response time |time=0.312690s;;;0.000000 size=11837B;;;0

Ici la ligne de retour contient deux parties séparées par le symbole pipe |.

Le chapitre suivant présente comment se compose le retour d'une sonde pour la création des scripts de sonde.

Créer sa sonde (API)

Voici comment créer des sondes ! Ces sondes seront à placer dans le répertoire $USERPLUGINSDIR$.

Concept de sonde

Les scripts et les exécutables doivent faire au moins deux choses :

• sortir avec une valeur valide de retour ( "code retour" )

• retourner au moins une ligne de texte sur la sortie standard ( STDOUT )

Le fonctionnement interne de la sonde importe peu à Shinken Enterprise, c'est l'interface entre eux deux qui compte.

La sonde peut vérifier le statut d'un port TCP, lancer une requête sur une base de données, ou faire tout ce qui est nécessaire pour vérifier un élément sur un réseau LAN ou WAN ou encore sur Internet. 

Les détails dépendront de ce qui doit être vérifié. 

Code retour

Shinken Enterprise détermine le statut d'un hôte ou d'un check en évaluant le code retour de la sonde.

La table suivante montre la liste des codes retour valides, avec leur statut correspondant, suivante si la commande est attachée à un check ou à un hôte :

Format de sortie des données de sonde

Au minimum, la sonde doit retourner une ligne de texte sur la sortie standard ( STDOUT ).

La sonde peut également retourner en option des données de performance pour la métrologie.  

Le format standard de sortie d'une sonde est donc le suivant :

TEXT OUTPUT | OPTIONAL_PERFDATA

Les données de performance sont optionnelles. Si une sonde retourne des données de performance, elles doivent être séparées du reste du texte par le symbole pipe | .

Exemples de retour de sonde

Voici quelques exemples possibles.

Cas 1: une ligne de retour ( texte seulement )

Imaginons une sonde qui retourne une ligne telle que décrite en dessous :

DISK OK - free space: /var 3326 MB (56%);

Si cette sonde est utilisée pour réaliser une vérification de service, la totalité de la ligne retour sera stockée dans $SERVICEOUTPUT$ .

Cas 2: une ligne de retour ( texte et données de performance )

La sonde peut retourner en option des données de performance utilisables par Graphite. Dans ce cas, les données de performance doivent être séparées par le symbole pipe " | " :

DISK OK - used space: /var 3326 MB (56%); | /var=3326

Si cette sonde est utilisée pour vérifier un service, la partie à gauche du symbole sera stockée dans  $SERVICEOUTPUT$  et la partie à droite du séparateur sera stockée dans $SERVICEPERFDATA$

Cas 3: plusieurs lignes de retour ( texte et données de performance )

En plus de retourner des données de performances, la sonde peut retourner un résultat long à l'aide d'un saut de ligne. 
À ce moment-là, le retour de la sonde sera divisé en trois parties :

• le résultat,
• le résultat long,
• les métriques.

DISK OK 
- used space: /var 3326 MB (56%); | /var=3326

Exemples de retour de sonde avec HTML/CSS

Il est tout à fait possible de retourner du HTML/CSS dans le retour des sondes.

De cette manière, il est possible d'insérer du style et donc d'améliorer le retour des sondes affiché dans l'Interface de Configuration ( évaluation des checks ), dans l'Interface de Visualisation ( liste et panneau de détails ) et dans les mails de notification.

Voici un exemple :

<span style="color:#e48c19;font-weight: bold;">[WARNING]</span> 1 disk uses more than 95% of his total disk space :<br/><li>/ (97%)</li>
<style type="text/css"> .disks-table, .disks-table td, .disks-table th { border: 1px solid #000000 !important; border-collapse: collapse !important; color: #000000

Exemples de retour de sonde avec HTML/CSS

Il est tout à fait possible de retourner du HTML/CSS dans le retour des sondes.

De cette manière, il est possible d'insérer du style et donc d'améliorer le retour des checks affiché dans un navigateur WEB, depuis l'UI de configuration ( évaluation des checks ) et depuis l'UI de visualisation ( liste et panneau de détails ).

Voici un exemple :

<span style="color:#e48c19;font-weight: bold;">[WARNING]</span> 1 disk uses more than 95% of his total disk space :<br/><li>/ (97%)</li>
<style type="text/css"> .disks-table, .disks-table td, .disks-table th { border: 1px solid #000000 !important; border-collapse: collapse !important; color: #000000 !important; } .disks-table { width: 90% !important; } .disks-table-th { background-color: #E8E7E7 !important; width: auto !important; max-width: 20% !important; padding: 2px !important; word-break: break-word !important; background-color: #E8E7E7 !important; text-align: center;}.disks-table-td { padding: 2px !important; width: auto !important; max-width: 20% !important; font-weight: normal !important; word-break: break-word !important; background-color: #FFFFFF !important; } .disks-host-command { font-style: italic !important; color: #7F7F7F !important; } .disks-table-center { text-alignwidth: center90% !important; } </style><br/>More than 95% of total disk space used :<br/> <table class="disks-table"><tr><th class="disks-table-th">Disk</th><th class="disks-table-th">Usage</th><th class="disks-table-th">Used</th><th class="disks-table-th">Total</th></tr>
 <tr> <td class="disks-table-td">/</td> <td class="disks-table-td">97%</td><td class="disks-table-td">68.9GB</td><td class="disks-table-td">75.2GB</td></tr>
</table><br> | "/boot_used_pct"=16%;95%;98%;0%;100% "/boot_used"=0.069993019104GB;0.441808128357;0.455759963989;0;0.465061187744 "/_used_pct"=97%;95%;98%;0%;100% "/_used"=68.8651046753GB;71.4608747482;73.7175339508;0;75.2219734192

Les données de performance

Les données de performance

Dans la sortie d’une sonde, les données de performance se trouvent après le caractère |, selon le format :  TEXT OUTPUT | OPTIONAL_PERFDATA. Ces données sont facultatives. Une sonde peut retourner une ou plusieurs données de performance.

Les données de performance sont sauvegardées dans la base de données Graphite (  voir la page Base de métrologie ( Graphite )  )

Les données de performance sont accessibles depuis le widget Graphique ( voir la page Widget Graphique ), l'onglet Graphiques ( voir la page Onglet Graphiques ) et les outils tiers capables de traiter les données de Graphite. Shinken assure la compatibilité avec Grafana ( voir la page Grafana - v8.3.2 )

Syntaxe des données de performance

La syntaxe de Shinken se rapproche de la syntaxe des données de performance utilisée par Nagios ( voir la documentation de nagios https://nagios-plugins.org/doc/guidelines.html#AEN200 ). Contrairement à Nagios, Shinken ne gère pas les intervalles pour les seuils critique et d'avertissement. Par conséquent, les intervalles de seuils d'une sonde compatible Nagios ne seront pas pris en charge par Shinken.

La syntaxe d’une donnée de performance est la suivante :  'label'=valueUNIT;warning;critical;minimumvalue;maximalvalue

Les différents champs sont séparés par un point virgule ( ; ).

Exemple

Ok: | 'metric'=14;90;9

Pour renvoyer plusieurs données de performance, les données doivent se suivre, séparées par des espaces.

Exemple : 

Ok: | 'metric_1'=14;90;95 'metric_2'=44;90;95

Affichage dans les interfaces 

Quelques exemples

Ok: | 'metric~'=14;90;95 'metric!'=44;90;95

• Les deux métriques sont fusionnés en "metric_" et les données sont mélangées. Un seul graphique sera visible depuis l'Interface de Visualisation

Ok: | 'shinken-broker [ master ]'=14;90;95

• Le label sera transformé en shinken-broker___master___ 

Ok: | 'shinken-broker [ master ]'=45.5B;70;80

• Il est possible de préciser l'unité de la métrique

Ok: | 'shinken-broker [ master ]'=-7;-25;-5

• Il est possible d'avoir des métriques négatives

Une donnée de performance est composée au minimum de :

key=value

La valeur key est une suite de caractères qui permettra de donner un titre au graphique qui sera composé des données de performance.
La valeur value est un nombre représentant la donnée de performance à l'instant de la requête de la sonde.

Un exemple:
/var=3326

Ici, dans le cas de cette sonde, la valeur key représente le nom de la partition disque de serveur, et la valeur value représente un volume de cette partition.

Afin de rajouter des informations additionnelles, il est intéressant de rajouter d'autres options séparées par des points-virgules :

 key=valueUNIT;warning;critical;minimumvalue;maximalvalue

• UNIT : chaîne de caractères représentant l'unité de la valeur - les unités sont facultatif,
• warning : seuil de warning affiché dans le graphique,
• critical : seuil de critique affiché dans le graphique,
• minimum value : Valeur minimale que pourra retourner la sonde,
• maximale value : Valeur maximale que pourra retourner la sonde.

Ces informations pourront être utilisées et affichées dans les graphiques accessibles depuis l'UI de visualisation via le Widget Graphique.

Voici un exemple:

/var=3326MB;5800;5900;0;6000

Ici, la taille de la partition /var, récupérée par la sonde à l'instant T, est de 3326MB. Le seuil de warning est de 5800, et le seuil de critique est de 5900. La valeur minimum récupérée sera 0 et la valeur maximale sera de 6000 ( car la partition fait 6GB ).

Taille maximum du retour d'une sonde

Shinken Enterprise va seulement lire les premiers 64 KB de données qu'une sonde retourne. Cela évite de surcharger une la base de données et le flux d'échange entre les démons.

Exemple de sonde écrite en python

Voici un exemple très simple et basique d'une sonde écrite en Python afin de vérifier la présence du fichier /tmp/test_file :file :

#!/usr/bin/env python

import os
import sys

# Shinken return values
shinkenRetValOk = 0
shinkenRetValWarn = 1
shinkenRetValCritical = 2

try:
    os.stat("/tmp/test_file")

except:
    print "CRITICAL! Unable to open test_file"
    sys.exit(shinkenRetValCritical)

print "OK! The file /tmp/test_file exists"
sys.exit(shinkenRetValOk)

Exemple de sonde écrite en VBS pour un Poller Windows

Voici un exemple très simple et basique d'une sonde check_file_exists.vbs écrite en VBS afin de vérifier la présence d'un fichier passé en argument ( avec retour d'une donnée de performance ):

Dim strfilepath
Dim wsh
Dim Perf_Data

'##########################################################'
Set objFSO = CreateObject("Scripting.FileSystemObject")
Set wsh = CreateObject("WScript.Shell")
'##########################################################'

If Wscript.Arguments.Count = 1 Then
strfilepath = Wscript.Arguments(0)

If (objFSO.FileExists(strfilepath)) Then
	Perf_Data = "|'path_file_existance'=1"
	Wscript.Echo "OK: the file with path " & strfilepath & " exists" & Perf_Data
	Wscript.Quit(0)
else
	Perf_Data = "|'path_file_existance'=0"
	Wscript.Echo "CRITICAL: the file with path " & strfilepath & " does NOT exist" & Perf_Data
	Wscript.Quit(2)
End If

else
	Wscript.Echo "UNKNOWN"
	Wscript.Quit(3)
End If

Ici pour l'utilisation de Pour utiliser cette sonde via sur un Poller sur Windows, la ligne de commande devra être définie comme tel : 

C:\WINDOWS\SysWOW64\cscript.exe //nologo $WINPLUGINSDIR$\check_file_exists.vbs "$_HOSTFILEPATH$"

Récupérer des sondes

Vous pouvez dupliquer des sondes que vous trouverez dans les répertoires Il est possible de dupliquer les sondes présente dans les répertoires $NAGIOSPLUGINS$ et $PLUGINSDIR$ et les placer dans votre répertoire le répertoire $USERPLUGINSDIR$ pour les personnaliser.

Mais vous pouvez en trouver beaucoup Beaucoup d'autres sondes sont disponibles dans la communauté Nagios, et plus particulièrement dans sur les espaces sites suivants :

• Shinken Monitoring Plugins: http://www.shinken.io/  - Des informations pour l'installation de pack Shinken IO ici Installer un pack de supervision

• Monitoring Plugins Project: https://www.monitoring-plugins.org

• Nagios Plugins Exchange: https://exchange.nagios.org/

Mise en place d'une sonde dans Shinken Enterprise

Une fois avoir créé votre propre la sonde réalisée ou une fois l'avoir téléchargée, il faut maintenant la mettre en place dans Shinken afin de pouvoir facilement l'utiliser via des checks appliqués à des modèles d'hôtes. Nous vous conseillons fortement Il est préférable de passer par des modèles d'hôtes et des checks dédiés à ces modèles pour pouvoir réutiliser ce check le plus simplement possible.

Mise en place de

la sonde

• Créer ou télécharger votre une sonde via une la commande wget depuis vos les serveurs Shinken avec les démons Poller.
• Placer la sonde dans $USERPLUGINSDIR$  ( /var/lib/shinken-user/libexec/ ) de votre ou vos des démons Shinken Poller.

Droits d'exécution

• Donner les droits d'exécution : chmod +x monscript.py

Création de la commande Shinken

• Ouvrir l'interface utilisateur ( UI ) de configuration Interface de Configuration et créer une commande "cmd_monscript" avec la ligne de commande suivante : $USERPLUGINSDIR$\monscript.py
• Si votre la sonde prend des arguments, ajustez votre il faut ajuster la ligne de commande. Vous pouvez vous Il est possible de s'inspirer d'autres commandes.

Création d'un modèle d'hôte

• Créer un modèle d'hôte : "monmodele"

Création d'un check dédié

• Pour appliquer systématiquement le script lors de l'application de "monmodele" à un hôte, il faut créer un "check dédié à modèle d'hôte", par exemple check_monscript ( cf: le check dédié "http" ).
• Dans ce check dédié, mettre "generic-service" dans la propriété "Modèle de Check hérité" et mettre le modèle "monmodèle" dans la propriété "Attaché sur les modèles d'hôte"
• Faire pointer la commande de vérification vers la commande cmd_monscript

Application du modèle et évaluation

• Appliquer le modèle "monmodèle" à des hôtes, le check doit bien être appliqué, vous pouvez il est possible d'essayer ce check depuis l'onglet "Checks"