Page History

Scroll Ignore

scroll-pdf	true
scroll-office	true
scroll-chm	true
scroll-docbook	true
scroll-eclipsehelp	true
scroll-epub	true
scroll-html	true

Panel

title	Sommaire

Table of Contents

style	none

Introduction

L'API fournie par les écouteurs est de type REST ; elle fonctionne donc par l'intermédiaire des différentes méthodes du protocole HTTP:

GET : Obtenir des informations sur un objetélément, ou la liste des objetséléments
PUT : Créer ou modifier un objetélément
POST : Modifier un objetélément
PATCH : Modifier un objetélément
DELETE : Supprimer un objetélément

L'identifiant des objets éléments est fournie fourni dans l'URL et les données supplémentaires, quand cela est est nécessaire, sont fournies dans le corps de la requête HTTP sous la forme d'un objet en format JSON.

Info
Notez que cet écouteur ne permet de travailler que sur les hôtes.

Cette page décrit le format des URL ainsi que les différentes actions réalisables.

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 l'outil de votre choix.

Panel
Image RemovedImage Added

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 d'écoute de l'écouteur : l'adresse est celle du Synchronizer, le port du listener REST fourni avec Shinken Entreprise est le 7761
Nom du listener 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 a à l'écouteur de conserver la compatibilité avec la version actuelle
Type d'objet éléments Shinken : le type d'objet élément Shinken traité par la requête. Actuellement, seuls les hôtes sont gérés.
Header HTTP : La liste des en-têtes HTTP ; dans le cas de l'écouteur ; nous spécifions que nous envoyons du contenu JSON
Données de l'objet élément : Les données décrivant l'objet é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'objet ; élément. Elles sont définies de la même manière que dans les fichiers CFG et décrites sur cette page.

Si l'authentification HTTP est configurée dans le listener, vous devez fournir les informations d'authentification lors de l'exécution de la requête HTTP. Avec curl, il s'agit de

dans la page suivante : Syntaxe des fichiers d'imports.

Sécuriser l'écouteur

Par défaut, l'écouteur transmet et reçoit les requêtes en clair ( non chiffrée ) et sans authentification. Vous pouvez sécuriser ces communications avec :

Une Authentification par identifiant/mot de passe
Un chiffrement grâce à SSL

Info
Il est fortement conseillé d'activer ces paramètres de sécurité en même temps.

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.

Validez ensuite cette configuration en cliquant 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 ).

Panel
Image Added

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 :

Code Block
$ curl -u '

root:root

admin-listener:mot_de_passe' -X PUT ....

Si l'authentification SSL est configurée dans le listener, vous devez fournir le certificat correspondant lors de la requête. Avec curl, il s'agit de l'option --cacert :

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.

Info
Shinken fournit un certificat SSL qui permet de chiffrer les communications pour tous les démons et/ou modules. Il se situe dans le répertoire /etc/shinken/certs/

Validez ensuite cette configuration en cliquant 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 ).

Panel
Image Added

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

Code Block
$ curl -

-cacert certificate.crt -X PUT ...

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

Info
Si vous utilisez le certificat fournit par Shinken ou un certificat auto signé ( non émis et vérifié par une autorité de certification ), vous aurez besoin de spécifier l'option -k ou --insecure dans la ligne de commande curl

Info
Si vous avez le certificat de l'autorité de certification vous pouvez le spécifiez dans la ligne de commande curl avec l'option --cacert <chemin du certificat de l'autorité>

Panel

Image Removed

Description des actions

Dans ces différents exemples, nous utilisons allons utiliser des requêtes :

non authentifiées

,

sans le chiffrement ( SSL

et

)
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ée sera donc

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

Pensez à adapter cette URL en fonction de votre configuration

Info

Afin d'avoir un affichage plus esthétique des résultats de la méthode GET, vous pouvez rediriger la sortie vers pyhon et utiliser le module json.tool grâce à la commande suivante à ajouter en fin de ligne :

Code Block
\| python -m json.tool

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

Définition

URL à utiliser	/shinken/listener-rest/v1/hosts
Méthodes possibles	GET
Code retour en cas de succès	200
Contenu du retour si succès	Liste des éléments au format JSON

Cette URL associée à la méthode GET, permet d'obtenir la liste de tous les éléments présents dans l'écouteur. Le format de retour est un JSON

info

.

Les éléments présents dans l'écouteur sont ceux qui ont été

crée

