Page History

Concept général

Shinken Entreprise permet d'effectuer des remplacements dynamiques de contenu ( autrefois appelé "MACRO" ).

• Cela permet de paramétrer avec une grande flexibilité les commandes lancées par Shinken, l'affichage des seuils, les liens externes des

• éléments… 
• La notation entre dollars "$" est utilisée pour permettre ce remplacement.

Exemple :

On dispose d'une commande qui se charge de contacter un hôte pour déterminer s'il est joignable ou non.

• Les variables donnent la capacité d'utiliser dans la configuration de la supervision,
  • des informations dites globales,
  • ainsi que les propriétés et les données présentes sur les éléments ( Hôtes, Cluster, Check, Utilisateurs ).
    • par exemple, les propriétés d'un hôte dans la vérification d'un check.

Exemple :

On dispose d'une commande qui se charge de contacter un hôte pour déterminer s'il est joignable ou non.

• On veut donc que la commande récupère automatiquement l'adresse de l'hôte sans avoir à spécifier manuellement l'adresse pour chaque hôte.
• Pour résoudre ce problème, on effectue un remplacement de contenu.
• Dans Shinken Entreprise, on peut utiliser la

• Variable $HOSTADDRESS$ qui va contenir l'adresse de l'hôte courant.

Ainsi, en utilisant cette notation Variable dans notre commande, lorsque celle-ci sera utilisée lors de la vérification d'un hôte, le mécanisme de remplacement dynamique va automatiquement remplacer la notation Variable par l'adresse de l'hôte.

check_ping -H "$HOSTADDRESS$" (...autres paramètres)

donne au final

check_ping -H "192.168.1.12" (...autres paramètres)

Utilisation du remplacement dynamique de contenu

Endroits où

le remplacement dynamique de contenu est effectué

Le remplacement dynamique de contenu n'est pas effectué dans toutes les propriétéspartout.

Voici la liste par type d'élément des propriétés où est effectué le remplacement dynamique de contenu :

Les Hôtes & Les Clusters, avec et leurs modèles

• Vivant ( Commande de vérification ) ( Les Arguments ),
• Affichage des seuils,
• URL externe,
• Liste des URL externes,Commande lancée par le gestionnaire d'événements ( Les Arguments )
• Données locales & héritées d'un modèle

• ,
• Commande lancée par le gestionnaire d'événements.

Les Clusters et leurs modèles

• Définition,
• Affichage des seuils,
• URL externe,
• Liste des URL externes
• Vivant (Commande de vérification) ( Les Arguments )
• Affichage des seuils
• Commande lancée par le gestionnaire d'événements ( Les Arguments )
• ,
• Données locales & héritées d'un modèle

Les Utilisateurs avec leurs modèles

• Données locales & héritées d'un modèle

• ,
• Commande lancée par le gestionnaire d'événements.

Les Checks et leur modèles

• Commande de vérification,
• Affichage des seuils,
• URL externe,
• Liste des URL externes,
• Données locales & héritées d'un modèle,
• Commande lancée par le gestionnaire d'événements.

Les Utilisateurs avec leurs modèles

• Données locales & héritées d'un modèle

Les Les Méthodes de notification

• Commande de notifications pour l'hôte ( Les Arguments )/cluster,
• Commande de notifications pour les checks ( Les Arguments ).

Les Commandes

• Ligne de Commande

Les Modulations de données

• Données locales & héritées d'un modèle

Remplacement récursif

Le remplacement dynamique de contenu est récursif.

• Ce qui veut dire

• que les Variables dans les Variables

• seront remplacées

• les Données locales & héritées d'un modèle,
• les Variables globales
• les Variables génératives

• .
• Il est

• possible d'effectuer une boucle de remplacement sans le vouloir ( exemple : VARIABLE_1  nécessite VARIABLE_2  qui nécessite VARIABLE_3 qui nécessite VARIABLE_1 ).
  Dans ce cas, une erreur est

• remontée, dans l'interface de Configuration et de Visualisation.

Limites lors du remplacement des

Variables

Il peut arriver que le résultat de certaines variables dynamiques Variables nécessite l'évaluation d'autres variables dynamiques Variables pour être obtenu.

