Description

Le WebService-receiver est le module qui permet de recevoir des résultats passifs pour des hôtes ou checks via HTTP(s).

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

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

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

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 Reveiver à l'emplacement /etc/shinken/receivers/, 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

Exemple de fichier de configuration


#===============================================================================
# ws-arbiter   (webservice)
#===============================================================================
# Daemons that can load this module:
# - receiver
# - arbiter
# 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 authentication =========
    # You can use HTTP basic authentication method for this module.
    # If username is set to anonymous and password is commented, then
    # no authentication will be required.
    username                 anonymous
    #password                secret


}


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.
NomTypeUnitéDéfautCommentaire


module_name


Texte---receiver-module-webservice

Nous vous conseillons de choisir un nom en fonction de l'utilisation du module pour que votre configuration soit simple à maintenir.

Doit être unique.


module_type


Texte---receiver-module-webserviceNe peut être modifié.


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


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

# port to listen 
port 7760


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 :


NomTypeUnitéDéfautCommentaire


host


TexteAdresse IPv40.0.0.0L'interface réseau sur laquelle le module "receiver-module-webservice" va écouter.


port


TextePort réseau7760Port réseau sur lequel le module "receiver-module-webservice" va écouter.


Sécurisation de la communication avec le module


# 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


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 :


NomTypeUnitéDéfautCommentaire


use_ssl


Booléen---0

Permet d'activer ou non l'utilisation du protocole HTTPS.

  • 0 : Désactivé ( utilise HTTP )
  • 1 : Activé ( utilise HTTPS )


ssl_cert


TexteChemin/etc/shinken/certs/server.certChemin vers le certificat SSL utilisé par le protocole HTTPS.


ssl_key


TexteChemin/etc/shinken/certs/server.keyChemin vers la clé SSL utilisée par le protocole HTTPS.


Authentification HTTP


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


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 au paramètres suivants :


NomTypeUnitéDéfautCommentaire


 username


Texte---anonymousNom d'utilisateur.


 password


Texte---secretMot de passe.


Lors d'une requête cURL, les identifiants se renseignent grâce à l'option -u

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