créés sur cet écouteur ( et qui n'ont pas été supprimés ).

Les propriétés et données Shinken affichées sont celles reçues par le collecteur.

. Il n'est pas possible d'obtenir un hôte présent en "Staging" ou en "Zone de travail" si celui-ci n'est pas crée par l'écouteur.

Info

Cet appel correspond à l'onglet "Liste des éléments enregistrés dans la base de données" sur la page de description de votre source.

Exemple

Code Block

$ curl -H "Content-Type: application/json" "http://localhost:7761/shinken/listener-rest/v1/hosts/" -X GET | python -m json.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   785728  100   785728    0     0   104k100k      0 --:--:-- --:--:-- --:--:--  109k101k
[
    {
        "_SE_UUID": "core-hosts-22b48e7408a549f6895badada2fd3690a0af58fafdfb4db5b0fe07c704caf937",
        "_SSHSYNC_KEY_PASSPHRASEKEYS": "root",
        "_SSH_USER": "root"core-hosts-a0af58fafdfb4db5b0fe07c704caf937,host_example_01",
        "_SYNC_KEYSid": "core-hosts-22b48e7408a549f6895badada2fd3690,hote-examplea0af58fafdfb4db5b0fe07c704caf937",
        "_idaddress": "22b48e7408a549f6895badada2fd3690192.168.1.48",
        "host_name": "hote-host_example_01",
        "imported_from": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
        "update_date": 15278391801625570835.6257291448688,
        "use": "linux"
    },
    {
        "_SE_UUID": "core-hosts-bafe4fae3fc447b992daa3f10ee260f23941f2a530194d149f18b82f84bcef51",
        "_SYNC_KEYS": "core-hosts-bafe4fae3fc447b992daa3f10ee260f23941f2a530194d149f18b82f84bcef51,hote-example-2host_example_02",
        "_id": "bafe4fae3fc447b992daa3f10ee260f23941f2a530194d149f18b82f84bcef51",
        "address": "192.168.01.4254",
        "host_name": "hote-example-2host_example_02",
        "imported_from": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
        "update_date": 15278399541625570975.469449763321,
        "use": "shinken-fullwindows"
    }
]

Tip

Afin d'avoir un affichage plus esthétique des résultats de la méthode GET, vous pouvez rediriger la sortie vers python et utiliser le module json.tool grâce à la commande suivante à ajouter en fin de ligne :

Code Block
\| python -m json.tool

Créer un hôte

Définition

URL à utiliser	/shinken/listener-rest/v1/hosts
Méthodes possibles	PUT
Code retour en cas de succès	201
Contenu du retour si succès	SE_UUID de l'élément créé

Pour mener à bien cette action, vous pouvez utiliser les méthodes PUT qui permettent d'envoyer à l'écouteur un nouvel objetélément

Lors de la création d'un nouvel objet élément, l'écouteur renvoie l'identifiant de l'objet élément créé sous la forme "core-hosts-<ID>". Cet identifiant devra être utilisé lors d'autres opérations manipulant l'objet élément :

Exemple

Code Block

$ curl -H  curl"Content-Type: application/json" "http://localhost:7761/shinken/listener-rest/v1/hosts/"  -X PUT -d '{ "host_name": "hote-host_example_01", "useaddress":"linux192.168.1.48", "_SSH_USERuse":"root", "_SSH_KEY_PASSPHRASE":"root" linux"}'
"core-hosts-22b48e7408a549f6895badada2fd3690a0af58fafdfb4db5b0fe07c704caf937"

Obtenir les données d'un hôte

Définition

URL à utiliser	/shinken/listener-rest/v1/hosts/SE_UUID
Méthodes possibles	GET
Code retour en cas de succès	200
Contenu du retour si succès	Propriétés et Données Shinken de l'élément reçu sur le collecteur au format JSON

La méthode GET , lorsqu'elle est accompagnée d'un identifiant, l'objet élément est renvoyé au format JSON.

Exemple

Info
Le SE_UUID présent dans l'URL est celui de l'hôte créé dans le premier appel de création. Pensez à mettre le vôtre !

Code Block

$ curl -H "Content-Type: application/json" "http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-22b48e7408a549f6895badada2fd3690a0af58fafdfb4db5b0fe07c704caf937" -X GET | python -mjsonm json.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   381361  100   381361    0     0  7266851046      0 --:--:-- --:--:-- --:--:-- 7620060166
{
    "_SE_UUID": "core-hosts-22b48e7408a549f6895badada2fd3690a0af58fafdfb4db5b0fe07c704caf937",
    "_SSHSYNC_KEY_PASSPHRASEKEYS": "root",
    "_SSH_USER": "rootcore-hosts-a0af58fafdfb4db5b0fe07c704caf937,host_example_01",
    "_SYNC_KEYSid": "core-hosts-22b48e7408a549f6895badada2fd3690,hote-examplea0af58fafdfb4db5b0fe07c704caf937",
    "_idaddress": "22b48e7408a549f6895badada2fd3690192.168.1.48",
    "host_name": "hote-host_example_01",
    "imported_from": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
    "update_date": 15278391801625570835.6257291448688,
    "use": "linux"
}

Modifier un hôte

Définition

URL à utiliser	/shinken/listener-rest/v1/hosts/SE_UUID
Méthodes possibles	POST, PUT, PATCH
Code retour en cas de succès	200
Contenu du retour si succès	Le mot clé "done"

Les requêtes de modification sont équivalentes à une requête de suppression et une de création avec le même SE_UUID. Cela permet de n'avoir que les dernières données à jour dans la base de l'écouteur.

Warning

Lors de modifications, les propriétés et données Shinken de l'élément présent dans l'écouteur sont remplacées par celles envoyées dans la nouvelle requête. Ne sont conservé que :

Le _SE_UUID
Le nom de l'élément si celui-ci n'est pas mis à jour dans la requête
Les propriétés et données reçues dans la requête de mise à jour

Exemple

Code Block
$ curl -H "Content-Type: application/json" "

Pour modifier un objet existant, utilisez la méthode POST en indiquant son identifiant dans l'URL. Les propriétés présentes dans l'objet JSON transmis dans la requête remplaceront ou compléteront alors celles se trouvant dans l'objet. Les autres propriétés ne sont pas modifiées.

Code Block
$ curl "http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-22b48e7408a549f6895badada2fd3690" -X POST -d '{ "address": "192.168.1.42" }' done

Pour réécrire totalement un objet existant, utilisez la méthode PUT en indiquant son identifiant dans l'URL. Les propriétés présentes dans l'objet actuel seront supprimées et l'hôte sera recréé avec le même identifiant que l'ancien. Cela correspond à une requête DELETE et une requête PUT avec un identifiant spécifique.

Code Block$ curl -X PUT

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

-22b48e7408a549f6895badada2fd3690

-a0af58fafdfb4db5b0fe07c704caf937" -X POST -d '{

host

business_

name

impact":

"hote-example", address": "192.168.1.42"

"4"}'
done

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