Pour éviter tout emballement récursif ( exemple : VARIABLE_1  nécessite VARIABLE_2  qui nécessite VARIABLE_3 qui nécessite VARIABLE_1 4 ...  ), les limites suivantes sont appliquées lors de la résolution des variables dynamiques Variables :

• Il ne peut pas y avoir plus de 32 niveaux d'imbrication de variablesVariables, au-delà de ce niveau, les variables Variables ne sont plus résolues.
• Il ne peut pas y avoir plus de 255 variablesVariables à résoudre sur la ligne de commande, au-delà de ce nombre, les variables Variables ne sont plus résolues.
• La ligne de commande générée après résolution des variables dynamiques Variables ne peut pas excéder 65000 caractères.

Si un dépassement se produit,

• la résolution des

• Variables est interrompue,
• et la

• Variable est tronquée pour être

• intégrée dans un message remontant cette information.

Comment est effectué le remplacement des

Variables

Le remplacement est fait dans deux démons :

• Le Synchronizer pour l'Interface de Configuration.
• Le Scheduler pour l'Interface de Visualisation, les notifications et l'exécution la préparation des commandes de supervision ( pour leur exécution par le Poller ).

Le Synchronizer ne gérant que la configuration des éléments,

• il n'a pas accès aux états des éléments

• supervisés, comme le statut d'un hôte. Il ne peut donc pas remplacer

• toutes les Variables.
• La liste des Variables non

• résolues par le Synchronizer est disponible dans le chapitre

• ci-dessous ( voir Les Variables

• issues des Propriétés ( $HOST...$, $SERVICE...$, $CONTACT...$ ) )

Il y a une autre différence entre ces deux remplacements sur les remplacements effectués par les deux démons : 

• le Scheduler, gère le nombre de variables dynamiques Variables présentes sur la ligne de commande, à chaque étape de substitution.
• le Synchronizer, lors de l'essai de check,
  • ne gère pas le nombre de
  variables
  • Variables présentes sur la ligne de commande lors des substitutions,
  • et il n'applique pas la règle limitant leur nombre à 255 à chaque étape de substitution.

Les différents types de Variables

Il existe trois types de Variables :

• Les Variables globales
• Les Variables d'élémentLes Variables globales 
• Les Variables génératives

Les Variables

Les Variables d'élément désignent les variables dont les valeurs proviennent d'un élément.

Les Variables pour les Propriétés ( $HOST..., $SERVICE..., $CONTACT... )

Parmi tous les éléments de Shinken Entreprise, il est possible d'accéder à certain attributs des hôtes, des checks et des utilisateurs.

Dans le premier exemple, la notation entre dollars permet d'accéder à une propriété de l'hôte, par exemple l'adresse: $HOSTADDRESS$. 

On accède ici à la propriété "address" de l'hôte. On peut accéder à d'autres attributs de l'hôte, mais aussi à ceux d'un check ou d'un utilisateur.

globales 

Il est possible dans Shinken Entreprise de définir des Variables globales accessibles partout dans Shinken et qui ne dépendent pas d'un élément particulier.

• Ces Variables globales se définissent dans des fichiers de configuration.
• Une globale nommée MAGLOBALE sera accessible avec la notation $MAGLOBALE$.

Définir des Variables globales

Les Variables globales peuvent être définies UNIQUEMENT par fichiers de configuration.

• Par défaut, un certain de nombre de Variables globales sont prédéfinies dans le dossier /etc/shinken/resource.d,
• Ce dossier contient tous les fichiers qui déclarent les Variables globales.
• Au démarrage du Synchroniser, ces fichiers sont chargés et les Variables globales qui y sont définies sont disponibles dans l'UI de Configuration.
• Au démarrage de l'Arbiter, ces fichiers sont chargés et les Variables globales qui y sont définies sont disponibles pour tous les autres démons.

La syntaxe pour la déclaration des Variables globales est la suivante :

# Commentaire: les lignes commençant par # seront ignorées
# Les noms de globales doivent être entourés de $

$NOMDELAGLOBALE$=valeur

Les noms de Variables globales ne peuvent contenir que des caractères alphanumériques ( A-Z 0-9 ), des tirets ( - ) et des soulignés (  _ ).

