Page History

Description

Le receiver-module-webservice est Le WebService-receiver est le module qui permet de recevoir des résultats passifs pour des hôtes ou checks via statuts et des contextes d'éléments en mode Passif ( voir la page Mode actif et mode passif ) via une API HTTP(s).

Configuration du module Webservice

Ce module met à disposition une écoute HTTP qui écoute les requêtes HTTP POST et effectue des actions sur hôtes, clusters et checks.

• Le Web Service Le module écoute sur port TCP 7760 TCP 7760 ( par défaut ). 
• Il supporte les accès authentifiés ou anonymes. 

La configuration se défini définit dans le fichier de configuration du module ( présent par défaut dans /etc/shinken/modules/ws-receiver.cfg ). receiver-module-webservice.cfg ). 

Ce module permet notamment de recevoir et traiter les statuts envoyés par les traps SNMP ( Voir la page Script d'interprétation des traps avec le module receiver-module-webservice )

Activation du module

Le module receiver-module-webservice est un module qui peut être activé seulement sur le démon Receiver.

• L'activation du module s'effectue en ajoutant le nom de ce module dans le fichier de configuration du démon Receiver.
• Pour se faire, ouvrez le fichier de configuration du Receiver à l'emplacement /etc/shinken/receivers/nom_du_receiver.cfg, et ajouter le nom de votre module "receiver-module-webservice".

Exemple : par défaut, nous livrons un module dont le nom est "receiver-module-webservice" :

define receiver {
    [...]
    modules                   Module 1, Module 2, Module 3, receiver-module-webservice
    [...]
}

Pour prendre en compte le changement de configuration, redémarrez l'Arbiter :

service shinken-arbiter restart

Configuration

La configuration du module se trouve par défaut dans le fichier /etc/shinken/modules/receiver-module-webservice.cfg

• Vous trouverez aussi un fichier d'exemple avec le chemin suivant : /etc/shinken-user-example/configuration/daemons/receiver/receiver-module-webservice/receiver-module-webservice-example.cfg

Exemple de fichier de configuration

#===============================================================================
# WebService-ReactionnerReceiver   (webservice)
#===============================================================================
# Daemons that can load this module:
# - receiver
# This module is a webservice that can be used to send checks to Shinken Enterprise
# as POST HTTP(s)
#===============================================================================


define module {

    #======== Module identity =========
    # Module name. Must be unique
    module_name               receiver-module-webservice
    # Module type (to load module code). Do not edit.
    module_type               ws_arbiter


    #======== Listening address =========
    # host: IP address to listen to.
    #       note: 0.0.0.0 = all interfaces.
    host                      0.0.0.0

    # port to listen
    port                      7760

    # HTTPs part, enable if you want to set the listening for HTTPS instead of default HTTP.
    # disabled by default. Set your own certificates.
    use_ssl                   0
    ssl_cert                  /etc/shinken/certs/server.cert
    ssl_key                   /etc/shinken/certs/server.key


    #======== HTTP authentificationauthentication =========
    # You can use HTTP basic authentificationauthentication method for this module.
    # If username is set to anonymous and password is commented, then
    # no authentificationauthentication will be required.
    username                 anonymous
    #password                secret


}

Les valeurs peuvent être :

• module_name: définit un nom unique pour le module
• module_type: doit être ws_arbiter
• host: adresse de l'interface réseau sur laquelle effectuer l'écoute. 0.0.0.0 signifie "toutes les interfaces"
• port: port TCP à écouter
• use_ssl et ssl_cert / ssl_key : permet que le module écoute sur le port en SSL (protocole HTTPS) et d'utiliser des certificats
• username et password: si mis à "anonymous" aucune accréditation nécessaire. Si vous mettez un nom utilisateur/mot de passe, une authentification est nécessaire

Utilisation du module Webservice

Le webservice du Receiver écoute des requêtes HTTP pour ensuite effectuer des actions sur les hôtes/clusters ou checks concernés.

Un simple curl ou appel HTTP dans votre programme suffit pour envoyer des actions à Shinken.

/push_check_result:  soumettre le résultat de check passif sur un hôte ou un check

Détails des sections composant le fichier de configuration

Identification du module

Il est possible de définir plusieurs instances de module de type receiver-module-webservice dans votre architecture Shinken.

• Chaque instance devra avoir un nom unique.

module_name

module_type

Configuration de l'interface et du port d'écoute

Il est possible de configurer l'interface réseau sur laquelle est mise à disposition l'API. Si par exemple l'API ne doit être accessible seulement via un réseau local, il est possible de n'écouter les requêtes que sur cette interface réseau.

Les paramètres suivants permettent de configurer l'accès à l'API :

host

port

Sécurisation de la communication avec le module

L'API du module est accessible via HTTP. Il est recommandé d'utiliser le protocole HTTPS pour chiffrer la communication avec le module.

Si pour des raisons de sécurité, cette API doit être accessible via HTTPS, il est possible de configurer les certificats avec les paramètres suivants :

use_ssl

ssl_cert

ssl_key

Authentification HTTP

Afin d'être authentifié auprès du module, il est possible de configurer les identifiants à utiliser dans les requêtes, dans la configuration du module grâce aux paramètres suivants :

 username 

 password

curl -u anonymous:secret -X POST ...

/acknowledge: Mettre un Prise en compte sur un hôte, un cluster ou un check

/downtime: Mettre une période de maintenance sur un hôte, un cluster ou un check

Paramètres de l'appel

Méthode HTTP

POST

time_stamp

host_name

service_description

comment

start_time

end_time

notify

author