Page History

Introduction

Concept

Il est possible d’ajouter le suffixe [FORCE] ( sans espace ) à la clé d’import d'un élément Shinken afin de forcer la valeur associée.

Lorsqu’une clé d'import est marquée avec [FORCE], elle est traitée de la manière suivante par le mélange des sources ( voir la page Le mélange des sources & les clés de synchronisation (sync-key) ) :

• Sa valeur est considérée comme prioritaire par rapport aux autres sources.
• Si une autre source importe le même objet avec une valeur différente, cette dernière est ignorée.
• En cas de conflit entre plusieurs valeurs forcées, la priorité de la source détermine la valeur conservée.

Ajouter [FORCE] à une clé d'import contenant une liste ( comme la propriété "members" servant à définir les membres d'un groupe d'utilisateurs ) aura pour effet de remplacer complètement la liste des autres sources par celle fournie avec l'option [FORCE].

Toutes les clés ne sont pas forçables. Seules les sources permettant de choisir dans quelles propriétés Shinken sont placées les informations qu’elles récupèrent (mapping) peuvent utiliser le suffixe [FORCE] ( voir le chapitre Sources pouvant forcer des clés d'import et les clés forçables ).

Exemple de valeur forcée dans un fichier d'import que pourrait importer un collecteur de type "cfg-file-import" :

define host {
	host_name[FORCE]    Test host
	address				192.168.1.42
	use					modele1, modele2
}

Forcer une propriété à la valeur par défaut

Pour forcer une propriété d'un objet à sa valeur par défaut, on peut utiliser la valeur "null".

Exemple de valeur forcée à null dans un fichier d'import que pourrait importer un collecteur de type cfg-file-import :

Format des URL

Les exemples utilisent la commande curl, disponible dans la plupart des distributions Linux ; cependant la requête HTTP peut être réalisée avec n'importe quel outil.

Une requête est composée de plusieurs éléments :

• Méthode HTTP : l'action que l'écouteur doit effectuer ; les actions disponibles sont décrites en détail dans les sections suivantes
• Adresse et port de l'écouteur : l'adresse est celle du Synchronizer, le port du listener REST fourni avec Shinken Entreprise est le 7761
• Nom de l'écouteur : il s'agit du nom de l'écouteur tel que défini dans la propriété listener_name du fichier de définition de l'écouteur ; le listener fourni avec Shinken Entreprise est listener-rest
• Version du protocole : dans cette version de Shinken Entreprise, il s'agit de la v1 ; si le protocole évolue dans de futures versions, le numéro de version évoluera également, ce qui permettra à l'écouteur de conserver la compatibilité avec la version actuelle

• Type d'éléments Shinken : le type d'élément Shinken traité par la requête. 

  Info
  Actuellement, seuls les hôtes sont gérés.

• Header HTTP : La liste des en-têtes HTTP ; dans le cas de l'écouteur ; il faut spécifier que le contenu sera du JSON ;
• Données de l'élément : Les données décrivant l'élément à importer respectent le format JSON. Il s'agit d'un dictionnaire décrivant toutes les propriétés et données de l'élément.
  • Elles sont définies à l'aide des noms de propriétés décrites dans la page Syntaxe des fichiers d'imports.
  • Des exemples de requêtes sont disponibles plus bas dans la page.

Sécuriser l'écouteur

Authentification

Il est possible d'authentifier les requêtes grâce à un couple identifiant /mot de passe, configurable uniquement sur la page de l'écouteur, dans l'onglet Configuration.

• Il suffit de cocher la case Authentification et saisir un identifiant et un mot de passe, qui ne seront valables que pour cet écouteur.
• Pour valider cette configuration il faudra sur le bouton Envoyer.
  • L'écouteur va se relancer avec cette nouvelle configuration ( ou lors de l'activation de la source si celle-ci est désactivée au moment de l'édition ).

Lors des appels à cet écouteur, il faudra spécifier cet identifiant et ce mot de passe pour que les requêtes s'exécutent.

Par exemple, avec curl, il faut utiliser l'option -u :

$ curl -u 'admin-listener:mot_de_passe' -X PUT ....

Chiffrement des appels

Afin de chiffrer les communications entre un écouteur et un client, il suffit d'activer l'option SSL ( Secure Socket Layer ).

Il suffit de cocher la case Utiliser SSL et saisir une clé SSL et un certificat SSL qui ne sera valable que pour cet écouteur.

Pour valider cette configuration, il faut cliquer sur le bouton Envoyer.

L'écouteur va se relancer avec cette nouvelle configuration ( ou lors de l'activation de la source si celle-ci est désactivée au moment de l'édition ).

Lors des appels à cet écouteur, il faudra penser à modifier le protocole HTTP en HTTPS.

$ curl -X PUT "https://synchronizer-server:7761/shinken/listener-rest/v1/hosts" 

Description des actions

Dans ces différents exemples, les requêtes seront :

• non authentifiées
• sans le chiffrement ( SSL )
• lancées depuis le serveur hébergeant le Synchronizer : localhost
• Utilisant le collecteur par défaut : listener-rest
• Utilisant le port par défaut : 7761

L'URL utilisé sera donc

http://localhost:7761/shinken/listener-rest/v1/hosts/"

curl ... | python -m json.tool

Obtenir la liste des hôtes créés par l'écouteur

Pour obtenir la liste des hôtes présent dans l'écouteur via l'Appel /shinken/listener-rest/v1/hosts, et la Méthode GET

• Voir la page V1 - ( GET ) /shinken/listener-rest/v1/hosts ( liste des hôtes présent dans l'écouteur )

Créer un hôte

Pour créer un hôte via l'Appel /shinken/listener-rest/v1/hosts, et la Méthode PUT

• Voir la page V1 - ( PUT ) /shinken/listener-rest/v1/hosts ( création d'hôte )

Obtenir les données d'un hôte

Pour obtenir les informations définissant un hôte via l'Appel /shinken/listener-rest/v1/hosts/SE_UUID, et la Méthode GET

• Voir la page V1 - ( GET ) /shinken/listener-rest/v1/hosts/SE_UUID ( Obtenir les données d'un hôte )

Modifier un hôte

Pour modifier un hôte via l'Appel /shinken/listener-rest/v1/hosts/SE_UUID, et l'une des métodes POST ou PUT ou PATCH

• Voir la page V1 - ( POST, PUT, PATCH ) /shinken/listener-rest/v1/hosts/SE_UUID ( modification de l'hôte )

Supprimer un hôte créé par l'écouteur

Pour supprimer un hôte via l'Appel /shinken/listener-rest/v1/hosts/SE_UUID, et l'une des métodes DELETE

• Voir la page V1 - ( DELETE ) /shinken/listener-rest/v1/hosts/SE_UUID ( Supprimer un hôte créé par l'écouteur )

Forcer la valeur des propriétés

Exemple

Résolution de conflits entre plusieurs [FORCE]

Lorsque le suffixe [FORCE] est utilisé dans plusieurs sources, la valeur provenant de la source avec le plus petit numéro d'ordre est retenue.

Par exemple, les trois sources suivantes utilisent l'adresse comme clé de synchronisation ( voir la page Le mélange des sources & les clés de synchronisation (sync-key) ) :

Et importent chacune un hôte ayant :

• la même adresse ( clé d'import address )
• et un nom différent ( clé d'import host_name ).

Les objets sont en conflit car le mélange des sources veut les regrouper ( même clé de synchronisation ).

Sources pouvant forcer des clés d'import et les clés forçables

Tous les écouteurs permettent de forcer des clés d'import.

Seuls les types de collecteurs suivants permettent l'utilisation du [FORCE] :

• cfg-file-import
• ldap-import
  • depuis un serveur Active Directory
  • depuis un serveur OpenLDAP
• synchronizer-collector-vmware
• synchronizer-collector-excel

Les clés d'import suivantes peuvent être forcées :

Liste des clés d'import pouvant être forcées