====== Howto : créer et activer un module de supervision ======

On se propose dans ce tutoriel de créer un module de supervision qui permettra de monitorer deux paramètres spécifiques à un fichier : sa taille et les droits qui lui sont appliqués.

Il faudra pouvoir configurer un ou plusieurs chemins d'accès au fichier au niveau du gabarit.

Le module devra permettre de remonter une alerte sur les deux paramètres remontés.


===== - Objectifs de cette fonctionnalité ===== 

Etendre tout ce qui inclus de base dans SI Monitor (cpu, ram...) par des modules personnalisables.

Exemple : Supervision des backups (émettre une alerte si le statut d'un backup n'est pas bon)\\
Exemple : Emettre une alerte sur mot clé (dans un fichier de log)\\
Exemple : Taille d'un fichier : Emettre une alarme sur la taille normale est dépassée. Peut aussi vérifier les droits sur un fichier \\
Exemple : Détecter l'existence d'un fichier.\\
Exemple : Nombre de paquets bloqués sur un Firewall. Valeur que l'on peut tracer sur un graphe avec émission d'une alerte si valeur anormale\\
Exemple de détection d'attaque DDOS : 
créer un script qui renvoie la valeur du nombre de paquets droppés sur une chaine IPTable (par ex) puis remettre le compteur à zéro (ex : toutes les minutes via un cron).
SI Monitor (via la création d'un module personnalisé), permet d'émettre une alerte si le nombre de paquets est anormalement élevé et de tracer un graphe.
etc...
===== - Fonctionnement =====
La tache cron (ou planificateur Windows) appelle SI Monitor probe (l'indicateur). Cet indicateur va simultanément récupérer la sortie d'un script personnalisé (plugin Nagios, script client...script dans n'importe quel langage à partir du moment où la sortie est textuelle (chaine de caractères).
L'indicateur fait son rapport au serveur Frontend qui se charge d'historiser, d'émettre une alarme le cas échéant et de tracer les graphes.

===== - Création du module mycheckfile =====
  - Se rendre dans le menu //Administration=>Modules//,
  - Renseignez un nom (sans espaces) et une description pour ce module,
  - On indique ici que le module est direct, puisque les données qui seront remontées concerneront l'hôte sur lequel la sonde est installée.
  - Cliquez sur //Créer//.
{{ :si-monitor_server:v4:howtos:capture_createmodule_1.png?direct&400 |}}

===== - Paramétrage du modèle XML =====

Lors de la création du module, un fichier XML décrivant le modèle du module a été créé. Il contient les informations suivantes :
<file xml mycheckfile.xml>
<?xml version="1.0" encoding="utf-8"?>
<module id="34" name="mycheckfile" minperiodicitycheck="5" maxperiodicitycheck="0" defaultperiodicitycheck="60">
	<singleparams/>
	<globalparams/>
	<reportvalues regex="/(.*)/i"/>
	<alarms/>
</module>
</file>

<note tip>
Cliquez sur "Editer le modèle" pour afficher la définition XML du module.
</note>

Les attributs du noeud //__module__// sont :
  * //id// : l'id correspondant dans la base de données
  * //name// : le nom correspondant dans la base de données
  * //minperiodicitycheck// : la période minimum de rafraîchissement de la donnée (il convient de ne pas indiquer une valeur trop faible pour éviter la surcharge au niveau sonde et au niveau serveur).
  * //maxperiodicitycheck// : la période maximum de rafraîchissement de la donnée (0 pour infini)
  * //defaultperiodicitycheck// : la période de rafraîchissement de la donnée par défaut

Le nœud module peut contenir les fils suivants :
  * //__singleparams__// : Les paramètres d'entrée dits "uniques"
  * //__globalparams__// : Les paramètres qui s'appliquent à l'ensemble du module
  * //__reportvalues__// : Les variables retournées par la sonde
  * //__alarms__// : Les alarmes qui peuvent être définies sur le module

==== - Paramètres d'entrée ====

Nous allons placer dans //__singleparams__// un nœud //__param__// qui contiendra notre paramètre d'entrée à savoir le chemin du fichier.
Le nœud //__singleparams__// contient des nœuds //__param__//.
Les attributs possibles pour le nœud //__param__// sont :
  * //type// qui peut être :
    * userdefined : défini par l'utilisateur, au niveau du formulaire de configuration de gabarit
    * calculated : calculé par le système
  * //name// : Le nom du paramètre (Lettres, chiffres et underscore)
  * //coupleid// : Permet de définir l'appartenance ou non à un couple de valeurs (ne sera pas utilisé ici)
  * //label_fr// : Label utilisé pour le formulaire
  * //mask// : Regex qui permet de vérifier la validité de la saisie
  * //form// : Type de champ de formulaire

Voici notre paramètre d'entrée :
<code xml>
<param type="userdefined" name="filepath" label_fr="Chemin complet" mask="[a-zA-Z0-9/]*" form="string"/>
</code>

==== - Paramètres dans le rapport ====

Pour ce module, l'indicateur de supervision va faire un rapport contenant un certain nombre d'informations, dont un rapport textuel qu'il faudra savoir interpréter.

Ce rapport textuel va être lu par une expression régulière (attribut //regex// du nœud //__reportvalues__//), qui placera sa lecture dans différentes variables (décrites dans les nœuds //__reportvalue__//)

Nous savons que notre script remontera les données sous cette forme :
<code>filepath:/var/log/syslog,filesize:141268368,filechmod:-rw-r-----</code>

Nous devons récupérer dans trois variables différentes les valeurs :
  * /var/log/syslog
  * 141268368
  * 0640

Pour celan nous utiliserons la regex suivante :
<code>/filepath:(.*),filesize:([0-9]+),filechmod:(.*)/i</code>

Notre XML devrait donc ressembler à ceci :
<code xml><reportvalues regex="/filepath:(.*),filesize:([0-9]+),filechmod:(.*)/i"/></code>

Il y a trois parenthèses capturantes dans cette regex. Nous aurons donc trois paramètres à ajouter avec les nœuds //__reportvalue__//.

Les attributs possibles du nœud //__reportvalue__// sont :
  * //index// : la position dans la regex, en partant de 0 (entier),
  * //mandatory// : obligatoire ou non (dans certains cas, le nombre de paramètres peut être variable (boolean),
  * //name// : le nom de la variable (lettres, nombre et underscore)

Nous aurons donc ici :
<code xml>
<reportvalue index="0" name="filepath"/>
<reportvalue index="1" name="filesize"/>
<reportvalue index="2" name="filechmod"/>
</code>

A ce stade, notre fichier XML de définition du modèle ressemble donc à ceci :

<file xml mycheckfile.xml>
<?xml version="1.0" encoding="utf-8"?>
<module id="34" name="mycheckfile" minperiodicitycheck="5" maxperiodicitycheck="0" defaultperiodicitycheck="60">
	<singleparams>
		<param type="userdefined" name="filepath" label_fr="Chemin complet" mask="[a-zA-Z0-9/]*" form="string"/>
	</singleparams>
	<globalvalues/>
	<reportvalues regex="/filepath:(.*),filesize:([0-9]+),filechmod:(.*)/i">
		<reportvalue index="0" name="filepath"/>
		<reportvalue index="1" name="filesize"/>
		<reportvalue index="2" name="filechmod"/>
	</reportvalues>
	<alarms/>
</module>
</file>

==== - Alarmes ====

Il ne nous reste plus qu'à définir quelles alarmes pourront être appliquées à notre module. Pour cela, nous utilisons évidemment le nœud //__alarms__// auquel nous allons ajouter des nœuds //__alarm__//.

Les alarmes du xml ne permettent pas de définir le seuil (alerte, erreur) mais les informations de bases (nom de l'alarme et opérateur). Pour configurer les seuils, il faut se référer à [[http://kb.irincom.com/si-monitor_client:seuil|la personnalisation des seuils]]

Les attributs possibles pour le nœud //__alarm__// sont :
  * //authorizedparam// : On spécifie ici sur quel paramètre de //__reportvalues__// s'appliquera l'alarme,
  * //authorizedoperand// : On indique ici les opérandes autorisées pour effectuer le test, séparées par le caractère | (parmi <, <=, ==, !=, >=, >),
  * //defaultoperand// : L'opérande par défaut

Nous proposons ici d'autoriser la création de deux types d'alarmes, la première sur le paramètre ''filesize'', et la deuxième sur le paramètre ''filechmod'' :

<code xml>
<alarm authorizedparam="filesize" authorizedoperand="&lt;|&lt;=|==|!=|&gt;=|&gt;" defaultoperand="&gt;"/>
<alarm authorizedparam="filechmod" authorizedoperand="!=" defaultoperand="!="/>
</code>

<note tip>Remarquez au passage que nous avons dû échapper notre chaîne de caractères pour qu'elle soit compatible avec XML (le signe < est échappé en &lt; et le signe > en &gt;). Si nécessaire, le site [[http://www.freeformatter.com/xml-escape.html]] peut vous aider dans cette tâche.</note>

Nous avons terminé la définition de notre module. Le fichier XML devrait être le suivant :
<file xml mycheckfile.xml>
<?xml version="1.0" encoding="utf-8"?>
<module id="34" name="mycheckfile" minperiodicitycheck="5" maxperiodicitycheck="0" defaultperiodicitycheck="60">
	<singleparams>
		<param type="userdefined" name="filepath" label_fr="Chemin complet" mask="[a-zA-Z0-9/]*" form="string"/>
	</singleparams>
	<globalvalues/>
	<reportvalues regex="/filepath:(.*),filesize:([0-9]+),filechmod:(.*)/i">
		<reportvalue index="0" name="filepath"/>
		<reportvalue index="1" name="filesize"/>
		<reportvalue index="2" name="filechmod"/>
	</reportvalues>
	<alarms>
		<alarm authorizedparam="filesize" authorizedoperand="&lt;|&lt;=|==|!=|&gt;=|&gt;" defaultoperand="&gt;"/>
		<alarm authorizedparam="filechmod" authorizedoperand="!=" defaultoperand="!="/>
	</alarms>
</module>
</file>
===== - Paramétrage du gabarit =====

Maintenant que notre module est prêt, nous allons l'activer dans un gabarit.

  - Rendez-vous sur la page //Administration=>Gabarits//
  - Sélectionnez le gabarit sur lequel vous souhaitez activer le module et cliquez sur //Configurer//, ou bien créez-en un nouveau le cas échéant.
  - Cliquez sur //Ajouter un module//. Votre module devrait apparaître dans la liste déroulante. Validez.{{ :si-monitor_server:v4:howtos:capture_createmodule_2.png?direct&400 |}}
  - Cliquez sur //Paramètres//.{{ :si-monitor_server:v4:howtos:capture_createmodule_3.png?direct&400 |}}
  - Puis ajoutez des chemins de fichier comme suit :{{ :si-monitor_server:v4:howtos:capture_createmodule_4.png?direct&400 |}}
  - Fermez la fenêtre lorsque vous avez terminé.
  - Cliquez sur //Activer// pour activer le module dans ce gabarit.
  - Enfin, cliquez sur //Revenir à la liste des gabarits//, puis cliquez sur //Distribuer// pour appliquer le gabarit aux différentes sondes.

Vous pouvez vérifier que votre configuration est active. Pour cela :
  - Rendez-vous dans le menu //Administration=>Hôtes//
  - Sélectionnez un hôte qui utilise votre gabarit
  - Cliquez sur //Fichier ini//
Vous devriez voir votre section comme ceci :
<code ini>
[plugin:mycheckfile]
@interval=60
@plugin=mycheckfile
@service=mycheckfile
filepath0=/var/log/syslog
filepath1=/var/log/messages
</code>

===== - Remontée de données =====

Pour cet exemple, nous utiliserons :
  * Un script python avec pour sortie la chaîne de caractères précitée.
<file python mycheckfile.py>
#!/usr/bin/python3
""" Les librairies nécessaires à l'exécution de notre script """
import os
import stat
import configparser
import base64

""" Configparser nous permet de lire le fichier ini de l'indicateur simonitor """
config = configparser.ConfigParser()
config.read('/etc/simonitor.ini')
res = []
""" Pour chaque ligne commençant par filepath dans la section plugin:mycheckfile et si le fichier existe... """
for key in config['plugin:mycheckfile']:
	if key.count("filepath") > 0:
		path = config['plugin:mycheckfile'][key]
		if os.path.isfile(path):
			""" ... récupérer les infos filesize et permissions """
			osfile = os.stat( path )

			mode = stat.filemode( osfile.st_mode )
			size = osfile.st_size
			""" Ajouter à la liste de résultats """
			res.append( 'filepath:'+path+',filesize:'+str( size )+',filechmod:'+mode )

""" Séparer les lignes par un \n """
strres = "\n".join( res )
""" Afficher le résultat """
print( strres )
</file>
  * Notre indicateur simonitor
  * Le scheduleur cron :
Voici la ligne cron que nous pourrions ajouter (fréquence d'exécution : 1 minute) :
<code>* * * * * /opt/simonitor/simonitor-probe -x "mycheckfile=;d;`/usr/bin/python3 /opt/simonitor/mycheckfile.py`" >> /dev/null 2>&1</code>

Au bout de quelques minutes, vous devriez voir apparaître des informations dans les logs :
{{ :si-monitor_server:v4:howtos:capture_createmodule_5.png?direct&400 |}}

Si vous rencontrez une erreur dans SI Monitor pensez à : 
   * Vérifiez que le firewall ne bloque pas le réseau, si des ports particuliers sont utilisés.
   * Vérifiez aussi que les données sont envoyées au bon serveur dans simonitor.ini, notamment en cas de version de dev et version de prod.
   * Vérifiez que le nom du module soit le même partout.
===== - Définition d'alarmes =====
Les alarmes sont définies :
  * soit pour un hôte en particulier,
  * soit pour un groupe d'hôtes.

Il existe deux niveaux d'alarme :
  * Alerte (warning) : Le seuil atteint nécessite une notification pour action, mais n'est pas bloquant pour la production
  * Alarme (error) : le seuil atteint est critique et impacte la production.