Définition

Code retour en cas de succès
URL à utiliser	/shinken/listener-rest/v1/hosts/SE_UUID
Méthodes possibles	DELETE

200

200
Contenu du retour si succès	Le mot clé "done"

Utilisez l'action DELETE pour supprimer un objet élément créé par l'écouteur, en fournissant l'identifiant de l'objet élément à supprimer.

Info
Notez que cette requête permet de supprimer les objets éléments dans la base de l'écouteur ; elle ne permet pas de supprimer un objet élément dans le Synchronizer lui-même, pour des raisons de sécurité.

Exemple

Code Block
$ curl -u 'root:root' -X DELETE http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-22b48e7408a549f6895badada2fd3690 done

Question

Questions fréquentes sur l'import d'éléments via l'API REST

Forcer l'utilisation d'un modèle

Lorsqu'on importe un hôte existant qui contient la propriété "use", la liste des modèle modèles décrits dans la propriété "use" est ajoutée à la liste des modèles actuellement utilisée utilisés par l'hôte.

Comme lors de l'import d'hôtes via fichiers Cfg, il est possible de forcer l'utilisation d'une liste de modèles ( remplacement et non-ajout de modèles ) en utilisant la propriété "use[FORCE]" au lieu de "use".

Plus de précisions sur l'utilisation du FORCE pour les modèles sont disponible dans la page de documentation suivante: Syntaxe des fichiers d'imports

Page tree

Versions Compared

Old Version 9

New Version Current

Key

Introduction

Format des URL

Sécuriser l'écouteur

Authentification

Chiffrement des appels

Description des actions

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

Définition

Exemple

Créer un hôte

Définition

Exemple

Obtenir les données d'un hôte

Définition

Exemple

Modifier un hôte

Définition

Exemple

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

Définition

Exemple

Questions fréquentes sur l'import d'éléments via l'API REST

Forcer l'utilisation d'un modèle