• Le nom d'une Variable globale sera toujours en majuscules.
• Pour permettre à l'utilisateur de faire ses propres packs et faciliter l'import d'une configuration écrite au format cfg ( voir la page Collecteur de type ( cfg-file-import ) - Import depuis des fichiers au format .cfg ),
  • il est possible de déclarer des Variables globales dans une source.
  • Pour cela, il faut placer les fichiers .cfg dans un dossier global-data de la source.
    • Les fichiers de déclaration de Variables globales seront copiés par le Synchronizer dans /etc/shinken/resource.d/ pour rendre leur contenu disponible comme pour les autres Variables globales.
      • Voir plus précisément le chapitre sur les données globales dans la page Collecteur de type cfg-file-import ( format Shinken ou nagios )

Variables globales prédéfinies

Shinken possède aussi des Variables globales directement utilisable et dont les valeurs proviennent des démons.

Il est donc possible d'accéder aux propriétés des hôtes, des checks ou bien des utilisateurs. Pour cela, il faut commencer le nom de la Variable par HOST, SERVICE ( pour les checks ) ou CONTACT ( pour les utilisateurs ).

Par exemple:

• $HOSTADDRESS$
• $SERVICEDISPLAYNAME$
• $CONTACTEMAIL$

Le schéma ci-dessus explique le cas du remplacement des données locales pour les checks et les hôtes.

Dans le cas des utilisateurs, plusieurs utilisateurs peuvent être accrochés sur un hôte ou un check. Ils sont utilisés pour envoyer les notifications lorsque l'hôte ou le check passe dans un état d'erreur.

Dans ce cas, une notification est envoyée à chaque utilisateur. La commande utilisée pour envoyer la notification peut alors utiliser un remplacement dynamique de contenu pour accéder aux informations de l'utilisateur qui va recevoir la notification.

Syntaxe	Description	Remplacé dans le Synchronizer	Remplacé dans le Scheduler

$HOSTNAME$

Nom de l'hôte ( propriété host_name )

$HOSTDISPLAYNAME$

Nom d'affichage de l'hôte ( propriété display_name )

$LONGDATETIME$	Heure/date courante au format long ( par exemple : Fri Oct 13 00:30:28 CDT 2000 )
$SHORTDATETIME$	Heure/date courante au format court ( par exemple : 10-13-2000 00:30:28 )
$DATE$	Date courante ( par exemple : 10-13-2000 )
$TIME$	Heure courante ( par exemple : 00:30:28

$HOSTADDRESS$

Adresse de l'hôte ( propriété address

)

$HOSTSTATE$

Etat courant de l'hôte ( UP, DOWN, ou UNREACHABLE

$TIMET$

Heure courante au format timestamp( par exemple : 1706871278 )

 $HOSTSTATETYPE$Type d'état permettant la confirmation du statut d'un hôte ( SOFT ou HARD

$SHINKENVERSION$

Contient la version de Shinken. ( par exemple : V02.08.02 )

$HOSTSTATEID$

Numéro correspondant à l'état courant de l'hôte ( 0=UP, 1=DOWN, ou 2=UNREACHABLE )

$LASTHOSTSTATE$

Etat précédent de l'hôte ( UP, DOWN, ou UNREACHABLE )

$LASTHOSTSTATEID$

Numéro correspondant à l'état précédent de l'hôte ( 0=UP, 1=DOWN, ou 2=UNREACHABLE )

$HOSTGROUPNAME$

Nom du groupe d'hôte auquel appartient l'hôte. Si il appartient à plusieurs groupes d'hôtes, un seul sera retourné

$HOSTGROUPNAMES$

Liste des groupes d'hôtes auxquels appartient l'hôte, séparés par des virgules

$LASTHOSTCHECK$

Date au format timestamp de la dernière vérification de l'hôte

$LASTHOSTSTATECHANGE$

Date au format timestamp du dernier changement d'état de l'hôte

$LASTHOSTUP$

Date au format timestamp du dernier état UP de l'hôte

$LASTHOSTDOWN$

Date au format timestamp du dernier état DOWN de l'hôte

$LASTHOSTUNREACHABLE$

Date au format timestamp du dernier état UNREACHABLE de l'hôte

$HOSTOUTPUT$

Résultat de la dernière vérification de l'hôte

$LONGHOSTOUTPUT$

Résultat long de la dernière vérification de l'hôte

$HOSTPERFDATA$

Données de performances renvoyées par la dernière vérification de l'hôte

$HOSTCHECKCOMMAND$

Nom de la commande utilisée pour la vérification de l'hôte ( avec les paramètres )

$HOSTNOTESURL$

URL externe de l'hôte ( propriété notes_url )

$HOSTBUSINESSIMPACT$

Nombre entre 0 et 5 indiquant l'impact métier de l'hôte

$HOSTFIRSTNOTIFICATIONDELAY$ 

Nombre de minutes à attendre avant d'envoyer la première notification pour un hôte

$HOSTNOTIFICATIONNUMBER$

N° d'ordre d'une notification pour un événement donné

$HOSTTHRESHOLDSDISPLAY$

Affichage des seuils, tel qu'il est paramétré sur l'hôte

Propriétés des checks

Utiliser des Variables globales

Les Variables globales sont accessibles en entourant le nom de la Variable globale par des dollars "$".

• La Variable globale "MAGLOBALE" est donc accessible avec la notation $MAGLOBALE$.

Les Variables d'élément ( Hôte, Cluster, Check, Utilisateur )

Les Variables d'élément correspondent à des propriétés ( de définition ou d'exécution ) ou des données d'un élément.

Les Variables issues des Propriétés ( $HOST...$, $SERVICE...$, $CONTACT...$ )

Parmi tous les éléments de Shinken Entreprise, il est possible d'accéder à certaines propriétés des Hôtes, des Clusters, des Checks et des Utilisateurs.

• Pour accéder à une propriété d'un élément, il faut bien sûr le $, puis le type de l'élément et le nom de la propriété
  • Pour les Types :
    • HOST => pour les Hôtes et Clusters ( c'est le même mot clé de type )
    • SERVICE => pour les Checks
    • CONTACT => pour les Utilisateurs

  • On accède a la propriété en rajoutant son nom aprés le type

    Panel
    title Propriétés de l'élément
    Variable Fonction $HOSTPROPRIETE$ Accède une propriété de l'hôte $SERVICEPROPRIETE$ Accède à une propriété du check $CONTACTPROPRIETE$ Accède à une propriété de l'utilisateur

  • Les propriétés disponibles par éléments diffèrent en fonction de l'élément.
    • Les noms des propriétés accessibles par le mécanisme de Variable sont listés dans les chapitres ci-dessous décrivant les éléments ( Hôtes, Clusters, Checks, Utilisateurs ). 
      
      
• Point important : Il existe 2 types de Propriétés
  
  • Des propriétés de définition ( Elles sont définies dans l'UI de Configuration et ne changent que lorsque l'on change la configuration ).
  • Des propriétés d'exécution ( Elles sont calculées par le Scheduler et susceptible de changer à chaque exécution d'une vérification de l'élément ).
    • Cela concerne les Hôtes, Les Clusters et les Checks.

• Par exemple, pour qu'une commande de vérification d'un check accède à l'adresse d'un hôte, il faut utiliser $HOSTADDRESS$.
  
  

Propriétés des Hôtes/Clusters

Propriétés des utilisateurs

Les Variables pour les Données ($_HOST..., $_SERVICE..., $_CONTACT... )

Définir des données personnalisées

Les Variables globales 

Il est possible en effectuant un remplacement de contenu d'accéder aux données locales à un hôte, un check ou un utilisateur. Il est aussi possible dans Shinken Entreprise de définir des globales accessibles partout dans Shinken et qui ne dépendent pas d'un élément particulier.

Ces globales se définissent dans des fichiers de configuration, dont le détail sera expliqué dans la section qui traite l'utilisation pratique des remplacements dynamiques de contenu. Elles sont accessibles simplement par leur nom, sans avoir besoin de le préfixer de _HOST, _SERVICE ou _CONTACT.

Par exemple, une globale nommée MAGLOBALE sera accessible avec la notation $MAGLOBALE$.

Les Variables génératives

Nous avons vu que lorsque l'on remplace dynamiquement du contenu, il est possible de faire référence aux données locales ainsi qu'aux globales. Il existe également des opérateurs spéciaux, qui ne récupèrent pas les globales et les données locales d'un élément, mais qui permettent de transférer des données, notamment des arguments de commande.

Ces opérateurs spéciaux sont accessibles avec les notations $ARGn$ et $VALUEn$.

Les Variables générées par l'utilisation d'une commande ( $ARGn$, $VALUEn$ )

Propriétés des checks

Propriétés des utilisateurs

Propriétés des notification

Les Variables pour les Données ($_HOST...$, $_SERVICE...$, $_CONTACT...$ )

Shinken Entreprise permet d'ajouter des données personnalisées sur certains éléments, comme les hôtes, les checks, les utilisateurs, et bien sûr les modèles d'hôtes, de checks et d'utilisateurs.

• Ces données permettent de compléter la définition d'un élément lorsque les propriétés par défaut de l'objet ne suffisent pas à le décrire complètement.

Par exemple, si un hôte possède deux interfaces réseau, les propriétés par défaut de l'objet ne permettent pas de spécifier deux adresses.

• Par contre, il est possible d'ajouter une donnée personnalisée qu'on appelle par exemple "ADDRESS_2" qui pourra être utilisée lorsqu'on aura besoin d'avoir la deuxième adresse de l'hôte dans un check.

Pour accéder à une donnée d'un élément, il faut bien sûr le $, puis un UNDERSCORE, puis le type de l'élément et le nom de la propriété :

• • Le UNDERSCORE => "_"
  • Les types sont les mêmes que pour les propriétés :
    • HOST => pour les Hôtes et Clusters ( c'est le même mot clé de type )
    • SERVICE => pour les Checks
    • CONTACT => pour les Utilisateurs

  • On accède à la donnée en rajoutant son nom aprés le type.

    Panel
    title Données personnalisées
    Variable Fonction $_HOSTDONNEE$ Accède à la donnée personnalisée "DONNEE" de l'hôte $_SERVICEDONNEE$ Accède à la donnée personnalisée "DONNEE" du check $_CONTACTDONNEE$ Accède à la donnée personnalisée "DONNEE" de l'utilisateur

• Par exemple, imaginons qu'on ajoute une donnée sur un hôte qui s'appelle ADDRESS_2
  • Sur la commande de vérification d'un check, il accède à l'adresse d'un hôte, il faut utiliser $_HOSTADDRESS_2$.
    
    

Définir des données personnalisées

Les données locales peuvent être définies sur les hôtes, checks, utilisateurs et leurs modèles respectifs de 2 manières :

• Par fichier de configuration
• Par l'interface de configuration

Dans un fichier de configuration, les données sont définies en préfixant un _ à leur nom. Le nom d'une donnée peut contenir seulement des caractères alphanumériques ( A-Z0-9 ), des tirets ( - ) ou underscore ( _ ). Aussi, le nom d'une donnée sera toujours en majuscules.

define host {
    host_name    mon_hote
    address		 192.168.0.12


    _DONNEE_PERSONNALISEE      valeur_de_la_donnée
}

Dans l'interface de configuration, l'ajout et la modification de données personnalisées s'effectuent grâce à l'onglet "Données".

Cette capture d'écran montre l'édition de données personnalisées dans le cas d'un hôte. Les mêmes manipulations sur les données personnalisées sont possibles pour les modèles d'hôtes, clusters, modèles de clusters, checks, modèles de check, utilisateurs et modèles d'utilisateurs.

Les Variables génératives ( $ARGn$, $VALUEn$ )

Lorsque l'on remplace dynamiquement du contenu,

• il est possible de faire référence aux propriétés, aux données locales ainsi qu'aux Variables globales.
• il existe également des Variables spéciales qui ne récupèrent ni des Variables globales, ni des données locales ou des propriétés d'un élément.
  • Elles permettent de transférer des données, notamment des arguments de commande.

Ces Variables spéciales sont accessibles avec les notations $ARGn$ et $VALUEn$.

Les Variables générées par l'utilisation d'une commande ( $ARGn$, $VALUEn$ )

Shinken Entreprise permet aux hôtes et aux checks de préciser les commandes qui seront utilisées pour la vérification de l'élément.

• Dans l'optique de rendre ces commandes le plus générique possible, et de permettre de factoriser la configuration, des arguments peuvent être passés à ces commandes.
• Ces arguments sont séparés par des points d'exclamation '!'.

Dans l'exemple, un check utilise la commande "ma_commande" et lui passe 3 arguments.

Dans la définition de la commande, on veut pouvoir récupérer la valeur de ces arguments pour pouvoir les utiliser sur la ligne de commande.

• Pour cela, on utilise la notation $ARGn$.
• La Variable $ARGn$ permet simplement d'accéder à la valeur du n-ième argument.

Dans l'exemple, on utilise $ARG1$, $ARG2$ et $ARG3$ pour récupérer les valeurs du premier, deuxième et troisième argument.

Les Variables générées par l'utilisation de la Duplication de check ( Duplicate Foreach ) - ( $KEY$, $VALUE1$ )

La fonctionnalité avancée Dupliquer des checks en fonction d'une liste de valeurs présentes dans la Donnée d'un hôte (duplicate_foreach) permet d'appliquer plusieurs fois le même check sur un hôte avec des paramètres différents, selon la valeur d'une donnée personnalisée sur l'hôte.

Sur chaque check utilisant la fonctionnalité Duplicate Foreach, une clé est affectée, et optionnellement des paramètres.

check1$(valeur1)$$(valeur2)$$(valeur3)$

La valeur de la clé est accessible avec la Variable $KEY$, et les arguments sont accessibles grâce aux Variables $VALUEn$.

Le tableau suivant récapitule les Variables permettant d’accéder aux valeurs de la donnée Duplicate Foreach:

Les Variables générées par l'utilisation de la Duplication de check ( Duplicate Foreach ) - ( $KEY$, $VALUE1$ )

Utilisation pratique des remplacements dynamiques de données

Les globales

Définir des données globales

Les données globales peuvent être définies uniquement par fichiers de configuration.

Par défaut, un certain de nombre de globales sont définies dans le dossier /etc/shinken/resource.d, dans lequel sont présents tous les fichiers qui déclarent des globales. Au démarrage de Shinken, ces fichiers sont donc chargés et les globales qui y sont définies sont alors disponibles.

La syntaxe pour la déclaration des globales est la suivante:

# Commentaire: les lignes commencant par # seront ignorées
# Les noms de globales doivent être entourés de $


$NOMDELAGLOBALE$=valeur

Comme pour les données locales, les noms de globaux ne peuvent contenir que des caractères alphanumériques (A-Z0-9), des tirets (-) et des underscore (_). Comme pour les données locales, le nom d'une globale sera toujours en majuscules.

Pour permettre à l'utilisateur de faire ses propres packs et faciliter l'import d'une configuration externe, il est possible de déclarer des globales dans une source. Pour cela, il faut placer les fichiers .cfg dans un dossier source_data de la source.

Les fichiers de déclaration de globaux seront donc copiés dans /etc/shinken/resource.d/ et disponibles comme les autres globales.

Utiliser des données globales

Remarques sur la notation entre dollars ($)

Globales prédéfinies

Limites lors de l'évaluation des variables dynamiques pour générer une ligne de commande

Il peut arriver que le résultat de certaines variables dynamiques nécessite l'évaluation d'autres variables dynamiques pour être obtenu.

Pour éviter tout emballement récursif ( exemple: VARIABLE_1  nécessite VARIABLE_2  qui nécessite VARIABLE_3 qui nécessite VARIABLE_1 ), les limites suivantes sont appliquées lors de la résolution des variables dynamiques :

• il ne peut pas y avoir plus de 32 niveaux d'imbrication de variables, au delà de ce niveau, les variables ne sont plus résolues
• il ne peut pas y avoir plus de 255 variables à résoudre sur la ligne de commande, au delà de ce nombre, les variables ne sont plus résolues
• la ligne de commande générée après résolution des variables dynamiques ne peut pas excéder 65000 caractères.

Si un dépassement se produit, la résolution des variables est interrompue, et la ligne de commande est tronquée pour être remplacée par une commande remontant cette information.

Différences de comportement entre le Synchronizer (configuration) et le Scheduler (production)

Certaines données n'étant disponibles qu'en production, le Synchronizer se contente de simuler leur existence lors des essais de check ( exemple: $HOSTPERFDATA$,  $SERVICEPERFDATA$ ... )

En conséquence, certaines problématiques que l'ont peut rencontrer en production ne peuvent pas être testées ou observées depuis l'essai de check, , comme par exemple une variable dynamique qui se substitue par une multitude de variables dynamiques. 

En particulier, pendant les résolutions des variables dynamiques la différence suivante peut être observée :